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(core): index activation while preserving replay [E21,H16]
Corey Olson0ad4100f5909
diff --git a/src/agent-grant.js b/src/agent-grant.jsindex 03f3903c..ba576667 100644--- a/src/agent-grant.js+++ b/src/agent-grant.js@@ -3,6 +3,7 @@ import { AGENT_GRANT_ENGINE } from './agent-grant-engine.js';import { REVIEW_GRANT_ENGINE } from './review-grant-engine.js';import { MOVE_REGISTRY } from './move-registry.js';import { Refused } from './refused.js';+import { recordedGrantActivation } from './relay-activation.js';// Attributed append-only findings never confer authority over item state.const ADMINISTRATIVE = new Set(['shout', 'claim', 'release', 'reserveReview', 'appendFact', 'recordAttempt']);@@ -20,17 +21,6 @@ function existingItem(board, id) {return board.db.prepare('SELECT * FROM item WHERE item_id=?').get(id) ?? null;}-/** A board activates only through a move recorded in its ordered prefix, never by opening a newer client. */-function recordedGrantActivation(board) {- const cursor = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get('relay_applied_sequence');- const sequence = cursor ? Number(cursor.meta_value) : 0;- if (!Number.isSafeInteger(sequence) || sequence < 1) return false;- return Boolean(board.db.prepare(`SELECT 1 FROM board_meta WHERE meta_key GLOB 'relay_receipt_*'- AND json_extract(meta_value, '$.sequence') <= ?- AND json_extract(json_extract(meta_value, '$.move'), '$.engine') >= ? LIMIT 1`)- .get(sequence, AGENT_GRANT_ENGINE));-}-/** A version marker is not a grant: it only prevents an older engine bypassing a new seat or claim. */export function agentGrantMinimum(board, move) {// Communication and review administration neither widen nor replace a claim. An old claim could erase its version marker.diff --git a/src/board-hot.js b/src/board-hot.jsindex f4d7931d..480cee8e 100644--- a/src/board-hot.js+++ b/src/board-hot.js@@ -1,4 +1,5 @@import { ensureFactIdentityIndexes } from './fact-identity.js';+import { ensureGrantActivationIndex } from './relay-activation.js';/*** The indexes and bounded reads behind the board's hot queries [C7]. Status, list, show, next, resume,@@ -26,6 +27,7 @@ const HOT_INDEXES = [export function ensureHotIndexes(db) {for (const sql of HOT_INDEXES) db.exec(sql);ensureFactIdentityIndexes(db);+ ensureGrantActivationIndex(db);}/**diff --git a/src/board.js b/src/board.jsindex 3406dca3..8eaef15b 100644--- a/src/board.js+++ b/src/board.js@@ -199,6 +199,8 @@ import {boardBusyError,} from './board-access.js';import { ensureHotIndexes } from './board-hot.js';+import { ensureGrantActivationIndex } from './relay-activation.js';+import { missingGrantActivationIndex } from './relay-activation.js';import {ensureFactIdentityIndexes,factIdentityExists,@@ -431,9 +433,10 @@ export function openBoard(file, clock = systemClock, { isMain, onDiagnostic, wri});// 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 (standing !== 'drifted' && (missingFactIdentityIndexes(db).length || missingGrantActivationIndex(db))) atomic(board, () => {if (boardStanding(db, SCHEMA_DIGEST, SCHEMA_VERSION) !== 'current') return;ensureFactIdentityIndexes(db);+ ensureGrantActivationIndex(db);recordSchemaStamp(db, SCHEMA_DIGEST);});if (standing === 'drifted') { warmCounters = false; reportDrift(file, onDiagnostic); }diff --git a/src/relay-activation.js b/src/relay-activation.jsnew file mode 100644index 00000000..c3116db9--- /dev/null+++ b/src/relay-activation.js@@ -0,0 +1,58 @@+/** Additive activation-witness index; native receipts and their engine meaning stay unchanged [E21,H16,C7]. */+import { AGENT_GRANT_ENGINE } from './agent-grant-engine.js';++export const GRANT_ACTIVATION_INDEX = 'board_meta_grant_activation_v1';+const UNSAFE_INDEX = 'board_meta_grant_activation_unsafe_v1';+const RECEIPTS = "meta_key GLOB 'relay_receipt_*'";+// Guard the outer envelope before extracting its nested move: either layer can be malformed.+const READABLE = `CASE WHEN json_valid(meta_value, 10) THEN+ CASE WHEN json_extract(meta_value, '$.move') IS NULL OR json_valid(json_extract(meta_value, '$.move'), 10)+ THEN 1 ELSE 0 END ELSE 0 END`;+const ENGINE = `CASE WHEN (${READABLE}) THEN json_extract(json_extract(meta_value, '$.move'), '$.engine') END`;+const SEQUENCE = "CASE WHEN json_valid(meta_value, 10) THEN json_extract(meta_value, '$.sequence') END";+let warnedMissingIndex = false;++/** Owning writable opens install the derived index once, including on already-current boards. */+export function missingGrantActivationIndex(db) {+ return db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type='index' AND tbl_name='board_meta' AND name IN (?,?)")+ .get(GRANT_ACTIVATION_INDEX, UNSAFE_INDEX).n !== 2;+}++/** Seek engine-qualified receipts first while retaining the original SQLite JSON comparisons. */+export function ensureGrantActivationIndex(db) {+ db.exec(`CREATE INDEX IF NOT EXISTS ${GRANT_ACTIVATION_INDEX} ON board_meta (+ ${ENGINE}, ${SEQUENCE}+ ) WHERE ${RECEIPTS};+ CREATE INDEX IF NOT EXISTS ${UNSAFE_INDEX} ON board_meta (meta_key)+ WHERE ${RECEIPTS} AND (${READABLE}) = 0`);+}++/** Retain the literal historical predicate, including its malformed-data errors and short circuit. */+function legacyActivation(db, sequence) {+ return Boolean(db.prepare(`SELECT 1 FROM board_meta WHERE meta_key GLOB 'relay_receipt_*'+ AND json_extract(meta_value, '$.sequence') <= ?+ AND json_extract(json_extract(meta_value, '$.move'), '$.engine') >= ? LIMIT 1`)+ .get(sequence, AGENT_GRANT_ENGINE));+}++/** Seek a witness inside the applied prefix; corrupt legacy receipts retain their original behavior. */+export function recordedGrantActivation(board) {+ const db = board.db;+ const cursor = db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get('relay_applied_sequence');+ const sequence = cursor ? Number(cursor.meta_value) : 0;+ if (!Number.isSafeInteger(sequence) || sequence < 1) return false;+ if (missingGrantActivationIndex(db)) {+ if (!warnedMissingIndex) {+ warnedMissingIndex = true;+ console.warn('[RELAY_ACTIVATION_INDEX_MISSING] activation uses the slower legacy query; open this board once from its owning main checkout to install the index');+ }+ return legacyActivation(db, sequence);+ }+ const unsafe = db.prepare(`SELECT 1 FROM board_meta INDEXED BY ${UNSAFE_INDEX}+ WHERE ${RECEIPTS} AND (${READABLE}) = 0 LIMIT 1`).get();+ // Only unsafe historical data takes this unbounded compatibility path; ordinary receipts never scan it.+ if (unsafe) return legacyActivation(db, sequence);+ return Boolean(db.prepare(`SELECT 1 FROM board_meta INDEXED BY ${GRANT_ACTIVATION_INDEX}+ WHERE ${RECEIPTS} AND (${SEQUENCE}) <= ? AND (${ENGINE}) >= ? LIMIT 1`)+ .get(sequence, AGENT_GRANT_ENGINE));+}diff --git a/test/relay-activation.test.js b/test/relay-activation.test.jsindex dccae671..71a37c01 100644--- a/test/relay-activation.test.js+++ b/test/relay-activation.test.js@@ -1,6 +1,10 @@/** Indexed activation preserves the recorded prefix and exact grant floors [E21,H16,C7]. */import assert from 'node:assert/strict';import { test } from 'node:test';+import { mkdtempSync } from 'node:fs';+import { rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';import * as store from '../src/board.js';import { agentGrantMinimum } from '../src/agent-grant.js';import { AGENT_GRANT_ENGINE } from '../src/agent-grant-engine.js';@@ -11,6 +15,8 @@ import { startRelayEpoch } from '../src/engine.js';import { exportBoard } from '../src/exchange.js';import { importBoard } from '../src/exchange.js';import { restoreRelaySnapshot } from '../src/exchange.js';+import { recordSchemaStamp } from '../src/board-migrate.js';+import { SCHEMA_DIGEST } from '../src/board-schema-source.js';const AT = '2026-10-01T12:00:00.000Z';const LEGACY = AGENT_GRANT_ENGINE - 1;@@ -43,7 +49,8 @@ function lookupPlan(board, probe) {const plans = [];board.db.prepare = sql => {if (sql.includes("meta_key GLOB 'relay_receipt_*'") && sql.includes('json_extract')) {- plans.push(...prepare(`EXPLAIN QUERY PLAN ${sql}`).all(appliedSequence(board), AGENT_GRANT_ENGINE).map(row => row.detail));+ const bindings = sql.includes('$.sequence') ? [appliedSequence(board), AGENT_GRANT_ENGINE] : [];+ plans.push(...prepare(`EXPLAIN QUERY PLAN ${sql}`).all(...bindings).map(row => row.detail));}return prepare(sql);};@@ -51,6 +58,24 @@ function lookupPlan(board, probe) {finally { board.db.prepare = prepare; }}+/** Use the literal pre-index predicate as an oracle for readable legacy types and corrupt-row behavior. */+function originalFloor(board) {+ const row = board.db.prepare("SELECT meta_value FROM board_meta WHERE meta_key='relay_applied_sequence'").get();+ const sequence = row ? Number(row.meta_value) : 0;+ if (!Number.isSafeInteger(sequence) || sequence < 1) return 1;+ const witness = board.db.prepare(`SELECT 1 FROM board_meta WHERE meta_key GLOB 'relay_receipt_*'+ AND json_extract(meta_value, '$.sequence') <= ?+ AND json_extract(json_extract(meta_value, '$.move'), '$.engine') >= ? LIMIT 1`)+ .get(sequence, AGENT_GRANT_ENGINE);+ return witness ? AGENT_GRANT_ENGINE : 1;+}++/** Compare the actual return or SQLite error without swallowing either path's original result. */+function observed(work) {+ try { return { result: work() }; }+ catch (error) { return { error: { code: error.code, errcode: error.errcode, message: error.message } }; }+}+test('recorded activation preserves pre/post floors, acknowledged replay and administrative ordering [E21,H16]', t => {const box = fixture(t);const { board, actor, probe } = box;@@ -125,3 +150,99 @@ test('activation lookup seeks the engine index as genuine old receipts grow [E21box.activate();assert.equal(lookupPlan(box.board, box.probe).floor, AGENT_GRANT_ENGINE);});++test('indexed activation retains original JSON types and malformed-receipt short circuits [E21,H16]', t => {+ const box = fixture(t);+ const { board, probe } = box;+ const cursor = appliedSequence(board);+ const write = board.db.prepare('INSERT OR REPLACE INTO board_meta(meta_key,meta_value) VALUES (?,?)');+ const remove = board.db.prepare('DELETE FROM board_meta WHERE meta_key=?');+ const move = engine => JSON.stringify({ ...probe, engine });+ // These are explicitly simulated legacy/corrupt metadata values, not claims of executed engine receipts.+ const samples = [+ JSON.stringify({ sequence: cursor, move: move(AGENT_GRANT_ENGINE) }),+ JSON.stringify({ sequence: cursor + 1, move: move(AGENT_GRANT_ENGINE) }),+ JSON.stringify({ sequence: String(cursor), move: move(AGENT_GRANT_ENGINE) }),+ JSON.stringify({ sequence: null, move: move(AGENT_GRANT_ENGINE) }),+ JSON.stringify({ sequence: cursor, move: move(String(AGENT_GRANT_ENGINE)) }),+ JSON.stringify({ sequence: cursor, move: move(null) }),+ JSON.stringify({ sequence: cursor, move: { engine: AGENT_GRANT_ENGINE } }),+ `{sequence:${cursor},move:'{engine:${AGENT_GRANT_ENGINE},}',}`,+ Buffer.from(JSON.stringify({ sequence: cursor, move: move(AGENT_GRANT_ENGINE) })),+ ];+ for (const sample of samples) {+ write.run('relay_receipt_simulated', sample);+ const stored = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get('relay_receipt_simulated');+ assert.deepEqual(observed(() => agentGrantMinimum(board, probe)), observed(() => originalFloor(board)));+ assert.deepEqual(board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get('relay_receipt_simulated'), stored,+ 'lookup never repairs or rewrites legacy receipt bytes');+ }+ remove.run('relay_receipt_simulated');+ const witness = JSON.stringify({ sequence: cursor, move: move(AGENT_GRANT_ENGINE) });+ const broken = ['not JSON', JSON.stringify({ sequence: cursor, move: 'not JSON' }), Buffer.from('not JSON')];+ for (const sample of broken) {+ for (const before of [true, false]) {+ write.run(before ? 'relay_receipt_0-witness' : 'relay_receipt_z-witness', witness);+ write.run(before ? 'relay_receipt_z-broken' : 'relay_receipt_0-broken', sample);+ assert.deepEqual(observed(() => agentGrantMinimum(board, probe)), observed(() => originalFloor(board)),+ 'malformed outer and inner values retain the original witness-before/error-before behavior');+ for (const key of ['relay_receipt_0-witness', 'relay_receipt_z-witness', 'relay_receipt_z-broken', 'relay_receipt_0-broken']) remove.run(key);+ }+ }+});++test('owning open upgrades an old indexless board once without changing native data or read-only ownership [E21,H16,C7]', t => {+ const dir = mkdtempSync(join(tmpdir(), 'pullboard-activation-index-'));+ t.after(() => rmSync(dir, { recursive: true, force: true }));+ const file = join(dir, 'board.sqlite');+ let board = store.openBoard(file);+ let document;+ let version;+ try {+ store.ensureCoordinator(board, dir);+ const legacy = { ...prepareEngineMove(board, 'shout', [{ from: 'coordinator', to: 'all', text: 'Legacy receipt', lanes: ['web'] }]), engine: LEGACY };+ assert.equal(applyEngineMove(board, legacy, { sequence: 1, at: AT }).error, undefined);+ document = exportBoard(board);+ version = board.db.prepare('PRAGMA user_version').get().user_version;+ // Model an otherwise-current legacy board with its original, indexless schema stamp.+ board.db.exec('DROP INDEX IF EXISTS board_meta_grant_activation_v1');+ recordSchemaStamp(board.db, SCHEMA_DIGEST);+ } finally { store.closeBoard(board); }+ const read = store.openBoardForRead(file);+ try {+ assert.equal(read.current, true, 'old indexless boards remain readable at the same native schema version');+ assert.equal(read.db.prepare("SELECT 1 FROM sqlite_master WHERE name='board_meta_grant_activation_v1'").get(), undefined);+ } finally { read.db.close(); }+ board = store.openBoard(file, undefined, { isMain: false });+ try {+ assert.equal(board.db.prepare("SELECT 1 FROM sqlite_master WHERE name='board_meta_grant_activation_v1'").get(), undefined,+ 'a non-owner never installs the additive index');+ const probe = { operation: 'editItem', args: [1, { agentId: 'unmarked-web-seat' }] };+ const warnings = [];+ const warn = console.warn;+ console.warn = (...args) => warnings.push(args.join(' '));+ try {+ assert.equal(agentGrantMinimum(board, probe), originalFloor(board));+ assert.equal(agentGrantMinimum(board, probe), originalFloor(board));+ } finally { console.warn = warn; }+ assert.equal(warnings.length, 1, 'missing-index fallback emits only one notice per process');+ assert.match(warnings[0], /^\[RELAY_ACTIVATION_INDEX_MISSING\].*owning main checkout/u);+ assert.equal(board.db.prepare("SELECT 1 FROM sqlite_master WHERE name='board_meta_grant_activation_v1'").get(), undefined,+ 'the fallback remains read-only and does not refuse or install an index');+ } finally { store.closeBoard(board); }+ board = store.openBoard(file);+ try {+ assert.ok(board.db.prepare("SELECT 1 FROM sqlite_master WHERE type='index' AND name='board_meta_grant_activation_v1'").get(),+ 'the owning writable opener installs the missing index on an already-current board');+ assert.equal(board.db.prepare('PRAGMA user_version').get().user_version, version);+ assert.deepEqual(exportBoard(board), document, 'index installation leaves every native row and export field unchanged');+ } finally { store.closeBoard(board); }+ const stamped = store.openBoardForRead(file);+ try { assert.equal(stamped.current, true, 'installation and the actual index-shape stamp commit together'); }+ finally { stamped.db.close(); }+ board = store.openBoard(file);+ try {+ assert.equal(board.db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE name='board_meta_grant_activation_v1'").get().n, 1);+ assert.deepEqual(exportBoard(board), document, 'a second owning open is idempotent');+ } finally { store.closeBoard(board); }+});