Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

fix(board): observe complete native maintenance writes [C7,P4,B2]

Corey Olsona8acdb291073
diff --git a/src/board-event-log-migrate.js b/src/board-event-log-migrate.js
index ae5092cf..b7fa2853 100644
--- a/src/board-event-log-migrate.js
+++ b/src/board-event-log-migrate.js
@@ -4,33 +4,13 @@ import {
SCHEMA,
} from './board-schema-source.js';
import { readEventLogVersion } from './board-read-open.js';
-import {
- beginBoardWrite,
- finishBoardWrite,
- prepareBoardWriteIdentity,
-} from './board-write-lock.js';
-
-/** Refuse unknown future event records before migrating anything, and mark older boards current. */
-export function migrateEventLogVersion(db, writeContext) {
- prepareBoardWriteIdentity();
- db.exec('BEGIN IMMEDIATE');
- const record = beginBoardWrite(db, writeContext);
- let released = false;
- try {
- db.exec(SCHEMA);
- const version = readEventLogVersion(db);
- if (version < EVENT_LOG_VERSION) {
- db.prepare('INSERT INTO board_meta (meta_key, meta_value) VALUES (?, ?) ON CONFLICT(meta_key) DO UPDATE SET meta_value = excluded.meta_value')
- .run('event_log_version', String(EVENT_LOG_VERSION));
- }
- db.exec('COMMIT');
- released = true;
- } catch (error) {
- db.exec('ROLLBACK');
- released = true;
- throw error;
- } finally {
- finishBoardWrite(record, released, 'migration-released');
+/** Refuse future event records and update older formats inside the owning open's atomic migration. */
+export function migrateEventLogVersion(db) {
+ db.exec(SCHEMA);
+ const version = readEventLogVersion(db);
+ if (version < EVENT_LOG_VERSION) {
+ db.prepare('INSERT INTO board_meta (meta_key, meta_value) VALUES (?, ?) ON CONFLICT(meta_key) DO UPDATE SET meta_value = excluded.meta_value')
+ .run('event_log_version', String(EVENT_LOG_VERSION));
}
}
diff --git a/src/board-write-lock.js b/src/board-write-lock.js
index 6d052d53..088fcaa1 100644
--- a/src/board-write-lock.js
+++ b/src/board-write-lock.js
@@ -51,6 +51,24 @@ function label(value, fallback) {
return typeof value === 'string' && /^[A-Za-z0-9_./:-]{1,100}$/u.test(value) ? value : fallback;
}
+/** Report journal conversion's total wait-plus-hold separately: SQLite exposes no acquisition boundary. */
+export function configureBoardJournal(db, context = {}) {
+ const start = performance.now();
+ let outcome = 'failed';
+ try {
+ db.exec('PRAGMA journal_mode = WAL');
+ outcome = 'completed';
+ } finally {
+ const durationMs = Math.max(0, Math.round(performance.now() - start));
+ if (durationMs > LONG_WRITE_MS) {
+ const line = { operation: 'journal_mode', timing: 'wait-plus-hold', command: label(context.command, 'api'),
+ seat: label(context.seat, 'unknown'), pid: process.pid, durationMs, outcome };
+ try { writeSync(2, 'pullboard: long board operation ' + JSON.stringify(line) + '\n'); }
+ catch { /* Optional diagnostics must preserve journal conversion's original result or refusal. */ }
+ }
+ }
+}
+
/** Resolve a registered seat from the caller's checkout, only after SQLite grants this write transaction. */
function contextFor(db, context) {
let seat = context.seat;
diff --git a/src/board.js b/src/board.js
index fbe77d26..8ca1c53b 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,6 +1,7 @@
import { migrateEventLogVersion } from './board-event-log-migrate.js';
import {
beginBoardWrite,
+ configureBoardJournal,
finishBoardWrite,
closeBoardWrites,
prepareBoardWriteIdentity,
@@ -357,20 +358,22 @@ export function openBoard(file, clock = systemClock, { isMain, onDiagnostic, wri
try {
db = new DatabaseSync(file);
db.exec(`PRAGMA busy_timeout = ${BOARD_BUSY_TIMEOUT_MS}`);
- if (file !== ':memory:' && isMain !== false) db.exec('PRAGMA journal_mode = WAL');
+ if (file !== ':memory:' && isMain !== false) configureBoardJournal(db, writeContext);
const board = { db, clock, writeContext };
let warmCounters = true;
if (isMain !== false || file === ':memory:') {
// Migrate and audit only a board whose version is behind; a drifted shape is reported and left alone (#1047).
const standing = boardStanding(db, SCHEMA_DIGEST, SCHEMA_VERSION, readEventLogVersion(db) < EVENT_LOG_VERSION);
- if (standing === 'behind') {
- migrateEventLogVersion(db, writeContext);
- migrate(db);
- ensureHotIndexes(db);
- db.prepare('INSERT OR IGNORE INTO board_meta (meta_key, meta_value) VALUES (?, ?)').run('board_id', randomBytes(16).toString('hex'));
- guardStore(board);
- }
- if (standing === 'behind' || standing === 'unstamped') recordSchemaStamp(db, SCHEMA_DIGEST);
+ if (standing === 'behind' || standing === 'unstamped') atomic(board, () => {
+ if (standing === 'behind') {
+ migrateEventLogVersion(db);
+ migrate(db);
+ ensureHotIndexes(db);
+ db.prepare('INSERT OR IGNORE INTO board_meta (meta_key, meta_value) VALUES (?, ?)').run('board_id', randomBytes(16).toString('hex'));
+ guardStore(board);
+ }
+ recordSchemaStamp(db, SCHEMA_DIGEST);
+ });
// Index-only upgrades keep the data version/digest unchanged. Install and restamp together;
// drifted or read-only stores never take this path, and old clients accept the resulting stamp.
if (standing !== 'drifted' && missingFactIdentityIndexes(db).length) atomic(board, () => {
diff --git a/src/exchange.js b/src/exchange.js
index 68a6dd2a..f8679e6f 100644
--- a/src/exchange.js
+++ b/src/exchange.js
@@ -2,6 +2,11 @@ import { beginCommandPhase } from './command-phase.js';
import { LANDING_LOCAL_PREFIX } from './landing-local-lease.js';
import { PROOF_COUNTER_PREFIX } from './proof-counters.js';
import { rebuildProofCounters } from './proof-counters.js';
+import {
+ beginBoardWrite,
+ finishBoardWrite,
+ prepareBoardWriteIdentity,
+} from './board-write-lock.js';
/**
* Export and import whole board files (A7), including their AUTOINCREMENT counters, so a copy can
* continue producing the same ids after its rows are restored.
@@ -225,7 +230,11 @@ function restoreDocument(board, document, replace = false, expectedNativeDigest
const db = board.db;
const names = tableNames(db);
validateDocument(db, document, names);
+ prepareBoardWriteIdentity();
db.exec('PRAGMA defer_foreign_keys = ON; BEGIN IMMEDIATE');
+ const writeRecord = beginBoardWrite(db, board.writeContext);
+ let released = false;
+ let outcome = 'release-failed';
try {
const localLanding = db.prepare('SELECT * FROM board_meta WHERE meta_key GLOB ?').all(LANDING_LOCAL_PREFIX + '*');
let localAgentCursors = null;
@@ -278,9 +287,15 @@ function restoreDocument(board, document, replace = false, expectedNativeDigest
rebuildProofCounters(board);
for (const { name, sql } of storeTriggers()) db.exec(sql);
db.exec('COMMIT');
+ released = true;
+ outcome = 'committed';
return { tables: names };
} catch (error) {
db.exec('ROLLBACK');
+ released = true;
+ outcome = 'rolled-back';
throw error;
+ } finally {
+ finishBoardWrite(writeRecord, released, outcome);
}
}
diff --git a/test/board-busy.test.js b/test/board-busy.test.js
index 58d4d058..d1c73c91 100644
--- a/test/board-busy.test.js
+++ b/test/board-busy.test.js
@@ -375,3 +375,155 @@ test('opening an older board names and logs its genuine index-building write [C7
assert.deepEqual(upgraded.prepare("SELECT name, sql FROM sqlite_master WHERE type='index' AND name LIKE 'event_fact_%_v2' ORDER BY name").all(), indexes);
} finally { upgraded.close(); }
});
+
+
+test('native import observes committed and rolled-back write ownership without changing restored rows [A7,C7,P4]', () => {
+ const box = e2e.project();
+ const document = snapshot(join(box.repo, '.git', 'pullboard', 'board.sqlite'));
+ const input = join(box.dir, 'native-import.json');
+ writeFileSync(input, JSON.stringify(document));
+ for (const rollback of [false, true]) {
+ const file = join(box.dir, `import-${rollback}.sqlite`);
+ const source = `
+ import assert from 'node:assert/strict';
+ import { readFileSync } from 'node:fs';
+ import { DatabaseSync } from 'node:sqlite';
+ import * as store from ${JSON.stringify(new URL('../src/board.js', import.meta.url).href)};
+ import { exportBoard, importBoard } from ${JSON.stringify(new URL('../src/exchange.js', import.meta.url).href)};
+ import { boardWriteHolderText } from ${JSON.stringify(new URL('../src/board-write-lock.js', import.meta.url).href)};
+ const file = process.argv[1];
+ const document = JSON.parse(readFileSync(process.argv[2], 'utf8'));
+ const board = store.openBoard(file, undefined, { writeContext: { command: 'private-import', seat: 'coordinator' } });
+ const before = exportBoard(board);
+ let held = false;
+ board.db.function('hold_private_import', () => {
+ if (held) return 1;
+ held = true;
+ const contender = new DatabaseSync(file);
+ try {
+ contender.exec('PRAGMA busy_timeout=0');
+ assert.throws(() => contender.exec('BEGIN IMMEDIATE'), error => (error.errcode & 255) === 5);
+ } finally { contender.close(); }
+ assert.match(boardWriteHolderText(file), /private-import/);
+ // budget: exercise the declared over-two-second diagnostic during a genuine native restore write.
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2_100);
+ if (${rollback}) throw new Error('private import rollback');
+ return 1;
+ });
+ board.db.exec('CREATE TEMP TRIGGER hold_private_import BEFORE INSERT ON main.item BEGIN SELECT hold_private_import(); END');
+ try {
+ if (${rollback}) {
+ assert.throws(() => importBoard(board, document), /private import rollback/);
+ assert.deepEqual(exportBoard(board), before);
+ } else {
+ importBoard(board, document);
+ assert.deepEqual(exportBoard(board), document);
+ }
+ assert.equal(held, true);
+ assert.equal(boardWriteHolderText(file), '');
+ process.stdout.write(JSON.stringify({ restored: !${rollback}, rolledBack: ${rollback} }));
+ } finally { store.closeBoard(board); }
+ `;
+ const result = runFixtureChild(process.execPath, ['--input-type=module', '-e', source, file, input], {
+ cwd: box.repo, env: box.env, encoding: 'utf8',
+ });
+ assert.equal(result.status, 0, result.context);
+ assert.deepEqual(JSON.parse(result.stdout), { restored: !rollback, rolledBack: rollback });
+ const records = longWrites(result.stderr);
+ assert.equal(records.length, 1);
+ assert.equal(records[0].command, 'private-import');
+ assert.equal(records[0].seat, 'coordinator');
+ assert.equal(records[0].outcome, rollback ? 'rolled-back' : 'committed');
+ assert.ok(records[0].durationMs > 2_000); // budget: declared #1197 diagnostic threshold.
+ }
+});
+
+test('journal conversion reports total wait-plus-hold separately and preserves its result [C7,P4]', () => {
+ const box = e2e.project();
+ const file = join(box.repo, '.git', 'pullboard', 'board.sqlite');
+ const before = snapshot(file);
+ const source = `
+ import assert from 'node:assert/strict';
+ import { DatabaseSync } from 'node:sqlite';
+ import { configureBoardJournal, boardWriteHolderText } from ${JSON.stringify(new URL('../src/board-write-lock.js', import.meta.url).href)};
+ const db = new DatabaseSync(process.argv[1]);
+ const original = db.exec;
+ const sentinel = new Error('private journal failure');
+ for (const fail of [false, true]) {
+ db.exec = function(sql) {
+ assert.equal(sql, 'PRAGMA journal_mode = WAL');
+ const result = original.call(this, sql);
+ assert.equal(boardWriteHolderText(process.argv[1]), '');
+ // budget: inject elapsed operation time, not a claimed SQLite held-lock duration.
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2_100);
+ if (fail) throw sentinel;
+ return result;
+ };
+ if (fail) assert.throws(() => configureBoardJournal(db, { command: 'private-journal', seat: 'coordinator' }), error => error === sentinel);
+ else assert.equal(configureBoardJournal(db, { command: 'private-journal', seat: 'coordinator' }), undefined);
+ }
+ db.close();
+ `;
+ const result = runFixtureChild(process.execPath, ['--input-type=module', '-e', source, file], {
+ cwd: box.repo, env: box.env, encoding: 'utf8',
+ });
+ assert.equal(result.status, 0, result.context);
+ assert.deepEqual(longWrites(result.stderr), []);
+ const prefix = 'pullboard: long board operation ';
+ const operations = result.stderr.split('\n').filter(line => line.startsWith(prefix))
+ .map(line => JSON.parse(line.slice(prefix.length)));
+ assert.equal(operations.length, 2);
+ assert.deepEqual(operations.map(row => row.outcome), ['completed', 'failed']);
+ for (const row of operations) {
+ assert.equal(row.operation, 'journal_mode');
+ assert.equal(row.timing, 'wait-plus-hold');
+ assert.equal(row.command, 'private-journal');
+ assert.equal(row.seat, 'coordinator');
+ assert.ok(row.durationMs > 2_000); // budget: declared #1197 operation diagnostic threshold.
+ }
+ assert.deepEqual(snapshot(file), before);
+});
+
+
+test('a failed owning migration rolls back schema, index and stamp work together [A5,A6,C7]', () => {
+ const box = e2e.project();
+ for (const name of ['bin', 'src', 'skills', 'package.json', 'CHANGELOG.md']) {
+ cpSync(resolve(import.meta.dirname, '..', name), join(box.repo, name), { recursive: true });
+ }
+ box.git(box.repo, 'add', 'bin', 'src', 'skills', 'package.json', 'CHANGELOG.md');
+ box.git(box.repo, 'commit', '-q', '-m', 'chore: install private rollback source [G1]');
+ const file = join(box.repo, '.git', 'pullboard', 'board.sqlite');
+ const before = snapshot(file);
+ const db = new DatabaseSync(file);
+ const version = db.prepare('PRAGMA user_version').get().user_version;
+ const indexes = db.prepare("SELECT name FROM sqlite_master WHERE type='index' AND name LIKE 'event_fact_%_v2'").all();
+ try {
+ assert.equal(indexes.length, 3);
+ for (const index of indexes) db.exec(`DROP INDEX "${index.name}"`);
+ db.exec(`PRAGMA user_version=${version - 1}; PRAGMA application_id=0`);
+ } finally { db.close(); }
+ const preload = join(box.dir, 'fail-private-index.mjs');
+ writeFileSync(preload, `
+ import { DatabaseSync } from 'node:sqlite';
+ const original = DatabaseSync.prototype.exec;
+ /** Fail only after genuine native index creation, while the outer migration still owns it. */
+ DatabaseSync.prototype.exec = function(sql, ...args) {
+ const result = original.call(this, sql, ...args);
+ if (sql.includes('CREATE INDEX IF NOT EXISTS event_fact_identity_v2')) throw new Error('private migration rollback');
+ return result;
+ };
+ `);
+ const result = runFixtureChild(process.execPath, ['--import', preload, join(box.repo, 'bin/pullboard.js'), 'shout', 'all', 'must roll back', '--json'], {
+ cwd: box.repo, env: box.env, encoding: 'utf8',
+ });
+ assert.equal(result.status, 1);
+ assert.match(result.stdout + result.stderr, /private migration rollback/);
+ assert.deepEqual(snapshot(file), before, 'native rows remain unchanged after failed schema work');
+ const unchanged = new DatabaseSync(file, { readOnly: true });
+ try {
+ assert.equal(unchanged.prepare('PRAGMA user_version').get().user_version, version - 1);
+ assert.equal(unchanged.prepare('PRAGMA application_id').get().application_id, 0);
+ assert.equal(unchanged.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type='index' AND name LIKE 'event_fact_%_v2'").get().n, 0);
+ } finally { unchanged.close(); }
+ assert.equal(boardWriteHolderText(file), '');
+});