forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/kernel/issue-id-resolver.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const { ISSUE_COMMAND_EXIT_CODES } = require('./issue-command-contract');
+
+// Git-style short issue-id resolution (kernel 9556660b). The kernel mints full
+// UUIDs, which are hostile to type by hand; this module resolves an UNAMBIGUOUS
+// hex prefix (>= 6 chars, e.g. `forge show 9556660b`) to the stored full id.
+// It runs ONCE at the broker boundary (runIssueOperation) so every issue
+// subcommand — including the batch-close fan-out and the gate.issue_verify
+// read-back — consumes the RESOLVED id. Resolution is deliberately conservative:
+//   * a full UUID never triggers a lookup (byte-identical fast path);
+//   * non-hex tokens (legacy `forge-*` / imported Beads ids) pass through untouched;
+//   * a prefix with ZERO matches passes through so the downstream not-found
+//     error is unchanged;
+//   * an EXACT stored id always wins over prefix expansion (a stored short
+//     hex id is never mis-expanded or rejected as "too short").
+
+const MIN_ISSUE_ID_PREFIX_LENGTH = 6;
+const MAX_AMBIGUOUS_CANDIDATES = 5;
+
+const FULL_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// A resolvable prefix: at least MIN hex chars, optionally continuing with hex
+// and dashes (so a copied dashed UUID partial like `9556660b-a414` resolves too).
+const HEX_PREFIX_PATTERN = /^[0-9a-f]{6}[0-9a-f-]*$/i;
+// Pure hex but under the minimum length — candidate for the too-short guidance
+// error (unless it exactly matches a stored id).
+const SHORT_HEX_PATTERN = /^[0-9a-f]{1,5}$/i;
+
+// The positional slots that carry issue ids, per kernel operation. Positions
+// index the operation's positional tokens under the SAME rule every downstream
+// consumer uses (firstPositionalArg / resolveDependencyEndpoints /
+// buildCommentPayload): a positional is any token not starting with '-'. That
+// keeps the resolved token exactly the one the downstream code reads — e.g.
+// `claim --issue <id>` still resolves because `<id>` is positional 0 under this
+// rule and flags.issue reads the same token. Operations absent from this map
+// (list/ready/search/stats/create/...) take no issue id and pass through with
+// no lookup — a search query is never mistaken for an id.
+const OPERATION_ID_POSITIONS = Object.freeze({
+	update: Object.freeze([0]),
+	claim: Object.freeze([0]),
+	release: Object.freeze([0]),
+	comment: Object.freeze([0]),
+	close: Object.freeze([0]),
+	show: Object.freeze([0]),
+	owns: Object.freeze([0]),
+	children: Object.freeze([0]),
+	'dep.add': Object.freeze([0, 1]),
+	'dep.remove': Object.freeze([0, 1]),
+});
+
+// The `--issue=<id>` / `--blocks=<id>` =-joined flag forms carry ids inside a
+// single token, invisible to the positional rule, so they are resolved by name.
+const ID_FLAG_EQUALS_PATTERN = /^--(issue|blocks)=(.+)$/;
+
+function tooShortError(token) {
+	return {
+		error: {
+			code: 'FORGE_ISSUE_ID_PREFIX_TOO_SHORT',
+			message: `Issue id prefix '${token}' is too short — use at least ${MIN_ISSUE_ID_PREFIX_LENGTH} hex characters `
+				+ '(e.g. the first 8 of the id) or the full id.',
+			exitCode: ISSUE_COMMAND_EXIT_CODES.validation,
+			details: { prefix: token, min_length: MIN_ISSUE_ID_PREFIX_LENGTH },
+		},
+	};
+}
+
+function ambiguousError(token, candidates) {
+	const shown = candidates.slice(0, MAX_AMBIGUOUS_CANDIDATES);
+	const count = candidates.length > MAX_AMBIGUOUS_CANDIDATES
+		? `${MAX_AMBIGUOUS_CANDIDATES}+`
+		: String(candidates.length);
+	const listing = shown
+		.map(candidate => `${candidate.id} (${candidate.title ?? 'untitled'})`)
+		.join('; ');
+	return {
+		error: {
+			code: 'FORGE_ISSUE_ID_AMBIGUOUS',
+			message: `Ambiguous issue id prefix '${token}' — matches ${count} issues: ${listing}. `
+				+ 'Use a longer prefix or the full id.',
+			exitCode: ISSUE_COMMAND_EXIT_CODES.validation,
+			details: {
+				prefix: token,
+				candidates: shown.map(candidate => ({ id: candidate.id, title: candidate.title ?? null })),
+			},
+		},
+	};
+}
+
+// Resolve one id token. `lookup(prefix, limit)` returns candidate rows
+// ({ id, title }) whose id starts with `prefix`, ordered by id ascending —
+// which guarantees an exact match (shortest id sharing the prefix) sorts first
+// and is never pushed out by the limit. Returns { id } on success (possibly the
+// untouched input) or { error: { code, message, exitCode, details } }.
+// Resolve a hex ref (prefix >= 6, or short hex < 6) against the store. Returns { id } —
+// the resolved full id, or `ref` untouched when nothing matches — or an { error } for the
+// too-short / ambiguous cases. `reportToken` is what user-facing errors name (the original
+// input the caller typed, which may be a handle rather than the bare hex).
+async function resolveHexToken(ref, lookup, reportToken = ref) {
+	const isPrefix = HEX_PREFIX_PATTERN.test(ref);
+	const isShortHex = !isPrefix && SHORT_HEX_PATTERN.test(ref);
+	if (!isPrefix && !isShortHex) return { id: ref };
+
+	const needle = ref.toLowerCase();
+	const candidates = (await lookup(needle, MAX_AMBIGUOUS_CANDIDATES + 1)) || [];
+	const exact = candidates.find(
+		candidate => candidate && typeof candidate.id === 'string' && candidate.id.toLowerCase() === needle,
+	);
+	if (exact) return { id: exact.id };
+	if (isShortHex) return tooShortError(reportToken);
+	if (candidates.length === 0) return { id: ref };
+	if (candidates.length === 1) return { id: candidates[0].id };
+	return ambiguousError(reportToken, candidates);
+}
+
+async function resolveIssueId(token, lookup) {
+	if (typeof token !== 'string' || token.length === 0) return { id: token };
+	if (FULL_UUID_PATTERN.test(token)) return { id: token };
+
+	// A display handle is `<title-slug>-<short-id>` (kernel 1db53c60); its short-id is the
+	// 8-char UUID prefix, so a handle ends in >= 8 trailing hex. Short legacy/Beads suffixes
+	// (`forge-2a3bc9`, 6 hex) are NOT handles and pass through untouched.
+	const handleSuffix = (/-([0-9a-f]{8,})$/i.exec(token) || [])[1] || null;
+
+	if (HEX_PREFIX_PATTERN.test(token) || SHORT_HEX_PATTERN.test(token)) {
+		const direct = await resolveHexToken(token, lookup);
+		// A handle whose slug is all hex letters (e.g. `facade-decade-fee-add-1a2b3c4d`) also
+		// matches the broad hex-prefix pattern; when the whole token matches nothing, retry
+		// with its trailing short-id so the handle still resolves (CodeRabbit, PR #335).
+		if (direct.id === token && handleSuffix && handleSuffix !== token) {
+			const viaHandle = await resolveHexToken(handleSuffix, lookup, token);
+			if (viaHandle.error || viaHandle.id !== handleSuffix) return viaHandle;
+		}
+		return direct;
+	}
+
+	// Non-hex token: a legacy/imported id (pass through so the store resolves it exactly),
+	// or a display handle. Prefer an exact whole-token match first so imported handle-shaped
+	// ids (`legacy-2a3bc9de`) still resolve; otherwise resolve by the handle's short-id.
+	if (!handleSuffix) return { id: token };
+	const whole = (await lookup(token.toLowerCase(), 2)) || [];
+	const wholeExact = whole.find(
+		candidate => candidate && typeof candidate.id === 'string' && candidate.id.toLowerCase() === token.toLowerCase(),
+	);
+	if (wholeExact) return { id: wholeExact.id };
+	return resolveHexToken(handleSuffix, lookup, token);
+}
+
+// Resolve every id-carrying token in `args` for `operation`. Returns
+// { args: resolvedArgs } (a copy; the input is never mutated) or the first
+// { error } encountered. Operations without id slots return their args
+// unchanged and never invoke the lookup.
+async function resolveIssueIdArgs(operation, args = [], lookup) {
+	const positions = OPERATION_ID_POSITIONS[operation];
+	if (!positions) return { args };
+
+	const resolved = [...args];
+	let positionalIndex = 0;
+	for (let index = 0; index < resolved.length; index += 1) {
+		const token = resolved[index];
+		if (typeof token !== 'string') continue;
+		if (token.startsWith('-')) {
+			const match = ID_FLAG_EQUALS_PATTERN.exec(token);
+			if (match) {
+				const result = await resolveIssueId(match[2], lookup);
+				if (result.error) return result;
+				resolved[index] = `--${match[1]}=${result.id}`;
+			}
+			continue;
+		}
+		if (positions.includes(positionalIndex)) {
+			const result = await resolveIssueId(token, lookup);
+			if (result.error) return result;
+			resolved[index] = result.id;
+		}
+		positionalIndex += 1;
+	}
+	return { args: resolved };
+}
+
+module.exports = {
+	MAX_AMBIGUOUS_CANDIDATES,
+	MIN_ISSUE_ID_PREFIX_LENGTH,
+	OPERATION_ID_POSITIONS,
+	resolveIssueId,
+	resolveIssueIdArgs,
+};

package/lib/kernel/lease-enforcer.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const { normalizePayload } = require('./evaluators');
+
+// Default lease TTL (kernel d71a824b): how long a claim lease stays live before it
+// is eligible for expiry-reclaim, when the caller does not pin an explicit
+// expires_at (--expires). This is the ONE place the lease duration lives, reused by
+// the CLI boundary (lib/forge-issues.js) to stamp a real expires_at so the dashboard's
+// liveness layer has something to compute against. 8 hours: long enough to outlast a
+// normal agent work session (no heartbeat/renewal exists yet, so a shorter window
+// would risk expiring mid-work and letting another agent reclaim → silent double-work),
+// short enough that a dead agent's lease frees within a working day. Callers that
+// bypass the boundary (broker-direct, tests) carry no ttl and keep the historical
+// null default (never expires).
+const DEFAULT_LEASE_TTL_MS = 8 * 60 * 60 * 1000;
+
+// The ECMAScript maximum representable Date, ±8.64e15 ms from the epoch. A time value
+// outside this range makes `new Date(t)` an Invalid Date whose .toISOString() THROWS a
+// RangeError. buildClaimRow calls computeLeaseExpiry synchronously on the claim path, so
+// an uncaught throw here would fail the whole claim.
+const MAX_DATE_MS = 8.64e15;
+
+// Compute a lease expires_at from claimed_at (`now`) + a TTL in milliseconds. Returns
+// null (never expires) for an absent/non-positive/non-finite ttl, an unparseable `now`,
+// or a claimed_at+ttl that overflows the representable Date range (a fat-fingered
+// FORGE_LEASE_TTL_MS) — so any of these degrades to the historical null default rather
+// than throwing on the claim path. The result is always the canonical Date#toISOString
+// form isValidExpiresAt requires (…mmmZ), so lexicographic comparison in isLeaseExpired
+// stays chronological.
+function computeLeaseExpiry(now, ttlMs) {
+	if (ttlMs === null || ttlMs === undefined) return null;
+	const ttl = Number(ttlMs);
+	if (!Number.isFinite(ttl) || ttl <= 0) return null;
+	const base = Date.parse(now);
+	if (Number.isNaN(base)) return null;
+	// Guard the sum BEFORE constructing the Date: an overflow (or a non-finite sum) would
+	// otherwise reach .toISOString() as an Invalid Date and throw RangeError.
+	const expiryMs = base + ttl;
+	if (!Number.isFinite(expiryMs) || Math.abs(expiryMs) > MAX_DATE_MS) return null;
+	return new Date(expiryMs).toISOString();
+}
+
+// Pure claim-lease enforcement helpers (task 9.5.10). No I/O — the broker
+// performs all reads/writes and the DB partial UNIQUE index
+// (idx_kernel_claims_active_lease) is the hard race-safe guarantee. These
+// functions are the optimization + clean error path layered on top, mirroring
+// the pure style of evaluators.js.
+//
+// Ownership model (Slice 1, deliberately conservative): a claim lease is a
+// kernel_claims row with state='active'. A lease is "live" iff it is active and
+// not expired. ANY claim.create against a live lease quarantines as
+// 'claim_conflict' — there is NO silent same-owner renewal, because `actor` is
+// not yet guaranteed distinct per concurrent agent and a renewal branch could
+// let one agent silently steal another's live lease. Legitimate same-key
+// retries never reach here: they are collapsed to duplicate replays by the
+// idempotency-key path before claim planning runs.
+//
+// Claim scope/row/conflict all read from the SAME normalizePayload the evaluator
+// uses to persist the event, so the lease can never describe a different issue
+// than the accepted event/outbox.
+
+// A claim lease's expires_at, if present, must be a UTC ISO-8601 timestamp with a
+// trailing 'Z' AND a real calendar date — otherwise lexicographic comparison in
+// isLeaseExpired is meaningless (e.g. 'zzz' sorts after any timestamp and would
+// never expire; other junk sorts before and would look already expired). A
+// null/absent value is valid and means "never expires". The broker quarantines
+// any claim.create whose expires_at fails this check.
+function isValidExpiresAt(value) {
+	if (value === null || value === undefined) return true;
+	if (typeof value !== 'string') return false;
+	const timestamp = Date.parse(value);
+	if (Number.isNaN(timestamp)) return false;
+	// Require the EXACT canonical Date#toISOString form (YYYY-MM-DDTHH:MM:SS.mmmZ):
+	// isLeaseExpired compares lexicographically, so a non-canonical spelling like
+	// '...00Z' would sort after the equal instant '...00.000Z' (Z > .) and a reclaim
+	// at the expiry instant would wrongly look live. The round-trip also rejects
+	// rollover dates Date.parse silently normalises (e.g. 2026-02-31 -> 2026-03-03).
+	return new Date(timestamp).toISOString() === value;
+}
+
+// A lease with no expires_at never expires. Timestamps are validated UTC ISO-8601
+// with a trailing 'Z' (see isValidExpiresAt), so lexicographic comparison equals
+// chronological comparison.
+function isLeaseExpired(claim, now) {
+	if (!claim?.expires_at) return false;
+	return claim.expires_at <= now;
+}
+
+function buildClaimRow(event, now) {
+	const payload = normalizePayload(event);
+	return {
+		id: event.entity_id,
+		issue_id: payload.issue_id,
+		actor: event.actor,
+		state: 'active',
+		session_id: event.session_id ?? null,
+		worktree_id: event.worktree_id ?? null,
+		claimed_at: now,
+		// An explicit expires_at (from --expires) wins; otherwise derive from the event's
+		// lease_ttl_ms + claimed_at so the CLI boundary can stamp a real expiry. No ttl on
+		// the event → null (never expires), preserving the historical broker-direct default.
+		expires_at: payload.expires_at ?? computeLeaseExpiry(now, event.lease_ttl_ms),
+	};
+}
+
+// Decide how a claim.create event should be applied against the issue's current
+// active claim (if any). Returns one of:
+//   { action: 'insert',  claim }                  — no active claim
+//   { action: 'reclaim', supersede, claim }       — active claim has expired
+//   { action: 'conflict' }                        — a live lease blocks the claim
+function planClaimAcquisition({ event, activeClaim, now }) {
+	if (!activeClaim) {
+		return { action: 'insert', claim: buildClaimRow(event, now) };
+	}
+	if (isLeaseExpired(activeClaim, now)) {
+		return {
+			action: 'reclaim',
+			supersede: { claimId: activeClaim.id, toState: 'reclaimable' },
+			claim: buildClaimRow(event, now),
+		};
+	}
+	return { action: 'conflict' };
+}
+
+// Build a conflicts-table row for a quarantined claim conflict. Matches the
+// shape produced by evaluators.buildConflict: claims are not revisioned, so the
+// NOT NULL expected_revision / actual_revision columns default to 0. The
+// human-meaningful detail (who owns the live lease, who attempted) lives in
+// payload_json.
+function buildClaimConflict(event, activeClaim, reason = 'claim_conflict') {
+	const payload = normalizePayload(event);
+	return {
+		entity_type: event.entity_type,
+		entity_id: event.entity_id,
+		expected_revision: 0,
+		actual_revision: 0,
+		status: 'quarantined',
+		reason,
+		payload_json: JSON.stringify({
+			reason,
+			issue_id: payload.issue_id ?? null,
+			attempted_by: event.actor,
+			current_owner: activeClaim ? activeClaim.actor : null,
+			current_claim_id: activeClaim ? activeClaim.id : null,
+		}),
+		created_at: event.created_at,
+	};
+}
+
+module.exports = {
+	DEFAULT_LEASE_TTL_MS,
+	buildClaimConflict,
+	buildClaimRow,
+	computeLeaseExpiry,
+	isLeaseExpired,
+	isValidExpiresAt,
+	planClaimAcquisition,
+};

package/lib/kernel/migrations.js

@@ -0,0 +1,333 @@
+const { getKernelSchema, validateKernelSchema } = require('./schema');
+
+function assertIdentifier(identifier, label) {
+	if (!/^[a-z][a-z0-9_]*$/.test(identifier)) {
+		throw new Error(`Invalid Kernel SQL ${label}: ${identifier}`);
+	}
+}
+
+function renderReference(reference) {
+	const parts = String(reference || '').split('.');
+	if (parts.length !== 2) {
+		throw new Error(`Invalid Kernel SQL reference: ${reference}`);
+	}
+	const [tableName, columnName] = parts;
+	assertIdentifier(tableName, 'reference table');
+	assertIdentifier(columnName, 'reference column');
+	return `REFERENCES kernel_${tableName}(${columnName})`;
+}
+
+function renderColumn(field) {
+	assertIdentifier(field.name, 'column');
+	const parts = [field.name, field.type];
+	if (field.notNull) parts.push('NOT NULL');
+	if (field.primaryKey) parts.push('PRIMARY KEY');
+	if (field.default !== undefined) parts.push(`DEFAULT ${field.default}`);
+	if (field.references) parts.push(renderReference(field.references));
+	return parts.join(' ');
+}
+
+function renderCreateTable(table) {
+	assertIdentifier(table.sqlName, 'table');
+	const columns = table.fields.map(field => `  ${renderColumn(field)}`).join(',\n');
+	return `CREATE TABLE IF NOT EXISTS ${table.sqlName} (\n${columns}\n);`;
+}
+
+function renderCreateIndex(table, index) {
+	assertIdentifier(index.name, 'index');
+	const unique = index.unique ? 'UNIQUE ' : '';
+	const columns = index.columns.map(column => {
+		assertIdentifier(column, 'index column');
+		return column;
+	}).join(', ');
+	return `CREATE ${unique}INDEX IF NOT EXISTS ${index.name} ON ${table.sqlName} (${columns});`;
+}
+
+function renderDropIndex(index) {
+	assertIdentifier(index.name, 'index');
+	return `DROP INDEX IF EXISTS ${index.name};`;
+}
+
+function renderDropTable(table) {
+	assertIdentifier(table.sqlName, 'table');
+	return `DROP TABLE IF EXISTS ${table.sqlName};`;
+}
+
+// Whole tables created by a LATER migration (not by the 001 initial schema). schema.js
+// stays the full current schema; the named tables are filtered out of 001 so they are
+// created exactly once by their dedicated migration (both on a fresh DB and, via the
+// ledger, on an existing DB). KEEP IN SYNC with every new table-creating migration.
+//   memories → 005
+const MIGRATION_ADDED_TABLES = ['memories'];
+
+function getInitialKernelSchema() {
+	const schema = getKernelSchema();
+	// Columns added by a later migration MUST be excluded from the initial (001)
+	// CREATE TABLE, so a fresh DB doesn't create them before the ALTER … ADD COLUMN
+	// migration runs (else "duplicate column name"). schema.js stays the full current
+	// schema; this map mirrors which columns each later migration backfills.
+	//   events.expected_revision → 002 ; issues.design/notes/assignee → 004 ;
+	//   issues.created_by/closed_at/close_reason/metadata → 006 ;
+	//   worktrees.issue_id/work_folder → 007
+	// KEEP IN SYNC: every new `ALTER TABLE … ADD COLUMN` migration MUST add its
+	// column(s) here, or a fresh DB will hit "duplicate column name" on setup.
+	const MIGRATION_ADDED_COLUMNS = {
+		events: ['expected_revision'],
+		issues: ['design', 'notes', 'assignee', 'created_by', 'closed_at', 'close_reason', 'metadata'],
+		worktrees: ['issue_id', 'work_folder'],
+	};
+	return {
+		...schema,
+		tables: schema.tables
+			.filter(table => !MIGRATION_ADDED_TABLES.includes(table.name))
+			.map(table => {
+				const excluded = MIGRATION_ADDED_COLUMNS[table.name];
+				if (!excluded) return table;
+				return {
+					...table,
+					fields: table.fields.filter(field => !excluded.includes(field.name)),
+				};
+			}),
+	};
+}
+
+function buildSchemaMigration(schema = getInitialKernelSchema()) {
+	validateKernelSchema(schema);
+
+	const apply = [];
+	for (const table of schema.tables) {
+		apply.push(renderCreateTable(table));
+		for (const tableIndex of table.indexes) {
+			apply.push(renderCreateIndex(table, tableIndex));
+		}
+	}
+
+	const rollback = [];
+	for (const table of [...schema.tables].reverse()) {
+		for (const tableIndex of [...table.indexes].reverse()) {
+			rollback.push(renderDropIndex(tableIndex));
+		}
+		rollback.push(renderDropTable(table));
+	}
+
+	return {
+		id: '001_kernel_schema',
+		apply,
+		rollback,
+	};
+}
+
+function buildEventExpectedRevisionMigration() {
+	return {
+		id: '002_kernel_events_expected_revision',
+		apply: ['ALTER TABLE kernel_events ADD COLUMN expected_revision INTEGER NOT NULL DEFAULT 0;'],
+		rollback: [
+			'CREATE TABLE IF NOT EXISTS kernel_events_002_rollback (\n  id TEXT NOT NULL PRIMARY KEY,\n  entity_type TEXT NOT NULL,\n  entity_id TEXT NOT NULL,\n  event_type TEXT NOT NULL,\n  idempotency_key TEXT NOT NULL,\n  actor TEXT NOT NULL,\n  origin TEXT NOT NULL,\n  payload_json TEXT NOT NULL,\n  created_at TEXT NOT NULL\n);',
+			'INSERT INTO kernel_events_002_rollback (id, entity_type, entity_id, event_type, idempotency_key, actor, origin, payload_json, created_at) SELECT id, entity_type, entity_id, event_type, idempotency_key, actor, origin, payload_json, created_at FROM kernel_events;',
+			'DROP TABLE kernel_events;',
+			'ALTER TABLE kernel_events_002_rollback RENAME TO kernel_events;',
+			'CREATE INDEX IF NOT EXISTS idx_kernel_events_entity_created ON kernel_events (entity_type, entity_id, created_at);',
+			'CREATE UNIQUE INDEX IF NOT EXISTS idx_kernel_events_idempotency ON kernel_events (idempotency_key);',
+		],
+	};
+}
+
+function buildClaimActiveLeaseMigration() {
+	// DB-enforced claim-lease invariant (task 9.5.10): at most one active claim
+	// per issue. A partial UNIQUE index is the only guarantee that survives
+	// multi-process races — a pre-read check cannot, because two writers can both
+	// read zero active claims before either commits. renderCreateIndex() has no
+	// partial-WHERE support, so this is a hand-written apply string (like 002).
+	return {
+		id: '003_kernel_claims_active_lease',
+		apply: [
+			"CREATE UNIQUE INDEX IF NOT EXISTS idx_kernel_claims_active_lease ON kernel_claims (issue_id) WHERE state = 'active';",
+		],
+		rollback: [
+			'DROP INDEX IF EXISTS idx_kernel_claims_active_lease;',
+		],
+	};
+}
+
+// KAP-10 (acceptance/design/notes) + KAP-11 (assignee): three additive content
+// columns on kernel_issues. acceptance_criteria/estimate already exist; these add
+// the remaining authored fields plus a persistent assignee (distinct from the
+// transient kernel_claims lease). Plain ADD COLUMNs — the 001 initial schema omits
+// these columns (getInitialKernelSchema/MIGRATION_ADDED_COLUMNS) and the broker's
+// per-migration ledger + guarded ADD COLUMN apply them exactly once.
+function buildIssueContentFieldsMigration() {
+	return {
+		id: '004_kernel_issues_content_fields',
+		apply: [
+			'ALTER TABLE kernel_issues ADD COLUMN design TEXT;',
+			'ALTER TABLE kernel_issues ADD COLUMN notes TEXT;',
+			'ALTER TABLE kernel_issues ADD COLUMN assignee TEXT;',
+		],
+		rollback: [
+			'ALTER TABLE kernel_issues DROP COLUMN assignee;',
+			'ALTER TABLE kernel_issues DROP COLUMN notes;',
+			'ALTER TABLE kernel_issues DROP COLUMN design;',
+		],
+	};
+}
+
+// 005: the project-memory read-model table (kernel_memories). Rendered from the
+// schema.js table definition so the DDL never drifts from the registry. Excluded from
+// the 001 initial schema (MIGRATION_ADDED_TABLES), so a fresh DB creates it exactly
+// once here and an existing DB picks it up through the broker's per-migration ledger.
+// CREATE … IF NOT EXISTS keeps a re-run idempotent.
+function buildMemoryProjectionMigration() {
+	const memories = getKernelSchema().tables.find(table => table.name === 'memories');
+	if (!memories) {
+		throw new Error('Kernel schema is missing the memories read-model table');
+	}
+	return {
+		id: '005_kernel_memories',
+		apply: [
+			renderCreateTable(memories),
+			...memories.indexes.map(memoryIndex => renderCreateIndex(memories, memoryIndex)),
+		],
+		rollback: [
+			...[...memories.indexes].reverse().map(memoryIndex => renderDropIndex(memoryIndex)),
+			renderDropTable(memories),
+		],
+	};
+}
+
+// 006: full-fidelity beads import. Four additive ADD COLUMNs on kernel_issues so no
+// beads issue data is dropped — the author (created_by), the close timestamp
+// (closed_at) and raw close reason (close_reason, distinct from the mapped terminal
+// status), plus a verbatim JSON metadata blob (metadata). Plain ADD COLUMNs — the 001
+// initial schema omits these columns (getInitialKernelSchema/MIGRATION_ADDED_COLUMNS)
+// and the broker's per-migration ledger + guarded ADD COLUMN apply them exactly once.
+function buildIssueFidelityColumnsMigration() {
+	return {
+		id: '006_kernel_issue_fidelity_columns',
+		apply: [
+			'ALTER TABLE kernel_issues ADD COLUMN created_by TEXT;',
+			'ALTER TABLE kernel_issues ADD COLUMN closed_at TEXT;',
+			'ALTER TABLE kernel_issues ADD COLUMN close_reason TEXT;',
+			'ALTER TABLE kernel_issues ADD COLUMN metadata TEXT;',
+		],
+		rollback: [
+			'ALTER TABLE kernel_issues DROP COLUMN metadata;',
+			'ALTER TABLE kernel_issues DROP COLUMN close_reason;',
+			'ALTER TABLE kernel_issues DROP COLUMN closed_at;',
+			'ALTER TABLE kernel_issues DROP COLUMN created_by;',
+		],
+	};
+}
+
+// 007: the kernel linkage backbone. Two additive ADD COLUMNs on kernel_worktrees so a
+// worktree row records the issue it serves (issue_id) and the work-folder that issue
+// owns (work_folder, repo-relative). This is what turns `kernel_worktrees` from a
+// schema-only/never-written table into the queryable issue → worktree → work-folder
+// chain, so orientation resolves the work-folder from the kernel instead of the
+// "most-complete folder" filesystem heuristic. Plain ADD COLUMNs — the 001 initial
+// schema omits these columns (getInitialKernelSchema/MIGRATION_ADDED_COLUMNS) and the
+// broker's per-migration ledger + guarded ADD COLUMN apply them exactly once.
+function buildWorktreeLinkageColumnsMigration() {
+	return {
+		id: '007_kernel_worktrees_linkage_columns',
+		apply: [
+			'ALTER TABLE kernel_worktrees ADD COLUMN issue_id TEXT;',
+			'ALTER TABLE kernel_worktrees ADD COLUMN work_folder TEXT;',
+		],
+		rollback: [
+			'ALTER TABLE kernel_worktrees DROP COLUMN work_folder;',
+			'ALTER TABLE kernel_worktrees DROP COLUMN issue_id;',
+		],
+	};
+}
+
+// 008: an FTS5 full-text index over kernel_memories, the shared token-efficient
+// retrieval layer (Section B of the decision-store design). It is an EXTERNAL-CONTENT
+// FTS5 table (content='kernel_memories', content_rowid='rowid'), so the index stores no
+// second copy of the row — it reads the memory text back from kernel_memories by rowid.
+// Three triggers keep the index synchronized with every INSERT/DELETE/UPDATE (the
+// upsert-by-key path fires INSERT on first write and UPDATE on a key collision), and a
+// one-time 'rebuild' backfills any rows written before the index existed (e.g. rows the
+// insights engine wrote through recordMemory). The FTS virtual table lives OUTSIDE
+// schema.js (it is not a kernel authority/read-model table), so it is created only here.
+// CREATE … IF NOT EXISTS + CREATE TRIGGER IF NOT EXISTS keep a re-run idempotent, and the
+// same DDL is reused by the driver's lazy ensureMemorySchema so a synchronous memory write
+// stays indexed without a prior broker.initialize().
+function memoryFtsDdl() {
+	return {
+		create: "CREATE VIRTUAL TABLE IF NOT EXISTS kernel_memories_fts USING fts5(\n  key,\n  value_json,\n  tags_json,\n  content='kernel_memories',\n  content_rowid='rowid'\n);",
+		triggers: [
+			'CREATE TRIGGER IF NOT EXISTS kernel_memories_ai AFTER INSERT ON kernel_memories BEGIN\n  INSERT INTO kernel_memories_fts(rowid, key, value_json, tags_json)\n  VALUES (new.rowid, new.key, new.value_json, new.tags_json);\nEND;',
+			"CREATE TRIGGER IF NOT EXISTS kernel_memories_ad AFTER DELETE ON kernel_memories BEGIN\n  INSERT INTO kernel_memories_fts(kernel_memories_fts, rowid, key, value_json, tags_json)\n  VALUES ('delete', old.rowid, old.key, old.value_json, old.tags_json);\nEND;",
+			"CREATE TRIGGER IF NOT EXISTS kernel_memories_au AFTER UPDATE ON kernel_memories BEGIN\n  INSERT INTO kernel_memories_fts(kernel_memories_fts, rowid, key, value_json, tags_json)\n  VALUES ('delete', old.rowid, old.key, old.value_json, old.tags_json);\n  INSERT INTO kernel_memories_fts(rowid, key, value_json, tags_json)\n  VALUES (new.rowid, new.key, new.value_json, new.tags_json);\nEND;",
+		],
+		rebuild: "INSERT INTO kernel_memories_fts(kernel_memories_fts) VALUES('rebuild');",
+	};
+}
+
+function buildMemoryFtsMigration() {
+	const ddl = memoryFtsDdl();
+	return {
+		id: '008_kernel_memories_fts',
+		apply: [ddl.create, ...ddl.triggers, ddl.rebuild],
+		rollback: [
+			'DROP TRIGGER IF EXISTS kernel_memories_au;',
+			'DROP TRIGGER IF EXISTS kernel_memories_ad;',
+			'DROP TRIGGER IF EXISTS kernel_memories_ai;',
+			'DROP TABLE IF EXISTS kernel_memories_fts;',
+		],
+	};
+}
+
+function validateKernelMigrations(migrations) {
+	const ids = new Set();
+	for (const migration of migrations) {
+		if (!migration || !migration.id) {
+			throw new Error('Kernel migration is missing an id');
+		}
+		if (ids.has(migration.id)) {
+			throw new Error(`Duplicate Kernel migration id: ${migration.id}`);
+		}
+		ids.add(migration.id);
+		if (!Array.isArray(migration.apply) || migration.apply.length === 0) {
+			throw new Error(`Kernel migration ${migration.id} has no apply statements`);
+		}
+		if (!Array.isArray(migration.rollback) || migration.rollback.length === 0) {
+			throw new Error(`Kernel migration ${migration.id} has no rollback statements`);
+		}
+	}
+
+	return true;
+}
+
+function buildKernelMigrationPlan(migrations = [
+	buildSchemaMigration(),
+	buildEventExpectedRevisionMigration(),
+	buildClaimActiveLeaseMigration(),
+	buildIssueContentFieldsMigration(),
+	buildMemoryProjectionMigration(),
+	buildIssueFidelityColumnsMigration(),
+	buildWorktreeLinkageColumnsMigration(),
+	buildMemoryFtsMigration(),
+]) {
+	validateKernelMigrations(migrations);
+
+	return {
+		migrations,
+		apply: migrations.flatMap(migration => migration.apply),
+		rollback: [...migrations].reverse().flatMap(migration => migration.rollback),
+	};
+}
+
+module.exports = {
+	buildClaimActiveLeaseMigration,
+	buildEventExpectedRevisionMigration,
+	buildIssueContentFieldsMigration,
+	buildIssueFidelityColumnsMigration,
+	buildKernelMigrationPlan,
+	buildMemoryFtsMigration,
+	buildMemoryProjectionMigration,
+	buildSchemaMigration,
+	buildWorktreeLinkageColumnsMigration,
+	memoryFtsDdl,
+	validateKernelMigrations,
+};