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(parity): retain local health outside sealed state [H5,H17]

Corey Olson0ac5ff65cfcb
diff --cc src/api.js
index 29cb9af1,10a08b03..c5f3bd91
--- a/src/api.js
+++ b/src/api.js
@@@ -1,8 -1,9 +1,11 @@@
+import { buildLocalBoardState } from './native-board-state.js';
- import { dependencyIds } from './native-board-state.js';
+import { stateFileInputs } from './native-board-state.js';
+import { fileRevision } from './native-board-state.js';
+import { nativeStateClockMatches } from './native-state-clock.js';
+ import { foreignDependencyStates } from './cross-repo-dependencies.js';
+ import {
- dependencyValues,
- hasForeignDependencies,
+ localDependencyIds,
+ } from './item-dependencies.js';
/** The local API v1: the CLI's moves, persistent board identities and live events (A2). */
import {
createHash,
@@@ -880,7 -1027,6 +893,8 @@@ export function createLocalApiHandler(
onItemBuild,
projects: apiProjects,
scopeCommonDir,
+ observedAt,
++ localRelayHealth: relayCanaryNeeds(board.root),
}), codeIsMain);
const state = { ...built.state, sequence: built.sequence };
const entry = snapshotEntry(before.revision, state, prepareFlowHistory(built.history), {
diff --cc src/native-board-state.js
index 99829e40,00000000..d9787c63
mode 100644,000000..100644
--- a/src/native-board-state.js
+++ b/src/native-board-state.js
@@@ -1,154 -1,0 +1,160 @@@
+/** One complete native state builder for local HTTP and sealed relay projections [A2,H5,H16]. */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONFIG_FILE } from './config.js';
+import { fitFile } from './blueprint-fit.js';
+import { BLOCKS_FILE } from './blocks.js';
+import * as store from './board.js';
+import { displayAgentName } from './agent-names.js';
+import { COORDINATOR } from './config.js';
+import { loadConfig } from './config.js';
+import { repoInfo } from './git.js';
+import { listApiProjects } from './projects.js';
+import { nativeStateClockWindow } from './native-state-clock.js';
+import { milestoneRoadmap } from './roadmap.js';
+import { proofStats } from './stats.js';
+import { ruleProofCounts } from './rule-proof-counts.js';
+import { milestoneNamesByItem } from './item-list.js';
+import { withListFields } from './item-list.js';
+import { projectRowDecisions } from './row-decisions.js';
+import { projectSpecApprovals } from './spec-approval.js';
+import { specApprovalState } from './spec-approval.js';
+import { pendingFit } from './blueprint-fit.js';
+import { projectFit } from './blueprint-fit.js';
+import { personBlockWords } from './blocks.js';
+import { verdictProjector } from './verdict-freshness.js';
+import { trunkRevisionReader } from './trunk-revision.js';
+import { projectState } from './serve.js';
+import { personRequestStatuses } from './relay-requests.js';
++import { dependencyValues, hasForeignDependencies } from './item-dependencies.js';
+
+/** Build the complete local API state, including fields that the shared project snapshot omits. */
- export function buildLocalBoardState(root, boardId, board, codeIsMain, { previous = null, fullItemRebuild = true, afterSequence = 0, changedLeases = new Set(), onItemBuild, projects = listApiProjects, scopeCommonDir = null, observedAt = Date.now(), freshnessReader = null } = {}) {
++export function buildLocalBoardState(root, boardId, board, codeIsMain, { previous = null, fullItemRebuild = true, afterSequence = 0, changedLeases = new Set(), onItemBuild, projects = listApiProjects, scopeCommonDir = null, observedAt = Date.now(), freshnessReader = null, localRelayHealth = null } = {}) {
+ if (!Number.isSafeInteger(observedAt) || observedAt < 0) throw new TypeError('native projection needs an observation timestamp');
+ board = Object.assign(Object.create(board), { clock: { ...board.clock, now: () => new Date(observedAt) } });
+ board.db.exec('BEGIN');
+ try {
+ const sequence = board.db.prepare('SELECT COALESCE(MAX(event_id), 0) AS id FROM event').get().id;
+ let rebuildAll = fullItemRebuild || (previous && previous.sequence > sequence);
- const eventRows = rebuildAll || !previous ? [] : board.db.prepare('SELECT event_id, item_id FROM event WHERE event_id > ? ORDER BY event_id').all(afterSequence);
++ const eventRows = rebuildAll || !previous ? [] : board.db.prepare('SELECT event_id, item_id, event_kind FROM event WHERE event_id > ? ORDER BY event_id').all(afterSequence);
+ if (!rebuildAll && previous && eventRows.length !== sequence - previous.sequence) rebuildAll = true;
+ const dirtyIds = new Set(rebuildAll ? [] : [...changedLeases]);
+ for (const event of eventRows) if (event.item_id !== null) dirtyIds.add(event.item_id);
+
++ const foreignChanged = eventRows.some(event => event.event_kind === 'board_link_state' || event.event_kind === 'board_link');
+ const currentItems = store.listItems(board, { all: true });
+ const currentById = new Map(currentItems.map((item) => [item.item_id, item]));
+ const currentDependencies = new Map(currentItems.map((item) => [item.item_id, dependencyIds(item)]));
+ const milestoneNames = milestoneNamesByItem(store.milestones(board));
+ for (const prior of previous?.itemMeta.values() ?? []) {
+ if (!currentById.has(prior.id)) dirtyIds.add(prior.id);
+ }
+ for (const item of currentItems) {
+ const prior = previous?.itemMeta.get(item.item_id);
++ // E32 announcements and consent changes carry no local item_id, but change foreign blockers.
++ if (foreignChanged && hasForeignDependencies(item)) dirtyIds.add(item.item_id);
+ if (rebuildAll || !previous?.items.has(item.item_id) || !prior || prior.raw !== JSON.stringify(item)) dirtyIds.add(item.item_id);
+ if (prior && prior.milestone !== (milestoneNames.get(item.item_id) ?? null)) dirtyIds.add(item.item_id);
+ }
+ // A dirty item's status affects the blockedBy list of every direct old or new dependent.
+ const changedIds = [...dirtyIds];
+ for (const dependent of previous?.itemMeta.values() ?? []) {
+ if (changedIds.some((id) => dependent.dependencies.includes(id))) dirtyIds.add(dependent.id);
+ }
+ for (const [id, dependencies] of currentDependencies) {
+ if (changedIds.some((changed) => dependencies.includes(changed))) dirtyIds.add(id);
+ }
+
+ const config = loadConfig(root);
+ const freshness = freshnessReader ?? verdictProjector(root, board, { main: trunkRevisionReader(repoInfo(root))() }).state;
+ const state = projectState(root, { seen: null, board, itemProjector: (item, context) => {
+ if (dirtyIds.has(item.item_id)) {
+ const projected = context.project();
+ const verdictState = freshness(item);
+ return verdictState ? { ...projected, verdictState } : projected;
+ }
+ return previous.items.get(item.item_id);
+ } });
+ state.agents = state.agents.map((agent) => ({ ...agent, model: agent.agent_model ?? 'unknown', displayName: displayAgentName(agent, config.agents.names) }));
+ state.board = boardId;
+ state.observedAt = new Date(observedAt).toISOString();
+ state.decisionQueue = store.openDecisions(board, COORDINATOR);
+ const projectData = {
+ requests: store.openRequests(board),
+ personRequests: personRequestStatuses(board),
+ milestones: scopeCommonDir === null
+ ? milestoneRoadmap(root, board)
+ : milestoneRoadmap(root, board, { projects, hideOutOfScope: true }),
+ rowDecisions: store.rowDecisions(board),
+ proofStats: proofStats(board, { now: observedAt }),
+ };
+ state.proofStats = projectData.proofStats;
+ state.requests = projectData.requests;
+ state.personRequests = projectData.personRequests;
+ state.milestones = projectData.milestones;
+ state.blocks = personBlockWords(repoInfo(root).commonDir, board.clock.now()); // Needs you below is recomputed with them [C6].
++ // Only the local HTTP host supplies its private telemetry; sealed projections omit it entirely.
++ if (localRelayHealth !== null) state.relayHealthAlerts = localRelayHealth;
+ const decorated = projectSpecApprovals(projectFit(pendingFit(repoInfo(root).commonDir), projectRowDecisions(projectData.rowDecisions, state)), specApprovalState(root, { board, config }));
+ decorated.ruleCounts = ruleProofCounts(root, board, decorated.spec);
+ const bases = new Map(decorated.items.map((item) => [item.id, item]));
+ for (const id of dirtyIds) {
+ if (!currentById.has(id)) continue;
+ const item = store.getItem(board, id);
+ const base = bases.get(id);
+ const full = {
+ ...base,
+ check: item.item_check,
+ ...(item.item_check_baseline ? { checkBaseline: item.item_check_baseline } : {}),
+ thread: store.itemThread(board, id),
+ };
+ bases.set(id, full);
+ onItemBuild?.({ board: boardId, itemId: id });
+ }
+ decorated.items = decorated.items.map((item) => bases.get(item.id) ?? item);
+ const leases = new Map(currentItems.map((item) => [item.item_id, item.item_lease_until ?? null]));
+ const listFields = withListFields(decorated, leases, { previous, dirtyIds });
+ const itemMeta = new Map(currentItems.map((item) => [item.item_id, {
+ id: item.item_id,
+ raw: JSON.stringify(item),
+ dependencies: currentDependencies.get(item.item_id) ?? [],
+ milestone: milestoneNames.get(item.item_id) ?? null,
+ }]));
+ const history = store.events(board);
+ const clockWindow = nativeStateClockWindow(listFields.state, history, currentItems, observedAt);
+ board.db.exec('COMMIT');
+ return { state: listFields.state, itemMeta, itemMoveCounts: listFields.itemMoveCounts, sequence, history, clockWindow };
+ } catch (error) {
+ try { board.db.exec('ROLLBACK'); } catch { /* Preserve the projection failure. */ }
+ throw error;
+ }
+}
+
+/** Parse an item's ordered prerequisite IDs from its persisted row. */
+export function dependencyIds(item) {
- return item.item_after ? item.item_after.split(',').map(Number) : [];
++ return dependencyValues(item);
+}
+
+
+/** Name project and built-in files separately, even when their basenames collide. */
+export function stateFileInputs(root, config) {
+ return [
+ { name: `config:${CONFIG_FILE}`, path: join(root, CONFIG_FILE) },
+ { name: `spec:${config.spec}`, path: join(root, config.spec) },
+ { name: `practice:${config.practice}`, path: join(root, config.practice) },
+ { name: 'builtin:standard-doctrine.md', path: new URL('./standard-doctrine.md', import.meta.url) },
+ ...['signoffs.jsonl', 'signers', 'first-commit', 'signers.initial'].map(name => ({ name: `approval:${name}`, path: join(root, '.pullboard', name) })),
+ { name: 'fit:blueprint-fit.json', path: fitFile(repoInfo(root).commonDir) },
+ // A new block changes Needs you without a board move, so the ledger is a state input [C6].
+ { name: 'blocks:blocks.jsonl', path: join(repoInfo(root).commonDir, BLOCKS_FILE) },
+ ];
+}
+
+/** Hash the exact bytes of one named input, preserving a missing-file marker. */
+export function fileRevision(file) {
+ if (!existsSync(file.path)) return [file.name, null];
+ return [file.name, createHash('sha256').update(readFileSync(file.path)).digest('hex')];
+}
+
diff --cc test/relay-parity-fixture.js
index e347914a,00000000..dc82b331
mode 100644,000000..100644
--- a/test/relay-parity-fixture.js
+++ b/test/relay-parity-fixture.js
@@@ -1,107 -1,0 +1,114 @@@
+/** Real loopback relay and complete native API observations for reader parity [H5,H15,H16,A2]. */
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as store from '../src/board.js';
+import { decodeBoardKey } from '../src/seal.js';
+import { relayPresentation } from '../src/relay-presentation.js';
+import { presentationDigest } from '../src/relay-presentation.js';
++import { observeRelayHealth } from '../src/relay-canary-health.js';
+import { runFixtureChild } from './fixture-child.js';
+import { runFixtureChildAsync } from './fixture-child.js';
+export { assertReaderParity } from './relay-parity-reader.js';
+import { createParityReader } from './relay-parity-reader.js';
+import { relayClientFixture } from './relay-client-fixture.js';
+
+/** Seed actual native writes, keeping the operation receipts available for the fail-closed coverage inventory. */
+export function seedParityBoard(root, lane) {
+ const board = store.openBoard(join(root, '.git', 'pullboard', 'board.sqlite'));
+ const exercised = new Set(['register', 'ensureCoordinator']); // The real fixture init executes these operations.
+ /** Record only an operation whose actual native call returned successfully. */
+ function moved(operation, action) { const result = action(); exercised.add(operation); return result; }
+ try {
+ const item = moved('addItem', () => store.addItem(board, { by: 'coordinator', lane, title: 'Reader parity lifecycle', criterion: 'Same native and relay fields' }));
+ moved('editItem', () => store.editItem(board, item, { agentId: 'coordinator', brief: 'Reader parity updated' }));
+ moved('shout', () => store.shout(board, { from: 'coordinator', to: 'person', text: 'Reader parity question', decision: true }));
+ moved('addMilestone', () => store.addMilestone(board, { agentId: 'coordinator', name: 'Reader parity release' }));
+ return { exercised: [...exercised], item };
+ } finally { store.closeBoard(board); }
+}
+
+/** Clock advancement alone is not a board change, while a real native mutation always is. */
+function assertPresentationChangeClock(root, item) {
+ const first = relayPresentation(root, { observedAt: Date.UTC(2026, 0, 1) });
+ const later = relayPresentation(root, { observedAt: Date.UTC(2026, 0, 2) });
+ assert.notEqual(first.state.observedAt, later.state.observedAt, 'emitted observations retain their actual caller clock');
+ assert.equal(presentationDigest(first), presentationDigest(later), 'an unchanged board does not publish merely because its clock advanced');
+ const board = store.openBoard(join(root, '.git', 'pullboard', 'board.sqlite'));
+ try { store.editItem(board, item, { agentId: 'coordinator', brief: 'Business input changed after the clock-only observation.' }); }
+ finally { store.closeBoard(board); }
+ const changed = relayPresentation(root, { observedAt: Date.UTC(2026, 0, 2) });
+ assert.notEqual(presentationDigest(later), presentationDigest(changed), 'a real business mutation changes the fingerprint at the same observation clock');
+}
+
+/** Give a scoped board a genuine foreign milestone target whose private title must stay outside its key. */
+function foreignBoardFixture(t, box) {
+ const root = mkdtempSync(join(tmpdir(), 'pullboard-parity-foreign-'));
+ t.after(() => rmSync(root, { recursive: true, force: true }));
+ assert.equal(runFixtureChild('git', ['init', '-q', '-b', 'main'], { cwd: root, env: box.env, encoding: 'utf8' }).status, 0);
+ mkdirSync(join(root, '.git', 'pullboard'), { recursive: true });
+ const board = store.openBoard(join(root, '.git', 'pullboard', 'board.sqlite'));
+ const secret = 'Foreign board private title must never enter another board snapshot';
+ let id;
+ try {
+ store.ensureCoordinator(board, root);
+ id = store.addItem(board, { by: 'coordinator', lane: box.lane, title: secret, criterion: 'Private second-board work' });
+ } finally { store.closeBoard(board); }
+ const own = store.openBoard(join(box.root, '.git', 'pullboard', 'board.sqlite'));
+ try { store.addMilestone(own, { agentId: 'coordinator', name: 'Cross-board privacy', items: [`foreign-parity#${id}`] }); }
+ finally { store.closeBoard(own); }
+ return { root, name: 'foreign-parity', secret };
+}
+
+/** Capture full API state and independently reconstruct the sealed API2 snapshot over actual authenticated HTTP. */
- export async function parityRoundtrip(t, { foreign = false } = {}) {
++export async function parityRoundtrip(t, { foreign = false, localHealth = false } = {}) {
+ const box = await relayClientFixture(t);
+ const seeded = seedParityBoard(box.root, box.lane);
+ const other = foreign ? foreignBoardFixture(t, box) : null;
+ assertPresentationChangeClock(box.root, seeded.item);
++ if (localHealth) {
++ const now = Date.now();
++ for (const at of [now - 1, now]) observeRelayHealth(box.root, {
++ ok: false, step: 'pull', code: 'RELAY_UNREACHABLE', roundTripMs: 1, relayVersion: 1,
++ }, { now: at });
++ }
+ await box.link();
+ const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));
+ const key = decodeBoardKey(readFileSync(box.keyFile, 'utf8').trim());
+ const session = await box.phoneSession();
+ const reader = await createParityReader({ root: box.root, origin: box.origin, token: session.token, boardId: link.board, key,
+ projects: () => [{ root: box.root, name: 'parity' }, ...(other ? [other] : [])] });
+ t.after(reader.close);
+ const { native, relay, restored } = await reader.read();
+ if (other) {
+ assert.ok(!JSON.stringify(restored).includes(other.secret), 'the actual sealed native snapshot never carries the foreign title');
+ const scoped = relay.milestones.find(milestone => milestone.name === 'Cross-board privacy');
+ assert.ok(scoped, 'the cross-board milestone remains visible');
+ assert.ok(JSON.stringify(scoped).includes('unavailable'), 'the external reference is an unavailable obligation');
+ assert.ok(!JSON.stringify(scoped).includes('foreign-parity'), 'the external project reference remains redacted');
+ }
+ /** One genuine private-environment process retains native and HTTP clients for the full declared operation inventory. */
+ async function exerciseOperations() {
+ const module = new URL('./relay-parity-operations.js', import.meta.url).href;
+ const parameters = { root: box.root, origin: box.origin, token: session.token, boardId: link.board, lane: box.lane, keyFile: box.keyFile };
+ const file = join(box.root, '.git', 'pullboard', 'parity-reader-session.json');
+ writeFileSync(file, JSON.stringify(parameters), { mode: 0o600 });
+ try {
+ const running = runFixtureChildAsync(process.execPath, ['--input-type=module', '-e', `import { readFileSync } from 'node:fs';
+import { exerciseOperationParity } from ${JSON.stringify(module)};
+try { console.log(JSON.stringify(await exerciseOperationParity(JSON.parse(readFileSync(${JSON.stringify(file)}, 'utf8'))))); } catch (error) { console.log(JSON.stringify({ error: error.message })); process.exitCode = 1; }`], { cwd: box.root, env: box.env, signal: t.signal });
+ t.after(async () => {
+ if (running.child.exitCode === null && running.child.signalCode === null) running.child.kill('SIGTERM');
+ await running;
+ });
+ const result = await running;
+ let document;
+ try { document = JSON.parse(result.stdout.trim()); }
+ catch { assert.fail(`operation child did not return JSON: ${result.failure ?? result.context}`); }
+ assert.equal(result.status, 0, `${document.error ?? 'operation child failed'}\n${result.failure ?? result.context}`);
+ return document;
+ } finally { rmSync(file, { force: true }); }
+ }
- return { native, relay, exercised: seeded.exercised, exerciseOperations };
++ return { native, relay, restored, exercised: seeded.exercised, exerciseOperations };
+}
diff --cc test/relay-parity-reader.js
index 2870069e,00000000..309888fb
mode 100644,000000..100644
--- a/test/relay-parity-reader.js
+++ b/test/relay-parity-reader.js
@@@ -1,66 -1,0 +1,73 @@@
+/** Complete authenticated HTTP and pinned API2 reader oracle [H5,H16,A2]. */
+import assert from 'node:assert/strict';
+import { randomBytes } from 'node:crypto';
+import { serveApi } from '../src/api.js';
+import { main } from '../src/cli.js';
+import { ENGINE_VERSION } from '../src/machine.js';
+import { openPagedSnapshot } from '../src/relay-page-layout.js';
+import { snapshotState } from '../relay/browser-model.js';
+
- /** Only the native filesystem routing identity differs deliberately from the relay board identity. */
++/** Deliberate machine-local differences; all other fields retain complete reader parity. */
+export const LOCAL_PARITY_FIELDS = Object.freeze([
+ { path: 'root', reason: 'Native routing uses a local repository directory; a relay reader routes by persistent board id.' },
++ { path: 'relayHealthAlerts', reason: 'Canary observations are private telemetry on this local client, never sealed board state.' },
++ { path: 'needs', kind: 'relay-health', reason: 'Only Needs derived from this local client canary stay on that client.' },
+]);
+
+/** Report the first undeclared field difference with both actual values, including missing keys. */
+export function assertReaderParity(native, relay, localFields = LOCAL_PARITY_FIELDS) {
- const ignored = new Set(localFields.map(entry => entry.path));
++ const ignored = new Set(localFields.filter(entry => !entry.kind).map(entry => entry.path));
+ assert.ok(localFields.every(entry => entry.path && entry.reason?.trim()), 'every local-only field has a reason');
+ /** Compare structure as well as values; a missing field is never equivalent to an explicit null. */
+ function compare(left, right, path) {
+ if (ignored.has(path)) return;
++ const localKinds = localFields.filter(entry => entry.path === path && entry.kind).map(entry => entry.kind);
++ if (localKinds.length && Array.isArray(left) && Array.isArray(right)) {
++ left = left.filter(entry => !localKinds.includes(entry.kind));
++ right = right.filter(entry => !localKinds.includes(entry.kind));
++ }
+ const label = value => value === undefined ? '<missing>' : JSON.stringify(value);
+ if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object') {
+ assert.deepEqual(left, right, `reader parity ${path}: native=${label(left)} relay=${label(right)}`);
+ return;
+ }
+ assert.equal(Array.isArray(left), Array.isArray(right), `reader parity ${path}: native=${label(left)} relay=${label(right)}`);
+ for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) compare(left[key], right[key], path ? `${path}.${key}` : key);
+ }
+ compare(native, relay, '');
+}
+
+/** Retain both real service clients across native mutations without starting another CLI process. */
+export async function createParityReader({ root, origin, token, boardId, key, projects = () => [{ root, name: 'parity' }] }) {
+ let observedAt = Date.now();
+ const secret = randomBytes(24).toString('base64url');
+ const api = await serveApi({ secret, runCommand: main, projects, isMain: true, stateDetail: 'full', scope: { projectRoot: root }, now: () => observedAt });
+ /** Read the current exact sealed clock, then ask the complete native HTTP API at that clock. */
+ async function read() {
+ /** Request through a distinct authenticated person session, never a direct journal read. */
+ async function request(path) {
+ const response = await fetch(origin + path, { headers: { authorization: `Bearer ${token}`, 'x-pullboard-engine': String(ENGINE_VERSION) } });
+ assert.equal(response.status, 200, `relay parity reader GET ${path.split('?')[0]}`);
+ return response.json();
+ }
+ const document = await request(`/api/v2/boards/${boardId}/state`);
+ assert.equal(document.apiVersion, 2, 'current snapshot transport is exercised');
+ const saved = document.state;
+ const page = await openPagedSnapshot(saved.root, { key, boardId, sequence: saved.sequence,
+ /** Fetch only the pinned, reachable sealed object graph through its actual service boundary. */
+ async get(id, parents) {
+ const object = await request(`/api/v2/boards/${boardId}/objects/${id}?pin=${encodeURIComponent(saved.read.id)}&via=${parents.join(',')}`);
+ return Uint8Array.from(Buffer.from(object.page.sealed, 'base64url'));
+ },
+ }, { maxEngine: ENGINE_VERSION });
+ const restored = await page.native();
+ const relay = snapshotState(restored, boardId);
+ observedAt = Date.parse(relay.observedAt);
+ assert.ok(Number.isSafeInteger(observedAt), 'the sealed projection carries its explicit observation clock');
+ const nativeResponse = await fetch(`http://127.0.0.1:${api.port}/api/v1/boards/${boardId}/state?detail=full`, { headers: { 'x-pullboard-key': secret } });
+ assert.equal(nativeResponse.status, 200, 'complete native API state is available');
+ const native = (await nativeResponse.json()).state;
+ return { native, relay, restored };
+ }
+ return { read, close: api.close };
+}
diff --cc test/relay-parity.test.js
index 4ad87270,00000000..1626b8b8
mode 100644,000000..100644
--- a/test/relay-parity.test.js
+++ b/test/relay-parity.test.js
@@@ -1,23 -1,0 +1,34 @@@
+/** Native API and actual sealed relay readers must expose the same board [H5,H15,H16,A2]. */
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { parityRoundtrip, assertReaderParity } from './relay-parity-fixture.js';
+
+test('a field that differs between native and relay readers is refused, naming the field [H5,H16,A2]', { timeout: 60_000 }, async t => { // budget: criterion's sixty-second guard ceiling, including real local HTTP and cleanup.
+ const { native, relay, exerciseOperations } = await parityRoundtrip(t);
+ const live = native.agents.find(agent => agent.heartbeatAt !== null);
+ assert.ok(live, 'a real native heartbeat is present in the seed');
+ const missingHeartbeat = structuredClone(native);
+ delete missingHeartbeat.agents.find(agent => agent.agent_id === live.agent_id).heartbeatAt;
+ assert.throws(() => assertReaderParity(native, missingHeartbeat), error => /agents\.\d+\.heartbeatAt/u.test(error.message)
+ && error.message.includes('native=') && error.message.includes('relay=<missing>'), 'the deliberate heartbeat removal names its exact field and both values');
+ assertReaderParity(native, relay);
+ const inventory = await exerciseOperations();
+ assert.deepEqual(inventory.covered, inventory.declared, 'every declared operation passes complete reader parity');
+});
+
+
+test('single-board parity never seals another board title through a milestone reference [H5,H16,A2]', { timeout: 60_000 }, async t => { // budget: the same real transport and cleanup ceiling as the parity guard.
+ const { native, relay } = await parityRoundtrip(t, { foreign: true });
+ assertReaderParity(native, relay);
+});
++
++test('local relay health and its Needs stay outside sealed state without hiding other differences [H5,H16,A2]', { timeout: 60_000 }, async t => { // budget: real local HTTP, sealed snapshot retrieval and cleanup under the guard ceiling.
++ const { native, relay, restored } = await parityRoundtrip(t, { localHealth: true });
++ assert.equal(native.relayHealthAlerts.length, 1, 'actual private canary failures remain visible locally');
++ assert.ok(native.needs.some(entry => entry.kind === 'relay-health'), 'local Needs retains the derived alert');
++ assert.equal(Object.hasOwn(restored.presentation.state, 'relayHealthAlerts'), false, 'sealed state omits the private telemetry field');
++ assert.ok(!restored.presentation.state.needs.some(entry => entry.kind === 'relay-health'), 'sealed Needs omits the private alert');
++ assertReaderParity(native, relay);
++ assert.throws(() => assertReaderParity(native, { ...relay, needs: [...relay.needs, { kind: 'undeclared-difference' }] }),
++ /reader parity needs/u, 'other Needs differences remain refused');
++});