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.

refactor(core): bound landing fallback and lock helpers [Q1,C7]

Corey Olsona6d4185a0a2d
diff --git a/src/board-busy.js b/src/board-busy.js
new file mode 100644
index 00000000..1bddaf21
--- /dev/null
+++ b/src/board-busy.js
@@ -0,0 +1,17 @@
+/** Translate SQLite lock contention without coupling error reporting to the full board store [C7]. */
+import { Refused } from './refused.js';
+
+/**
+ * Replace SQLite's bare lock error with the board path and elapsed wait when the wait expires.
+ *
+ * @param {string} file
+ * @param {number} startedAt
+ * @param {Error & { errcode?: number }} error
+ * @returns {Error}
+ */
+export function boardBusyError(file, startedAt, error) {
+ const sqliteCode = Number.isInteger(error.errcode) ? error.errcode & 0xff : null;
+ if (sqliteCode !== 5 && error.code !== 'SQLITE_BUSY' && !/database is locked/iu.test(error.message ?? '')) return error;
+ return new Refused('BOARD_BUSY', `board file ${file} remained held by another process after ${Date.now() - startedAt}ms; wait for it to finish and retry`);
+}
+
diff --git a/src/board.js b/src/board.js
index 2e2aa4d7..5b79e1dd 100644
--- a/src/board.js
+++ b/src/board.js
@@ -15,6 +15,8 @@ import {
export { verdictReviewProblem, verdictsFor, acceptedVerdict, checkedLandingCommit };
export { landingLeaseMove, landingLeaseState } from './landing-lease.js';
import { guardLandingWrite } from './landing-lease.js';
+import { boardBusyError } from './board-busy.js';
+export { boardBusyError };
import {
randomBytes,
randomUUID,
@@ -142,19 +144,6 @@ export const EVENT_LOG_VERSION = 1;
/** Maximum time a board connection waits for another process to release SQLite's lock. */
export const BOARD_BUSY_TIMEOUT_MS = 10_000;
-/**
- * Replace SQLite's bare lock error with the board path and elapsed wait when the wait expires.
- *
- * @param {string} file
- * @param {number} startedAt
- * @param {Error & { errcode?: number }} error
- * @returns {Error}
- */
-export function boardBusyError(file, startedAt, error) {
- const sqliteCode = Number.isInteger(error.errcode) ? error.errcode & 0xff : null;
- if (sqliteCode !== 5 && error.code !== 'SQLITE_BUSY' && !/database is locked/iu.test(error.message ?? '')) return error;
- return new Refused('BOARD_BUSY', `board file ${file} remained held by another process after ${Date.now() - startedAt}ms; wait for it to finish and retry`);
-}
const BRIEF_LIMIT = 8000;
const REVIEW_RELEASE_COOLDOWN_MS = 60 * 60 * 1000;
diff --git a/src/landing-relay.js b/src/landing-relay.js
new file mode 100644
index 00000000..583b48eb
--- /dev/null
+++ b/src/landing-relay.js
@@ -0,0 +1,20 @@
+/** Keep physical landing authority out of optimistic local or queued relay fallbacks [Q1,H16]. */
+import { Refused } from './refused.js';
+
+/** Preserve ordinary move fallbacks while requiring acknowledged order for fenced landing work. */
+export function landingRelayCallbacks(operation, args, { apply, queue }) {
+ const authority = operation === 'landingLeaseMove' || args?.[0]?.landingFence !== undefined;
+ /** A local preview is never a grant to start physical landing work. */
+ const applyConfirmed = () => {
+ if (authority) throw new Refused('LAND_RELAY_REQUIRED', 'a linked landing lease needs an acknowledged relay order; restore the relay connection before landing');
+ return apply();
+ };
+ return {
+ apply: applyConfirmed,
+ /** Landing authority cannot be manufactured by queuing an unacknowledged move. */
+ queue(error, move) {
+ if (authority) throw error;
+ return queue(error, move, applyConfirmed);
+ },
+ };
+}
diff --git a/src/relay.js b/src/relay.js
index 66f04dd8..b1c1a9bb 100644
--- a/src/relay.js
+++ b/src/relay.js
@@ -110,6 +110,7 @@ import {
} from './relay-outbox.js';
import { stampCoordinatorHolder } from './coordinator-hold.js';
import { Refused } from './refused.js';
+import { landingRelayCallbacks } from './landing-relay.js';
import { refusalFromReceipt } from './recorded-refusal.js';
import { relayNotices } from './relay-notices.js';
import {
@@ -1148,14 +1149,13 @@ function outboxLink(root, file, state, io) {
/** Send one board operation before executing it locally, and report its canonical engine result. */
export async function relayOperation(root, operation, args, io, command, applyLocally) {
const file = linkFile(root);
- const landingAuthority = operation === 'landingLeaseMove' || args?.[0]?.landingFence !== undefined;
return locked(file, async () => {
const state = loadLink(file);
- /** Apply through the CLI's existing board handle so local events and guards remain unchanged. */
- const applyPausedMoveLocally = () => {
- if (landingAuthority) throw new Refused('LAND_RELAY_REQUIRED', 'a linked landing lease needs an acknowledged relay order; restore the relay connection before landing');
- return typeof applyLocally === 'function' ? applyLocally() : localRecords(root, (board) => store[operation](board, ...args));
- };
+ const guarded = landingRelayCallbacks(operation, args, {
+ apply: () => typeof applyLocally === 'function' ? applyLocally() : localRecords(root, (board) => store[operation](board, ...args)),
+ queue: (error, move, apply) => queueMove(outboxLink(root, file, state, io), { operation, args, command, move, error, applyLocally: apply }),
+ });
+ const applyPausedMoveLocally = guarded.apply;
if (!state && deletedRecovery(root)) return deletedMoveResult(root, operation, args, command, io, applyPausedMoveLocally);
if (!state || state.unlinking) throw new Refused('RELAY_UNLINK_PENDING', 'finish unlinking this device with pullboard relay off before sending a move');
if (state.recovery) throw new Refused('RELAY_RECOVERY_PENDING', `finish the saved recovery for sequence ${state.recovery.skip} before sending a linked move`);
@@ -1168,10 +1168,7 @@ export async function relayOperation(root, operation, args, io, command, applyLo
moves.add(state.board);
try {
let ordered;
- const queue = (error, move) => {
- if (landingAuthority) throw error;
- return queueMove(outboxLink(root, file, state, io), { operation, args, command, move, error, applyLocally: applyPausedMoveLocally });
- };
+ const queue = guarded.queue;
try { ordered = await ensureOrdered(root, file, state, io); }
catch (error) {
if (outboxQueueable(state, error, operation, io)) return await queue(error);
diff --git a/test/landing-lease.test.js b/test/landing-lease.test.js
index f67f77fd..fe97479c 100644
--- a/test/landing-lease.test.js
+++ b/test/landing-lease.test.js
@@ -9,6 +9,7 @@ import * as store from '../src/board.js';
import { assertLandingLease, guardLandingWrite, LANDING_LEASE_MS } from '../src/landing-lease.js';
import { applyEngineMove, prepareEngineMove } from '../src/engine.js';
import { exportBoard, importBoard } from '../src/exchange.js';
+import { landingRelayCallbacks } from '../src/landing-relay.js';
/** Create isolated physical databases sharing an initial board and a controllable receipt clock. */
function fixture(t) {
@@ -86,3 +87,20 @@ test('ordered landing admission replays identically and a takeover fences the ol
assert.equal(move('landingLeaseMove', oldFence).error.code, 'COORDINATOR_HELD');
assert.throws(() => assertLandingLease(box.boards[0], oldFence), error => error.code === 'LAND_LEASE_LOST');
});
+
+
+test('fenced landing moves never take a local or queued relay fallback [Q1,H16]', () => {
+ let applied = 0; let queued = 0;
+ const cause = new Error('private relay unavailable');
+ const callbacks = { apply() { applied++; return 'local'; }, queue(error, move, apply) { queued++; assert.equal(error, cause); assert.equal(move, 'sealed'); return apply(); } };
+ for (const [operation, args] of [['landingLeaseMove', [{}]], ['recordLandingBatch', [{ landingFence: { generation: 1 } }]], ['finishLandingBatch', [{ landingFence: { generation: 1 } }]]]) {
+ const guarded = landingRelayCallbacks(operation, args, callbacks);
+ assert.throws(guarded.apply, error => error.code === 'LAND_RELAY_REQUIRED');
+ assert.throws(() => guarded.queue(cause, 'sealed'), error => error === cause);
+ }
+ assert.equal(applied, 0); assert.equal(queued, 0);
+ const ordinary = landingRelayCallbacks('shout', [{}], callbacks);
+ assert.equal(ordinary.apply(), 'local');
+ assert.equal(ordinary.queue(cause, 'sealed'), 'local');
+ assert.equal(applied, 2); assert.equal(queued, 1);
+});