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(api): share stable report validators with local clients [A2,R1,R2]

Corey Olsondf5dbdbf1271
diff --git a/src/api-http.js b/src/api-http.js
index 8983ecc9..127aad29 100644
--- a/src/api-http.js
+++ b/src/api-http.js
@@ -36,8 +36,9 @@ function stateText(state, eventLogVersion) {
* no-store: the browser never answers a poll from its cache, so a page that wants the newest clock
* readings still gets them by not asking If-None-Match.
*/
-function sendState(req, res, text, tagged, validator = text) {
+function sendState(req, res, text, tagged, validator = text, reportValidator) {
const headers = { 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff' };
+ if (typeof reportValidator === 'string' && /^[a-f0-9]{64}:[0-9]+$/u.test(reportValidator)) headers['x-pullboard-report-validator'] = reportValidator;
if (tagged) {
const board = validator.replace(/"(asOf|ageMinutes)":(?:"[^"]*"|[-+.0-9eE]+|null)/gu, '"$1":null');
Object.assign(headers, { etag: '"' + createHash('sha256').update(board).digest('base64url').slice(0, 32) + '"' });
@@ -321,7 +322,7 @@ export function createApiHandler(adapter, { pollMs = 200, tagState = false } = {
if (options.detail === 'full') throw new Refused('BAD_REQUEST', 'a delta brings item summaries up to date; use since=N without detail=full');
if (typeof adapter.delta !== 'function') throw new Refused('DELTA_NOT_AVAILABLE', 'this API adapter does not answer since=N; use its board state');
const delta = await adapter.delta(board, who, seen, { since, eventLogVersion: url.searchParams.get('eventLogVersion') });
- return sendState(req, res, JSON.stringify({ version: 1, ...delta }), tagState);
+ return sendState(req, res, JSON.stringify({ version: 1, ...delta }), tagState, undefined, delta.reportValidator);
}
if (typeof adapter.stateJson === 'function') {
const encoded = await adapter.stateJson(board, who, seen, options);
@@ -329,7 +330,7 @@ export function createApiHandler(adapter, { pollMs = 200, tagState = false } = {
if (typeof state !== 'string' || encoded?.validator !== undefined && typeof encoded.validator !== 'string') throw new TypeError('the local state serializer must return JSON text and optional internal validator text');
const eventLogVersion = await adapter.eventLogVersion?.(board, who);
return sendState(req, res, stateText(state, eventLogVersion), tagState,
- typeof encoded?.validator === 'string' ? stateText(encoded.validator, eventLogVersion) : undefined);
+ typeof encoded?.validator === 'string' ? stateText(encoded.validator, eventLogVersion) : undefined, encoded?.reportValidator);
}
const state = await adapter.state(board, who, seen, options);
const eventLogVersion = await adapter.eventLogVersion?.(board, who);
diff --git a/src/api.js b/src/api.js
index 0a7e4947..f64867ac 100644
--- a/src/api.js
+++ b/src/api.js
@@ -553,6 +553,7 @@ function snapshotEntry(revision, state, preparedFlow, { inputs = null, itemMeta
const summary = { ...state, items: state.items.map(itemSummary) };
const reportValidator = { json: JSON.stringify(state.proofStats?.flow?.report), expiries: [...new Set(preparedFlow.items.flatMap(item =>
item.state === 'claimed' ? [item.leaseUntil] : item.state === 'submitted' ? [item.reserve?.until] : []).filter(Number.isFinite))].sort((a, b) => a - b) };
+ reportValidator.digest = createHash('sha256').update(reportValidator.json ?? 'null').digest('hex');
return { revision, sequence: state.sequence, state, summary, preparedFlow, reportValidator, summaryFields: prepareStateJson(summary), stateJsonFields: null,
print: fingerprint(summary), items: new Map(state.items.map((item) => [item.id, item])), itemMeta, itemMoveCounts, inputs, searchTexts: null };
}
@@ -657,6 +658,14 @@ function jsonField(key, value) {
return encoded === undefined ? '' : JSON.stringify(key) + ':' + encoded;
}
+/** Reuse recorded report material while retaining genuine native lease-boundary changes. */
+function reportValidation(entry, now = Date.now()) {
+ const expiries = entry.reportValidator.expiries;
+ let low = 0, high = expiries.length;
+ while (low < high) { const middle = (low + high) >>> 1; if (expiries[middle] <= now) low = middle + 1; else high = middle; }
+ return entry.reportValidator.digest + ':' + low;
+}
+
/** Reuse static state fragments while encoding request-specific unread and flow data. */
function serializeState(state, fields, reportJson) {
if (!fields) return JSON.stringify(state);
@@ -996,13 +1005,9 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =
const state = stateForRequest(full ? entry.state : entry.summary, board.root, seen, entry.preparedFlow, cached, codeIsMain);
// Full fragments wait for the first full request, so a server sending summaries never builds them.
const fields = full ? (entry.stateJsonFields ??= prepareStateJson(entry.state)) : entry.summaryFields;
- const expiries = entry.reportValidator.expiries;
- let low = 0, high = expiries.length;
- const now = Date.now();
- while (low < high) { const middle = (low + high) >>> 1; if (expiries[middle] <= now) low = middle + 1; else high = middle; }
- // A snapshot's recorded report stays validator-stable; real lease boundaries remain observable.
- const validator = serializeState(state, fields, entry.reportValidator.json) + '\0report-expiry:' + low;
- return { state, json: serializeState(state, fields), validator, entry };
+ const reportValidator = reportValidation(entry);
+ const validator = serializeState(state, fields, entry.reportValidator.json) + '\0report-expiry:' + reportValidator;
+ return { state, json: serializeState(state, fields), validator, reportValidator, entry };
});
// Only the build actually returned is sent; a delta extends summaries, never a full state.
if (!full) keepSentBase(sent.entry);
@@ -1032,7 +1037,7 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =
};
const sent = withSnapshot(board, (entry, cached) => ({ entry, answer: answerFor(entry, cached) }));
if (sent.answer.delta) keepSentBase(sent.entry);
- return sent.answer;
+ return Object.defineProperty(sent.answer, 'reportValidator', { value: reportValidation(sent.entry) });
}
/**
* The spec-approval view one board's details share, kept while the files, HEAD and board records it
@@ -1151,7 +1156,7 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =
state: (board, who, seen, options) => withGitReadFacts(() => localState(board, seen, options).state),
stateJson: (board, who, seen, options) => withGitReadFacts(() => {
const sent = localState(board, seen, options);
- return { json: sent.json, validator: sent.validator };
+ return { json: sent.json, validator: sent.validator, reportValidator: sent.reportValidator };
}),
watchRevision: (board) => {
const watcher = withGitReadFacts(() => watchLocalStateRevision(board, { scopeCommonDir }));
diff --git a/test/flow-report-api.test.js b/test/flow-report-api.test.js
index 22b97b36..4599750f 100644
--- a/test/flow-report-api.test.js
+++ b/test/flow-report-api.test.js
@@ -49,18 +49,28 @@ test('flow report polls ignore only observation increments and retain claim and
event(board, review, 'submit', { commit }, now - 500);
event(board, review, 'reserve', { until: new Date(until + 2500).toISOString() }, now);
const first = await apiFetch(api, path), initial = await first.json();
- const tag = first.headers.get('etag');
+ const tag = first.headers.get('etag'), token = first.headers.get('x-pullboard-report-validator');
+ assert.match(token, /^[a-f0-9]{64}:[0-9]+$/u);
+ assert.equal(Object.hasOwn(initial, 'reportValidator'), false, 'transport metadata does not change public JSON');
await delay(30);
const current = await (await apiFetch(api, path)).json();
assert.notDeepEqual(current.state.proofStats.flow.report, initial.state.proofStats.flow.report, 'public durations continue advancing');
+ const deltaPath = path + '?since=' + initial.state.sequence;
+ const stableDelta = await apiFetch(api, deltaPath);
+ assert.equal(stableDelta.headers.get('x-pullboard-report-validator'), token, 'delta and full reads share stable report material');
+ assert.ok((await stableDelta.json()).delta);
assert.equal((await apiFetch(api, path, { headers: { 'if-none-match': tag } })).status, 304);
await delay(Math.max(0, until - Date.now() + 30));
const expiredClaim = await apiFetch(api, path, { headers: { 'if-none-match': tag } });
assert.equal(expiredClaim.status, 200, 'a real claim boundary invalidates the report validator');
- const claimTag = expiredClaim.headers.get('etag');
+ const claimTag = expiredClaim.headers.get('etag'), claimToken = expiredClaim.headers.get('x-pullboard-report-validator');
+ assert.notEqual(claimToken, token);
+ assert.equal((await apiFetch(api, deltaPath)).headers.get('x-pullboard-report-validator'), claimToken);
await expiredClaim.json();
await delay(Math.max(0, until + 2500 - Date.now() + 30));
- assert.equal((await apiFetch(api, path, { headers: { 'if-none-match': claimTag } })).status, 200, 'a real reservation boundary invalidates it again');
+ const expiredReview = await apiFetch(api, path, { headers: { 'if-none-match': claimTag } });
+ assert.equal(expiredReview.status, 200, 'a real reservation boundary invalidates it again');
+ assert.notEqual(expiredReview.headers.get('x-pullboard-report-validator'), claimToken);
});
test('completed flow durations and captured submission sizes remain validator material [A2,R1,R2]', async t => {
@@ -69,13 +79,17 @@ test('completed flow durations and captured submission sizes remain validator ma
const now = Date.now(), commit = 'b'.repeat(40);
event(board, id, 'claim', { leaseUntil: new Date(now + 120_000).toISOString() }, now);
const before = await apiFetch(api, path);
- const oldTag = before.headers.get('etag');
- await before.json();
+ const oldTag = before.headers.get('etag'), oldToken = before.headers.get('x-pullboard-report-validator');
+ const oldState = await before.json();
event(board, id, 'submit', { commit, submissionSize: { base: 'c'.repeat(40), head: commit, lines: 150, method: 'added-plus-deleted-no-renames' } }, now + 60_000);
event(board, id, 'reserve', { until: new Date(now + 120_000).toISOString() }, now + 60_000);
event(board, id, 'accept', { commit }, now + 60_001);
const changed = await apiFetch(api, path, { headers: { 'if-none-match': oldTag } });
assert.equal(changed.status, 200);
+ assert.notEqual(changed.headers.get('x-pullboard-report-validator'), oldToken);
+ const changedDelta = await apiFetch(api, path + '?since=' + oldState.state.sequence);
+ assert.equal(changedDelta.headers.get('x-pullboard-report-validator'), changed.headers.get('x-pullboard-report-validator'));
+ assert.equal(Object.hasOwn(await changedDelta.json(), 'reportValidator'), false);
const report = (await changed.json()).state.proofStats.flow.report;
assert.equal(report.overall.sizeBuckets['100to300'].accepted, 1);
assert.equal(report.items.find(item => item.id === id).stages.build.minutes, 1);