forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/kernel/broker.js

@@ -0,0 +1,1218 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { buildConflict, evaluateKernelEvent, normalizePayload } = require('./evaluators');
+const { CONFLICT_SIGNAL, classifyConflictSignal } = require('./conflict-signal');
+const { buildKernelMigrationPlan } = require('./migrations');
+const { buildClaimConflict, isValidExpiresAt, planClaimAcquisition } = require('./lease-enforcer');
+const {
+	ISSUE_COMMAND_EXIT_CODES,
+	ISSUE_COMMAND_SCHEMA_VERSION,
+	formatIssueCommandError,
+	getIssueCommandContract,
+	isValidIssuePriority,
+	normalizePriority,
+} = require('./issue-command-contract');
+const { isValidIssueStatus, isValidStatusTransition, rankForPriorityLabel } = require('./taxonomy-validator');
+const { assertFilesystemSafeForKernel } = require('./fs-class');
+const { resolveIssueIdArgs } = require('./issue-id-resolver');
+
+const LOCAL_BROKER_PRAGMAS = Object.freeze([
+	'PRAGMA journal_mode=WAL;',
+	'PRAGMA synchronous=NORMAL;',
+	'PRAGMA foreign_keys=ON;',
+	'PRAGMA busy_timeout=5000;',
+]);
+
+// Bounded wall-clock ceiling for the single `git rev-parse --git-common-dir`
+// probe below. This synchronous spawn has intermittently hung on Windows/Node
+// (issue ba388d01), and because it runs on every kernel broker init it can wedge
+// any command that touches the store (e.g. `forge remember`) until an outer
+// timeout kills it. The bound only guards against a *pathological* hang: the
+// original hang ran past 15s before it was SIGTERM'd, so 30s still fails-fast on
+// a true wedge while tolerating a legitimately-slow git on a loaded CI runner (a
+// 5s bound false-timed-out a healthy ~5.3s git call on the windows/Node22
+// matrix). Do not go back to unbounded.
+const GIT_COMMON_DIR_TIMEOUT_MS = 30000;
+
+function normalizeExecOutput(output) {
+	if (Buffer.isBuffer(output)) {
+		return output.toString('utf8');
+	}
+	return String(output || '');
+}
+
+// Conventional common dir for the ordinary (non-worktree) case. Used as the
+// graceful fallback when the git probe is too slow, hangs, or errors — a working
+// store location beats crashing every store-touching command.
+function defaultGitCommonDir(projectRoot) {
+	return path.resolve(projectRoot, '.git');
+}
+
+function resolveGitCommonDir(projectRoot, deps = {}) {
+	if (!projectRoot) {
+		throw new Error('projectRoot is required to resolve the Kernel broker common-dir');
+	}
+
+	const exec = deps.execFileSync || execFileSync;
+	let rawCommonDir;
+	try {
+		rawCommonDir = normalizeExecOutput(exec('git', [
+			'-C',
+			projectRoot,
+			'rev-parse',
+			'--git-common-dir',
+		], { encoding: 'utf8', timeout: GIT_COMMON_DIR_TIMEOUT_MS })).trim();
+	} catch (error) {
+		// A timed-out (ETIMEDOUT) or otherwise-failing git MUST NOT crash the
+		// caller: `resolveGitCommonDir` runs on every kernel broker init, so a
+		// throw here breaks `forge remember`/`recall` and every store-touching
+		// command. Degrade gracefully to the conventional <projectRoot>/.git so
+		// the store still resolves. This is correct for the common non-worktree
+		// case; inside a worktree it would ideally share the main repo's .git, but
+		// a working fallback beats a hard failure on a pathological git hang.
+		const warn = deps.warn || ((message) => console.warn(message));
+		warn(`[forge] git rev-parse --git-common-dir failed (${error.code || error.message}); `
+			+ `falling back to ${defaultGitCommonDir(projectRoot)}`);
+		return defaultGitCommonDir(projectRoot);
+	}
+
+	if (!rawCommonDir) {
+		// Empty output is not a hang, but treat it as the same graceful fallback
+		// rather than throwing so an odd git build cannot brick the store.
+		return defaultGitCommonDir(projectRoot);
+	}
+
+	return path.resolve(path.isAbsolute(rawCommonDir)
+		? rawCommonDir
+		: path.join(projectRoot, rawCommonDir));
+}
+
+function buildLocalBrokerConfig(options = {}) {
+	const projectRoot = options.projectRoot || process.cwd();
+	const gitCommonDir = path.resolve(options.gitCommonDir || resolveGitCommonDir(projectRoot, options));
+	const brokerDir = path.join(gitCommonDir, 'forge');
+
+	return {
+		mode: 'local',
+		storage: 'sqlite',
+		journalMode: 'WAL',
+		synchronous: 'NORMAL',
+		foreignKeys: true,
+		busyTimeoutMs: 5000,
+		projectRoot,
+		gitCommonDir,
+		brokerDir,
+		databasePath: options.databasePath || path.join(brokerDir, 'kernel.sqlite'),
+		pragmas: [...LOCAL_BROKER_PRAGMAS],
+		migrationPlan: options.migrationPlan || buildKernelMigrationPlan(),
+	};
+}
+
+function requireDriverMethod(driver, methodName) {
+	if (!driver || typeof driver[methodName] !== 'function') {
+		throw new Error(`Kernel local broker driver must provide ${methodName}()`);
+	}
+}
+
+// The migration ledger records which migration ids have been applied so initialize()
+// applies each migration AT MOST ONCE — no full re-run, no blanket duplicate-error
+// swallow. The ledger table is broker-managed bookkeeping (created before the plan is
+// consulted), so it is intentionally NOT part of the migration schema/plan.
+const MIGRATION_LEDGER_TABLE = 'kernel_migrations';
+const MIGRATION_LEDGER_CREATE = `CREATE TABLE IF NOT EXISTS ${MIGRATION_LEDGER_TABLE} (\n  id TEXT NOT NULL PRIMARY KEY,\n  applied_at TEXT NOT NULL\n);`;
+
+// Guarded ADD COLUMN: a PRECONDITION check (PRAGMA table_info) plus a TOCTOU catch
+// fallback. SQLite has no `ADD COLUMN IF NOT EXISTS`, and the target column can already
+// exist on a fresh DB (001 never seeds migration-added columns, but a pre-ledger DB the
+// old re-run model already migrated will have it). Skip the ADD when the column is
+// already present; if a concurrent initialize() adds it between the check and the run,
+// the catch re-verifies the post-state and skips too. ANY other SQL error still
+// propagates — the discarded blanket swallow could not, because it trusted the error
+// string instead of confirming the actual column state.
+function parseAddColumnTarget(statement) {
+	const match = /^\s*ALTER\s+TABLE\s+(\w+)\s+ADD\s+COLUMN\s+(\w+)\b/i.exec(String(statement || ''));
+	return match ? { table: match[1], column: match[2] } : null;
+}
+
+async function columnExists(driver, table, column, config) {
+	const rows = await driver.queryAll(`PRAGMA table_info(${table});`, config);
+	return Array.isArray(rows) && rows.some(row => row && row.name === column);
+}
+
+// Record a migration as applied. The id is a controlled internal constant, validated to
+// a ledger-safe charset before interpolation (the broker driver exposes only param-less
+// exec). INSERT OR IGNORE makes a concurrent double-init a harmless no-op.
+function recordMigrationSql(id) {
+	if (typeof id !== 'string' || !/^[0-9a-z_]+$/i.test(id)) {
+		throw new Error(`Kernel migration id is not ledger-safe: ${id}`);
+	}
+	return `INSERT OR IGNORE INTO ${MIGRATION_LEDGER_TABLE} (id, applied_at) VALUES ('${id}', '${new Date().toISOString()}');`;
+}
+
+// Conflict classification is delegated to the typed classifier at the driver
+// boundary (lib/kernel/conflict-signal.js). The broker branches on stable TYPED
+// codes and NEVER parses raw SQLite error text — that error-dialect knowledge
+// lives in one place, so a future backend (libSQL/Turso/CF) is decoupled here.
+function isIdempotencyConflict(error) {
+	return classifyConflictSignal(error) === CONFLICT_SIGNAL.UNIQUE_IDEMPOTENCY;
+}
+
+// The active-lease partial UNIQUE index (kernel_claims.issue_id) — a distinct code
+// from a duplicate-id (kernel_claims.id) violation, which classifies as null and is
+// re-thrown rather than misclassified as a lease conflict.
+function isClaimLeaseConflict(error) {
+	return classifyConflictSignal(error) === CONFLICT_SIGNAL.UNIQUE_CLAIM_LEASE;
+}
+
+// The driver's applyAcceptedIssueMutation tags a lost-update collision structurally
+// (its row-level CAS UPDATE matched 0 rows because the issue's revision moved
+// between the evaluator's out-of-transaction pre-read and the serialized commit).
+// classifyConflictSignal maps that driver-supplied tag to CAS_STALE.
+function isRevisionConflict(error) {
+	return classifyConflictSignal(error) === CONFLICT_SIGNAL.CAS_STALE;
+}
+
+async function execMigrationStatement(driver, statement, config) {
+	const addColumn = parseAddColumnTarget(statement);
+	if (addColumn && await columnExists(driver, addColumn.table, addColumn.column, config)) {
+		return { skipped: true, reason: 'column-already-exists' };
+	}
+	try {
+		await driver.exec(statement, config);
+	} catch (error) {
+		// TOCTOU: a concurrent initialize() can add this column between our pre-check
+		// and this exec — both readers saw it missing; the other writer won. Re-verify
+		// the actual post-state via PRAGMA: if the column is now present the migration's
+		// intent is satisfied, so skip. This is post-condition verification, NOT the
+		// discarded error-string swallow. Any other failure — and any failure where the
+		// column still isn't there — propagates. If the re-check itself throws, surface
+		// the ORIGINAL exec error, not the re-check's.
+		if (addColumn) {
+			try {
+				if (await columnExists(driver, addColumn.table, addColumn.column, config)) {
+					return { skipped: true, reason: 'column-added-concurrently' };
+				}
+			} catch {
+				throw error; // re-check failed — surface the ORIGINAL exec error
+			}
+		}
+		throw error;
+	}
+	return { skipped: false };
+}
+
+function buildProjectionOutboxEntry(event, target, now) {
+	return {
+		event_id: event.id,
+		target,
+		status: 'pending',
+		attempts: 0,
+		created_at: now,
+	};
+}
+
+function parseEventPayload(event = {}) {
+	if (event.payload) return event.payload;
+	if (!event.payload_json) return {};
+	try {
+		return JSON.parse(event.payload_json);
+	} catch {
+		return {};
+	}
+}
+
+function buildDependencyScope(event) {
+	if (event.event_type !== 'dependency.add') return null;
+	const payload = parseEventPayload(event);
+	if (!payload.issue_id || !payload.blocks_issue_id) return null;
+	return {
+		issue_id: payload.issue_id,
+		blocks_issue_id: payload.blocks_issue_id,
+		dependency_type: payload.dependency_type || 'blocks',
+		entity_type: event.entity_type,
+		entity_id: event.entity_id,
+	};
+}
+
+// A claim.create event targets entity_type='claim'/entity_id=<claim id>, so the
+// issue being claimed lives in the payload (exactly like dependency.add). Returns
+// null for non-claim events AND for malformed claim.create events (missing
+// issue_id or invalid expires_at) — the broker turns the latter into an
+// invalid_claim_scope quarantine rather than letting them through unscoped.
+function buildClaimScope(event) {
+	if (event.event_type !== 'claim.create') return null;
+	// A claim.create MUST be on the claim entity stream (entity_type='claim'). A
+	// claim.create carried on another entity (e.g. an 'issue' event) is malformed:
+	// it would otherwise insert a kernel_claims lease while the event/outbox are
+	// recorded on the wrong stream. Reject the scope so it quarantines.
+	if (event.entity_type !== 'claim') return null;
+	// Read from the SAME normalized payload the evaluator persists, so the lease
+	// can never describe a different issue than the accepted event/outbox.
+	const payload = normalizePayload(event);
+	// issue_id must be a non-empty STRING: a truthy non-string ({}, [], a number)
+	// would otherwise be coerced into a bogus lease key or surface as a raw FK
+	// error instead of the documented invalid_claim_scope quarantine.
+	if (!payload || typeof payload.issue_id !== 'string' || !payload.issue_id) return null;
+	// Reject a malformed expires_at up front: a junk value would make
+	// isLeaseExpired meaningless (lock the issue forever or look instantly stale).
+	if (!isValidExpiresAt(payload.expires_at)) return null;
+	return {
+		issue_id: payload.issue_id,
+		entity_type: event.entity_type,
+		entity_id: event.entity_id,
+	};
+}
+
+const GUARDED_DRIVER_METHODS = Object.freeze([
+	'exec',
+	'loadKernelEntity',
+	'listKernelEvents',
+	'loadKernelEventByIdempotencyKey',
+	'insertKernelConflict',
+	'insertKernelEvent',
+	'enqueueKernelProjection',
+]);
+
+function requireGuardedDriverMethods(driver) {
+	for (const methodName of GUARDED_DRIVER_METHODS) {
+		requireDriverMethod(driver, methodName);
+	}
+}
+
+// Insert a quarantined claim-conflict row and return the quarantine result.
+async function insertClaimConflictResult(driver, event, currentClaim, reason, context, config, now) {
+	const conflict = await driver.insertKernelConflict({
+		...buildClaimConflict(event, currentClaim, reason),
+		created_at: event.created_at || now,
+	}, context, config);
+	return { decision: 'quarantine', reason, conflict, projection: false };
+}
+
+// Re-read the idempotency key and, if a committed winner now exists, return a
+// duplicate replay. Used wherever a same-key retry might otherwise be misread as
+// a fresh conflict — the parallel guard reads are not a consistent snapshot, so
+// the idempotency lookup can miss a winner that a later read (or an insert
+// collision) then observes.
+async function replayDuplicateIfIdempotent(driver, event, context, config) {
+	if (!event.idempotency_key) return null;
+	const existingEvent = await driver.loadKernelEventByIdempotencyKey(event.idempotency_key, context, config);
+	if (!existingEvent) return null;
+	return { decision: 'duplicate', event, originalEvent: existingEvent, projection: false };
+}
+
+// Decide how an accepted claim.create maps to a claim row. Returns {terminal} to
+// short-circuit runGuardedEvent (duplicate replay or claim_conflict quarantine),
+// or {claimPlan} (possibly null for non-claim events) to proceed to the commit.
+async function resolveClaimAcquisition({ driver, event, claimScope, activeClaim, context, config, now }) {
+	if (!claimScope) return { claimPlan: null };
+	const claimPlan = planClaimAcquisition({ event, activeClaim, now });
+	if (claimPlan.action === 'conflict') {
+		// Split-read guard: the idempotency lookup may have run before the winner
+		// committed while the active-claim lookup ran after, so a legitimate
+		// same-key retry can reach here. Re-check before quarantining.
+		const terminal = (await replayDuplicateIfIdempotent(driver, event, context, config))
+			|| await insertClaimConflictResult(driver, event, activeClaim, 'claim_conflict', context, config, now);
+		return { terminal };
+	}
+	if (claimPlan.action === 'reclaim') {
+		requireDriverMethod(driver, 'updateKernelClaimState');
+	}
+	return { claimPlan };
+}
+
+// Recover from a failed accept transaction (after ROLLBACK). A committed
+// idempotency winner replays as a duplicate regardless of which unique index
+// tripped (the claim insert precedes the event insert, so the active-lease index
+// can throw before the events idempotency index); a genuine cross-owner lease
+// collision becomes a claim_conflict quarantine; anything else rethrows.
+async function recoverGuardedFailure({ driver, err, event, claimScope, context, config, now }) {
+	const isUniqueConflict = isIdempotencyConflict(err) || (claimScope && isClaimLeaseConflict(err));
+	if (isUniqueConflict) {
+		const replay = await replayDuplicateIfIdempotent(driver, event, context, config);
+		if (replay) return replay;
+	}
+	if (claimScope && isClaimLeaseConflict(err)) {
+		const winner = await driver.loadActiveKernelClaim(claimScope.issue_id, context, config);
+		return insertClaimConflictResult(driver, event, winner, 'claim_conflict', context, config, now);
+	}
+	// Issue-revision lost-update detected by the driver's row-level CAS: a same-key
+	// retry of an already-committed winner still replays as a duplicate; otherwise
+	// quarantine as stale_revision (byte-identical to an evaluator-produced conflict)
+	// so mapMutationResult surfaces it as a RETRYABLE conflict — the caller re-reads
+	// the bumped revision and retries.
+	if (isRevisionConflict(err)) {
+		const replay = await replayDuplicateIfIdempotent(driver, event, context, config);
+		if (replay) return replay;
+		const conflict = await driver.insertKernelConflict({
+			...buildConflict(event, 'stale_revision', err.actualRevision),
+			created_at: event.created_at || now,
+		}, context, config);
+		return { decision: 'quarantine', reason: 'stale_revision', conflict, projection: false };
+	}
+	throw err;
+}
+
+// Commit an accepted event: acquire/supersede the claim lease (if any), insert
+// the event, and enqueue the projection outbox entry — all inside one
+// BEGIN IMMEDIATE transaction, with ROLLBACK + recovery on failure.
+async function commitGuardedAccept({ driver, event, evaluation, claimScope, activeClaim, context, config, now }) {
+	const resolved = await resolveClaimAcquisition({ driver, event, claimScope, activeClaim, context, config, now });
+	if (resolved.terminal) return resolved.terminal;
+	const { claimPlan } = resolved;
+
+	await driver.exec('BEGIN IMMEDIATE;', config);
+	try {
+		if (claimPlan) {
+			if (claimPlan.action === 'reclaim') {
+				await driver.updateKernelClaimState(
+					claimPlan.supersede.claimId, claimPlan.supersede.toState, context, config,
+				);
+			}
+			await driver.insertKernelClaim(claimPlan.claim, context, config);
+		}
+		const acceptedEvent = await driver.insertKernelEvent({
+			...evaluation.event,
+			created_at: evaluation.event.created_at || now,
+		}, context, config);
+		// Apply the accepted event's authority-table effect (issue upsert / revision
+		// bump / comment insert) on the SAME connection, inside this transaction, so
+		// the event and its issue-row effect commit or roll back atomically. The hook
+		// is OPTIONAL: drivers that only supply event-store primitives (and every
+		// inline broker test fake) omit it, leaving the append/CAS path unchanged.
+		let mutation;
+		if (typeof driver.applyAcceptedIssueMutation === 'function') {
+			mutation = await driver.applyAcceptedIssueMutation(acceptedEvent, context, config);
+		}
+		const outboxEntry = await driver.enqueueKernelProjection(
+			buildProjectionOutboxEntry(acceptedEvent, context.projectionTarget || 'beads', now),
+			context,
+			config,
+		);
+		await driver.exec('COMMIT;', config);
+		return { ...evaluation, event: acceptedEvent, outboxEntry, mutation };
+	} catch (err) {
+		await driver.exec('ROLLBACK;', config);
+		return recoverGuardedFailure({ driver, err, event, claimScope, context, config, now });
+	}
+}
+
+// --- Issue-mutation routing (K-DRV Wave 3) ------------------------------------
+// The KernelIssueAdapter routes every op to runIssueOperation. Reads delegate
+// straight to driver.issueOperation; mutations must instead flow through the
+// guarded-event path so CAS/idempotency/quarantine (proven in #220) apply. This
+// surface builds a kernel event from the CLI args, runs runGuardedEvent, and maps
+// the decision back to an issue-command-contract response — without changing
+// runGuardedEvent itself.
+
+// Ops that must go through runGuardedEvent. Reads stay on driver.issueOperation.
+const ISSUE_MUTATION_OPERATIONS = Object.freeze(new Set([
+	'create', 'update', 'close', 'comment',
+	'dep.add', 'dep.remove', 'claim', 'release',
+]));
+
+// Ops whose kernel event targets a non-issue entity stream (a dependency edge or a
+// claim lease). These carry entity_type 'dependency'/'claim' and an entity_id that
+// is the dep/claim row id — NOT the issue id — so they must never fall into the
+// issue-upsert apply branch in the driver.
+const DEPENDENCY_OPERATIONS = Object.freeze(new Set(['dep.add', 'dep.remove']));
+const CLAIM_OPERATIONS = Object.freeze(new Set(['claim', 'release']));
+
+// Map an issue mutation op to its event_type and the contract command id used for
+// response/error shaping.
+const ISSUE_MUTATION_EVENT_TYPES = Object.freeze({
+	create: 'issue.create',
+	update: 'issue.update',
+	close: 'issue.close',
+	comment: 'issue.comment',
+	'dep.add': 'dependency.add',
+	'dep.remove': 'dependency.remove',
+	claim: 'claim.create',
+	release: 'claim.release',
+});
+const ISSUE_MUTATION_COMMAND_IDS = Object.freeze({
+	create: 'issue.create',
+	update: 'issue.update',
+	close: 'issue.close',
+	comment: 'issue.comment',
+	'dep.add': 'issue.dep.add',
+	'dep.remove': 'issue.dep.remove',
+	claim: 'claim',
+	release: 'release',
+});
+
+function nextCommandsFor(commandId) {
+	const contract = getIssueCommandContract(commandId);
+	return contract ? [...contract.nextCommands] : [];
+}
+
+// First non-flag token (the issue id for update/close/comment).
+function firstPositionalArg(args = []) {
+	return (args || []).find(value => typeof value === 'string' && !value.startsWith('-'));
+}
+
+// Parse the long-flag pairs CLI mutations carry. Supports BOTH forms:
+//   --key value   (space-separated)
+//   --key=value   (=-joined, e.g. --reason="...")
+// Only --key flags are captured; bare positionals are ignored here. The =-form
+// is required because the CLI delegates issue flags verbatim (bin parseFlags
+// early-returns for passthrough commands), so --reason=... arrives as one token.
+function parseFlagPairs(args = []) {
+	const flags = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const token = args[index];
+		if (typeof token !== 'string' || !token.startsWith('--')) continue;
+		const body = token.slice(2);
+		const eq = body.indexOf('=');
+		if (eq !== -1) {
+			// --key=value (value may itself contain '='; only split on the first).
+			flags[body.slice(0, eq)] = body.slice(eq + 1);
+			continue;
+		}
+		const key = body;
+		const next = args[index + 1];
+		if (typeof next === 'string' && !next.startsWith('--')) {
+			flags[key] = next;
+			index += 1;
+		} else {
+			flags[key] = true;
+		}
+	}
+	return flags;
+}
+
+// KAP-4: parseFlagPairs is last-value-wins, so repeated --label flags do NOT
+// accumulate. The CLI surface is a single COMMA-SEPARATED flag (--label "a,b");
+// split on ',', trim each, and drop empties into a string[]. A non-string flag
+// (bare --label with no value) yields []. The driver persists this as JSON-array
+// TEXT; the read side (parseLabels/rowToIssueSummary) already surfaces labels[].
+function parseLabelFlag(value) {
+	if (typeof value !== 'string') return [];
+	return value.split(',').map(label => label.trim()).filter(Boolean);
+}
+
+// Normalize the priority flags into the canonical stored form shared by create and
+// update. `--priority` is canonicalized to its P0..P4 label (the bare ranks 0..4 and
+// the P-labels map to the SAME label), and `priority_rank` is DERIVED from that label
+// so the kernel can order by priority — unless `--priority-rank` is given explicitly,
+// which still wins. A junk/out-of-range priority is left UNNORMALIZED so the validation
+// gate (assertValidIssueMutationPayload) rejects it instead of clamping it.
+function applyPriorityFlags(payload, flags) {
+	if (typeof flags.priority === 'string') payload.priority = normalizePriority(flags.priority);
+	if (flags['priority-rank'] !== undefined) {
+		payload.priority_rank = Number(flags['priority-rank']);
+	} else if (typeof payload.priority === 'string') {
+		payload.priority_rank = rankForPriorityLabel(payload.priority);
+	}
+}
+
+// Build the create payload from flags. --id is optional (minted when absent); the
+// minted/declared id becomes the event entity_id and the new issue's primary key.
+function buildCreatePayload(flags) {
+	const id = typeof flags.id === 'string' ? flags.id : randomUUID();
+	const payload = { id };
+	if (typeof flags.title === 'string') payload.title = flags.title;
+	// Beads stored the long-form description in `body` (beads-kernel-compat maps
+	// description ?? body ?? notes -> body). --body wins when both are supplied;
+	// otherwise --description populates the same body column so it is never dropped.
+	if (typeof flags.body === 'string') payload.body = flags.body;
+	else if (typeof flags.description === 'string') payload.body = flags.description;
+	payload.type = typeof flags.type === 'string' ? flags.type : 'task';
+	payload.status = typeof flags.status === 'string' ? flags.status : 'open';
+	applyPriorityFlags(payload, flags);
+	if (typeof flags.parent === 'string') payload.parent_id = flags.parent;
+	if (typeof flags.label === 'string') payload.labels = parseLabelFlag(flags.label);
+	// KAP-10 (acceptance/design/notes) + KAP-11 (assignee): authored content fields
+	// and a persistent assignee. The driver persists each to its own column.
+	if (typeof flags.acceptance === 'string') payload.acceptance_criteria = flags.acceptance;
+	if (typeof flags.design === 'string') payload.design = flags.design;
+	if (typeof flags.notes === 'string') payload.notes = flags.notes;
+	if (typeof flags.assignee === 'string') payload.assignee = flags.assignee;
+	// Beads full-fidelity import: author, close timestamp + raw close reason, and a
+	// verbatim metadata JSON blob (stored as-is). --close-reason is distinct from the
+	// --reason close-event flag; the importer sets these so no beads field is dropped.
+	if (typeof flags['created-by'] === 'string') payload.created_by = flags['created-by'];
+	if (typeof flags['closed-at'] === 'string') payload.closed_at = flags['closed-at'];
+	if (typeof flags['close-reason'] === 'string') payload.close_reason = flags['close-reason'];
+	if (typeof flags.metadata === 'string') payload.metadata = flags.metadata;
+	return payload;
+}
+
+// Build the update/close payload from flags (status/title/etc. when present).
+function buildUpdatePayload(flags) {
+	const payload = {};
+	if (typeof flags.status === 'string') payload.status = flags.status;
+	if (typeof flags.title === 'string') payload.title = flags.title;
+	// --body wins when both are supplied; otherwise --description rewrites the same
+	// body column (parity with create — beads stored the description in body).
+	if (typeof flags.body === 'string') payload.body = flags.body;
+	else if (typeof flags.description === 'string') payload.body = flags.description;
+	applyPriorityFlags(payload, flags);
+	// KAP-4: --label reparents the full label set (last-value-wins, comma-split).
+	if (typeof flags.label === 'string') payload.labels = parseLabelFlag(flags.label);
+	// KAP-5: --parent reparents on update (create already maps --parent → parent_id).
+	if (typeof flags.parent === 'string') payload.parent_id = flags.parent;
+	// KAP-5: --reason is captured in the close EVENT payload (no column/migration);
+	// kernel_events already persists payload_json. The close op uses buildUpdatePayload.
+	if (typeof flags.reason === 'string') payload.reason = flags.reason;
+	// KAP-10 (acceptance/design/notes) + KAP-11 (assignee): update overwrites each
+	// content field / reassigns the assignee when its flag is supplied.
+	if (typeof flags.acceptance === 'string') payload.acceptance_criteria = flags.acceptance;
+	if (typeof flags.design === 'string') payload.design = flags.design;
+	if (typeof flags.notes === 'string') payload.notes = flags.notes;
+	if (typeof flags.assignee === 'string') payload.assignee = flags.assignee;
+	// Beads full-fidelity import: overwrite author/close timestamp/raw close reason/
+	// metadata when supplied. --close-reason is a distinct COLUMN from the --reason
+	// close-event payload, and metadata is stored verbatim.
+	if (typeof flags['created-by'] === 'string') payload.created_by = flags['created-by'];
+	if (typeof flags['closed-at'] === 'string') payload.closed_at = flags['closed-at'];
+	if (typeof flags['close-reason'] === 'string') payload.close_reason = flags['close-reason'];
+	if (typeof flags.metadata === 'string') payload.metadata = flags.metadata;
+	return payload;
+}
+
+// The comment body is the first non-id positional (forge comment <id> <body...>).
+function buildCommentPayload(issueId, args) {
+	const positionals = (args || []).filter(value => typeof value === 'string' && !value.startsWith('-'));
+	const body = positionals.slice(1).join(' ');
+	return { issue_id: issueId, body, comment_id: randomUUID() };
+}
+
+// Resolve the (issue_id, blocks_issue_id) endpoints a dependency op names. The
+// DOCUMENTED CLI is positional — `forge issue dep add <issue-id> <blocks-issue-id>`
+// — so the first two positionals are the endpoints; the --issue/--blocks flag pair
+// is an explicit alternative that takes precedence when present. Both MUST resolve so
+// buildDependencyScope can scope the event (else the cycle guard is skipped and the
+// edge insert is malformed — previously a positional invocation left issue_id
+// undefined and the INSERT failed with a SQLite bind error).
+function resolveDependencyEndpoints(flags, args = []) {
+	const positionals = args.filter(arg => typeof arg === 'string' && !arg.startsWith('-'));
+	const issueId = typeof flags.issue === 'string' ? flags.issue : positionals[0];
+	const blocksIssueId = typeof flags.blocks === 'string' ? flags.blocks : positionals[1];
+	return {
+		issue_id: typeof issueId === 'string' ? issueId : undefined,
+		blocks_issue_id: typeof blocksIssueId === 'string' ? blocksIssueId : undefined,
+		dependency_type: typeof flags['dep-type'] === 'string' ? flags['dep-type'] : 'blocks',
+	};
+}
+
+// Build the kernel event for a dependency.add / dependency.remove op. The event is
+// scoped on the 'dependency' entity stream: a freshly minted entity_id becomes the
+// dependency row id (add) and the cycle-guard / edge-write key. The idempotency key
+// is derived from the edge endpoints so a retry of the same edge replays rather
+// than minting a second row.
+function buildDependencyMutationEvent(operation, flags, actor, origin, context, args = []) {
+	const endpoints = resolveDependencyEndpoints(flags, args);
+	const dependencyId = context.dependencyId || randomUUID();
+	const eventType = ISSUE_MUTATION_EVENT_TYPES[operation];
+	const idempotencyKey = context.idempotencyKey
+		|| `${eventType}:${endpoints.issue_id}:${endpoints.blocks_issue_id}`;
+	return {
+		entity_type: 'dependency',
+		entity_id: dependencyId,
+		event_type: eventType,
+		idempotency_key: idempotencyKey,
+		expected_revision: 0,
+		actor,
+		origin,
+		payload: {
+			issue_id: endpoints.issue_id,
+			blocks_issue_id: endpoints.blocks_issue_id,
+			dependency_type: endpoints.dependency_type,
+		},
+	};
+}
+
+// Build the kernel event for a claim / release op. The event is scoped on the
+// 'claim' entity stream (entity_id = claim lease id). The default idempotency key
+// is keyed on issue_id + actor + session so a same-SESSION retry replays as a
+// duplicate while a different session (or actor) produces a distinct key that reaches
+// the lease-conflict path.
+//
+// SESSION-SCOPED KEY (kernel d71a824b): keying on `actor` alone was a correctness
+// hole — `actor` defaults to a shared 'forge' and two concurrent agents acting as the
+// SAME human actor on the SAME issue collided on ONE key, so the loser's claim
+// collapsed to an idempotent duplicate-replay (ok:true) instead of reaching the
+// claim_conflict lease guard, and BOTH agents then passed owns() → silent double-work.
+// Appending the per-agent session-id gives distinct sessions distinct keys, so exactly
+// one wins the partial-UNIQUE active lease and the other is correctly quarantined. A
+// session-less caller (sessionId null) keeps the historical
+// `${eventType}:${issueId}:${actor}` key BYTE-FOR-BYTE, so single-agent same-key
+// retries still replay as duplicates and existing callers/tests are unaffected.
+//
+// The DOCUMENTED CLI is positional — `forge claim <id>` / `forge release <id>` —
+// so the issue id is the first positional, matching update/close/dep. The --issue
+// flag remains an explicit alternative that takes precedence when present. Reading
+// only flags.issue previously left issue_id undefined on the CLI path: claim then
+// failed buildClaimScope (invalid_claim_scope quarantine) and release bound undefined
+// to the lease-clear UPDATE ("cannot be bound to SQLite parameter 1").
+function buildClaimMutationEvent(operation, flags, actor, origin, context, args = []) {
+	const issueId = typeof flags.issue === 'string' ? flags.issue : firstPositionalArg(args);
+	const claimId = context.claimId || randomUUID();
+	const eventType = ISSUE_MUTATION_EVENT_TYPES[operation];
+	// Treat an empty/whitespace-only session-id as session-LESS: it must never append to
+	// the idempotency key and never be stored as a non-null session_id. This uses the
+	// SAME trim-truthy emptiness test as the owns() read (lib/kernel/sqlite-driver.js), so
+	// '' can never count as "present" at the write site and "absent" at the read site.
+	const sessionId = typeof context.sessionId === 'string' && context.sessionId.trim() !== ''
+		? context.sessionId
+		: null;
+	const idempotencyKey = context.idempotencyKey
+		|| (sessionId
+			? `${eventType}:${issueId}:${actor}:${sessionId}`
+			: `${eventType}:${issueId}:${actor}`);
+	const payload = { issue_id: issueId };
+	if (typeof flags.expires === 'string') payload.expires_at = flags.expires;
+	return {
+		entity_type: 'claim',
+		entity_id: claimId,
+		event_type: eventType,
+		idempotency_key: idempotencyKey,
+		expected_revision: 0,
+		actor,
+		origin,
+		session_id: sessionId,
+		worktree_id: context.worktreeId ?? null,
+		// Carry the lease TTL (ms) so buildClaimRow can derive expires_at = claimed_at + ttl
+		// when no explicit --expires is given. Absent/non-positive → null expiry (never
+		// expires), matching the historical broker-direct default. The CLI boundary
+		// (lib/forge-issues.js) supplies context.leaseTtlMs; broker-direct callers omit it.
+		lease_ttl_ms: context.leaseTtlMs ?? null,
+		payload,
+	};
+}
+
+// Reject an out-of-contract create/update payload before it reaches the CAS path,
+// throwing a tagged error runIssueMutation maps to the contract validation error
+// (exit 6). Beads refused these too: an empty/whitespace (or, on create, missing)
+// title, and any status/type/priority outside the canonical vocabulary, are rejected
+// rather than silently stored. On UPDATE only the fields actually supplied are
+// checked; on CREATE a title is mandatory.
+function assertValidIssueMutationPayload(payload, isCreate) {
+	const reject = (message, field) => {
+		const error = new Error(message);
+		error.isIssueValidation = true;
+		error.validationField = field;
+		throw error;
+	};
+	const hasTitle = typeof payload.title === 'string';
+	if ((isCreate || hasTitle) && (!hasTitle || payload.title.trim() === '')) {
+		reject('Issue title must be a non-empty string', 'title');
+	}
+	// NOTE: issue `type` is intentionally NOT validated here. `feature`/`story`/etc.
+	// are labels, not canonical types (D18), but forge-internal callers (e.g.
+	// lib/commands/plan.js) and the documented CLI still create with --type=feature,
+	// which the kernel stores verbatim. Rejecting it would be an out-of-scope regression;
+	// this gate matches Beads on title/status/priority only.
+	if (payload.status !== undefined && !isValidIssueStatus(payload.status)) {
+		reject(`Unknown issue status: ${payload.status}`, 'status');
+	}
+	if (payload.priority !== undefined && !isValidIssuePriority(payload.priority)) {
+		reject(`Invalid issue priority: ${payload.priority}`, 'priority');
+	}
+}
+
+// Construct the kernel event for a mutation op. For update/close/comment, the
+// expected_revision is the FRESHLY READ stored revision (so runIssueOperation can
+// never manufacture a stale CAS — a behind revision only arrives via a raw
+// runGuardedEvent call). entity_id is the issue id; payload carries the change.
+async function buildIssueMutationEvent(driver, operation, args, context, config) {
+	const flags = parseFlagPairs(args);
+	const actor = context.actor || 'forge';
+	const origin = context.origin || 'cli';
+
+	if (operation === 'create') {
+		const payload = buildCreatePayload(flags);
+		assertValidIssueMutationPayload(payload, true);
+		return {
+			entity_type: 'issue',
+			entity_id: payload.id,
+			event_type: ISSUE_MUTATION_EVENT_TYPES.create,
+			idempotency_key: context.idempotencyKey || `issue.create:${payload.id}`,
+			expected_revision: 0,
+			actor,
+			origin,
+			payload,
+		};
+	}
+
+	// Dependency / claim ops target their own entity stream (no issue-row CAS): the
+	// event entity_type is 'dependency'/'claim' and entity_id is a fresh dep/claim id.
+	if (DEPENDENCY_OPERATIONS.has(operation)) {
+		return buildDependencyMutationEvent(operation, flags, actor, origin, context, args);
+	}
+	if (CLAIM_OPERATIONS.has(operation)) {
+		// Claim eligibility: a `backlog` (parked) issue is NOT workable — beginning it
+		// would jump backlog->in_progress and skip the required promote (backlog->open).
+		// Reject the claim here rather than minting a lease that silently activates parked
+		// work. `release` is never gated (an over-eager park must always be releasable).
+		if (operation === 'claim') {
+			const claimIssueId = typeof flags.issue === 'string' ? flags.issue : firstPositionalArg(args);
+			const claimEntity = await driver.loadKernelEntity('issue', claimIssueId, context, config);
+			if (claimEntity && claimEntity.status === 'backlog') {
+				const err = new Error(
+					`Cannot claim a parked (backlog) issue ${claimIssueId}: promote it first `
+					+ `(forge issue update ${claimIssueId} --status open)`,
+				);
+				err.isIssueValidation = true;
+				err.validationField = 'status';
+				throw err;
+			}
+		}
+		return buildClaimMutationEvent(operation, flags, actor, origin, context, args);
+	}
+
+	const issueId = firstPositionalArg(args);
+	const entity = await driver.loadKernelEntity('issue', issueId, context, config);
+	// Existence guard: update/close/comment target an EXISTING issue. Without this a
+	// missing issue yields entity=null -> expected_revision 0, which the row-level CAS
+	// accepts as a fresh insert — silently minting a phantom issue on a typo'd id (data
+	// corruption; Beads errors not-found). Signal not-found so runIssueMutation returns
+	// the contract FORGE_ISSUE_NOT_FOUND / exit 3 instead of writing a row.
+	if (!entity) {
+		const notFound = new Error(`Issue ${issueId ?? '<missing id>'} not found`);
+		notFound.isIssueNotFound = true;
+		throw notFound;
+	}
+	const expectedRevision = Number(entity?.entity_revision || 0);
+	// For close, the driver maps event_type='issue.close' to a terminal status; an
+	// explicit --status flag (rework move) still wins via the update payload.
+	const payload = operation === 'comment'
+		? buildCommentPayload(issueId, args)
+		: buildUpdatePayload(flags);
+	// update/close validate only the supplied taxonomy fields (no mandatory title);
+	// comment carries no taxonomy fields, so it is exempt.
+	if (operation !== 'comment') {
+		assertValidIssueMutationPayload(payload, false);
+	}
+	// Enforce the stored status-transition graph on any status CHANGE the payload
+	// carries (an `update --status`, or a `close --status` rework move). Without this
+	// the row-level CAS happily persists an illegal jump — done->open resurrects a
+	// terminal issue, backlog->in_progress skips the required promote. isValidStatusTransition
+	// treats an unchanged status as an idempotent no-op, so a re-set to the same value passes.
+	// Only gate when the CURRENT status is a known-valid stored value: if the loaded entity
+	// carries no readable status (minimal driver fakes; a not-yet-materialized row), fall
+	// through to the CAS/quarantine path rather than manufacturing a false validation error.
+	if (payload.status !== undefined
+		&& isValidIssueStatus(entity.status)
+		&& !isValidStatusTransition(entity.status, payload.status)) {
+		const err = new Error(`Illegal status transition: ${entity.status} -> ${payload.status}`);
+		err.isIssueValidation = true;
+		err.validationField = 'status';
+		throw err;
+	}
+	// Comments never bump entity_revision, so a revision-based key would collide for
+	// every comment on the same issue (second → false duplicate → silently dropped).
+	// Key on the minted comment_id instead. For update/close the synthesized key uses
+	// the current revision: a CLI retry re-reads the bumped revision and re-applies
+	// (not truly idempotent) — callers needing retry-safety pass context.idempotencyKey.
+	const idempotencyKey = context.idempotencyKey || (operation === 'comment'
+		? `${ISSUE_MUTATION_EVENT_TYPES.comment}:${issueId}:${payload.comment_id}`
+		: `${ISSUE_MUTATION_EVENT_TYPES[operation]}:${issueId}:rev-${expectedRevision}`);
+	return {
+		entity_type: 'issue',
+		entity_id: issueId,
+		event_type: ISSUE_MUTATION_EVENT_TYPES[operation],
+		idempotency_key: idempotencyKey,
+		expected_revision: expectedRevision,
+		actor,
+		origin,
+		payload,
+	};
+}
+
+function okMutationResponse(commandId, data) {
+	return {
+		ok: true,
+		schema_version: ISSUE_COMMAND_SCHEMA_VERSION,
+		command: commandId,
+		data,
+		next_commands: nextCommandsFor(commandId),
+	};
+}
+
+// The issue id a mutation event touches: for issue ops it IS the entity_id; for
+// dependency/claim ops the entity_id is the dep/claim row id, so the issue lives in
+// the payload. Used to report a stable issue revision on a duplicate replay.
+function mutationIssueId(operation, event) {
+	if (DEPENDENCY_OPERATIONS.has(operation) || CLAIM_OPERATIONS.has(operation)) {
+		const payload = parseEventPayload(event);
+		return payload.issue_id;
+	}
+	return event.entity_id;
+}
+
+// Build the accept-decision mutation response data (id + revision plus the op-specific
+// id echoes). Extracted from mapMutationResult so that function's cognitive complexity
+// stays low as op-specific fields accrue (comment_id / dependency_id / claim_id /
+// KAP-8 newly_unblocked).
+function buildAcceptMutationData(operation, event, mutation) {
+	const isDep = DEPENDENCY_OPERATIONS.has(operation);
+	const isClaim = CLAIM_OPERATIONS.has(operation);
+	// data.id is the ISSUE id consumers key on. For dep/claim ops the event entity_id
+	// is the dependency/claim ROW id, so resolve the issue id from the payload; the row
+	// id is echoed separately via dependency_id / claim_id.
+	const data = {
+		id: (isDep || isClaim) ? mutationIssueId(operation, event) : (mutation.id ?? event.entity_id),
+		revision: Number(mutation.revision ?? 0),
+	};
+	// Surface the canonical priority the write persisted (create/update with --priority)
+	// so the mutation response is self-describing — the bare-int and P-label inputs both
+	// echo the SAME normalized label. dep/claim payloads carry no priority, so it is omitted.
+	const payload = parseEventPayload(event);
+	if (typeof payload.priority === 'string') data.priority = payload.priority;
+	if (mutation.comment_id) data.comment_id = mutation.comment_id;
+	if (isDep) {
+		data.dependency_id = mutation.dependency_id ?? event.entity_id;
+	}
+	if (isClaim) {
+		data.claim_id = mutation.claim_id ?? event.entity_id;
+	}
+	// KAP-8: a close surfaces the ids that became ready now that this issue is done.
+	// Only the close path's driver mutation populates newly_unblocked; echo it when
+	// present (an empty array is meaningful — "nothing unblocked" — so include it).
+	if (operation === 'close' && Array.isArray(mutation.newly_unblocked)) {
+		data.newly_unblocked = mutation.newly_unblocked;
+	}
+	return data;
+}
+
+// Map a runGuardedEvent result to an issue-command-contract mutation response (or
+// error). A duplicate replay reports the existing single row; a quarantine becomes
+// a (sometimes retryable) conflict error; an accept returns
+// {id, revision, comment_id?/dependency_id?/claim_id?}.
+async function mapMutationResult(driver, operation, event, result, context, config) {
+	const commandId = ISSUE_MUTATION_COMMAND_IDS[operation];
+
+	if (result.decision === 'accept') {
+		return okMutationResponse(commandId, buildAcceptMutationData(operation, event, result.mutation || {}));
+	}
+
+	if (result.decision === 'duplicate' || result.decision === 'dedupe' || result.decision === 'projection_echo') {
+		// Idempotent replay / equivalent write: no double-write. Report the host
+		// issue's current persisted revision so the caller sees a stable result. For
+		// dep/claim ops the issue id comes from the payload, not the entity_id — and
+		// data.id is that issue id (the dep/claim ROW id is echoed via *_id below).
+		const issueId = mutationIssueId(operation, event);
+		const entity = await driver.loadKernelEntity('issue', issueId, context, config);
+		const data = {
+			id: issueId,
+			revision: Number(entity?.entity_revision || 0),
+		};
+		if (DEPENDENCY_OPERATIONS.has(operation)) data.dependency_id = event.entity_id;
+		if (CLAIM_OPERATIONS.has(operation)) data.claim_id = event.entity_id;
+		return okMutationResponse(commandId, data);
+	}
+
+	if (result.decision === 'quarantine') {
+		const retryable = result.reason === 'stale_revision';
+		return formatIssueCommandError({
+			command: commandId,
+			code: `FORGE_ISSUE_${String(result.reason || 'CONFLICT').toUpperCase()}`,
+			message: `Issue mutation ${operation} on ${event.entity_id} was quarantined: ${result.reason}`,
+			exitCode: ISSUE_COMMAND_EXIT_CODES.conflict,
+			retryable,
+			details: { reason: result.reason, entity_id: event.entity_id },
+			nextCommands: nextCommandsFor(commandId),
+		});
+	}
+
+	// Any other decision (should not occur for issue mutations) is an internal error.
+	return formatIssueCommandError({
+		command: commandId,
+		code: 'FORGE_ISSUE_INTERNAL',
+		message: `Issue mutation ${operation} returned an unexpected decision: ${result.decision}`,
+		exitCode: ISSUE_COMMAND_EXIT_CODES.internal,
+		retryable: false,
+		nextCommands: nextCommandsFor(commandId),
+	});
+}
+
+function createLocalBroker(options = {}) {
+	const driver = options.driver;
+	let cachedConfig;
+
+	// Memoized config build AND the structural home of the D19 default-on
+	// filesystem gate. getConfig() is the single chokepoint every DB-creating
+	// broker path funnels through (initialize, runIssueOperation, runGuardedEvent,
+	// the projection-outbox surface, and the public `config` getter), so asserting
+	// here guards them ALL — not just initialize(). This closes the D19-B2 bypass
+	// where runIssueOperation / listProjectionOutbox reached driver.exec → getDatabase
+	// → createDatabase on a refuse-class FS without ever calling initialize().
+	//
+	// FAIL-CLOSED ordering: build a LOCAL config, assert, and ONLY THEN populate the
+	// memo. If we cached before asserting, the first call would throw but a second
+	// call would see a populated memo, skip the (re-)assert, and proceed to create
+	// the DB — reintroducing the bypass. env/classifier/warn are injectable via
+	// createLocalBroker options for deterministic tests. Throws on refuse unless
+	// FORGE_KERNEL_ALLOW_UNSAFE_FS is set; warns (never throws) on warn classes.
+	function getConfig() {
+		if (!cachedConfig) {
+			const config = buildLocalBrokerConfig(options);
+			assertFilesystemSafeForKernel(config.databasePath, {
+				env: options.env,
+				warn: options.warn,
+				classifyFilesystem: options.classifyFilesystem,
+			});
+			cachedConfig = config;
+		}
+		return cachedConfig;
+	}
+
+	// The guarded-event pipeline (CAS/idempotency/lease/quarantine + atomic commit).
+	// Extracted to a local function so runIssueOperation can route issue mutations
+	// through it without re-implementing the path or going through `this`.
+	async function runGuardedEventImpl(event, context = {}) {
+		requireGuardedDriverMethods(driver);
+
+		const config = getConfig();
+		const now = context.now || new Date().toISOString();
+		const normalizedEvent = {
+			...event,
+			created_at: event.created_at || now,
+		};
+		const dependencyScope = buildDependencyScope(normalizedEvent);
+		if (dependencyScope) {
+			requireDriverMethod(driver, 'listKernelDependencies');
+		}
+		const claimScope = buildClaimScope(normalizedEvent);
+		// A claim.create with a missing/invalid payload (or wrong entity) has no
+		// scope. Quarantine it instead of falling through as a non-claim event:
+		// the generic evaluator would otherwise accept and persist the event +
+		// outbox without ever creating a kernel_claims lease, so a later claim on
+		// the real issue would proceed as if nothing were claimed. BUT a retry of
+		// an already-accepted claim (same idempotency_key) must still replay as a
+		// duplicate even if this retry's payload is malformed, so check that first.
+		if (normalizedEvent.event_type === 'claim.create' && !claimScope) {
+			return (await replayDuplicateIfIdempotent(driver, normalizedEvent, context, config))
+				|| insertClaimConflictResult(driver, normalizedEvent, null, 'invalid_claim_scope', context, config, now);
+		}
+		if (claimScope) {
+			requireDriverMethod(driver, 'loadActiveKernelClaim');
+			requireDriverMethod(driver, 'insertKernelClaim');
+		}
+
+		const [entity, entityEvents, idempotencyEvent, dependencies, activeClaim] = await Promise.all([
+			driver.loadKernelEntity(normalizedEvent.entity_type, normalizedEvent.entity_id, context, config),
+			driver.listKernelEvents(normalizedEvent.entity_type, normalizedEvent.entity_id, context, config),
+			driver.loadKernelEventByIdempotencyKey(normalizedEvent.idempotency_key, context, config),
+			dependencyScope
+				? driver.listKernelDependencies(dependencyScope, context, config)
+				: Promise.resolve([]),
+			claimScope
+				? driver.loadActiveKernelClaim(claimScope.issue_id, context, config)
+				: Promise.resolve(null),
+		]);
+		const priorEvents = idempotencyEvent
+			? [idempotencyEvent, ...entityEvents.filter(candidate => candidate.id !== idempotencyEvent.id)]
+			: entityEvents;
+		const evaluation = evaluateKernelEvent({
+			event: normalizedEvent,
+			entity,
+			priorEvents,
+			dependencies,
+		});
+
+		if (evaluation.decision === 'quarantine') {
+			const conflict = await driver.insertKernelConflict({
+				...evaluation.conflict,
+				created_at: evaluation.conflict.created_at || now,
+			}, context, config);
+			return { ...evaluation, conflict };
+		}
+
+		if (evaluation.decision !== 'accept') {
+			return evaluation;
+		}
+
+		return commitGuardedAccept({
+			driver, event: normalizedEvent, evaluation, claimScope, activeClaim, context, config, now,
+		});
+	}
+
+	// Route an issue mutation op through the guarded-event path: build the event,
+	// run it, and shape the issue-command-contract response/error.
+	async function runIssueMutation(operation, args, context) {
+		const config = getConfig();
+		let event;
+		try {
+			event = await buildIssueMutationEvent(driver, operation, args, context, config);
+		} catch (err) {
+			if (err && err.isIssueNotFound) {
+				// Missing target for update/close/comment: return the contract not-found
+				// error (exit 3) instead of letting the CAS mint a phantom row.
+				return formatIssueCommandError({
+					command: ISSUE_MUTATION_COMMAND_IDS[operation],
+					code: 'FORGE_ISSUE_NOT_FOUND',
+					message: err.message,
+					exitCode: ISSUE_COMMAND_EXIT_CODES.notFound,
+				});
+			}
+			if (err && err.isIssueValidation) {
+				// Out-of-contract input (empty title / invalid status/type/priority):
+				// return the contract validation error (exit 6) without writing a row.
+				return formatIssueCommandError({
+					command: ISSUE_MUTATION_COMMAND_IDS[operation],
+					code: 'FORGE_ISSUE_VALIDATION',
+					message: err.message,
+					exitCode: ISSUE_COMMAND_EXIT_CODES.validation,
+					details: err.validationField ? { field: err.validationField } : undefined,
+				});
+			}
+			throw err;
+		}
+		const result = await runGuardedEventImpl(event, context);
+		return mapMutationResult(driver, operation, event, result, context, config);
+	}
+
+	return {
+		get config() {
+			return getConfig();
+		},
+
+		async initialize() {
+			// D19 default-on filesystem gate now lives in getConfig() (the structural
+			// chokepoint shared by every DB-creating path), so the first getConfig()
+			// call here asserts the FS is safe BEFORE any driver.exec — the SQLite file
+			// is never created on a refuse-class (cloud/network) FS. Throws on refuse
+			// unless FORGE_KERNEL_ALLOW_UNSAFE_FS; injectable via createLocalBroker opts.
+			const config = getConfig();
+			requireDriverMethod(driver, 'exec');
+			requireDriverMethod(driver, 'queryAll');
+			for (const statement of config.pragmas) {
+				await driver.exec(statement, config);
+			}
+			// Apply only un-applied migrations, tracked in the ledger — no re-run of the
+			// whole plan on every init, and no blanket duplicate-error swallow.
+			await driver.exec(MIGRATION_LEDGER_CREATE, config);
+			const appliedRows = await driver.queryAll(`SELECT id FROM ${MIGRATION_LEDGER_TABLE};`, config);
+			const applied = new Set((appliedRows || []).map(row => row?.id));
+			const newlyApplied = [];
+			for (const migration of config.migrationPlan.migrations) {
+				if (applied.has(migration.id)) continue;
+				// Concurrency scope: execMigrationStatement only makes ADD COLUMN
+				// race-safe (pre-check + TOCTOU catch). This apply loop is NOT
+				// serialized, so a future non-idempotent, non-ADD-COLUMN migration
+				// (data backfill, non-`IF NOT EXISTS` DDL) would reintroduce a race —
+				// it would need `BEGIN IMMEDIATE` + an in-lock ledger re-read.
+				for (const statement of migration.apply || []) {
+					await execMigrationStatement(driver, statement, config);
+				}
+				await driver.exec(recordMigrationSql(migration.id), config);
+				newlyApplied.push(migration.id);
+			}
+
+			return {
+				success: true,
+				mode: config.mode,
+				databasePath: config.databasePath,
+				gitCommonDir: config.gitCommonDir,
+				journalMode: config.journalMode,
+				synchronous: config.synchronous,
+				foreignKeys: config.foreignKeys,
+				migrationsApplied: config.migrationPlan.migrations.map(migration => migration.id),
+				migrationsNewlyApplied: newlyApplied,
+			};
+		},
+
+		async runIssueOperation(operation, args = [], context = {}) {
+			// Git-style short issue-id support (kernel 9556660b): resolve any hex id
+			// prefix (>= 6 chars) in the id-carrying slots to the stored full id ONCE,
+			// here at the single boundary every kernel issue op flows through — so
+			// every subcommand, the batch-close fan-out, and the gate.issue_verify
+			// read-back all consume the RESOLVED id. Full UUIDs and legacy non-hex ids
+			// never trigger a lookup (byte-identical passthrough); the lookup — and
+			// therefore getConfig()'s FS gate — only fires when a token actually looks
+			// like a prefix, keeping mock-driver and gate ordering behavior unchanged.
+			const resolution = await resolveIssueIdArgs(operation, args, async (prefix, limit) => {
+				requireDriverMethod(driver, 'findIssueIdsByPrefix');
+				return driver.findIssueIdsByPrefix(prefix, limit, context, getConfig());
+			});
+			if (resolution.error) {
+				return formatIssueCommandError({
+					command: ISSUE_MUTATION_COMMAND_IDS[operation] || `issue.${operation}`,
+					code: resolution.error.code,
+					message: resolution.error.message,
+					exitCode: resolution.error.exitCode,
+					details: resolution.error.details,
+				});
+			}
+			// Mutations (create/update/close/comment) flow through the guarded-event
+			// path to preserve CAS/idempotency/quarantine; reads delegate directly to
+			// the driver's parameterized SELECT branch.
+			if (ISSUE_MUTATION_OPERATIONS.has(operation)) {
+				requireGuardedDriverMethods(driver);
+				requireDriverMethod(driver, 'applyAcceptedIssueMutation');
+				return runIssueMutation(operation, resolution.args, context);
+			}
+			requireDriverMethod(driver, 'issueOperation');
+			return driver.issueOperation(operation, resolution.args, context, getConfig());
+		},
+
+		async runGuardedEvent(event, context = {}) {
+			return runGuardedEventImpl(event, context);
+		},
+
+		// Faithful-import write path (the `forge migrate` enabler PR-3 calls). Consumes
+		// the records importBeadsSnapshot(snapshot).kernel produces — `{ issues, comments,
+		// dependencies, events }` — and writes them DIRECTLY to the authority tables via
+		// the driver's import primitive, PRESERVING each issue's original
+		// created_at/updated_at, terminal status (done/cancelled), priority(+rank),
+		// labels, acceptance/content + beads-fidelity columns, plus its comments and
+		// dependency edges. Distinct from the create/update guarded path (which now-stamps
+		// + bumps CAS); the normal mutation contract is unchanged.
+		//
+		// PRECONDITION: initialize() must have run first (this does NOT auto-init) so the
+		// schema/migrations exist. The canonical input is the `.kernel` records object; the
+		// full importBeadsSnapshot result is accepted as a convenience and unwrapped.
+		// Idempotent (re-import skips existing ids) and transactional. Returns
+		// { issues, comments, dependencies, events } each { inserted, skipped } — where events
+		// are the legacy beads activity/interaction records landed in kernel_events.
+		async importIssues(records = {}, options = {}) {
+			requireDriverMethod(driver, 'importIssues');
+			const config = getConfig();
+			const kernel = records && records.kernel ? records.kernel : records;
+			return driver.importIssues(kernel, options, {}, config);
+		},
+
+		// --- Projection-outbox read/update surface (D16) -----------------------
+		// Additive read/update methods for projection consumers. These never touch
+		// the append/CAS path above (runGuardedEvent / enqueueKernelProjection);
+		// they only read and update existing outbox rows or dead-letter them.
+
+		async listProjectionOutbox(filter = {}, context = {}) {
+			requireDriverMethod(driver, 'listProjectionOutbox');
+			return driver.listProjectionOutbox(filter, context, getConfig());
+		},
+
+		async loadProjectionModel(context = {}) {
+			requireDriverMethod(driver, 'loadProjectionModel');
+			return driver.loadProjectionModel(context, getConfig());
+		},
+
+		async markProjectionDelivered(ids, meta = {}, context = {}) {
+			requireDriverMethod(driver, 'markProjectionDelivered');
+			return driver.markProjectionDelivered(ids, meta, context, getConfig());
+		},
+
+		async recordProjectionFailure(record, context = {}) {
+			requireDriverMethod(driver, 'recordProjectionFailure');
+			return driver.recordProjectionFailure(record, context, getConfig());
+		},
+
+		async deadLetterProjection(record, context = {}) {
+			requireDriverMethod(driver, 'deadLetterProjection');
+			return driver.deadLetterProjection(record, context, getConfig());
+		},
+	};
+}
+
+module.exports = {
+	LOCAL_BROKER_PRAGMAS,
+	buildLocalBrokerConfig,
+	createLocalBroker,
+	execMigrationStatement,
+	resolveGitCommonDir,
+};