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): page every supported snapshot write [H15,H17]

Corey Olsonfb301725e205
diff --git a/relay/README.md b/relay/README.md
index 281defe3..3a545a17 100644
--- a/relay/README.md
+++ b/relay/README.md
@@ -165,8 +165,10 @@ keeps the head cursor, so the next move never reuses an earlier sequence.
Upgrade the relay before linking a board larger than the legacy cap. `GET /api/v2`
advertises `apiVersion: 2`, `snapshot: "sealed-pages"` and the per-object bounds.
-A new CLI preserves legacy reads and small legacy uploads, then negotiates API2
-for a large upload or an existing paged head. Once paged, a board cannot silently
+A new CLI preserves legacy reads and uses API2 for every new snapshot write
+when the relay supports it. Small boards use the same complete-history transport;
+a tiny compressed carrier cannot bypass the bounded phone boot. Old relays keep
+their original snapshot interface. Once paged, a board cannot silently
downgrade. An older API1 reader receives `RELAY_API_VERSION` and
`npm i -g pullboard@latest`; it never receives an incomplete legacy snapshot.
This transport does not change the executable move engine or seal envelope.
diff --git a/src/relay-page-client.js b/src/relay-page-client.js
index 78b0d3ba..4e02fdf1 100644
--- a/src/relay-page-client.js
+++ b/src/relay-page-client.js
@@ -1,5 +1,6 @@
/** Native bounded snapshot upload/resume and complete restore; no private cache fingerprint crosses HTTP [H15,H17]. */
import { Refused } from './refused.js';
+import { legacyPageRoute } from './relay-page-support.js';
import { relayStorage } from './relay-storage.js';
export { relayStorage, relayStorageLine } from './relay-storage.js';
import { createRelayPageCache, snapshotSourceId } from './relay-page-cache.js';
@@ -118,7 +119,7 @@ export async function pagedSnapshotRequest(state, options, { request, key, decod
} finally { cache.close(); }
}
-/** Negotiate bounded snapshots only when needed; small legacy heads keep their existing wire interface. */
+/** New supported writes use complete paged history at every board size; legacy reads and old relays stay supported. */
export async function relaySnapshotRequest(state, path, options = {}, io, hooks) {
const snapshot = path === '/api/v1/boards/' + state.board + '/state' && ['GET', 'PUT'].includes(options.method ?? 'GET');
/** Probe the configured relay once per command without downgrading a board already known to use pages. */
@@ -128,7 +129,10 @@ export async function relaySnapshotRequest(state, path, options = {}, io, hooks)
if (!origins) { origins = new Map(); PAGE_CAPABILITIES.set(owner, origins); }
if (!origins.has(state.url)) origins.set(state.url, (async () => {
try { return (await hooks.raw('/api/v2', {})).apiVersion === 2; }
- catch (error) { if (error.httpStatus === 404 && error.relayVersion === 1) return false; throw error; }
+ catch (error) {
+ if (legacyPageRoute(error)) return false;
+ throw error;
+ }
})());
const supported = await origins.get(state.url);
if (!supported && state.snapshotApiVersion === 2) throw new Refused('RELAY_API_VERSION', 'This board requires relay API version 2. Upgrade the configured relay before syncing.');
@@ -152,8 +156,7 @@ export async function relaySnapshotRequest(state, path, options = {}, io, hooks)
hooks.persist();
}
}
- const oversized = options.method === 'PUT' && typeof options.body?.sealed === 'string' && options.body.sealed.length > Math.floor(hooks.legacyLimit * 4 / 3);
- if (snapshot && (state.snapshotApiVersion === 2 || oversized) && await supportsPages()) return paged();
+ if (snapshot && (state.snapshotApiVersion === 2 || options.method === 'PUT') && await supportsPages()) return paged();
try { return await hooks.raw(path, options); }
catch (error) {
const storage = relayStorage(error.storage);
diff --git a/src/relay-page-support.js b/src/relay-page-support.js
new file mode 100644
index 00000000..585e620c
--- /dev/null
+++ b/src/relay-page-support.js
@@ -0,0 +1,6 @@
+/** Old API1 routers may reject an unknown capability path with either supported envelope status [H15,H17]. */
+
+/** Treat only a recognized old route response as unsupported, never an auth or uncertain transport refusal. */
+export function legacyPageRoute(error) {
+ return error?.relayVersion === 1 && (error.httpStatus === 404 || error.httpStatus === 400 && error.code === 'BAD_REQUEST');
+}
diff --git a/src/relay-upload-pause.js b/src/relay-upload-pause.js
index 564cc902..065c11d4 100644
--- a/src/relay-upload-pause.js
+++ b/src/relay-upload-pause.js
@@ -3,6 +3,7 @@ import { createRelayPageCache, snapshotSourceId } from './relay-page-cache.js';
import { relayStorage } from './relay-storage.js';
import { agentSessionDigest } from './person.js';
import { Refused } from './refused.js';
+import { legacyPageRoute } from './relay-page-support.js';
/** Classify a durable transport limit without trusting arbitrary relay text as executable advice. */
export function uploadPauseType(pause) {
@@ -27,7 +28,7 @@ export async function uploadRetryReady(state, pause, request) {
if (ready) state.snapshotApiVersion = 2;
return ready;
}
- catch (error) { if (error.httpStatus === 404 && error.relayVersion === 1) return false; throw error; }
+ catch (error) { if (legacyPageRoute(error)) return false; throw error; }
}
const result = await request('/api/v2/boards/' + state.board + '/storage');
const storage = relayStorage(result.storage);
diff --git a/test/relay-client-fixture.js b/test/relay-client-fixture.js
index f3f7da3c..74e7cfa5 100644
--- a/test/relay-client-fixture.js
+++ b/test/relay-client-fixture.js
@@ -334,8 +334,10 @@ globalThis.fetch = function tracedFetch(input, init) {
calls.push({ method: req.method, path: req.url, accept: req.headers.accept ?? '', engine: req.headers['x-pullboard-engine'],
browser: String(req.headers.cookie ?? '').includes('pb_session=') });
if (legacySnapshotApi && req.method === 'GET' && req.url === '/api/v2') {
- res.writeHead(200, { 'content-type': 'application/json' });
- res.end(JSON.stringify({ version: 1, apiVersion: 1, snapshot: 'legacy' }));
+ res.writeHead(legacySnapshotApi === 'bad-route' ? 400 : 200, { 'content-type': 'application/json' });
+ res.end(JSON.stringify(legacySnapshotApi === 'bad-route'
+ ? { version: 1, error: { code: 'BAD_REQUEST', message: 'Use API1 on this legacy relay.' } }
+ : { version: 1, apiVersion: 1, snapshot: 'legacy' }));
request.resume(); return;
}
if (req.method === 'POST' && req.url === '/auth/device/confirmation/status' && nextConfirmationStatusHold) {
@@ -765,3 +767,11 @@ globalThis.fetch = function tracedFetch(input, init) {
},
};
}
+
+
+/** Preserve explicit API1 wire-contract cases while the default fixture exercises current API2 writers. */
+export async function legacyRelayClientFixture(t, options) {
+ const box = await relayClientFixture(t, options);
+ box.legacySnapshotApi();
+ return box;
+}
diff --git a/test/relay-page-client.test.js b/test/relay-page-client.test.js
index 5a5b1deb..1ce24ddc 100644
--- a/test/relay-page-client.test.js
+++ b/test/relay-page-client.test.js
@@ -183,3 +183,40 @@ test('a relay without API2 retains legacy snapshot behavior rather than guessing
assert.deepEqual(calls, ['/api/v2', path]);
assert.equal(state.snapshotApiVersion, undefined);
});
+
+
+test('an API1 BAD_REQUEST capability response keeps small legacy uploads usable without a key read [H15,H17]', async () => {
+ const state = { board: 'a'.repeat(32), url: 'https://synthetic-legacy-route.example' };
+ const path = '/api/v1/boards/' + state.board + '/state';
+ const response = { version: 1, state: { sequence: 0, sealed: 'old-saved-carrier' } };
+ const hooks = { legacyLimit: 10_000_000,
+ /** An older shared router refuses unknown paths with BAD_REQUEST, not necessarily 404. */
+ async raw(target) {
+ if (target === '/api/v2') throw Object.assign(new Refused('BAD_REQUEST', 'Use API1.'), { httpStatus: 400, relayVersion: 1 });
+ assert.equal(target, path); return response;
+ },
+ /** A legacy retry of already captured bytes does not need an API2 decode or private key. */
+ key() { assert.fail('unsupported capabilities must preserve the saved legacy carrier'); },
+ };
+ assert.equal(await relaySnapshotRequest(state, path, { method: 'PUT', body: response.state }, {}, hooks), response);
+});
+
+test('new snapshots on a capable relay use complete paged history even for a small board [H15,H17]', async t => {
+ const box = await fixture(t);
+ box.document.tables.shout[0].shout_text = 'tiny retained history';
+ assert.ok(Buffer.byteLength(JSON.stringify(box.document)) < 900_000);
+ const pending = { sequence: 0, sealed: 'synthetic-small-native-carrier' };
+ const path = '/api/v1/boards/' + box.state.board + '/state';
+ const hooks = { ...box.adapter, key: () => box.key ?? box.adapter.key, legacyLimit: 10_000_000, persist() {},
+ /** Legacy reads remain supported, but a new capable writer should publish the complete page graph. */
+ async raw(target, options) {
+ if (target === '/api/v2') return { version: 1, apiVersion: 2 };
+ if (target === path) return { version: 1, state: { ...pending } };
+ return box.adapter.request(target, options);
+ },
+ };
+ const result = await relaySnapshotRequest(box.state, path, { method: 'PUT', body: pending }, {}, hooks);
+ assert.equal(box.state.snapshotApiVersion, 2, 'small boards receive the same complete-history transport, not a legacy presentation-only read');
+ assert.ok(result.state.root);
+ assert.deepEqual(JSON.parse((await pagedSnapshotRequest(box.state, {}, box.adapter)).state.sealed), box.document);
+});
diff --git a/test/relay-pages-http.test.js b/test/relay-pages-http.test.js
index a192e169..47c21e85 100644
--- a/test/relay-pages-http.test.js
+++ b/test/relay-pages-http.test.js
@@ -137,6 +137,11 @@ test('an account quota refusal preserves the readable head and is named in phone
assert.equal((await box.read(head.document.state)).marker, 'readable before quota');
const boards = await box.call('GET', '/api/v1/boards');
assert.ok(boards.document.warnings.some(warning => warning.board === BOARD && warning.code === 'ACCOUNT_STORAGE_LIMIT'));
+ const legacy = Buffer.from(await seal(box.key, randomBytes(8_000), { boardId: OTHER, kind: 'snapshot', sequence: 0 })).toString('base64url');
+ const oldQuota = await box.call('PUT', '/api/v1/boards/' + OTHER + '/state', { sequence: 0, sealed: legacy });
+ assert.equal(oldQuota.status, 507);
+ assert.equal(oldQuota.document.error.code, 'ACCOUNT_STORAGE_LIMIT');
+ assert.equal(oldQuota.document.error.storage.account.id, box.signed.user.id, 'legacy clients receive the same authenticated quota identity and totals');
assert.equal((await box.call('POST', '/api/v2/boards/' + BOARD + '/uploads', { sequence: 0, account: 'another-account' })).document.error.code, 'BAD_REQUEST');
assert.equal((await box.call('DELETE', '/api/v1/boards/' + BOARD)).status, 200);
await box.auth.linkBoard(box.signed.token, BOARD, 'fixture/repository');
diff --git a/test/relay-snapshot-size.test.js b/test/relay-snapshot-size.test.js
index c73193cc..34fcbb43 100644
--- a/test/relay-snapshot-size.test.js
+++ b/test/relay-snapshot-size.test.js
@@ -12,6 +12,7 @@ import { presentationDigest, relaySnapshot } from '../src/relay-presentation.js'
import { relayClientFixture } from './relay-client-fixture.js';
import { findChromeExecutable, startChrome } from './relay-browser-fixture.js';
import { readSealedDescriptor } from '../src/sealed-pages.js';
+import { openPagedSnapshot } from '../src/relay-page-layout.js';
const RELAY_LIMIT = 10_000_000;
const BODY_LIMIT = 14_000_000;
@@ -50,6 +51,7 @@ test('a large board syncs to the relay compressed [H5,H15,H17]', {
skip: !findChromeExecutable() && 'Chrome is not installed',
}, async t => {
const box = await relayClientFixture(t);
+ box.legacySnapshotApi(); // This case explicitly preserves an older relay's whole-snapshot interface.
await box.link();
// Pair a second native CLI while the board is small; it must later restore the relay snapshot.
@@ -357,3 +359,38 @@ test('thirty thousand events open on the phone within three seconds and stream a
writeFileSync(join(output, 'oldest-shout-phone.png'), Buffer.from(screenshot.data, 'base64'), { mode: 0o600 });
}
});
+
+
+test('large compressible history uses bounded pages even when its whole encrypted snapshot fits the old wire cap [H15,H17]', async t => {
+ const box = await relayClientFixture(t);
+ await box.link();
+ const board = store.openBoard(join(box.root, '.git/pullboard/board.sqlite'));
+ try {
+ store.atomic(board, () => {
+ for (let index = 0; index < 4_000; index++) store.shout(board, {
+ from: 'coordinator', to: 'all', lanes: [box.lane], text: 'Retained compressible history ' + index + ' ' + 'q'.repeat(1_000),
+ });
+ });
+ } finally { store.closeBoard(board); }
+ const before = relaySnapshot(box.root);
+ const raw = Buffer.from(JSON.stringify(before));
+ assert.ok(raw.byteLength > 1_000_000);
+ const compressedBytes = gzipSync(raw).byteLength;
+ assert.ok(compressedBytes < RELAY_LIMIT, 'a whole encrypted carrier fits the old wire cap despite a large phone decode');
+ t.diagnostic(JSON.stringify({ nativeBytes: raw.byteLength, compressedBytes }));
+ assert.equal((await box.cli('status')).code, 0);
+ const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));
+ assert.equal(link.snapshotApiVersion, 2, 'large retained plaintext needs paging even when its encrypted carrier compresses well');
+ const response = await fetch(box.origin + '/api/v2/boards/' + link.board + '/state', {
+ headers: { authorization: 'Bearer ' + link.token, 'x-pullboard-engine': String(ENGINE_VERSION) },
+ });
+ const head = (await response.json()).state;
+ const key = decodeBoardKey(readFileSync(box.keyFile, 'utf8').trim());
+ const context = pagedReadContext(box, link, head, key);
+ const root = await readSealedDescriptor(head.root, context);
+ assert.ok(root.links[0].bytes < 1_000_000);
+ const page = await openPagedSnapshot(head.root, context, { maxEngine: ENGINE_VERSION });
+ const restored = await page.native();
+ const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+ assert.equal(hash(restored.tables), hash(before.tables), 'paged encoding retains all compressible history too');
+});
diff --git a/test/relay-stuck-upload.test.js b/test/relay-stuck-upload.test.js
index d24d7550..ec6dadc0 100644
--- a/test/relay-stuck-upload.test.js
+++ b/test/relay-stuck-upload.test.js
@@ -1,4 +1,4 @@
-/** A refused baseline pauses safely and recovers without blocking ordered moves [H16,B26]. */
+/** Legacy API1 refusals recover without blocking moves; current API2 pause proofs live in relay-upload-pause.test.js [H16,B26]. */
import assert from 'node:assert/strict';
import { runFixtureChild as spawnSync } from './fixture-child.js';
import { mkdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
@@ -7,7 +7,7 @@ import { test } from 'node:test';
import { gunzipSync } from 'node:zlib';
import { decodeBoardKey, unseal } from '../src/seal.js';
import { ENGINE_VERSION } from '../src/machine.js';
-import { relayClientFixture } from './relay-client-fixture.js';
+import { legacyRelayClientFixture as relayClientFixture } from './relay-client-fixture.js';
test('a refused upload never blocks board moves [H16,B26]', async (t) => {
const box = await relayClientFixture(t);
diff --git a/test/relay-upload-pause.test.js b/test/relay-upload-pause.test.js
index c4353420..fcc31999 100644
--- a/test/relay-upload-pause.test.js
+++ b/test/relay-upload-pause.test.js
@@ -27,7 +27,7 @@ async function pausedCrypto(box) {
test('a size-paused baseline keeps its cipher, warns once per session and resumes with all local moves after API2 [H15,H17]', async t => {
const box = await relayClientFixture(t);
- box.legacySnapshotApi();
+ box.legacySnapshotApi('bad-route');
box.rejectSnapshots({ status: 400, code: 'BAD_REQUEST', message: 'the body exceeds 14000000 bytes; send a smaller snapshot' });
const linked = await box.link();
assert.equal((linked.document.diagnostics ?? []).filter(line => /relay paused/u.test(line)).length, 1);
@@ -91,12 +91,22 @@ test('quota-paused checkpoints keep exact pending bytes, permit ordered moves an
assert.equal((await box.cli('shout', 'all', 'ordered move while checkpoint quota is paused')).code, 0);
assert.deepEqual(box.moveAcks.map(row => row.event_id), [1]);
assert.equal(state(box).checkpoint.sealed === saved.checkpoint.sealed, true);
+ assert.equal(saved.snapshotApiVersion, 2, 'the native quota refusal occurred during a real bounded-page upload');
+ const staged = await box.script(`
+ const { createRelayPageCache, snapshotSourceId } = await import(${JSON.stringify(new URL('../src/relay-page-cache.js', import.meta.url).href)});
+ const { readFileSync } = await import('node:fs');
+ const link = JSON.parse(readFileSync(${JSON.stringify(box.linkFile)}, 'utf8'));
+ const cache = createRelayPageCache(link);
+ try { console.log(JSON.stringify({ root: cache.job(snapshotSourceId(link.checkpoint.sealed)).reference.id })); }
+ finally { cache.close(); }
+ `);
+ assert.equal(staged.code, 0);
const priorWrites = box.transit.length;
box.setStorageQuota(3_000_000);
assert.equal((await box.cli('status')).code, 0);
- const attempts = box.transit.slice(priorWrites).filter(row => row.method === 'PUT' && row.path.endsWith('/state'));
+ const attempts = box.transit.slice(priorWrites).filter(row => row.method === 'POST' && row.path.endsWith('/publish'));
assert.ok(attempts.length >= 1);
- assert.equal(JSON.parse(attempts[0].request).sealed === saved.checkpoint.sealed, true, 'recovery retries the retained checkpoint before sealing newer state');
+ assert.equal(JSON.parse(attempts[0].request).root.id, staged.document.root, 'recovery publishes the retained checkpoint graph before sealing newer state');
assert.equal((await box.cli('status')).code, 0);
assert.equal(state(box).checkpointRefusal, undefined); assert.equal(state(box).checkpoint, undefined);
assert.equal(state(box).storage.limitBytes, 3_000_000);