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.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(relay): bound boot and stream all history [H15,H17,H18]
Corey Olson95bb45017508
diff --git a/relay/browser-pages.js b/relay/browser-pages.jsnew file mode 100644index 00000000..6ef58ae4--- /dev/null+++ b/relay/browser-pages.js@@ -0,0 +1,43 @@+/** Phone reads current state and selected history without restoring the native board's complete tables [H15,H17]. */+import { openPagedSnapshot } from '../src/relay-page-layout.js';+import { PAGE_CIPHER_BYTES, pageReference } from '../src/sealed-pages.js';+import { Refused } from '../src/refused.js';++/** Decode canonical bounded ciphertext without including a response value in refusal guidance. */+function cipher(value) {+ if (typeof value !== 'string' || value.length > 600_000 || !/^[A-Za-z0-9_-]+$/u.test(value)) throw new Refused('RELAY_RESPONSE', 'This sealed history page is invalid. Refresh the board.');+ const binary = atob(value.replaceAll('-', '+').replaceAll('_', '/') + '='.repeat((4 - value.length % 4) % 4));+ if (!binary.length || binary.length > PAGE_CIPHER_BYTES) throw new Refused('RELAY_RESPONSE', 'This sealed history page is too large. Refresh the board.');+ return Uint8Array.from(binary, character => character.charCodeAt(0));+}++/** Authenticate a fresh read pin and expose only individually bounded current/detail/search reads to the cockpit. */+export async function phoneSnapshotPages(row, { boardId, key, maxEngine, read, bound }) {+ if (row?.apiVersion !== 2 || !Number.isSafeInteger(row.sequence) || row.sequence < 0 || typeof read !== 'function' || typeof bound !== 'function' ||+ !/^[A-Za-z0-9-]{1,128}$/u.test(row.read?.id ?? '')) throw new Refused('RELAY_RESPONSE', 'This paged board response is invalid. Refresh the board.');+ const root = pageReference(row.root);+ if (root.sequence !== row.sequence) throw new Refused('RELAY_RESPONSE', 'This board checkpoint has inconsistent coverage. Refresh the board.');+ const context = { boardId, key, sequence: row.sequence, bound,+ /** Every fetched object is authorized again under this read pin's authenticated parent path. */+ async get(id, parents) {+ const document = await read('/api/v2/boards/' + boardId + '/objects/' + id + '?pin=' + encodeURIComponent(row.read.id) + '&via=' + parents.join(','));+ if (document.apiVersion !== 2 || document.page?.id !== id) throw new Refused('RELAY_RESPONSE', 'The relay returned another history page. Refresh the board.');+ return cipher(document.page.sealed);+ },+ };+ const page = await bound(() => openPagedSnapshot(root, context, { maxEngine }));+ return {+ id: root.id,+ total: page.historyTotal,+ /** Read only the current board projection, never the complete historical tables. */+ presentation: () => bound(() => page.presentation()),+ /** The selected item opens its own sealed detail pages. */+ item: id => bound(() => page.item(id)),+ /** An addressed old message reads its numeric ranges and answer, not every earlier message. */+ shout: id => bound(() => page.shout(id)),+ /** Criteria are inspected only after the person searches. */+ searchItems: query => bound(() => page.searchItems(query)),+ /** The board has no total background deadline: each underlying object I/O and crypto operation is independently bounded. */+ history: () => page.history(),+ };+}diff --git a/relay/retention.js b/relay/retention.jsindex 45c7da84..92ad6b56 100644--- a/relay/retention.js+++ b/relay/retention.js@@ -35,9 +35,9 @@ function privateDirectory(directory) {}/** Keep lifecycle mutations in the host's trusted process; this is never an unauthenticated HTTP API. */-export function createRelayRetention({ directory, backupsDirectory = directory + '-backups', auth, now = Date.now }) {+export function createRelayRetention({ directory, backupsDirectory = directory + '-backups', auth, now = Date.now, onDelete = () => {} }) {if (typeof directory !== 'string' || !directory.trim() || typeof backupsDirectory !== 'string' ||- !backupsDirectory.trim() || typeof now !== 'function' || !auth?.linkedBoards || !auth?.forgetBoard || !auth?.withBoard || !auth?.pendingCleanup || !auth?.finishCleanup || !auth?.withCleanup) {+ !backupsDirectory.trim() || typeof now !== 'function' || typeof onDelete !== 'function' || !auth?.linkedBoards || !auth?.forgetBoard || !auth?.withBoard || !auth?.pendingCleanup || !auth?.finishCleanup || !auth?.withCleanup) {throw new Refused('RELAY_CONFIG', 'configure private relay storage, authentication and a retention clock');}const root = resolve(directory);@@ -115,6 +115,8 @@ export function createRelayRetention({ directory, backupsDirectory = directory +for (const file of files) {try { unlinkSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }}+ const result = onDelete(id);+ if (result && typeof result.then === 'function') throw new Refused('RELAY_CONFIG', 'Finish relay cleanup notices synchronously before completing deletion.');auth.finishCleanup(id);});}diff --git a/relay/service.js b/relay/service.jsindex 6588c94d..2da129b4 100644--- a/relay/service.js+++ b/relay/service.js@@ -123,7 +123,7 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOriginif (!Number.isSafeInteger(maintenanceMs) || maintenanceMs < 0 || maintenanceMs > 2_147_483_647 || (maintenanceMs > 0 && maintenanceMs < 10)) {throw new Refused('RELAY_CONFIG', 'use a maintenance interval of at least ten milliseconds, or zero for an external scheduler');}- const retention = createRelayRetention({ directory: root, backupsDirectory, auth, now });+ const retention = createRelayRetention({ directory: root, backupsDirectory, auth, now, onDelete: id => quota?.clear(id) });let maintenanceError = null;/** Expose only a stable failure code to the trusted operator; never log paths, keys or provider errors. */diff --git a/src/relay-page-layout.js b/src/relay-page-layout.jsindex d251451a..7efa9794 100644--- a/src/relay-page-layout.js+++ b/src/relay-page-layout.js@@ -6,6 +6,7 @@ const FORMAT = 'pullboard-paged-snapshot/1';const BATCH_BYTES = 131_072;const encoder = new TextEncoder();const DETAIL = new Set(['criterion', 'brief', 'verdicts', 'history', 'thread']);+export const CURRENT_SNAPSHOT_BYTES = 900_000;/** Reject an authenticated but incompatible layout before installing any of its data. */function invalid() { return new Refused('RELAY_SNAPSHOT', 'This paged board snapshot is invalid. Refresh it from a linked machine or upgrade Pullboard.'); }@@ -13,6 +14,28 @@ function invalid() { return new Refused('RELAY_SNAPSHOT', 'This paged board snap/** Preserve the current item fields while making the existing cockpit request its omitted detail. */function summary(item) { return Object.fromEntries(Object.entries(item).filter(([name]) => !DETAIL.has(name))); }+/** Bound just the first screen; the untouched complete projection and full fields remain in background/detail pages. */+export function currentSnapshotPresentation(presentation) {+ const state = presentation?.state;+ if (!state || !Array.isArray(state.items)) throw invalid();+ for (let step = 0; step < 10; step++) {+ const count = Math.max(1, 128 >> step), text = Math.max(32, 4096 >> step);+ /** Keep schema names while limiting first-screen arrays, nesting and visible text, never the retained source. */+ function limited(value, depth = 0) {+ if (typeof value === 'string') return value.length > text ? value.slice(0, text) + '…' : value;+ if (value === null || typeof value !== 'object') return value;+ if (depth >= 10) return Array.isArray(value) ? [] : {};+ if (Array.isArray(value)) return value.slice(0, count).map(child => limited(child, depth + 1));+ return Object.fromEntries(Object.entries(value).filter(([name]) => name.length <= 256).slice(0, 128)+ .map(([name, child]) => [name, limited(child, depth + 1)]));+ }+ const projected = { version: 1, config: limited(presentation.config ?? {}),+ state: Object.fromEntries(Object.entries(state).map(([name, value]) => [name, limited(name === 'items' ? value.map(summary) : value)])) };+ if (encoder.encode(JSON.stringify(projected)).byteLength <= CURRENT_SNAPSHOT_BYTES) return projected;+ }+ throw invalid();+}+/** Match the local view's criteria search without making full item histories part of a search read. */function searchText(item) { return ('#' + item.id + ' ' + item.title + ' ' + item.lane + ' ' + item.specs.join(' ') + ' ' + (item.criterion || '')).toLowerCase(); }@@ -89,11 +112,11 @@ async function rowDirectory(reference, context, field) {}/** Read only selected numeric ranges; whole-table restore and point lookup use the same authenticated walk. */-async function* readRows(reference, field, context, target = null, depth = 0) {+async function* readRows(reference, field, context, target = null, depth = 0, reverse = false) {if (depth >= 32 || (context.parents ?? []).includes(reference.id)) throw invalid();const entries = await rowDirectory(reference, context, field);const childContext = { ...context, parents: [...(context.parents ?? []), reference.id] };- for (const entry of entries) {+ for (const entry of reverse ? entries.toReversed() : entries) {if (target !== null && (target < entry.first || target > entry.last)) continue;let count = 0;if (entry.leaf) {@@ -103,11 +126,14 @@ async function* readRows(reference, field, context, target = null, depth = 0) {for (const [ordinal, row] of rows.entries()) {const key = keyOf(row, field, entry.first + ordinal);if (key <= previous || key > entry.last || (ordinal === 0 && key !== entry.first) || (ordinal === rows.length - 1 && key !== entry.last)) throw invalid();- previous = key; count++;- if (target === null || target === key) yield row;+ previous = key;+ }+ for (const [ordinal, row] of reverse ? [...rows.entries()].reverse() : rows.entries()) {+ count++;+ if (target === null || target === keyOf(row, field, entry.first + ordinal)) yield row;}} else {- for await (const row of readRows(entry.reference, field, childContext, target, depth + 1)) { count++; yield row; }+ for await (const row of readRows(entry.reference, field, childContext, target, depth + 1, reverse)) { count++; yield row; }}if (target === null && count !== entry.count) throw invalid();}@@ -122,10 +148,11 @@ export async function writePagedSnapshot(document, context) {if (document?.version !== 1 || meta.get('board_id') !== context.boardId || !Number.isSafeInteger(engine) || engine < 1 ||String(context.sequence) !== meta.get('relay_applied_sequence') || !Array.isArray(state?.items) || !Array.isArray(tables.shout)) throw invalid();const names = Object.keys(tables);- if (!names.length || names.length > PAGE_FANOUT - 4 || names.some(name => !/^[a-z][a-z0-9_]*$/u.test(name))) throw invalid();- const boot = { ...document.presentation, state: { ...state, items: state.items.map(summary) } };- delete boot.shouts;- const references = [await writeSealedValue(boot, context)];+ if (!names.length || names.length > PAGE_FANOUT - 5 || names.some(name => !/^[a-z][a-z0-9_]*$/u.test(name))) throw invalid();+ const full = { ...document.presentation, state: { ...state, items: state.items.map(summary) } };+ delete full.shouts;+ const boot = currentSnapshotPresentation(full);+ const references = [await writeSealedValue(boot, context), await writeSealedValue(full, context)];for (const name of names) references.push(await writeRows(tables[name], name === 'shout' ? 'shout_id' : null, context));const items = [...state.items].sort((a, b) => a.id - b.id);references.push(await writeRows(items, 'id', context));@@ -133,7 +160,8 @@ export async function writePagedSnapshot(document, context) {const answers = new Map();for (const row of tables.shout) if (row.shout_answers !== null && !answers.has(row.shout_answers)) answers.set(row.shout_answers, row.shout_id);references.push(await writeRows([...answers].sort(([a], [b]) => a - b).map(([id, answer]) => ({ id, answer })), 'id', context));- return writeSealedDescriptor({ format: FORMAT, version: 1, boardId: context.boardId, sequence: context.sequence, engine, tables: names }, references, context);+ const counts = { tables: Object.fromEntries(names.map(name => [name, tables[name].length])), items: items.length };+ return writeSealedDescriptor({ format: FORMAT, version: 1, boardId: context.boardId, sequence: context.sequence, engine, tables: names, counts }, references, context);}/** Open a snapshot directory without requesting its unrelated historical children. */@@ -142,16 +170,24 @@ export async function openPagedSnapshot(rawReference, context, { maxEngine } = {const { value, links } = await readSealedDescriptor(reference, context);if (value?.format !== FORMAT || value.version !== 1 || value.boardId !== context.boardId || value.sequence !== context.sequence ||!Number.isSafeInteger(value.engine) || value.engine < 1 || !Number.isSafeInteger(maxEngine) || !Array.isArray(value.tables) ||- value.tables.length + 4 !== links.length || new Set(value.tables).size !== value.tables.length ||+ value.tables.length + 5 !== links.length || new Set(value.tables).size !== value.tables.length ||value.tables.some(name => typeof name !== 'string' || !/^[a-z][a-z0-9_]*$/u.test(name))) throw invalid();if (value.engine > maxEngine) throw new Refused('ENGINE_VERSION', `This snapshot needs engine ${value.engine}; this device reads ${maxEngine}. Upgrade Pullboard before reading the board.`);+ const counts = value.counts;+ if (!counts?.tables || Object.keys(counts.tables).length !== value.tables.length || !Number.isSafeInteger(counts.items) || counts.items < 0 ||+ value.tables.some(name => !Object.hasOwn(counts.tables, name) || !Number.isSafeInteger(counts.tables[name]) || counts.tables[name] < 0)) throw invalid();+ const historyTotal = counts.items + Object.values(counts.tables).reduce((sum, count) => sum + count, 0);+ if (!Number.isSafeInteger(historyTotal)) throw invalid();const childContext = { ...context, parents: [...(context.parents ?? []), reference.id] };- const tableReferences = new Map(value.tables.map((name, index) => [name, links[index + 1]]));- const [details, search, answers] = links.slice(value.tables.length + 1);+ const tableReferences = new Map(value.tables.map((name, index) => [name, links[index + 2]]));+ const [details, search, answers] = links.slice(value.tables.length + 2);if (!tableReferences.has('board_meta') || !tableReferences.has('shout')) throw invalid();let current;/** Cache only the current presentation, not arbitrary historical pages. */- async function presentation() { return current ??= await readSealedValue(links[0], childContext); }+ async function presentation() {+ if (links[0].bytes > CURRENT_SNAPSHOT_BYTES) throw invalid();+ return current ??= await readSealedValue(links[0], childContext, { maxBytes: CURRENT_SNAPSHOT_BYTES });+ }/** Resolve one keyed row without reading sibling history pages. */async function find(ref, field, id) {if (!Number.isSafeInteger(id) || id < 0) throw invalid();@@ -164,10 +200,12 @@ export async function openPagedSnapshot(rawReference, context, { maxEngine } = {for (const [name, ref] of tableReferences) {tables[name] = [];for await (const row of readRows(ref, name === 'shout' ? 'shout_id' : null, childContext)) tables[name].push(row);+ if (tables[name].length !== counts.tables[name]) throw invalid();}- const boot = await presentation();+ const boot = await readSealedValue(links[1], childContext);const allItems = new Map();for await (const row of readRows(details, 'id', childContext)) allItems.set(row.id, row);+ if (allItems.size !== counts.items) throw invalid();const items = boot.state.items.map(item => { const full = allItems.get(item.id); if (!full) throw invalid(); return full; });return { version: 1, tables, presentation: { ...boot, state: { ...boot.state, items }, shouts: tables.shout } };}@@ -196,5 +234,31 @@ export async function openPagedSnapshot(rawReference, context, { maxEngine } = {if (!found) throw new Refused('NO_ITEM', `no item #${id}`);return found;}- return { version: 1, engine: value.engine, presentation, native, item, shout, searchItems };+ /** Stream every retained table and full item detail newest first after current state has already rendered. */+ async function* history() {+ yield { kind: 'presentation', value: await readSealedValue(links[1], childContext) };+ const tables = ['shout', 'event', ...value.tables.filter(name => !['shout', 'event'].includes(name))];+ for (const name of tables) {+ const ref = tableReferences.get(name);+ if (!ref) continue;+ let rows = [], size = 0, loaded = 0;+ for await (const row of readRows(ref, name === 'shout' ? 'shout_id' : null, childContext, null, 0, true)) {+ rows.push(row); loaded++;+ size += encoder.encode(JSON.stringify(row)).byteLength;+ if (rows.length === PAGE_FANOUT || size >= BATCH_BYTES) { yield { kind: 'table', name, rows }; rows = []; size = 0; }+ }+ if (rows.length) yield { kind: 'table', name, rows };+ if (loaded !== counts.tables[name]) throw invalid();+ }+ let rows = [], size = 0, loaded = 0;+ for await (const row of readRows(details, 'id', childContext, null, 0, true)) {+ rows.push(row); loaded++;+ size += encoder.encode(JSON.stringify(row)).byteLength;+ if (rows.length === PAGE_FANOUT || size >= BATCH_BYTES) { yield { kind: 'items', rows }; rows = []; size = 0; }+ }+ if (rows.length) yield { kind: 'items', rows };+ if (loaded !== counts.items) throw invalid();+ yield { kind: 'complete', sequence: value.sequence };+ }+ return { version: 1, engine: value.engine, historyTotal, presentation, native, item, shout, searchItems, history };}diff --git a/src/sealed-pages.js b/src/sealed-pages.jsindex b3abddc5..ce7b85b3 100644--- a/src/sealed-pages.js+++ b/src/sealed-pages.js@@ -129,6 +129,7 @@ export async function writeSealedValue(value, context) {/** Authenticate, bound inflation and parse a single object before interpreting its references. */async function readPage(reference, context, parents = []) {+ if (typeof context.bound === 'function') return context.bound(() => readPage(reference, { ...context, bound: undefined }, parents));const received = await context.get(reference.id, parents);if (!(received instanceof Uint8Array) || received.byteLength > PAGE_CIPHER_BYTES || await pageDigest(received) !== reference.id) throw invalid();const compressed = await unseal(context.key, received, { boardId: context.boardId, kind: 'snapshot', sequence: reference.sequence });diff --git a/test/relay-page-layout.test.js b/test/relay-page-layout.test.jsindex 8076baff..001c5878 100644--- a/test/relay-page-layout.test.js+++ b/test/relay-page-layout.test.js@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';import { randomBytes } from 'node:crypto';import { test } from 'node:test';import { generateBoardKey } from '../src/seal.js';-import { openPagedSnapshot, writePagedSnapshot } from '../src/relay-page-layout.js';+import { CURRENT_SNAPSHOT_BYTES, currentSnapshotPresentation, openPagedSnapshot, writePagedSnapshot } from '../src/relay-page-layout.js';import { readSealedDescriptor, writeSealedDescriptor } from '../src/sealed-pages.js';/** Keep synthetic cipher objects and prove every requested history path belongs to the selected root. */@@ -124,3 +124,47 @@ test('invalid history ranges and duplicate root tables cannot become a partial bbox.document.tables.shout[1].shout_id = 1;await assert.rejects(writePagedSnapshot(box.document, box.context), { code: 'RELAY_SNAPSHOT' });});++test('bounded current state precedes thirty thousand events and complete background history arrives newest first [H15,H17]', async () => {+ const box = await fixture();+ box.document.tables.event = Array.from({ length: 30_000 }, (_, index) => ({ event_id: index + 1, event_detail: 'Preserved historical event ' + index }));+ box.document.presentation.state.items = Array.from({ length: 2000 }, (_, index) => ({ id: index + 1, title: 'A long item title '.repeat(250),+ lane: 'core', specs: ['H17'], criterion: 'A full governing requirement '.repeat(100), brief: 'Retained detail', verdicts: [], history: [], thread: [] }));+ const original = JSON.stringify(box.document.presentation);+ const root = await box.publish();+ const page = await openPagedSnapshot(root, box.context, { maxEngine: 56 });+ const boot = await page.presentation();+ assert.ok(Buffer.byteLength(JSON.stringify(boot)) < CURRENT_SNAPSHOT_BYTES && CURRENT_SNAPSHOT_BYTES < 1_000_000);+ assert.ok(boot.state.items.length < 2000);+ assert.ok(box.reads.length < 8, 'the thirty-thousand-event history is not part of startup');+ let events = 0, lastEvent = Infinity, shouts = 0, lastShout = Infinity, items = 0, full = null, complete = false;+ for await (const chunk of page.history()) {+ if (chunk.kind === 'presentation') full = chunk.value;+ if (chunk.kind === 'table' && chunk.name === 'event') for (const row of chunk.rows) {+ assert.ok(row.event_id < lastEvent); lastEvent = row.event_id; events++;+ }+ if (chunk.kind === 'table' && chunk.name === 'shout') for (const row of chunk.rows) {+ assert.ok(row.shout_id < lastShout); lastShout = row.shout_id; shouts++;+ }+ if (chunk.kind === 'items') items += chunk.rows.length;+ if (chunk.kind === 'complete') complete = true;+ }+ assert.equal(events, 30_000); assert.equal(lastEvent, 1);+ assert.equal(shouts, 4200); assert.equal(lastShout, 1);+ assert.equal(items, 2000); assert.equal(full.state.items.length, 2000); assert.equal(complete, true);+ assert.equal(page.historyTotal, Object.values(box.document.tables).reduce((sum, rows) => sum + rows.length, 0) + 2000);+ assert.equal(JSON.stringify(box.document.presentation), original, 'initial-screen bounds never truncate retained source data');+ assert.equal((await page.shout(1)).shout_text, 'Historical work 0');+});++test('a huge current field is bounded only on first paint and remains complete in detail [H15,H17]', async () => {+ const box = await fixture();+ const text = 'Large current title '.repeat(100_000);+ box.document.presentation.state.items[0].title = text;+ const direct = currentSnapshotPresentation(box.document.presentation);+ assert.ok(Buffer.byteLength(JSON.stringify(direct)) < 1_000_000);+ const root = await box.publish();+ const page = await openPagedSnapshot(root, box.context, { maxEngine: 56 });+ assert.ok((await page.presentation()).state.items[0].title.length < text.length);+ assert.equal((await page.item(90)).title, text);+});diff --git a/test/relay-pages-http.test.js b/test/relay-pages-http.test.jsindex 071a5f83..2f1c373c 100644--- a/test/relay-pages-http.test.js+++ b/test/relay-pages-http.test.js@@ -135,6 +135,11 @@ test('an account quota refusal preserves the readable head and is named in phoneconst boards = await box.call('GET', '/api/v1/boards');assert.ok(boards.document.warnings.some(warning => warning.board === BOARD && warning.code === 'ACCOUNT_STORAGE_LIMIT'));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');+ const relinked = await box.call('GET', '/api/v1/boards');+ assert.ok(!(relinked.document.warnings ?? []).some(warning => warning.board === BOARD && warning.code === 'ACCOUNT_STORAGE_LIMIT'),+ 'unlink clears the prior failed-upload notice before a fresh link has its first snapshot');});test('all page reads reauthorize the board and a readable agent cannot replace a snapshot [H15,H17]', async t => {