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(relay): preserve checkpoint semantics [H5,H16,O3,S1]

Corey Olson811380de52f2
diff --git a/src/help.js b/src/help.js
index 045eb7a5..bc89f997 100644
--- a/src/help.js
+++ b/src/help.js
@@ -547,7 +547,7 @@ export const HELP = buildHelp();
/** Replace help placeholders with ordinary values so every command receives a usable example. */
function exampleFor(name, usage) {
if (HELP_EXAMPLES[name]) return HELP_EXAMPLES[name];
- return usage.split(/\s+\|\s+|\|/u, 1)[0]
+ return usage.split(/\s+\|\s+/u, 1)[0]
.replace(/\s+\[[^\]]+\]/gu, '')
.replace(/<lane>/gu, 'web')
.replace(/<title>/gu, '"Example"')
@@ -556,7 +556,8 @@ function exampleFor(name, usage) {
.replace(/<path>/gu, 'src/cli.js')
.replace(/<commit>/gu, '0123456')
.replace(/<principal>/gu, '[email protected]')
- .replace(/<[^>]+>/gu, 'value');
+ .replace(/<[^>]+>/gu, 'value')
+ .replace(/\|[^\s|]+/gu, '');
}
/** Read literal command words before an argument, flag or optional segment. */
diff --git a/src/relay-presentation.js b/src/relay-presentation.js
index ff81670d..aeb24c08 100644
--- a/src/relay-presentation.js
+++ b/src/relay-presentation.js
@@ -45,7 +45,9 @@ function readRelayPresentation(root, providedBoard, observedAt) {
const comparison = project(COMPARISON_CLOCK);
// exportBoard omits only derived proof counters and machine-local landing lease cache rows.
// Exact source bytes also retain expired/hidden business inputs that a fixed-clock view may omit.
- const inputs = { native: exportBoard(board), files: stateFileInputs(root, config).map(fileRevision),
+ // The comparison projects every person-visible block. Private agent recovery lines are not sealed inputs.
+ const files = stateFileInputs(root, config).filter(file => file.name !== 'blocks:blocks.jsonl').map(fileRevision);
+ const inputs = { native: exportBoard(board), files,
head: resolveCommit(root, 'HEAD'), trunk: trunkRevisionReader(info)(), config };
const changeFingerprint = createHash('sha256').update(JSON.stringify({ inputs, comparison })).digest('hex');
return { version: 1, state, config, shouts: store.allShouts(board), changeFingerprint };
diff --git a/test/relay-checkpoint-inputs.test.js b/test/relay-checkpoint-inputs.test.js
new file mode 100644
index 00000000..74ceb958
--- /dev/null
+++ b/test/relay-checkpoint-inputs.test.js
@@ -0,0 +1,45 @@
+/** Checkpoint invalidation follows sealed business inputs rather than private command recovery [H5,C6,H16]. */
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createE2eHelpers } from './e2e-helpers.js';
+import { repoInfo } from '../src/git.js';
+import { recordBlock } from '../src/blocks.js';
+import {
+ relayPresentation,
+ presentationDigest,
+} from '../src/relay-presentation.js';
+
+/** Supply real Git and SQLite state while freezing only the documented presentation observation argument. */
+function checkpointBox(t) {
+ const helpers = createE2eHelpers();
+ t.after(helpers.cleanup);
+ const box = helpers.project();
+ const observedAt = Date.now();
+ t.diagnostic('checkpoint input executor: ' + JSON.stringify({ node: process.versions.node, platform: process.platform, arch: process.arch }));
+ return { root: box.repo, commonDir: repoInfo(box.repo).commonDir, observedAt };
+}
+
+/** Write a synthetic local refusal through the public ledger API, without a board move or authentication claim. */
+function refusal(box, audience, code) {
+ recordBlock(box.commonDir, { at: new Date(box.observedAt).toISOString(), code, command: 'pullboard add',
+ by: 'coordinator', path: box.root, audience, reason: 'synthetic checkpoint input refusal', step: 'correct the synthetic request' });
+}
+
+test('checkpoint fingerprints ignore an agent-only refusal when complete sealed state is unchanged [H5,C6,H16]', t => {
+ const box = checkpointBox(t);
+ const before = relayPresentation(box.root, { observedAt: box.observedAt });
+ refusal(box, 'agent', 'UNKNOWN_SPEC');
+ const after = relayPresentation(box.root, { observedAt: box.observedAt });
+ assert.deepEqual(after.state, before.state, 'all emitted state fields remain exact, including presence, proof stats and observation time');
+ assert.equal(presentationDigest(after), presentationDigest(before), 'a private recovery ledger append alone needs no new sealed checkpoint');
+});
+
+test('checkpoint fingerprints retain a new person-visible refusal and its complete Needs you state [H5,C6,H16]', t => {
+ const box = checkpointBox(t);
+ const before = relayPresentation(box.root, { observedAt: box.observedAt });
+ refusal(box, 'person', 'HUMAN_REQUIRED');
+ const after = relayPresentation(box.root, { observedAt: box.observedAt });
+ assert.ok(after.state.blocks.some(block => block.code === 'HUMAN_REQUIRED' && block.reason === 'synthetic checkpoint input refusal'));
+ assert.notDeepEqual(after.state, before.state);
+ assert.notEqual(presentationDigest(after), presentationDigest(before), 'public recovery still invalidates the complete checkpoint');
+});
diff --git a/test/relay-snapshot-size.test.js b/test/relay-snapshot-size.test.js
index 2e3b4486..333e41de 100644
--- a/test/relay-snapshot-size.test.js
+++ b/test/relay-snapshot-size.test.js
@@ -198,8 +198,6 @@ test('a large board syncs to the relay compressed [H5,H15,H17]', {
throw error;
}
assert.equal(await chrome.evaluate("document.querySelector('#feed')?.textContent.includes(" + JSON.stringify(marker) + ') ?? false'), true, 'the production browser decoder reads the compressed checkpoint');
- const projection = { ...expected.presentation.state, root: sourceState.board };
- const projectionHash = createHash('sha256').update(JSON.stringify(projection)).digest('hex');
const tablesHash = createHash('sha256').update(JSON.stringify(expected.tables)).digest('hex');
const browserRead = await chrome.evaluate(`(async () => {
const { createTransport } = await import('/relay/client.js');
@@ -219,9 +217,17 @@ test('a large board syncs to the relay compressed [H5,H15,H17]', {
const bytes = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(value))));
return [...bytes].map(value => value.toString(16).padStart(2, '0')).join('');
}
- return { projectionHash: await digest(document.state), tablesHash: await digest(native.tables) };
+ return { projectionHash: await digest(document.state), tablesHash: await digest(native.tables),
+ observedAt: native.presentation.state.observedAt, displayedObservedAt: document.state.observedAt };
})()`, 'hash browser projection and native snapshot');
- assert.deepEqual(browserRead, { projectionHash, tablesHash }, 'the production browser client reads the exact projection and browser gzip retains every native table byte');
+ const { observedAt, displayedObservedAt, ...browserHashes } = browserRead;
+ assert.equal(displayedObservedAt, observedAt, 'the browser retains the authenticated checkpoint observation');
+ const clock = Date.parse(observedAt);
+ assert.ok(Number.isSafeInteger(clock), 'the native checkpoint carries its explicit observation clock');
+ // Compare complete production readers at the SAME documented observation, not two wall-clock instants.
+ const projection = { ...relaySnapshot(box.root, { observedAt: clock }).presentation.state, root: sourceState.board };
+ const projectionHash = createHash('sha256').update(JSON.stringify(projection)).digest('hex');
+ assert.deepEqual(browserHashes, { projectionHash, tablesHash }, 'the production browser client reads the exact projection and browser gzip retains every native table byte');
// An older relay that does not advertise paged snapshots keeps its explicit per-request refusal.
box.legacySnapshotApi();
diff --git a/test/spec.test.js b/test/spec.test.js
index d5c615c2..11d14f8b 100644
--- a/test/spec.test.js
+++ b/test/spec.test.js
@@ -6,6 +6,8 @@ import * as store from '../src/board.js';
import { applyEngineMove, prepareEngineMove } from '../src/engine.js';
import { exportBoard, importBoard } from '../src/exchange.js';
import { SPEC_VERDICT_ENGINE } from '../src/spec-verdict-engine.js';
+import { ENGINE_VERSION } from '../src/machine.js';
+import { minimumMoveEngine } from '../src/move-registry.js';
import { runFixtureExecFile as execFileSync, runFixtureChild as spawnSync, runFixtureChild, runFixtureGit } from './fixture-child.js';
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
@@ -1246,7 +1248,8 @@ test('an exact row verifier receipt replays once with its engine floor and nativ
gate: 'review', tier: 'must', section: 'G · Goals' } });
const move = prepareEngineMove(board, 'recordRowVerification', [{ agentId: verifier,
source: '- G1 [draft, must] An exact requirement. | gate: review', decision: 'accepted', reason: 'Reviewed exactly.' }]);
- assert.equal(move.engine, SPEC_VERDICT_ENGINE);
+ assert.equal(move.engine, ENGINE_VERSION, 'the native writer stamps its current version');
+ assert.equal(minimumMoveEngine(move.operation, move.args, board), SPEC_VERDICT_ENGINE, 'the historical reader floor remains fixed');
const options = { sequence: 1, at: new Date().toISOString() };
const before = store.events(board).length;
assert.throws(() => applyEngineMove(board, { ...move, engine: SPEC_VERDICT_ENGINE - 1 }, options), { code: 'RELAY_MOVE' });