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 paged sync across runtimes [H15,H17,E16]

Corey Olsonc35d79c082e2
diff --git a/relay/browser-client.js b/relay/browser-client.js
index 358de36e..e407e199 100644
--- a/relay/browser-client.js
+++ b/relay/browser-client.js
@@ -122,6 +122,22 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
if (pair && (!BOARD.test(pair.board ?? '') || typeof pair.key !== 'string')) pair = null;
try { if (pair) decodeBoardKey(pair.key); } catch { pair = null; }
+ /** Preserve shared collections across updates: the cockpit shallow-copies state and revocation must clear those arrays too. */
+ function installState(entry, value) {
+ if (!entry.state) { entry.state = value; return; }
+ for (const [field, previous] of Object.entries(entry.state)) {
+ if (Array.isArray(previous) && previous !== value[field]) {
+ previous.length = 0;
+ if (Array.isArray(value[field])) {
+ for (const row of value[field]) previous.push(row);
+ Object.defineProperty(value, field, { ...Object.getOwnPropertyDescriptor(value, field), value: previous });
+ }
+ }
+ if (!Object.hasOwn(value, field)) delete entry.state[field];
+ }
+ Object.defineProperties(entry.state, Object.getOwnPropertyDescriptors(value));
+ }
+
/** Discard decrypted memory and this document when relay authorization is lost. */
async function denied(error) {
if (accessLost) return;
@@ -232,7 +248,7 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
install(full, details) {
const state = presentationState(full, entry.id);
if (details) state.items = state.items.map(item => details.get(item.id) ?? item);
- entry.state = { ...state, historyProgress: entry.history.status() };
+ installState(entry, { ...state, historyProgress: entry.history.status() });
entry.historyChanged = true;
},
changed() {
@@ -283,7 +299,7 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
if (row.sequence >= entry.cursor && !unchanged) {
const value = await page.presentation();
if (accessLost) throw accessError;
- entry.state = presentationState(value, entry.id);
+ installState(entry, presentationState(value, entry.id));
entry.shouts = null; entry.cursor = row.sequence;
}
entry.pages = page;
@@ -300,7 +316,7 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
entry.snapshotTag = response.headers.get('etag');
if (row.sequence >= entry.cursor) {
entry.history?.close(); entry.history = null; entry.pages = null; entry.pageCache?.clear();
- entry.state = state;
+ installState(entry, state);
entry.shouts = Array.isArray(value.presentation?.shouts) ? value.presentation.shouts : null;
entry.cursor = row.sequence;
}
@@ -349,7 +365,7 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
if (move.engine !== ENGINE_VERSION) throw new Refused('RELAY_ENGINE_VERSION', 'This board needs engine ' + move.engine + '; this browser reads engine ' + ENGINE_VERSION + '. Upgrade the browser client.');
if (move.presentation) {
entry.history?.close(); entry.history = null; entry.pages = null; entry.pageCache?.clear();
- entry.state = presentationState(move.presentation, entry.id);
+ installState(entry, presentationState(move.presentation, entry.id));
entry.shouts = Array.isArray(move.presentation.shouts) ? move.presentation.shouts : null;
entry.cursor = row.event_id;
} else {
diff --git a/src/relay-page-cache.js b/src/relay-page-cache.js
index 0c2e5cec..cd608b30 100644
--- a/src/relay-page-cache.js
+++ b/src/relay-page-cache.js
@@ -133,7 +133,9 @@ export function createRelayPageCache(state) {
/** Stream only objects not yet acknowledged by this relay, without an aggregate request body. */
function* pending(source) {
- for (const row of db.prepare('SELECT object.id FROM object JOIN job_object USING(id) WHERE source=? AND ack=0 ORDER BY object.rowid').iterate(source)) yield object(row.id);
+ // Node 22.13 may finalize an unreferenced statement while its iterator is suspended across a yield.
+ const statement = db.prepare('SELECT object.id FROM object JOIN job_object USING(id) WHERE source=? AND ack=0 ORDER BY object.rowid');
+ for (const row of statement.iterate(source)) yield object(row.id);
}
/** A lost ACK safely retries the same immutable object; only an actual ACK marks it done. */
diff --git a/src/relay-page-client.js b/src/relay-page-client.js
index 0cab371d..70d072f4 100644
--- a/src/relay-page-client.js
+++ b/src/relay-page-client.js
@@ -41,28 +41,32 @@ export async function pagedSnapshotRequest(state, options, { request, key, decod
if (saved.apiVersion !== 2 || !/^[A-Za-z0-9-]{1,128}$/u.test(saved.read?.id ?? '')) throw invalid();
const root = pageReference(saved.root);
if (root.sequence !== saved.sequence) throw invalid();
- const context = {
- key, boardId: state.board, sequence: saved.sequence,
- /** The server checks this path against the principal's pinned root on every request. */
- async get(id, parents) {
- const result = await request(path + '/objects/' + id + '?pin=' + encodeURIComponent(saved.read.id) + '&via=' + parents.join(','));
- if (result.apiVersion !== 2 || result.page?.id !== id) throw invalid();
- return bytes(result.page.sealed);
- },
- };
- const page = await openPagedSnapshot(root, context, { maxEngine });
- const native = await page.native();
- // Local resealing adapts existing restore callers, not the wire protocol. The authenticated root, cursor and
- // sender remain in the response; no locally generated bytes are reported as a server ciphertext ACK.
- let sealed = await encode(native, saved.sequence);
const cache = createRelayPageCache(state);
try {
+ const context = {
+ key, boardId: state.board, sequence: saved.sequence,
+ /** The server checks this path against the principal's pinned root on every request. */
+ async get(id, parents) {
+ const result = await request(path + '/objects/' + id + '?pin=' + encodeURIComponent(saved.read.id) + '&via=' + parents.join(','));
+ if (result.apiVersion !== 2 || result.page?.id !== id) throw invalid();
+ return bytes(result.page.sealed);
+ },
+ /** A successful pinned read proves remote custody; private reuse metadata is recorded only after authentication. */
+ rememberRead(object, fingerprint, reference) {
+ cache.put(object); cache.remember(fingerprint, reference); cache.acknowledge(object.id);
+ },
+ };
+ const page = await openPagedSnapshot(root, context, { maxEngine });
+ const native = await page.native();
+ // Local resealing adapts existing restore callers, not the wire protocol. The authenticated root, cursor and
+ // sender remain in the response; no locally generated bytes are reported as a server ciphertext ACK.
+ let sealed = await encode(native, saved.sequence);
for (const pending of [state.snapshot, state.checkpoint]) if (pending?.sequence === saved.sequence && typeof pending.sealed === 'string') {
const prepared = cache.job(snapshotSourceId(pending.sealed));
if (prepared?.reference.id === root.id) { sealed = pending.sealed; break; }
}
+ return { ...document, state: { ...saved, sealed } };
} finally { cache.close(); }
- return { ...document, state: { ...saved, sealed } };
}
if (options.method !== 'PUT' || !Number.isSafeInteger(options.body?.sequence) || typeof options.body.sealed !== 'string') throw invalid();
const pending = options.body;
diff --git a/src/sealed-pages.js b/src/sealed-pages.js
index 9baf93d0..907cf8e4 100644
--- a/src/sealed-pages.js
+++ b/src/sealed-pages.js
@@ -141,16 +141,23 @@ async function readPage(reference, context, parents = []) {
const kind = plain[PREFIX.byteLength];
const body = plain.subarray(PREFIX.byteLength + 1);
const fingerprint = await pageDigest(plain);
+ /** Retain only an authenticated cipher and its checked edges in an optional private device cache. */
+ async function remembered(result, links = []) {
+ await context.rememberRead?.({ id: reference.id, sequence: reference.sequence, bytes: received,
+ children: links.map(child => child.id) }, fingerprint, reference);
+ return result;
+ }
if (kind === 1) {
if (body.byteLength !== reference.bytes) throw invalid();
- return { body, fingerprint };
+ return remembered({ body, fingerprint });
}
if (kind === 2) {
if (body.byteLength !== reference.bytes) throw invalid();
let descriptor;
try { descriptor = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body)); } catch { throw invalid(); }
if (!descriptor || !Object.hasOwn(descriptor, 'value') || !Array.isArray(descriptor.links) || descriptor.links.length > PAGE_FANOUT) throw invalid();
- return { descriptor: { value: descriptor.value, links: descriptor.links.map(pageReference) }, fingerprint };
+ const links = descriptor.links.map(pageReference);
+ return remembered({ descriptor: { value: descriptor.value, links }, fingerprint }, links);
}
if (kind !== 0) throw invalid();
let children;
@@ -159,7 +166,7 @@ async function readPage(reference, context, parents = []) {
children = children.map(pageReference);
const length = children.reduce((sum, child) => sum + child.bytes, 0);
if (!Number.isSafeInteger(length) || length !== reference.bytes) throw invalid();
- return { children, fingerprint };
+ return remembered({ children, fingerprint }, children);
}
/** Authenticate a private cache hit before trusting its plaintext fingerprint; never upload the result. */
diff --git a/test/relay-browser.test.js b/test/relay-browser.test.js
index 9426704c..69b5562e 100644
--- a/test/relay-browser.test.js
+++ b/test/relay-browser.test.js
@@ -11,6 +11,7 @@ import { snapshotState, presentationState } from '../relay/browser-model.js';
import { decodeBoardKey, seal, unseal } from '../src/seal.js';
import { relaySnapshot } from '../src/relay-presentation.js';
import { ENGINE_VERSION } from '../src/machine.js';
+import { openPagedSnapshot } from '../src/relay-page-layout.js';
import { addItem, answerDecision, closeBoard, openBoard, shout } from '../src/board.js';
import { relayClientFixture } from './relay-client-fixture.js';
import { findChromeExecutable, relayWorkBudgetMs, startChrome } from './relay-browser-fixture.js';
@@ -113,6 +114,7 @@ test('older native snapshots project into read-only API state and reject wrong b
test('conditional sealed snapshots reauthorize before 304 and refresh spec-only presentation [H5,H15]', async t => {
const box = await relayClientFixture(t);
+ box.legacySnapshotApi(); // This case asserts the historical single-cipher ETag contract.
await box.link();
const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));
const endpoint = box.origin + '/api/v1/boards/' + link.board + '/state';
@@ -422,6 +424,7 @@ test('real Chrome waits for and installs the late snapshot that compacts a legac
skip: !findChromeExecutable() && 'Chrome is not installed',
}, async t => {
const box = await relayClientFixture(t);
+ box.legacySnapshotApi(); // The stand-in deliberately publishes a historical API1 checkpoint below.
const initialTitle = 'LATE_SNAPSHOT_INITIAL_108';
const finalTitle = 'LATE_SNAPSHOT_REPAIRED_108';
assert.equal((await box.cli('add', box.lane, initialTitle)).code, 0);
@@ -679,6 +682,7 @@ test('a signed-in phone waits for its first listing before prescribing a command
/** A pre-ordered mirror's durable local outbox keeps its final browser projection recoverable. */
test('legacy queued presentations never disclose later unacknowledged moves [H5,H15]', async t => {
const box = await relayClientFixture(t);
+ box.legacySnapshotApi(); // Its refused write and queued-link metadata belong to the legacy protocol.
await box.link();
const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));
// Recreate the historical pre-161 link metadata, then commit two local-first rows directly.
@@ -784,7 +788,7 @@ test('a revoked device read is refused as revoked [H5,E16]', {
const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));
const session = await box.phoneSession();
const headers = { cookie: 'pb_session=' + session.token, 'x-pullboard-engine': String(ENGINE_VERSION) };
- const endpoint = box.origin + '/api/v1/boards/' + link.board + '/state';
+ const endpoint = box.origin + '/api/v2/boards/' + link.board + '/state';
assert.equal((await fetch(endpoint, { headers })).status, 200, 'the genuine enrolled browser can read before revocation');
await revokeBrowser(box, chrome, device);
await box.restartRelay();
@@ -828,6 +832,9 @@ test('revocation clears an already open browser and its cached board request sta
const { chrome, device } = await enrolledBrowser(box, t);
const board = JSON.parse(readFileSync(box.linkFile, 'utf8')).board;
assert.equal(await chrome.evaluate("(window.__removedBoardReference = data.project).items.some(item => item.title === 'private cleanup fixture item')"), true);
+ await chrome.waitFor('data.project?.historyProgress?.complete === true');
+ assert.equal(await chrome.evaluate('window.__removedBoardReference.items === data.project.items'), true,
+ 'completed background history retains the shared item collection already held by the cockpit');
// These are device-local opaque caches, never authority or a relay response. Use the real key/sealer.
await chrome.evaluate(`(async () => {
const module = await import('/relay/seal.js');
@@ -859,7 +866,7 @@ test('reviewer: a revoked bound session cannot regain ciphertext through auth ma
const oldSession = await box.phoneSession();
const retainedKey = await chrome.evaluate(`JSON.parse(localStorage.getItem('pullboard.relay.keys.v1'))[${JSON.stringify(link.board)}]`);
assert.equal(typeof retainedKey, 'string', 'the genuinely enrolled browser already received this board key');
- const endpoint = box.origin + '/api/v1/boards/' + link.board + '/state';
+ const endpoint = box.origin + '/api/v2/boards/' + link.board + '/state';
const oldHeaders = {authorization:'Bearer '+oldSession.token,'x-pullboard-engine':String(ENGINE_VERSION)};
assert.equal((await fetch(endpoint,{headers:oldHeaders})).status,200,'the bound session has original read access');
await revokeBrowser(box, chrome, device);
@@ -885,9 +892,19 @@ test('reviewer: a revoked bound session cannot regain ciphertext through auth ma
delegatedStatus=delegated.status;
if(delegated.status===200){
const {state}=await delegated.json();
- assert.equal(typeof state.sealed,'string','the relay served actual ciphertext, not merely a board name');
- const plain=await unseal(decodeBoardKey(retainedKey),Buffer.from(state.sealed,'base64url'),{boardId:link.board,kind:'snapshot',sequence:state.sequence});
- const snapshot=snapshotDocument(plain);
+ const page=await openPagedSnapshot(state.root,{
+ key:decodeBoardKey(retainedKey),boardId:link.board,sequence:state.sequence,
+ /** Prove any wrongly delegated access reaches the real pinned ciphertext graph with that new credential. */
+ async get(id,parents){
+ const response=await fetch(box.origin+'/api/v2/boards/'+link.board+'/objects/'+id+'?pin='+encodeURIComponent(state.read.id)+'&via='+parents.join(','),{
+ headers:{authorization:'Bearer '+document.token,'x-pullboard-engine':String(ENGINE_VERSION)},
+ });
+ assert.equal(response.status,200);
+ const value=await response.json();
+ return Uint8Array.from(Buffer.from(value.page.sealed,'base64url'));
+ },
+ },{maxEngine:ENGINE_VERSION});
+ const snapshot=await page.native();
decryptedOriginal=JSON.stringify(snapshot).includes('private cleanup fixture item');
assert.equal(decryptedOriginal,true,'the previously received browser key decrypts the regained board');
}
diff --git a/test/relay-client-fixture.js b/test/relay-client-fixture.js
index 74e7cfa5..8fca91fb 100644
--- a/test/relay-client-fixture.js
+++ b/test/relay-client-fixture.js
@@ -21,6 +21,22 @@ import { relayWorkBudgetMs, MAX_SNAPSHOT_ATTEMPTS } from './relay-budget.js';
const CLI = resolve(import.meta.dirname, '../bin/pullboard.js');
const MAX_OBSERVED_SNAPSHOT_UPLOADS = MAX_SNAPSHOT_ATTEMPTS;
const DEFAULT_SNAPSHOT_UPLOADS = 3;
+// One former whole-snapshot wire allowance is a finite unit of observed API2 transfer work too.
+const PAGE_WORK_BYTES = 10_000_000;
+
+/** Keep legacy attempts exact while counting received API2 wire bytes and checkpoint attempts, never elapsed activity. */
+function uploadWork(value) {
+ const work = typeof value === 'number' ? { legacyUploads: value } : value;
+ const result = Object.fromEntries(['legacyUploads', 'pageUploadBytes', 'pageSessions', 'pageCheckpointAttempts'].map(key => [key, work?.[key] ?? 0]));
+ assert.ok(Object.values(result).every(number => Number.isSafeInteger(number) && number >= 0), 'fixture upload work has bounded integer counters');
+ result.units = result.legacyUploads + Math.max(result.pageSessions, result.pageCheckpointAttempts) + Math.ceil(result.pageUploadBytes / PAGE_WORK_BYTES);
+ // Attempt and byte ceilings are independent: bytes do not consume a checkpoint attempt. Time still has the released six-unit cap.
+ result.budgetUnits = Math.min(result.units, MAX_OBSERVED_SNAPSHOT_UPLOADS);
+ result.overLimit = result.legacyUploads > MAX_OBSERVED_SNAPSHOT_UPLOADS || result.pageSessions > MAX_OBSERVED_SNAPSHOT_UPLOADS
+ || result.pageCheckpointAttempts > MAX_OBSERVED_SNAPSHOT_UPLOADS || result.pageUploadBytes > PAGE_WORK_BYTES * MAX_OBSERVED_SNAPSHOT_UPLOADS;
+ return result;
+}
+
/** Derive a private CLI child deadline from observed uploads, with a finite runaway guard. */
export function cliChildDeadlineMs(observedUploads) {
@@ -67,19 +83,21 @@ function childResult(root, env, argv, observedSnapshotUploads, initialSnapshotUp
return new Promise((resolveResult, reject) => {
const startedAt = performance.now();
let deadlineMs = cliChildDeadlineMs(initialSnapshotUploads);
+ let work = uploadWork(initialSnapshotUploads);
const child = spawn(process.execPath, argv, { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] });
let stdout = '';
let stderr = '';
let exceededDeadline = false;
+ let exceededWork = false;
let settled = false;
const timer = setInterval(() => {
- const count = observedSnapshotUploads?.() ?? initialSnapshotUploads;
- if (count > MAX_OBSERVED_SNAPSHOT_UPLOADS) {
- exceededDeadline = true;
+ work = uploadWork(observedSnapshotUploads?.() ?? initialSnapshotUploads);
+ if (work.overLimit) {
+ exceededWork = true;
child.kill('SIGKILL');
return;
}
- deadlineMs = Math.max(deadlineMs, cliChildDeadlineMs(count));
+ deadlineMs = Math.max(deadlineMs, cliChildDeadlineMs(work.budgetUnits));
if (performance.now() - startedAt >= deadlineMs) { exceededDeadline = true; child.kill('SIGKILL'); }
}, 20);
child.stdout.setEncoding('utf8').on('data', part => { stdout += part; });
@@ -99,18 +117,23 @@ function childResult(root, env, argv, observedSnapshotUploads, initialSnapshotUp
if (settled) return;
settled = true;
clearInterval(timer);
- if (signal) return reject(new Error(reportFailure(code, signal, exceededDeadline
- ? `upload-derived child deadline ${deadlineMs}ms exceeded` : '')));
+ const phase = work.pageUploadBytes > 0 ? 'API2 page upload' : work.pageSessions || work.pageCheckpointAttempts ? 'API2 checkpoint' : 'snapshot upload';
+ if (signal) return reject(new Error(reportFailure(code, signal, exceededWork
+ ? `declared upload work limit exceeded: at most ${MAX_OBSERVED_SNAPSHOT_UPLOADS} attempts and ${PAGE_WORK_BYTES * MAX_OBSERVED_SNAPSHOT_UPLOADS} page bytes; recorded work ${JSON.stringify(work)}`
+ : exceededDeadline ? `${phase} stalled: upload-derived child deadline ${deadlineMs}ms exceeded; recorded work ${JSON.stringify(work)}` : '')));
const failure = code === 0 ? null : reportFailure(code, signal);
let document;
try { document = JSON.parse(stdout); }
catch (error) { return reject(new Error(reportFailure(code, signal, `private relay fixture child did not return JSON: ${error.message}`))); }
- resolveResult({ code, document, failure, snapshotUploads: observedSnapshotUploads?.() ?? initialSnapshotUploads,
- snapshotDeadlineMs: deadlineMs });
+ work = uploadWork(observedSnapshotUploads?.() ?? initialSnapshotUploads);
+ resolveResult({ code, document, failure, snapshotUploads: work.legacyUploads,
+ snapshotWork: { ...work, observed: typeof observedSnapshotUploads === 'function' }, snapshotDeadlineMs: deadlineMs });
});
});
}
+export { childResult as relayFixtureChild };
+
/** Start an isolated board and authorized loopback relay; a null coordinatorModel keeps its initial identity unknown. */
export async function relayClientFixture(t, { cliChildren, coordinatorModel, accountStorageBytes } = {}) {
const scratch = realpathSync(mkdtempSync(join(tmpdir(), 'pullboard-relay-cleanup-')));
@@ -202,6 +225,7 @@ globalThis.fetch = function tracedFetch(input, init) {
let snapshotWriteDelayMs = 0;
let oneSnapshotDelay = null;
let snapshotWriteCount = 0;
+ const pageWork = { pageUploadBytes: 0, pageSessions: 0, pageCheckpointAttempts: 0 };
const snapshotWriteDelays = [];
const snapshotWriteRecords = [];
let stateReadDelayMs = 0;
@@ -268,6 +292,10 @@ globalThis.fetch = function tracedFetch(input, init) {
const server = createServer(async (req, res) => {
const snapshotWrite = req.method === 'PUT' && /\/api\/v1\/boards\/[0-9a-f]{32}\/state$/.test(req.url ?? '');
if (snapshotWrite) snapshotWriteCount += 1;
+ const pageObject = req.method === 'PUT' && /^\/api\/v2\/boards\/[0-9a-f]{32}\/uploads\/[^/]+\/objects\/[0-9a-f]{64}$/u.test(req.url ?? '');
+ if (req.method === 'POST' && /^\/api\/v2\/boards\/[0-9a-f]{32}\/uploads$/u.test(req.url ?? '')) pageWork.pageSessions++;
+ if (req.method === 'POST' && /^\/api\/v2\/boards\/[0-9a-f]{32}\/uploads\/[^/]+\/publish$/u.test(req.url ?? '')) pageWork.pageCheckpointAttempts++;
+
const requestChunks = [];
const responseChunks = [];
const acceptedApprovalCompletionRefusal = refuseNextAcceptedApprovalCompletionResponse
@@ -280,6 +308,7 @@ globalThis.fetch = function tracedFetch(input, init) {
const request = new Transform({
transform(chunk, _encoding, callback) {
requestChunks.push(Buffer.from(chunk));
+ if (pageObject) pageWork.pageUploadBytes += chunk.byteLength;
callback(null, chunk);
},
});
@@ -494,6 +523,10 @@ globalThis.fetch = function tracedFetch(input, init) {
const plannedUploads = plannedSnapshotUploads(args);
const snapshotUploads = plannedUploads ?? requestedUploads;
const writesBefore = snapshotWriteCount;
+ const pagesBefore = { ...pageWork };
+ /** Observe only this child's received work; retries consume the same finite six-unit allowance. */
+ const observedWork = () => ({ legacyUploads: snapshotWriteCount - writesBefore,
+ ...Object.fromEntries(Object.entries(pageWork).map(([name, count]) => [name, count - pagesBefore[name]])) });
const childEnv = traceSnapshotWrites ? { ...env, PULLBOARD_TEST_RELAY_TRACE_FILE: traceFile,
PULLBOARD_TEST_RELAY_TRACE_ORIGIN: origin,
NODE_OPTIONS: [env.NODE_OPTIONS, '--import=' + pathToFileURL(tracePreload).href].filter(Boolean).join(' ') } : env;
@@ -507,11 +540,10 @@ globalThis.fetch = function tracedFetch(input, init) {
}
let result;
try {
- result = await childResult(root, childEnv, [CLI, ...args, '--json'],
- traceSnapshotWrites ? () => snapshotWriteCount - writesBefore : undefined, initialUploads);
+ result = await childResult(root, childEnv, [CLI, ...args, '--json'], observedWork, initialUploads);
} catch (error) {
if (traceSnapshotWrites) {
- const evidence = JSON.stringify({ fetches: childTrace(), relayReceives: snapshotWriteRecords.slice(writesBefore) });
+ const evidence = JSON.stringify({ fetches: childTrace(), relayReceives: snapshotWriteRecords.slice(writesBefore), uploadWork: observedWork() });
const message = error instanceof Error ? error.message : String(error);
throw new Error(`${message}; safe snapshot transport evidence: ${evidence}`, { cause: error });
}
diff --git a/test/relay-client.test.js b/test/relay-client.test.js
index cc535774..947cbad1 100644
--- a/test/relay-client.test.js
+++ b/test/relay-client.test.js
@@ -27,6 +27,7 @@ import { presentationShout } from '../src/relay-presentation.js';
import { fetchFresh } from './http-fixture.js';
import { relayResetSample } from './relay-reset-fixture.js';
import { request as relayRequest } from '../src/relay.js';
+import { openPagedSnapshot } from '../src/relay-page-layout.js';
import { AGENT_SHELL_MARKERS, SSH_SHELL_MARKERS } from '../src/person.js';
const SIGN_INS = new Map();
@@ -186,7 +187,7 @@ function threeReplicaPhaseCapture(t) {
}
/** Run the real auth and opaque board handlers together on a private loopback port. */
-async function relayServer(t, directory, auth) {
+async function relayServer(t, directory, auth, { legacyRelay = false } = {}) {
let signIn;
let api;
let refuseMoves = false;
@@ -198,6 +199,12 @@ async function relayServer(t, directory, auth) {
const uploads = [];
const server = createServer(async (req, res) => {
calls.push({ method: req.method, path: req.url });
+ // A historical relay has no pages router. Keep that protocol an explicit fixture choice rather than
+ // making a current paged board pretend its API1 whole-snapshot endpoint still has the same representation.
+ if (legacyRelay && /^\/api\/v2(?:\/|$)/u.test(req.url)) {
+ res.writeHead(404, { 'content-type': 'application/json' }).end('{"version":1,"error":{"code":"NOT_FOUND","message":"legacy relay has no pages router"}}');
+ return;
+ }
if (req.method === 'POST' && /\/moves$/.test(req.url)) {
const drop = loseReply;
loseReply = false;
@@ -279,7 +286,7 @@ function seedDoctrine(seed) {
}
}
-test('[H1,H3,H7,H15,H16] relay on snapshots and orders ciphertext, refuses offline moves, and off preserves the board', async (t) => {
+test('[H1,H3,H7,H15,H16] relay on snapshots and orders ciphertext, refuses offline moves, and off preserves the board (legacy relay)', async (t) => {
const scratch = realpathSync(mkdtempSync(join(tmpdir(), 'pullboard-relay-client-')));
const root = join(scratch, 'repo');
const home = join(scratch, 'home');
@@ -316,7 +323,9 @@ test('[H1,H3,H7,H15,H16] relay on snapshots and orders ciphertext, refuses offli
t.after(() => SIGN_INS.delete(root));
const auth = createRelayAuth({ database: join(scratch, 'auth.sqlite'), github: createGitHubClient(provider.config) });
t.after(() => { auth.close(); });
- const relay = await relayServer(t, relayDirectory, auth);
+ // This scenario also installs and migrates historical single-record checkpoints later in its body.
+ // Its original full-native, privacy, ordering, retry and unlink assertions remain unchanged.
+ const relay = await relayServer(t, relayDirectory, auth, { legacyRelay: true });
t.after(() => { rmSync(scratch, { recursive: true, force: true }); });
const flow = auth.beginWeb();
const authorization = await fetch(flow.authorizationURL, { redirect: 'manual' });
@@ -366,6 +375,7 @@ test('[H1,H3,H7,H15,H16] relay on snapshots and orders ciphertext, refuses offli
assert.match(on.link, /^https:\/\/app\.pullboard\.dev\/#board=/);
assert.match(on.link, /(?:^|&)key=[A-Za-z0-9_-]{43}(?:&|$)/);
assert.equal(on.url, relay.origin);
+ assert.ok(relay.calls.some(call => call.path === '/api/v2'), 'the current client probes the legacy relay before preserving its supported API1 flow');
const keyFile = join(pullboardHome, 'relay-keys', `${boardId}.key`);
assert.equal(statSync(keyFile).mode & 0o777, 0o600);
const keyText = readFileSync(keyFile, 'utf8').trim();
@@ -621,6 +631,49 @@ function recoveryLines(result) {
/** Escape text for a literal match inside a regular expression. */
function literal(text) { return text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&'); }
+test('a current paged relay keeps the complete native board while a legacy reader is told to upgrade [H1,H3,H15,H16]', async t => {
+ const box = await lostReplyFixture(t);
+ const marker = 'PAGED_CURRENT_NATIVE_PRIVATE_ITEM';
+ await cli(box.root, box.env, 'add', box.lane, marker);
+ const expected = await cli(box.root, box.env, 'export');
+ const link = JSON.parse(readFileSync(join(box.root, '.git/pullboard/relay.json'), 'utf8'));
+ assert.equal(link.snapshotApiVersion, 2, 'the unmodified current relay advertises and receives the paged protocol');
+ const key = decodeBoardKey(readFileSync(join(box.pullboardHome, 'relay-keys', link.board + '.key'), 'utf8').trim());
+ const headers = { 'x-pullboard-engine': String(ENGINE_VERSION), authorization: `Bearer ${link.token}` };
+ const legacy = await fetch(box.relay.origin + '/api/v1/boards/' + link.board + '/state', { headers });
+ assert.equal(legacy.status, 400);
+ const upgrade = await legacy.json();
+ assert.equal(upgrade.error.code, 'RELAY_API_VERSION', 'a legacy reader is explicitly told to upgrade, never given a partial native snapshot');
+ assert.match(upgrade.error.message, /npm i -g pullboard@latest/u, 'the legacy refusal gives the concrete upgrade command');
+ const response = await fetch(box.relay.origin + '/api/v2/boards/' + link.board + '/state', { headers });
+ assert.equal(response.status, 200, 'the same actual machine credential can read the current protocol');
+ const document = await response.json();
+ assert.equal(document.apiVersion, 2);
+ const saved = document.state;
+ const opened = await openPagedSnapshot(saved.root, {
+ key, boardId: link.board, sequence: saved.sequence,
+ /** Read exactly the authenticated pinned graph, using the real server's object membership checks. */
+ async get(id, parents) {
+ const reply = await fetch(box.relay.origin + '/api/v2/boards/' + link.board + '/objects/' + id
+ + '?pin=' + encodeURIComponent(saved.read.id) + '&via=' + parents.join(','), { headers });
+ assert.equal(reply.status, 200);
+ const page = await reply.json();
+ assert.equal(page.apiVersion, 2);
+ assert.equal(page.page.id, id);
+ return Uint8Array.from(Buffer.from(page.page.sealed, 'base64url'));
+ },
+ }, { maxEngine: ENGINE_VERSION });
+ const native = await opened.native();
+ assert.deepEqual(native.tables, expected.tables, 'paged restore retains every native row and counter, not just the first-screen summary');
+ assert.ok(native.presentation.state.items.some(item => item.title === marker));
+ assert.ok(box.relay.calls.some(call => call.method === 'PUT' && /\/api\/v2\/boards\/[^/]+\/uploads\/[^/]+\/objects\//u.test(call.path)),
+ 'the current client uploaded bounded sealed objects through the real pages API');
+ // The native export is verified after decryption; the server's stored bytes must remain opaque.
+ const relayDirectory = join(box.root, '..', 'relay');
+ const stored = Buffer.concat(readdirSync(relayDirectory).map(name => readFileSync(join(relayDirectory, name))));
+ assert.equal(stored.includes(Buffer.from(marker)), false);
+});
+
test('[H16,C7] a relay transport failure names its cause', async (t) => {
const fixture = await lostReplyFixture(t);
const { root, env, lane, relay } = fixture;
diff --git a/test/relay-page-client.test.js b/test/relay-page-client.test.js
index 1ce24ddc..f45f4c71 100644
--- a/test/relay-page-client.test.js
+++ b/test/relay-page-client.test.js
@@ -12,6 +12,8 @@ import { pagedSnapshotRequest, relaySnapshotRequest, relayStorage, relayStorageL
import { generateBoardKey } from '../src/seal.js';
import { writeSealedValue } from '../src/sealed-pages.js';
import { Refused } from '../src/refused.js';
+import { createServer } from 'node:http';
+import { relayFixtureChild, cliChildDeadlineMs } from './relay-client-fixture.js';
/** Use only an isolated device home, restoring the surrounding test process after its cache closes. */
function privateHome(t) {
@@ -97,6 +99,26 @@ test('a lost object ACK resumes the exact durable graph and native restore prese
assert.equal(box.state.storage.account.login, 'fixture-login');
});
+test('a fresh device reuses authenticated restored history instead of uploading it again [H15,H17]', async t => {
+ const box = await fixture(t);
+ await pagedSnapshotRequest(box.state, { method: 'PUT', body: { sequence: 0, sealed: 'first-device-cipher' } }, box.adapter);
+ const initialObjects = box.calls.filter(call => call.method === 'PUT').map(call => call.path.split('/').at(-1));
+ assert.ok(initialObjects.length > 8, 'the fixture has several genuine historical cipher pages');
+ // Change only the private device home: the second device has none of the writer's cache or ACKs.
+ process.env.PULLBOARD_HOME = join(process.env.PULLBOARD_HOME, 'independent-reader');
+ const read = await pagedSnapshotRequest(box.state, {}, box.adapter);
+ assert.deepEqual(JSON.parse(read.state.sealed), box.document, 'the fresh device authenticates and restores every native row');
+ const afterRead = box.calls.length;
+ box.document.presentation.state.name = 'New device presentation';
+ const result = await pagedSnapshotRequest(box.state, { method: 'PUT', body: { sequence: 0, sealed: 'second-device-cipher' } }, box.adapter);
+ const writes = box.calls.slice(afterRead).filter(call => call.method === 'PUT');
+ assert.ok(writes.length < initialObjects.length / 2, 'changing only current presentation must not upload retained history again');
+ assert.equal(writes.filter(call => initialObjects.includes(call.path.split('/').at(-1))).length, 0, 'no authenticated historical object is uploaded again');
+ assert.equal(result.state.sealed, 'second-device-cipher');
+ assert.deepEqual(JSON.parse((await pagedSnapshotRequest(box.state, {}, box.adapter)).state.sealed), box.document,
+ 'the independently published checkpoint still restores all native rows and the changed presentation');
+});
+
test('a collected remote subtree is restaged despite old cached ACKs, without replacing the source graph [H15,H17]', async t => {
const box = await fixture(t);
const pending = { sequence: 0, sealed: 'synthetic-stable-pending-cipher' };
@@ -130,6 +152,41 @@ test('private reuse authenticates the fingerprint binding rather than trusting a
} finally { cache.close(); }
});
+test('a stalled API2 upload is killed at its finite work-derived deadline and names the stall [C7,H15,H17]', async t => {
+ const work = { legacyUploads: 0, pageUploadBytes: 0, pageSessions: 0, pageCheckpointAttempts: 0 };
+ let held = false;
+ const api = '/api/v2/boards/' + 'b'.repeat(32);
+ const objectPath = api + '/uploads/stalled-fixture/objects/' + 'c'.repeat(64);
+ const server = createServer((request, response) => {
+ if (request.method === 'POST' && request.url === api + '/uploads') {
+ work.pageSessions++; response.writeHead(200, { 'content-type': 'application/json' }); response.end('{}'); return;
+ }
+ if (request.method === 'PUT' && request.url === objectPath) {
+ request.on('data', bytes => { work.pageUploadBytes += bytes.byteLength; });
+ request.on('end', () => { held = true; }); // Deliberately never acknowledge this genuinely received page.
+ return;
+ }
+ response.writeHead(404); response.end();
+ });
+ await new Promise(resolveListen => server.listen(0, '127.0.0.1', resolveListen));
+ t.after(async () => { server.closeAllConnections(); await new Promise(resolveClose => server.close(resolveClose)); });
+ const origin = 'http://127.0.0.1:' + server.address().port;
+ const script = `await (await fetch(${JSON.stringify(origin + api + '/uploads')}, {method:'POST'})).arrayBuffer();
+ await fetch(${JSON.stringify(origin + objectPath)}, {method:'PUT',body:new Uint8Array(1024)});`;
+ let failure;
+ try { await relayFixtureChild(process.cwd(), process.env, ['--input-type=module', '-e', script], () => work, 0); }
+ catch (error) { failure = error; }
+ assert.equal(held, true, 'the stand-in really received the upload and withheld its ACK');
+ assert.equal(work.pageSessions, 1);
+ assert.equal(work.pageUploadBytes, 1024);
+ assert.ok(failure, 'a real stalled child must fail rather than complete or wait without a bound');
+ assert.match(failure.message, /signal: SIGKILL/u);
+ assert.match(failure.message, /API2 page upload stalled/u);
+ assert.ok(failure.message.includes('upload-derived child deadline ' + cliChildDeadlineMs(2) + 'ms exceeded'),
+ 'the observed session and one bounded byte unit determine the unchanged allowance');
+ t.diagnostic(JSON.stringify({ stalledUploadWork: work, derivedDeadlineMs: cliChildDeadlineMs(2), stalledUploadKilled: true }));
+});
+
test('account status has a validated identity, exact byte counts and a clear operator-set limit [H15,H17]', () => {
const storage = { account: { id: 'account-1', login: 'owner-login' }, usedBytes: 251_000_000, limitBytes: 256_000_000 };
assert.deepEqual(relayStorage(storage), storage);
diff --git a/test/relay-snapshot-size.test.js b/test/relay-snapshot-size.test.js
index 34fcbb43..c2cecb7d 100644
--- a/test/relay-snapshot-size.test.js
+++ b/test/relay-snapshot-size.test.js
@@ -263,7 +263,13 @@ test('thirty thousand events open on the phone within three seconds and stream a
const before = relaySnapshot(box.root);
assert.ok(before.tables.event.length >= 30_000 && before.tables.event.length < 31_000);
assert.ok(gzipSync(Buffer.from(JSON.stringify(before))).byteLength > RELAY_LIMIT * 3, 'even compressed whole-board state is several times the old limit');
- assert.equal((await box.cli('status')).code, 0, 'the actual opted-in CLI publishes through bounded pages');
+ const uploadedStatus = await box.cli('status');
+ assert.equal(uploadedStatus.code, 0, 'the actual opted-in CLI publishes through bounded pages');
+ assert.equal(uploadedStatus.snapshotWork.observed, true);
+ assert.ok(uploadedStatus.snapshotWork.pageUploadBytes > 0 && uploadedStatus.snapshotWork.pageCheckpointAttempts > 0,
+ 'API2 page bytes and actual checkpoint attempts contribute non-zero recorded work');
+ assert.ok(uploadedStatus.snapshotWork.budgetUnits <= 6 && !uploadedStatus.snapshotWork.overLimit, 'observed attempts and bytes stay bounded without raising the existing time allowance');
+ t.diagnostic(JSON.stringify({ api2UploadWork: uploadedStatus.snapshotWork, derivedChildDeadlineMs: uploadedStatus.snapshotDeadlineMs }));
const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));
assert.equal(link.snapshotApiVersion, 2);
assert.equal(link.checkpoint, undefined);
diff --git a/test/sealed-pages.test.js b/test/sealed-pages.test.js
index ae68fcdb..110417f3 100644
--- a/test/sealed-pages.test.js
+++ b/test/sealed-pages.test.js
@@ -77,12 +77,20 @@ test('private reuse preserves authenticated old pages without disclosing their f
test('wrong board, position, ciphertext and subtree lengths cannot become snapshot data [H15,H17]', async () => {
const box = await storage();
const reference = await writeSealedValue({ marker: 'authenticated synthetic data' }, box.context);
- await assert.rejects(readSealedValue(reference, { ...box.context, boardId: 'b'.repeat(32) }), { code: 'SEAL_AUTH_FAILED' });
- await assert.rejects(readSealedValue({ ...reference, sequence: 8 }, box.context), { code: 'SEAL_AUTH_FAILED' });
- await assert.rejects(readSealedValue({ ...reference, bytes: reference.bytes + 1 }, box.context), { code: 'SNAPSHOT_PAGE_FORMAT' });
+ const remembered = [];
+ const context = { ...box.context, rememberRead: (...args) => { remembered.push(args); } };
+ await assert.rejects(readSealedValue(reference, { ...context, boardId: 'b'.repeat(32) }), { code: 'SEAL_AUTH_FAILED' });
+ await assert.rejects(readSealedValue({ ...reference, sequence: 8 }, context), { code: 'SEAL_AUTH_FAILED' });
+ await assert.rejects(readSealedValue({ ...reference, bytes: reference.bytes + 1 }, context), { code: 'SNAPSHOT_PAGE_FORMAT' });
+ assert.equal(remembered.length, 0, 'neither misbound nor structurally invalid data can seed private reuse or remote-custody ACKs');
+ assert.deepEqual(await readSealedValue(reference, context), { marker: 'authenticated synthetic data' });
+ assert.equal(remembered.length, 1, 'a complete valid read can seed the private device cache');
+ assert.equal(remembered[0][0].id, reference.id);
+ assert.deepEqual(remembered[0][0].children, []);
const bytes = box.objects.get(reference.id).bytes;
bytes[bytes.length - 1] ^= 1;
- await assert.rejects(readSealedValue(reference, box.context), { code: 'SNAPSHOT_PAGE_FORMAT' });
+ await assert.rejects(readSealedValue(reference, context), { code: 'SNAPSHOT_PAGE_FORMAT' });
+ assert.equal(remembered.length, 1, 'tampered ciphertext cannot add or replace cached evidence');
});
test('a selected-value reader stops fetching when its consumer stops or has no allocation budget [H15,H17]', async () => {