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
perf(store): index global fact identity checks [B29,C7]
Corey Olson1104abbe10cf
diff --git a/src/board-hot.js b/src/board-hot.jsindex 8c44bddd..f4d7931d 100644--- a/src/board-hot.js+++ b/src/board-hot.js@@ -1,3 +1,5 @@+import { ensureFactIdentityIndexes } from './fact-identity.js';+/*** The indexes and bounded reads behind the board's hot queries [C7]. Status, list, show, next, resume,* health and the view read events and shouts by kind, sender, answer and recency; on a board of tens of@@ -23,6 +25,7 @@ const HOT_INDEXES = [*/export function ensureHotIndexes(db) {for (const sql of HOT_INDEXES) db.exec(sql);+ ensureFactIdentityIndexes(db);}/**diff --git a/src/board.js b/src/board.jsindex 79f49d64..c9ab3dca 100644--- a/src/board.js+++ b/src/board.js@@ -138,6 +138,7 @@ import {boardBusyError,} from './board-access.js';import { ensureHotIndexes } from './board-hot.js';+import { ensureFactIdentityIndexes, factIdentityExists, missingFactIdentityIndexes } from './fact-identity.js';import { NEXT_STEPS } from './next-step-words.js';import { boardWriteBusyError } from './board-busy.js';export { boardBusyError } from './board-access.js';@@ -353,6 +354,13 @@ export function openBoard(file, clock = systemClock, { isMain, onDiagnostic } =guardStore(board);}if (standing === 'behind' || standing === 'unstamped') recordSchemaStamp(db, SCHEMA_DIGEST);+ // Index-only upgrades keep the data version/digest unchanged. Install and restamp together;+ // drifted or read-only stores never take this path, and old clients accept the resulting stamp.+ if (standing !== 'drifted' && missingFactIdentityIndexes(db).length) atomic(board, () => {+ if (boardStanding(db, SCHEMA_DIGEST, SCHEMA_VERSION) !== 'current') return;+ ensureFactIdentityIndexes(db);+ recordSchemaStamp(db, SCHEMA_DIGEST);+ });if (standing === 'drifted') { warmCounters = false; reportDrift(file, onDiagnostic); }} else {// Read compatibility before any local effect; persistent schema belongs to trunk alone.@@ -1880,7 +1888,7 @@ export function appendFact(board, id, { agentId, kind, text, ref = null, supersethrow new Refused('FACT_JUDGEMENT', `only the item's live holder${isHeld(board, item) ? ' (' + item.item_owner + ')' : ''} or the coordinator may append a judgement or supersede a fact; append an observation or ask the coordinator`);}if (typeof factId !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/u.test(factId)) throw new Refused('BAD_FACT_ID', 'a fact identity is invalid; retry with the current Pullboard engine');- if (board.db.prepare("SELECT 1 FROM event WHERE event_kind = 'fact' AND json_extract(event_detail, '$.id') = ?").get(factId)) throw new Refused('BAD_FACT_ID', 'this fact identity is already recorded; retry the original sealed move instead of appending it again');+ if (factIdentityExists(board.db, factId)) throw new Refused('BAD_FACT_ID', 'this fact identity is already recorded; retry the original sealed move instead of appending it again');if (supersedes !== null && (typeof supersedes !== 'string' || !itemThread(board, id).some((entry) => entry.type === 'fact' && entry.id === supersedes))) {throw new Refused('NO_FACT', `no fact ${String(supersedes)} on item #${id}; use a fact id from pullboard show ${id} --json`);}diff --git a/src/fact-identity.js b/src/fact-identity.jsnew file mode 100644index 00000000..3fd71a54--- /dev/null+++ b/src/fact-identity.js@@ -0,0 +1,47 @@+/** Indexed global fact identities, preserving the original lookup for unindexed legacy JSON [B29,C7]. */++/** Declare safe, nonunique indexes without rejecting legacy duplicate ids or invalid JSON. */+export function factIdentityIndexSql(table) {+ if (!['event', 'event_archive'].includes(table)) throw new TypeError('fact identity indexes require an event table');+ return `CREATE INDEX IF NOT EXISTS ${table}_fact_identity ON ${table} (json_extract(event_detail, '$.id'))+ WHERE event_kind = 'fact' AND json_valid(event_detail);+ CREATE INDEX IF NOT EXISTS ${table}_fact_legacy ON ${table} (event_id)+ WHERE event_kind = 'fact' AND NOT json_valid(event_detail);`;+}++/** Discover only the two supported physical partitions; archived identities remain globally reserved. */+function factTables(db) {+ return db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('event', 'event_archive') ORDER BY name")+ .all().map(({ name }) => name);+}++/** Find additive indexes missing from a legacy board without executing any DDL. */+export function missingFactIdentityIndexes(db) {+ return factTables(db).filter((table) => db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type = 'index' AND name IN (?, ?)")+ .get(`${table}_fact_identity`, `${table}_fact_legacy`).n !== 2);+}++/** Install additive indexes only when the owning writable opener calls the hot-index path. */+export function ensureFactIdentityIndexes(db) {+ for (const table of missingFactIdentityIndexes(db)) db.exec(factIdentityIndexSql(table));+}++/**+ * Look up an identity without parsing every valid fact. Strict-invalid JSON can include legacy JSON5;+ * retain the original query for that history rather than silently ignoring it or changing its errors.+ */+export function factIdentityExists(db, id) {+ const tables = factTables(db);+ const legacy = tables.some((table) => db.prepare(`SELECT 1 FROM ${table}+ WHERE event_kind = 'fact' AND NOT json_valid(event_detail) LIMIT 1`).get());+ if (legacy) {+ let history = 'event';+ if (tables.includes('event_archive')) {+ history = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'view' AND name = 'event_history'").get()+ ? 'event_history' : '(SELECT * FROM event UNION ALL SELECT * FROM event_archive)';+ }+ return Boolean(db.prepare(`SELECT 1 FROM ${history} WHERE event_kind = 'fact' AND json_extract(event_detail, '$.id') = ?`).get(id));+ }+ return tables.some((table) => Boolean(db.prepare(`SELECT 1 FROM ${table}+ WHERE event_kind = 'fact' AND json_valid(event_detail) AND json_extract(event_detail, '$.id') = ?`).get(id)));+}diff --git a/test/query-plans.test.js b/test/query-plans.test.jsindex 5aa720f8..bde7ca1f 100644--- a/test/query-plans.test.js+++ b/test/query-plans.test.js@@ -20,6 +20,8 @@ import { resumeNeeds } from '../src/resume-needs.js';import { undraftedRigor } from '../src/rigor-notices.js';import { runFixtureChild, runFixtureGit } from './fixture-child.js';import { applyEngineMove, prepareEngineMove } from '../src/engine.js';+import { recordSchemaStamp } from '../src/board-migrate.js';+import { SCHEMA_DIGEST } from '../src/board-schema-source.js';const BIN = resolve(import.meta.dirname, '../bin/pullboard.js');const SERVE = pathToFileURL(resolve(import.meta.dirname, '../src/serve.js')).href;@@ -65,17 +67,28 @@ test('a new fact id is checked by index across current, legacy and archived factassert.ok(identityPlans.length > 0, 'the real appendFact executed its identity lookup');assert.ok(identityPlans.every(({ plan }) => plan.some((detail) => /SEARCH event\b.*<expr>=\?/u.test(detail))),`new fact identity must search an expression index, not scan every fact: ${JSON.stringify(plans)}`);+ const legacyPlans = plans.filter(({ sql }) => sql.includes('NOT json_valid'));+ assert.ok(legacyPlans.length > 0 && legacyPlans.every(({ plan }) => plan.some((detail) => /USING (?:COVERING )?INDEX event_fact_legacy\b/u.test(detail))),+ `legacy detection must read only its partial legacy index: ${JSON.stringify(plans)}`);assert.throws(() => store.appendFact(board, second, options('fresh-identity')), { code: 'BAD_FACT_ID' }, 'identity is global across items');assert.throws(() => store.appendFact(board, second, options('legacy-399')), { code: 'BAD_FACT_ID' });store.closeBoard(board);const legacy = new DatabaseSync(file);// A synthetic physical cold partition exercises compatibility without importing unlanded retention code.- legacy.exec('CREATE TABLE event_archive AS SELECT * FROM event WHERE 0; PRAGMA user_version=2');+ legacy.exec('CREATE TABLE event_archive AS SELECT * FROM event WHERE 0; DROP INDEX event_fact_identity; DROP INDEX event_fact_legacy');legacy.prepare("INSERT INTO event_archive (event_id,event_at,event_by,event_kind,item_id,event_detail) VALUES (?,?,?,?,?,?)").run(900000, clock.now().toISOString(), 'coordinator', 'fact', first, JSON.stringify({ id: 'cold-identity', text: 'Cold legacy note' }));+ legacy.prepare("INSERT INTO event (event_at,event_by,event_kind,item_id,event_detail) VALUES (?,?,?,?,?)")+ .run(clock.now().toISOString(), 'coordinator', 'fact', second, JSON.stringify({ id: 'legacy-0', text: 'Historical duplicate retained' }));+ recordSchemaStamp(legacy, SCHEMA_DIGEST);legacy.close();+ const readonly = store.openBoardReadOnly(file);+ assert.equal(readonly.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type='index' AND name LIKE '%_fact_%'").get().n, 0,+ 'read-only open never installs an additive index');+ readonly.close();board = store.openBoard(file, clock);+ assert.equal(board.db.prepare('PRAGMA user_version').get().user_version, 3, 'index upgrade preserves the existing data schema version');assert.throws(() => store.appendFact(board, second, options('cold-identity')), { code: 'BAD_FACT_ID' }, 'cold identity remains reserved');store.appendFact(board, second, options('after-migration'));const coldPlans = board.db.prepare("EXPLAIN QUERY PLAN SELECT 1 FROM event_archive WHERE event_kind='fact' AND json_valid(event_detail) AND json_extract(event_detail,'$.id')=?")@@ -88,6 +101,11 @@ test('a new fact id is checked by index across current, legacy and archived factassert.deepEqual(applyEngineMove(board, move, { sequence: 1, at: clock.now().toISOString() }), replay, 'same sealed move retries its receipt');assert.equal(store.events(board).filter((event) => event.event_kind === 'fact' && JSON.parse(event.event_detail).id === move.id).length, 1);+ board.db.prepare("INSERT INTO event (event_at,event_by,event_kind,item_id,event_detail) VALUES (?,?,?,?,?)")+ .run(clock.now().toISOString(), 'coordinator', 'fact', first, "{id:'legacy-json5',text:'kept'}");+ assert.throws(() => store.appendFact(board, second, options('legacy-json5')), { code: 'BAD_FACT_ID' }, 'strict-invalid but readable JSON5 keeps its identity');+ store.appendFact(board, second, options('after-json5'));+const beforeMalformed = board.db.prepare('SELECT count(*) AS n FROM event').get().n;board.db.prepare("INSERT INTO event (event_at,event_by,event_kind,item_id,event_detail) VALUES (?,?,?,?,?)").run(clock.now().toISOString(), 'coordinator', 'fact', first, '{malformed');