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
fix(api): serve item detail by index from a per-item cache [N26]
Corey Olsonea987a80fe26
diff --git a/src/api-http.js b/src/api-http.jsindex 04aeca83..ac514f50 100644--- a/src/api-http.js+++ b/src/api-http.js@@ -1,4 +1,5 @@/** API v1's shared HTTP boundary; local and relay adapters supply the same board operations (A2). */+import { createHash } from 'node:crypto';import { Refused } from './refused.js';import { relayStorage } from './relay-storage.js';import { refusalDocument } from './json.js';@@ -21,11 +22,32 @@ function json(res, status, value) {res.end(JSON.stringify({ version: 1, ...value }));}-/** Emit a local adapter's pre-serialized state inside the unchanged API v1 envelope. */-function jsonState(res, status, state, eventLogVersion) {- res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff' });+/** A local adapter's pre-serialized state inside the unchanged API v1 envelope. */+function stateText(state, eventLogVersion) {const version = eventLogVersion === undefined ? '' : ',"eventLogVersion":' + JSON.stringify(eventLogVersion);- res.end('{"version":1,"state":' + state + version + '}');+ return '{"version":1,"state":' + state + version + '}';+}++/**+ * Send a state reply. A revalidating server (the local one) tags it with a digest of its text and+ * answers 304 Not Modified with no body when the caller's If-None-Match already names it, so a poll+ * of an unchanged board sends nothing, and lets the browser keep the reply privately and ask again+ * on every poll (#1040). The digest blanks the clock readings stamped afresh on every read (flow+ * asOf, queue ageMinutes), as the view's own board comparison does (#644). Other adapters keep no-store.+ */+function sendState(req, res, text, revalidate) {+ const headers = { 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff' };+ if (revalidate) {+ const board = text.replace(/"(asOf|ageMinutes)":(?:"[^"]*"|[-+.0-9eE]+|null)/gu, '"$1":null');+ Object.assign(headers, { 'cache-control': 'private, no-cache', etag: '"' + createHash('sha256').update(board).digest('base64url').slice(0, 32) + '"' });+ const held = String(req.headers['if-none-match'] ?? '').split(',').map((tag) => tag.trim().replace(/^W\//u, ''));+ if (held.includes(headers.etag)) {+ res.writeHead(304, headers);+ return res.end();+ }+ }+ res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', ...headers });+ res.end(text);}/** Read a bounded JSON object, draining oversize requests so a refusal reaches the caller. */@@ -109,7 +131,7 @@ function stateDetail(value) {}/** Create the common API router; an adapter controls authorization and board storage. */-export function createApiHandler(adapter, { pollMs = 200 } = {}) {+export function createApiHandler(adapter, { pollMs = 200, revalidateState = false } = {}) {if (!Number.isInteger(pollMs) || pollMs < 10 || pollMs > 60_000) throw new Refused('API_POLL', 'use a poll interval from 10 to 60000 milliseconds');const streams = new Set();@@ -297,17 +319,18 @@ export function createApiHandler(adapter, { pollMs = 200 } = {}) {const since = sinceCursor(url.searchParams.get('since'));if (options.detail === 'full') throw new Refused('BAD_REQUEST', 'a delta brings item summaries up to date; use since=N without detail=full');if (typeof adapter.delta !== 'function') throw new Refused('DELTA_NOT_AVAILABLE', 'this API adapter does not answer since=N; use its board state');- return json(res, 200, await adapter.delta(board, who, seen, { since, eventLogVersion: url.searchParams.get('eventLogVersion') }));+ const delta = await adapter.delta(board, who, seen, { since, eventLogVersion: url.searchParams.get('eventLogVersion') });+ return sendState(req, res, JSON.stringify({ version: 1, ...delta }), revalidateState);}if (typeof adapter.stateJson === 'function') {const state = await adapter.stateJson(board, who, seen, options);if (typeof state !== 'string') throw new TypeError('the local state serializer must return JSON text');const eventLogVersion = await adapter.eventLogVersion?.(board, who);- return jsonState(res, 200, state, eventLogVersion);+ return sendState(req, res, stateText(state, eventLogVersion), revalidateState);}const state = await adapter.state(board, who, seen, options);const eventLogVersion = await adapter.eventLogVersion?.(board, who);- return json(res, 200, { state, ...(eventLogVersion === undefined ? {} : { eventLogVersion }) });+ return sendState(req, res, JSON.stringify({ version: 1, state, ...(eventLogVersion === undefined ? {} : { eventLogVersion }) }), revalidateState);}if (req.method === 'GET' && route[2] === 'code') {if (typeof adapter.code !== 'function') throw new Refused('CODE_NOT_AVAILABLE', 'this API adapter does not provide committed-code previews; use the local view or a local API server');diff --git a/src/api.js b/src/api.jsindex 900af9ea..f05b992e 100644--- a/src/api.js+++ b/src/api.js@@ -545,6 +545,8 @@ const DELTA_WHOLE = new Set(['unseen', 'proofStats', 'decisions', 'holds', 'requconst DELTA_KEYS = Object.freeze({ items: 'id', shouts: 'shout_id', asked: 'shout_id', events: 'event_id', agents: 'agent_id', spec: 'id', practice: 'id', milestones: 'name' });/** How many recent builds of each board a server keeps as possible delta bases. */const DELTA_BASES = 24;+/** How many item details a server keeps for each board: past a board our size, the least recently read go first. */+const DETAIL_CACHE_ITEMS = 4096;/** A digest of one value's JSON, which is what a client holds of it. */function jsonDigest(value) {@@ -668,6 +670,29 @@ function withBoard(root, read, isMain) {try { return read(board, info); } finally { store.closeBoard(board); }}+/**+ * Read a board on a read-only connection when it is at this code's schema and event-log version.+ * Why: openBoard migrates, writes the board id and checkpoints the log on close, so every read+ * waited behind agents' writes (#1040). Any other board goes through withBoard, which upgrades or refuses it.+ */+function withReadBoard(root, read, isMain) {+ const info = repoInfo(root);+ loadConfig(info.root);+ let db = null;+ let current = false;+ try {+ db = store.openBoardReadOnly(join(info.commonDir, 'pullboard', 'board.sqlite'));+ current = db.prepare('PRAGMA user_version').get().user_version === store.SCHEMA_VERSION && store.readEventLogVersion(db) === store.EVENT_LOG_VERSION;+ } catch {+ current = false; // A missing, older or newer board: withBoard creates, upgrades or refuses it by name.+ }+ if (!current) {+ db?.close();+ return withBoard(root, read, isMain);+ }+ try { return read({ db, clock: store.systemClock }, info); } finally { db.close(); }+}+/** Registered boards carry one persistent identity across local and relay addresses. */export function apiBoards(projects = listApiProjects, isMain) {return projects().flatMap((project) => {@@ -698,9 +723,13 @@ function apiBoardListing(projects = listApiProjects, isMain) {/** Resolve only registered boards, so a request cannot open an arbitrary path on the machine. */function findBoard(id, projects, isMain) {- const board = apiBoards(projects, isMain).find((entry) => entry.id === id);+ // Each request resolves its board, so this opens boards read-only and stops at the match (#1040).+ const board = projects().find((project) => {+ try { return withReadBoard(project.root, (current) => store.boardId(current), isMain) === id; }+ catch { return false; } // An unreadable board is left out, as the board listing leaves it out.+ });if (!board) throw new Refused('NO_BOARD', `no registered board ${id}; run pullboard serve in its repo and use GET /api/v1/boards`);- return board;+ return { ...board, id };}/** Restrict a local API to exactly one registered repository by its canonical Git common directory.@@ -845,7 +874,9 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =const cookieKey = sessionCookie === undefined ? null : Buffer.from(sessionCookie.value);const permittedOrigins = new Set(allowedOrigins);const stateCache = new Map();- const verdictCache = new Map();+ // Each board's item details by item id, and each board's spec-approval view (#1040).+ const detailCache = new Map();+ const approvalCache = new Map();// The fingerprints of the summary states each board's clients were sent, least recently sent// first, and the latest sequence a forgotten one had. A build only read for an item, a search or// a reset was never sent, so no client holds it and it is never a base.@@ -958,53 +989,34 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =if (sent.answer.delta) keepSentBase(sent.entry);return sent.answer;}- /** One item's detail from the current build, or null when the board has no such item. */+ /**+ * The spec-approval view one board's details share, kept while the files, HEAD and board records it+ * reads hold: it reads every row decision and sign-off, so building it per detail cost most of one.+ */+ function approvalFor(root, currentBoard, info) {+ const config = loadConfig(root);+ const meta = currentBoard.db.prepare("SELECT meta_key, meta_value FROM board_meta WHERE meta_key IN ('row_decisions', 'spec_approval_baseline') ORDER BY meta_key").all();+ const key = JSON.stringify([stateFileInputs(info.root, config).map(fileMarker), fileMarkerForPath(join(info.root, '.mailmap')), resolveCommit(info.root, 'HEAD'), meta]);+ const cacheId = JSON.stringify([info.commonDir, root]);+ const cached = approvalCache.get(cacheId);+ if (cached?.key === key) return cached.approval;+ const approval = specApprovalState(root, { board: currentBoard, config });+ approvalCache.delete(cacheId);+ approvalCache.set(cacheId, { key, approval });+ while (approvalCache.size > 32) approvalCache.delete(approvalCache.keys().next().value);+ return approval;+ }+ /**+ * One item's detail, or null when the board has no such item. It reads only that item's rows by+ * index, and its detail is kept by the item's last event id with the few facts beyond its own+ * events that a detail shows: its row and live leases, its prerequisites' statuses, the trunk and+ * the spec-approval inputs (#1040).+ */function localItem(board, id) {- return withBoard(board.root, (currentBoard) => {+ return withReadBoard(board.root, (currentBoard, info) => {currentBoard.db.exec('BEGIN');try {- let source;- try { source = store.getItem(currentBoard, id); }- catch (error) {- if (error instanceof Refused && error.code === 'NO_ITEM') {- currentBoard.db.exec('COMMIT');- return null;- }- throw error;- }- const status = new Map();- for (const dependency of dependencyIds(source)) {- const row = currentBoard.db.prepare('SELECT item_status FROM item WHERE item_id = ?').get(dependency);- if (row) status.set(dependency, row.item_status);- }- const base = projectItemSpecApprovals(projectItemState(currentBoard, source, status),- specApprovalState(board.root, { board: currentBoard, config: loadConfig(board.root) }));- // Detail reads need no new Git process while the trunk and immutable receipt log hold.- const info = repoInfo(board.root);- const tip = trunkRevisionReader(info)();- const verdictCacheId = JSON.stringify([info.commonDir, board.id]);- const event = currentBoard.db.prepare('SELECT COALESCE(MAX(event_id), 0) AS id FROM event').get().id;- const revision = JSON.stringify([tip, event]);- let cachedVerdicts = verdictCache.get(verdictCacheId);- if (cachedVerdicts?.revision !== revision) {- cachedVerdicts = { revision, states: new Map() };- verdictCache.delete(verdictCacheId);- verdictCache.set(verdictCacheId, cachedVerdicts);- while (verdictCache.size > 32) verdictCache.delete(verdictCache.keys().next().value);- }- // The projector owns this transaction's connection; only derived values cross requests.- const verdictState = cachedVerdicts.states.has(id) ? cachedVerdicts.states.get(id)- : verdictProjector(board.root, currentBoard, { main: tip }).state(source);- if (!verdictState?.reason) cachedVerdicts.states.set(id, verdictState);- const projected = {- ...base,- ...(verdictState ? { verdictState } : {}),- check: source.item_check,- ...(source.item_check_baseline ? { checkBaseline: source.item_check_baseline } : {}),- thread: store.itemThread(currentBoard, id),- };- onItemBuild?.({ board: board.id, itemId: id });- const detail = itemDetail(projected);+ const detail = itemDetailIn(board, currentBoard, info, id);currentBoard.db.exec('COMMIT');return detail;} catch (error) {@@ -1013,6 +1025,55 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =}}, codeIsMain);}+ /** Serve an item's cached detail while its key holds, building and keeping it when the key moved. */+ function itemDetailIn(board, currentBoard, info, id) {+ const { db } = currentBoard;+ const row = db.prepare('SELECT * FROM item WHERE item_id = ?').get(id);+ if (!row) return null;+ const now = currentBoard.clock.now().toISOString();+ const status = new Map();+ for (const dependency of dependencyIds(row)) {+ const dependent = db.prepare('SELECT item_status FROM item WHERE item_id = ?').get(dependency);+ if (dependent) status.set(dependency, dependent.item_status);+ }+ // Detail reads need no new Git process while the trunk holds.+ const tip = trunkRevisionReader(info)();+ const approval = approvalFor(board.root, currentBoard, info);+ const key = JSON.stringify([row, row.item_status === 'claimed' && (row.item_lease_until ?? '') > now,+ row.item_status === 'submitted' && Boolean(row.item_review_by) && (row.item_review_until ?? '') > now,+ db.prepare('SELECT MAX(event_id) AS id FROM event WHERE item_id = ?').get(id).id,+ db.prepare('SELECT MAX(verdict_id) AS id FROM verdict WHERE item_id = ?').get(id).id,+ [...status], db.prepare('SELECT meta_value FROM board_meta WHERE meta_key = ?').get(`item_check_baseline_${id}`)?.meta_value ?? null, tip]);+ const cacheId = JSON.stringify([info.commonDir, board.id]);+ let details = detailCache.get(cacheId);+ const cached = details?.get(id);+ if (cached?.key === key && cached.approval === approval) return cached.detail;+ const source = store.getItem(currentBoard, id);+ const base = projectItemSpecApprovals(projectItemState(currentBoard, source, status), approval);+ // The projector owns this transaction's connection; only derived values cross requests.+ const verdictState = verdictProjector(board.root, currentBoard, { main: tip }).state(source);+ const projected = {+ ...base,+ ...(verdictState ? { verdictState } : {}),+ check: source.item_check,+ ...(source.item_check_baseline ? { checkBaseline: source.item_check_baseline } : {}),+ thread: store.itemThread(currentBoard, id),+ };+ onItemBuild?.({ board: board.id, itemId: id });+ const detail = itemDetail(projected);+ // Missing Git objects can arrive with no event or trunk move, so an uncertain verdict is read again.+ if (!verdictState?.reason) {+ if (!details) {+ details = new Map();+ detailCache.set(cacheId, details);+ while (detailCache.size > 32) detailCache.delete(detailCache.keys().next().value);+ }+ details.delete(id);+ details.set(id, { key, approval, detail });+ while (details.size > DETAIL_CACHE_ITEMS) details.delete(details.keys().next().value);+ }+ return detail;+ }/** The ids of the items the view's search would show for this text, in board-state order. */function localSearch(board, text) {const words = String(text).trim().toLowerCase();@@ -1060,7 +1121,7 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =request: (board, body) => createRequest(board.root, body, codeIsMain, personChannel),tokens: async (board) => (await relayTokens(board.root, { err() {} })).tokens,revokeToken: (board, id) => relayRevoke(board.root, id, { personChannel, say() {}, err() {} }),- });+ }, { revalidateState: true });}/**diff --git a/test/api.test.js b/test/api.test.jsindex cd422324..c16c2dc2 100644--- a/test/api.test.js+++ b/test/api.test.js@@ -1541,3 +1541,59 @@ test('one move recomputes only the items it touched [A2,N26]', async (t) => {await api.close();}});++/** An agent writing to the board from its own process until the stop file appears, then printing its write count. */+const WRITER = `import { DatabaseSync } from 'node:sqlite'; import { existsSync } from 'node:fs';+const [file, stop] = process.argv.slice(1); const db = new DatabaseSync(file); db.exec('PRAGMA busy_timeout = 5000');+const insert = db.prepare("INSERT INTO event (event_at, event_by, event_kind, item_id, event_detail) VALUES (?, 'coordinator', 'edit', ?, '{}')");+let n = 0; process.stdout.write('ready\\n');+while (!existsSync(stop)) { db.exec('BEGIN IMMEDIATE'); insert.run(new Date().toISOString(), 1 + (n++ % 1000)); db.exec('COMMIT'); await new Promise((done) => setTimeout(done, 2)); }+db.close(); process.stdout.write(n + '\\n');`;++test('[N26,A2] an item detail answers under 20 ms on a large board', async (t) => {+ const box = project();+ const boardFile = join(box.repo, '.git', 'pullboard', 'board.sqlite');+ const board = openBoard(boardFile, undefined, { isMain: true });+ const ids = [];+ try {+ for (let index = 0; index < 1000; index += 1) {+ ids.push(addBoardItem(board, { by: 'coordinator', lane: 'app', title: `Large item ${index + 1}`, criterion: `Detail ${index + 1}`, specIds: ['G1'],+ route: 'light', brief: 'Files:\n- app/large.js\nChange:\n- Keep it.\nTest:\n- It reads fast.', check: 'true' }));+ }+ const insert = board.db.prepare("INSERT INTO event (event_at, event_by, event_kind, item_id, event_detail) VALUES (?, 'coordinator', 'edit', ?, '{}')");+ board.db.exec('BEGIN');+ for (let event = board.db.prepare('SELECT COUNT(*) AS n FROM event').get().n; event < 40_000; event += 1) insert.run(new Date(Date.UTC(2026, 0, 1, 0, 0, event)).toISOString(), ids[event % 1000]);+ board.db.exec('COMMIT');+ } finally { closeBoard(board); }+ const builds = [];+ const api = await startLocalHandler(t, box, { personChannel: 'api', stateDetail: 'summary', onItemBuild: (entry) => builds.push(entry.itemId) });+ const path = `/api/v1/boards/${(await (await apiFetch(api, '/api/v1/boards')).json()).boards[0].id}`;+ const polled = await apiFetch(api, `${path}/state`);+ assert.equal((await polled.json()).state.items.length, 1000);+ const unchanged = await apiFetch(api, `${path}/state`, { headers: { 'if-none-match': polled.headers.get('etag') } });+ assert.equal(unchanged.status, 304, 'an unchanged state poll gets a not-modified reply');+ assert.equal(await unchanged.text(), '');++ const stop = join(box.dir, 'stop-writer');+ const writer = spawn(process.execPath, ['--input-type=module', '-e', WRITER, boardFile, stop], { stdio: ['ignore', 'pipe', 'pipe'] });+ let written = '';+ writer.stdout.on('data', (part) => { written += part; });+ while (!written.includes('ready')) await new Promise((done) => setTimeout(done, 5));+ const times = [];+ try {+ for (const id of ids.slice(0, 20)) {+ const started = performance.now();+ assert.equal((await (await apiFetch(api, `${path}/items/${id}`)).json()).item.id, id);+ times.push(performance.now() - started);+ }+ } finally { writeFileSync(stop, ''); await once(writer, 'close'); }+ assert.ok(Number(written.split('\n')[1]) > 0, 'an agent wrote to the board while the details were read');+ const sorted = [...times].sort((left, right) => left - right), median = (sorted[9] + sorted[10]) / 2;+ const report = `item detail ms, median ${median.toFixed(1)}: ${times.map((ms) => ms.toFixed(1)).join(' ')}`;+ t.diagnostic(report);+ assert.ok(median < 20 && sorted[19] < 50, report);+ await (await apiFetch(api, `${path}/items/${ids[19]}`)).json();+ builds.length = 0;+ assert.equal((await (await apiFetch(api, `${path}/items/${ids[19]}`)).json()).item.id, ids[19]);+ assert.deepEqual(builds, [], 'an item whose last event has not moved is served from its cached detail');+});