forge-workflow 0.0.10 → 0.1.0-beta.2

package/lib/kernel/readiness-model.js

@@ -0,0 +1,329 @@
+'use strict';
+
+const { getTypeBehavior, isTerminalStatus, normalizeRank, toEpochMillis } = require('./taxonomy-validator');
+
+// Readiness is a DERIVED read model (D18). `ready`/`blocked` are computed on demand
+// from dependencies, claims, quarantine/conflicts, gates, defer windows, and policy —
+// they are NEVER stored as issue status values.
+const READINESS_REASONS = Object.freeze({
+	DEPENDENCY: 'dependency',
+	// A blocker that is itself PARKED (backlog): it will never complete on its own, so it
+	// blocks its dependents indefinitely. Surfaced as a distinct code (not plain
+	// `dependency`) so a parked blocker is not mistaken for ordinary in-flight work — a
+	// consumer can flag it for promotion instead of waiting on it forever.
+	DEPENDENCY_PARKED: 'dependency_parked',
+	QUARANTINE: 'quarantine',
+	CONFLICT: 'conflict',
+	GATE: 'gate',
+	CLAIM: 'claimed',
+	DEFERRED: 'deferred',
+	POLICY: 'policy_disabled',
+});
+
+const READINESS_STATES = Object.freeze([
+	'ready',
+	'blocked',
+	'gated',
+	'deferred',
+	'claimed',
+	'disabled',
+	'closed',
+	'backlog',
+]);
+
+const WORKABLE_STATUSES = Object.freeze(['open', 'in_progress']);
+
+/** @returns {boolean} true if `status` is a pickable working status (open/in_progress). */
+function isWorkableStatus(status) {
+	return WORKABLE_STATUSES.includes(status);
+}
+
+// Ready work must be claimable: epics (containers) and decisions are claimable:false, so they
+// never belong in the ready queue even when unblocked. A known non-claimable type is excluded;
+// an unknown/unspecified type is not penalised (callers may omit `type`).
+function isReadyEligibleType(type) {
+	const behavior = getTypeBehavior(type);
+	return behavior ? behavior.claimable : true;
+}
+
+// Edge-only blocking test: keys off the dependency RELATIONSHIP (dependency_type),
+// NOT the blocking issue's type. Distinct from taxonomy-validator's isBlockingDependency,
+// which also falls back to `.type`; do not merge them (see readiness decision-dependency).
+function isBlockingDependencyEdge(dependency) {
+	return (dependency.dependency_type || 'blocks') === 'blocks';
+}
+
+function isDeferred(issue, now) {
+	if (!issue.defer_until) return false;
+	const deferMillis = toEpochMillis(issue.defer_until);
+	if (deferMillis === null) return false; // an unparseable defer window is not a defer
+	const nowMillis = toEpochMillis(now);
+	// Fail closed: without a usable clock we cannot confirm the window elapsed, so a deferred
+	// issue stays deferred rather than incorrectly surfacing as ready. Keeps the model pure
+	// (caller supplies `now`) instead of reaching for a wall clock.
+	if (nowMillis === null) return true;
+	return deferMillis > nowMillis;
+}
+
+function findConflictingClaim(issueId, claims, actor, now) {
+	const nowMillis = toEpochMillis(now);
+	for (const claim of claims || []) {
+		if (claim.issue_id !== issueId) continue;
+		if ((claim.state || 'active') !== 'active') continue;
+		if (actor && claim.actor === actor) continue; // the requesting actor's own claim does not block them
+		// An active row whose lease has elapsed is dead (validateClaim agrees) — it must not
+		// keep the issue out of the ready queue for other actors. If `now` is unknown we cannot
+		// confirm expiry, so the claim still blocks (conservative).
+		const expiresMillis = toEpochMillis(claim.expires_at);
+		if (expiresMillis !== null && nowMillis !== null && expiresMillis <= nowMillis) continue;
+		return claim;
+	}
+	return null;
+}
+
+function collectDependencyBlockers(context, reasons, blockedBy) {
+	for (const dependency of context.dependencyStatuses || []) {
+		if (!isBlockingDependencyEdge(dependency)) continue;
+		// A terminal (done OR cancelled) blocker will never complete again, so it no longer
+		// blocks — a cancelled dependency must not wedge the dependent as permanently blocked.
+		if (isTerminalStatus(dependency.status)) continue;
+		blockedBy.push(dependency.id);
+		// A parked (backlog) blocker earns a distinct code + flag: it is stalled by design,
+		// not being actively worked, so consumers can call it out for promotion.
+		const isParked = dependency.status === 'backlog';
+		const code = isParked ? READINESS_REASONS.DEPENDENCY_PARKED : READINESS_REASONS.DEPENDENCY;
+		const reason = { code, issue_id: dependency.id, status: dependency.status };
+		if (isParked) {
+			reason.parked = true;
+		}
+		if (dependency.type === 'decision') {
+			reason.decision = true;
+		}
+		reasons.push(reason);
+	}
+}
+
+function collectConflictBlockers(issue, context, reasons) {
+	let hasConflict = false;
+	for (const conflict of context.conflicts || []) {
+		// Conflicts are keyed by (entity_type, entity_id). Only issue-scoped conflicts block an
+		// issue; a quarantined dependency/release/sprint that happens to share the id string must
+		// not. Absent entity_type is treated as legacy issue-scoped.
+		if (conflict.entity_type && conflict.entity_type !== 'issue') continue;
+		if (conflict.entity_id && issue.id && conflict.entity_id !== issue.id) continue;
+		hasConflict = true;
+		const status = conflict.status || 'quarantined';
+		const code = status === 'quarantined' ? READINESS_REASONS.QUARANTINE : READINESS_REASONS.CONFLICT;
+		reasons.push({ code, status });
+	}
+	return hasConflict;
+}
+
+function collectGateBlockers(context, reasons) {
+	let hasGate = false;
+	for (const gate of context.gates || []) {
+		if (gate.satisfied) continue;
+		hasGate = true;
+		reasons.push({ code: READINESS_REASONS.GATE, gate: gate.name });
+	}
+	return hasGate;
+}
+
+// Precedence high→low. `blocked` (dependencies/quarantine/conflict) always outranks the
+// softer not-ready reasons; consumers picking next work should read the full reasons[]
+// because a claim hidden behind a defer window is not reflected in this single summary.
+function deriveState(flags) {
+	if (flags.blocked) return 'blocked';
+	if (flags.hasGate) return 'gated';
+	if (flags.deferred) return 'deferred';
+	if (flags.hasClaim) return 'claimed';
+	if (flags.policyDisabled) return 'disabled';
+	if (flags.ready) return 'ready';
+	return 'backlog';
+}
+
+/**
+ * Derive an issue's readiness (a read model, never stored) from its context.
+ * @param {object} issue stored issue fields (id, status, defer_until, ...).
+ * @param {object} context { now, actor, dependencyStatuses[], conflicts[], gates[], claims[], policyDisabled }.
+ * @returns {{id, status, ready: boolean, blocked: boolean, blocked_by: string[], reasons: object[], state: string}}
+ */
+function deriveReadiness(issue = {}, context = {}) {
+	const id = issue.id;
+	const status = issue.status;
+
+	if (isTerminalStatus(status)) {
+		return { id, status, ready: false, blocked: false, blocked_by: [], reasons: [], state: 'closed' };
+	}
+
+	// A `backlog` (parked) issue is a first-class lifecycle state, not workable work: it
+	// reads as parked regardless of any dependencies/gates — never ready, never blocked —
+	// so parked ideas do not surface in ready/blocked queues or flag stale.
+	if (status === 'backlog') {
+		return { id, status, ready: false, blocked: false, blocked_by: [], reasons: [], state: 'backlog' };
+	}
+
+	const reasons = [];
+	const blockedBy = [];
+
+	collectDependencyBlockers(context, reasons, blockedBy);
+	const hasConflict = collectConflictBlockers(issue, context, reasons);
+	const hasGate = collectGateBlockers(context, reasons);
+
+	const deferred = isDeferred(issue, context.now);
+	if (deferred) {
+		reasons.push({ code: READINESS_REASONS.DEFERRED, until: issue.defer_until });
+	}
+
+	const policyDisabled = Boolean(context.policyDisabled);
+	if (policyDisabled) {
+		reasons.push({ code: READINESS_REASONS.POLICY });
+	}
+
+	const conflictingClaim = findConflictingClaim(id, context.claims, context.actor, context.now);
+	if (conflictingClaim) {
+		reasons.push({ code: READINESS_REASONS.CLAIM, actor: conflictingClaim.actor });
+	}
+
+	const blocked = blockedBy.length > 0 || hasConflict;
+	const ready = !blocked
+		&& !hasGate
+		&& !deferred
+		&& !policyDisabled
+		&& !conflictingClaim
+		&& isWorkableStatus(status)
+		&& isReadyEligibleType(issue.type);
+
+	const state = deriveState({
+		blocked,
+		hasGate,
+		deferred,
+		hasClaim: Boolean(conflictingClaim),
+		policyDisabled,
+		ready,
+	});
+
+	return { id, status, ready, blocked, blocked_by: blockedBy, reasons, state };
+}
+
+// BETA stop-gap for claim thundering-herd (kernel 369c43d7): concurrent `forge ready`
+// callers previously all saw the identical rank-0 top pick and raced to claim it (CAS
+// lets exactly one win, but the rest burn a claim_conflict write + wasted pre-claim
+// reasoning, then re-collide on rank-1, etc). Randomizing which of the top-K
+// same-priority issues sorts first spreads concurrent agents across different ready
+// issues. Priority tier ordering stays the PRIMARY, un-randomized sort key: only the
+// contiguous run of issues sharing the single highest-ranked (lowest-number) priority
+// tier is shuffled, and only its first `topK` members — a lower-priority issue can
+// never be promoted ahead of a ready higher-priority one. Full fix is Phase-2 per-project
+// lease dispatch; this is the cheap interim mitigation only.
+const DEFAULT_TOP_K_READY_PICK = 5;
+
+// Fisher-Yates, using an injectable rng (defaults to Math.random) so callers/tests can
+// seed it for deterministic assertions. Mutates and returns `array`.
+function shuffleInPlace(array, rng) {
+	for (let i = array.length - 1; i > 0; i--) {
+		const j = Math.floor(rng() * (i + 1));
+		[array[i], array[j]] = [array[j], array[i]];
+	}
+	return array;
+}
+
+// Randomize only the top-K of the single highest-priority tier at the front of an
+// already rank+id sorted `sortedIssues` array. Everything else (the tier's remainder
+// beyond K, and every lower-priority tier) keeps its deterministic order untouched.
+function applyTopKRandomizedPick(sortedIssues, { topK = DEFAULT_TOP_K_READY_PICK, rng = Math.random } = {}) {
+	if (sortedIssues.length < 2) return sortedIssues;
+
+	const topRank = normalizeRank(sortedIssues[0].priority_rank);
+	let tierEnd = 0;
+	while (tierEnd < sortedIssues.length && normalizeRank(sortedIssues[tierEnd].priority_rank) === topRank) {
+		tierEnd++;
+	}
+
+	const k = Math.max(0, Math.min(topK, tierEnd));
+	if (k < 2) return sortedIssues; // nothing to shuffle: <2 candidates in the randomized head
+
+	const head = shuffleInPlace(sortedIssues.slice(0, k), rng);
+	const rest = sortedIssues.slice(k);
+	return [...head, ...rest];
+}
+
+function groupBy(items, keyFn) {
+	const grouped = new Map();
+	for (const item of items || []) {
+		const key = keyFn(item);
+		if (!grouped.has(key)) grouped.set(key, []);
+		grouped.get(key).push(item);
+	}
+	return grouped;
+}
+
+/**
+ * Compute readiness for a whole board, resolving each dependency's status from the issue set.
+ * @param {object} input { issues[], dependencies[], conflicts[], claims[], gates[], policyDisabledIds[], now, actor,
+ *   topK, rng }. `topK` (default {@link DEFAULT_TOP_K_READY_PICK}) and `rng` (default `Math.random`, injectable for
+ *   deterministic tests) control the BETA top-K randomized ready pick (kernel 369c43d7): only the top-K of the
+ *   single highest-priority ready tier is shuffled; priority ordering otherwise stays the primary sort.
+ * @returns {{readinessById: object, readyQueue: string[], blocked: string[]}} readyQueue is ranked by the single
+ *   numeric rank, with the top-K of its leading priority tier randomized.
+ */
+function buildReadinessIndex(input = {}) {
+	const issues = input.issues || [];
+	const statusById = new Map(issues.map(issue => [issue.id, issue.status]));
+	const typeById = new Map(issues.map(issue => [issue.id, issue.type]));
+
+	const dependencyStatusesByIssue = new Map();
+	for (const dependency of input.dependencies || []) {
+		if (!dependencyStatusesByIssue.has(dependency.issue_id)) {
+			dependencyStatusesByIssue.set(dependency.issue_id, []);
+		}
+		dependencyStatusesByIssue.get(dependency.issue_id).push({
+			id: dependency.blocks_issue_id,
+			status: statusById.get(dependency.blocks_issue_id),
+			type: typeById.get(dependency.blocks_issue_id),
+			dependency_type: dependency.dependency_type,
+		});
+	}
+
+	const conflictsByIssue = groupBy(input.conflicts, conflict => conflict.entity_id);
+	const claimsByIssue = groupBy(input.claims, claim => claim.issue_id);
+	const gatesByIssue = groupBy(input.gates, gate => gate.issue_id);
+	const policyDisabledIds = new Set(input.policyDisabledIds || []);
+
+	// Null-prototype map: issue ids are unconstrained external strings, so a literal `{}`
+	// keyed by them would be a prototype-pollution vector (e.g. an id of `__proto__`).
+	const readinessById = Object.create(null);
+	for (const issue of issues) {
+		readinessById[issue.id] = deriveReadiness(issue, {
+			now: input.now,
+			actor: input.actor,
+			dependencyStatuses: dependencyStatusesByIssue.get(issue.id) || [],
+			conflicts: conflictsByIssue.get(issue.id) || [],
+			claims: claimsByIssue.get(issue.id) || [],
+			gates: gatesByIssue.get(issue.id) || [],
+			policyDisabled: policyDisabledIds.has(issue.id),
+		});
+	}
+
+	const readyIssues = issues.filter(issue => readinessById[issue.id].ready);
+	readyIssues.sort((left, right) => (
+		(normalizeRank(left.priority_rank) - normalizeRank(right.priority_rank))
+		|| String(left.id).localeCompare(String(right.id))
+	));
+	const pickedReadyIssues = applyTopKRandomizedPick(readyIssues, { topK: input.topK, rng: input.rng });
+
+	return {
+		readinessById,
+		readyQueue: pickedReadyIssues.map(issue => issue.id),
+		blocked: issues.filter(issue => readinessById[issue.id].blocked).map(issue => issue.id),
+	};
+}
+
+module.exports = {
+	READINESS_REASONS,
+	READINESS_STATES,
+	DEFAULT_TOP_K_READY_PICK,
+	buildReadinessIndex,
+	deriveReadiness,
+	isWorkableStatus,
+};

package/lib/kernel/schema.js

@@ -0,0 +1,356 @@
+const KERNEL_STORAGE_CLASSES = Object.freeze([
+	'authority',
+	'read_model',
+	'projection',
+	'archive',
+	'configuration',
+	'cache',
+	'external_provider',
+]);
+
+const KERNEL_FIELD_AUTHORITIES = Object.freeze([
+	'forge',
+	'provider',
+	'configured_provider',
+	'projection_only',
+]);
+
+function deepFreeze(value) {
+	if (!value || typeof value !== 'object') return value;
+	Object.freeze(value);
+	for (const nestedValue of Object.values(value)) {
+		deepFreeze(nestedValue);
+	}
+	return value;
+}
+
+function field(name, type, options = {}) {
+	return {
+		name,
+		type,
+		storageClass: options.storageClass,
+		authority: options.authority || 'forge',
+		primaryKey: Boolean(options.primaryKey),
+		notNull: Boolean(options.notNull || options.primaryKey),
+		default: options.default,
+		references: options.references,
+	};
+}
+
+function index(name, columns, options = {}) {
+	return {
+		name,
+		columns,
+		unique: Boolean(options.unique),
+	};
+}
+
+function table(name, storageClass, fields, indexes = []) {
+	return {
+		name,
+		sqlName: `kernel_${name}`,
+		storageClass,
+		authority: 'forge',
+		fields: fields.map(fieldDefinition => ({
+			...fieldDefinition,
+			storageClass: fieldDefinition.storageClass || storageClass,
+		})),
+		indexes,
+	};
+}
+
+const TABLE_LIST = deepFreeze([
+	table('issues', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('title', 'TEXT', { notNull: true }),
+		field('body', 'TEXT'),
+		field('type', 'TEXT', { notNull: true, default: "'task'" }),
+		field('status', 'TEXT', { notNull: true, default: "'open'" }),
+		field('priority', 'TEXT', { notNull: true, default: "'P2'" }),
+		field('priority_rank', 'INTEGER', { notNull: true, default: '0', storageClass: 'read_model' }),
+		field('created_at', 'TEXT', { notNull: true }),
+		field('updated_at', 'TEXT', { notNull: true }),
+		field('entity_revision', 'INTEGER', { notNull: true, default: '0' }),
+		// D18 taxonomy: hierarchy, planning buckets, and execution stage are separate
+		// axes from status. ready/blocked stay derived (readiness-model), never stored.
+		field('parent_id', 'TEXT', { references: 'issues.id' }),
+		field('sprint_id', 'TEXT'),
+		field('release_id', 'TEXT'),
+		field('stage_state', 'TEXT'),
+		field('labels', 'TEXT'),
+		field('acceptance_criteria', 'TEXT'),
+		field('estimate', 'TEXT'),
+		// KAP-10 (design/notes) + KAP-11 (assignee): authored content fields and a
+		// persistent assignee. Migration 004 backfills existing DBs; fresh DBs get them here.
+		field('design', 'TEXT'),
+		field('notes', 'TEXT'),
+		field('assignee', 'TEXT'),
+		// Beads full-fidelity import: the issue author, the close timestamp + raw close
+		// reason (distinct from the mapped terminal status), and a verbatim JSON blob for
+		// any other beads metadata. Migration 006 backfills existing DBs; fresh DBs get
+		// them here.
+		field('created_by', 'TEXT'),
+		field('closed_at', 'TEXT'),
+		field('close_reason', 'TEXT'),
+		field('metadata', 'TEXT'),
+	], [
+		index('idx_kernel_issues_status_priority', ['status', 'priority_rank']),
+		index('idx_kernel_issues_updated_at', ['updated_at']),
+		index('idx_kernel_issues_parent', ['parent_id']),
+		index('idx_kernel_issues_sprint', ['sprint_id']),
+		index('idx_kernel_issues_release', ['release_id']),
+	]),
+	table('dependencies', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('issue_id', 'TEXT', { notNull: true, references: 'issues.id' }),
+		field('blocks_issue_id', 'TEXT', { notNull: true, references: 'issues.id' }),
+		field('dependency_type', 'TEXT', { notNull: true, default: "'blocks'" }),
+		field('created_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_dependencies_issue', ['issue_id']),
+		index('idx_kernel_dependencies_blocks', ['blocks_issue_id']),
+	]),
+	table('comments', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('issue_id', 'TEXT', { notNull: true, references: 'issues.id' }),
+		field('body', 'TEXT', { notNull: true }),
+		field('actor', 'TEXT', { notNull: true }),
+		field('visibility', 'TEXT', { notNull: true, default: "'local'" }),
+		field('created_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_comments_issue_created', ['issue_id', 'created_at']),
+	]),
+	table('priority_events', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('issue_id', 'TEXT', { notNull: true, references: 'issues.id' }),
+		field('old_priority', 'TEXT'),
+		field('new_priority', 'TEXT', { notNull: true }),
+		field('priority_rank', 'INTEGER', { notNull: true }),
+		field('actor', 'TEXT', { notNull: true }),
+		field('created_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_priority_events_issue_created', ['issue_id', 'created_at']),
+	]),
+	table('claims', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('issue_id', 'TEXT', { notNull: true, references: 'issues.id' }),
+		field('actor', 'TEXT', { notNull: true }),
+		field('state', 'TEXT', { notNull: true, default: "'active'" }),
+		field('session_id', 'TEXT'),
+		field('worktree_id', 'TEXT'),
+		field('claimed_at', 'TEXT', { notNull: true }),
+		field('expires_at', 'TEXT'),
+	], [
+		index('idx_kernel_claims_issue_state', ['issue_id', 'state']),
+		index('idx_kernel_claims_actor_state', ['actor', 'state']),
+	]),
+	table('sessions', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('actor', 'TEXT', { notNull: true }),
+		field('git_common_dir', 'TEXT', { notNull: true }),
+		field('worktree_id', 'TEXT'),
+		field('started_at', 'TEXT', { notNull: true }),
+		field('ended_at', 'TEXT'),
+		field('state', 'TEXT', { notNull: true, default: "'active'" }),
+	], [
+		index('idx_kernel_sessions_common_dir_state', ['git_common_dir', 'state']),
+	]),
+	table('worktrees', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('git_common_dir', 'TEXT', { notNull: true }),
+		field('path', 'TEXT', { notNull: true, storageClass: 'configuration' }),
+		field('branch', 'TEXT', { notNull: true }),
+		field('actor', 'TEXT'),
+		// The kernel linkage backbone: a worktree row records which issue it serves
+		// (issue_id) and which work-folder that issue owns (work_folder, repo-relative).
+		// Both are nullable — a worktree can be registered before its issue/work-folder
+		// is known. Added by migration 007 (see migrations.js MIGRATION_ADDED_COLUMNS).
+		field('issue_id', 'TEXT'),
+		field('work_folder', 'TEXT', { storageClass: 'configuration' }),
+		field('registered_at', 'TEXT', { notNull: true }),
+		field('state', 'TEXT', { notNull: true, default: "'active'" }),
+	], [
+		index('idx_kernel_worktrees_common_dir_branch', ['git_common_dir', 'branch']),
+	]),
+	table('stage_runs', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('issue_id', 'TEXT', { notNull: true, references: 'issues.id' }),
+		field('stage', 'TEXT', { notNull: true }),
+		field('substage', 'TEXT'),
+		field('status', 'TEXT', { notNull: true }),
+		field('started_at', 'TEXT', { notNull: true }),
+		field('completed_at', 'TEXT'),
+		field('evidence_id', 'TEXT'),
+	], [
+		index('idx_kernel_stage_runs_issue_stage', ['issue_id', 'stage']),
+		index('idx_kernel_stage_runs_status', ['status']),
+	]),
+	table('evidence', 'archive', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('issue_id', 'TEXT'),
+		field('run_id', 'TEXT'),
+		field('kind', 'TEXT', { notNull: true }),
+		field('uri', 'TEXT'),
+		field('summary', 'TEXT'),
+		field('created_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_evidence_issue_kind', ['issue_id', 'kind']),
+	]),
+	table('projections', 'projection', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('target', 'TEXT', { notNull: true, storageClass: 'external_provider', authority: 'configured_provider' }),
+		field('entity_type', 'TEXT', { notNull: true }),
+		field('entity_id', 'TEXT', { notNull: true }),
+		field('status', 'TEXT', { notNull: true }),
+		field('last_error', 'TEXT', { storageClass: 'cache', authority: 'projection_only' }),
+		field('updated_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_projections_target_status', ['target', 'status']),
+		index('idx_kernel_projections_entity', ['entity_type', 'entity_id']),
+	]),
+	table('conflicts', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('entity_type', 'TEXT', { notNull: true }),
+		field('entity_id', 'TEXT', { notNull: true }),
+		field('expected_revision', 'INTEGER', { notNull: true }),
+		field('actual_revision', 'INTEGER', { notNull: true }),
+		field('status', 'TEXT', { notNull: true, default: "'quarantined'" }),
+		field('payload_json', 'TEXT', { notNull: true }),
+		field('created_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_conflicts_status', ['status']),
+		index('idx_kernel_conflicts_entity', ['entity_type', 'entity_id']),
+	]),
+	table('events', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('entity_type', 'TEXT', { notNull: true }),
+		field('entity_id', 'TEXT', { notNull: true }),
+		field('event_type', 'TEXT', { notNull: true }),
+		field('idempotency_key', 'TEXT', { notNull: true }),
+		field('expected_revision', 'INTEGER', { notNull: true }),
+		field('actor', 'TEXT', { notNull: true }),
+		field('origin', 'TEXT', { notNull: true }),
+		field('payload_json', 'TEXT', { notNull: true }),
+		field('created_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_events_entity_created', ['entity_type', 'entity_id', 'created_at']),
+		index('idx_kernel_events_idempotency', ['idempotency_key'], { unique: true }),
+	]),
+	table('outbox', 'projection', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('event_id', 'TEXT', { notNull: true, references: 'events.id' }),
+		field('target', 'TEXT', { notNull: true }),
+		field('status', 'TEXT', { notNull: true, default: "'pending'" }),
+		field('attempts', 'INTEGER', { notNull: true, default: '0' }),
+		field('next_attempt_at', 'TEXT'),
+		field('created_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_outbox_target_status', ['target', 'status']),
+	]),
+	table('dead_letters', 'projection', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('outbox_id', 'TEXT'),
+		field('target', 'TEXT', { notNull: true }),
+		field('status', 'TEXT', { notNull: true, default: "'open'" }),
+		field('error', 'TEXT', { notNull: true }),
+		field('payload_json', 'TEXT', { notNull: true }),
+		field('created_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_dead_letters_status', ['status']),
+	]),
+	// Project memory is a Forge read model: durable key/value notes written DIRECTLY
+	// (NOT through the issue CAS/guarded-event path). `key` is the stable identity;
+	// value_json holds the serialized memory value, and the *_json columns carry the
+	// optional list fields. Created by migration 005 (excluded from the 001 initial
+	// schema), so a fresh DB creates it exactly once and an existing DB picks it up
+	// via the broker ledger.
+	table('memories', 'read_model', [
+		field('key', 'TEXT', { primaryKey: true }),
+		field('value_json', 'TEXT', { notNull: true }),
+		field('source_agent', 'TEXT', { notNull: true }),
+		field('scope', 'TEXT'),
+		field('confidence', 'REAL'),
+		field('tags_json', 'TEXT'),
+		field('supersedes_json', 'TEXT'),
+		field('beads_refs_json', 'TEXT'),
+		field('created_at', 'TEXT', { notNull: true }),
+		field('updated_at', 'TEXT', { notNull: true }),
+	], [
+		index('idx_kernel_memories_source_agent', ['source_agent']),
+	]),
+]);
+
+const KERNEL_TABLES = deepFreeze(Object.fromEntries(TABLE_LIST.map(candidate => [candidate.name, candidate])));
+
+function classifyKernelStorage(tableName) {
+	const tableDefinition = KERNEL_TABLES[tableName];
+	if (!tableDefinition) {
+		throw new Error(`Unknown Kernel table: ${tableName}`);
+	}
+
+	return {
+		table: tableDefinition.name,
+		sqlName: tableDefinition.sqlName,
+		storageClass: tableDefinition.storageClass,
+		authority: tableDefinition.authority,
+	};
+}
+
+function validateKernelSchema(schema = getKernelSchema()) {
+	const tableNames = new Set();
+	for (const tableDefinition of schema.tables) {
+		if (tableNames.has(tableDefinition.name)) {
+			throw new Error(`Duplicate Kernel table: ${tableDefinition.name}`);
+		}
+		tableNames.add(tableDefinition.name);
+		if (!KERNEL_STORAGE_CLASSES.includes(tableDefinition.storageClass)) {
+			throw new Error(`Invalid storage class for ${tableDefinition.name}: ${tableDefinition.storageClass}`);
+		}
+		if (!KERNEL_FIELD_AUTHORITIES.includes(tableDefinition.authority)) {
+			throw new Error(`Invalid table authority for ${tableDefinition.name}: ${tableDefinition.authority}`);
+		}
+		for (const fieldDefinition of tableDefinition.fields) {
+			if (!KERNEL_STORAGE_CLASSES.includes(fieldDefinition.storageClass)) {
+				throw new Error(`Invalid storage class for ${tableDefinition.name}.${fieldDefinition.name}: ${fieldDefinition.storageClass}`);
+			}
+			if (!KERNEL_FIELD_AUTHORITIES.includes(fieldDefinition.authority)) {
+				throw new Error(`Invalid field authority for ${tableDefinition.name}.${fieldDefinition.name}: ${fieldDefinition.authority}`);
+			}
+		}
+	}
+
+	return true;
+}
+
+/** Deep-clone a table list so callers receive isolated, mutation-safe schema definitions. */
+function cloneTableList(tableList) {
+	return tableList.map(tableDefinition => ({
+		...tableDefinition,
+		fields: tableDefinition.fields.map(fieldDefinition => ({ ...fieldDefinition })),
+		indexes: tableDefinition.indexes.map(indexDefinition => ({
+			...indexDefinition,
+			columns: [...indexDefinition.columns],
+		})),
+	}));
+}
+
+function getKernelSchema() {
+	return {
+		version: 1,
+		tables: cloneTableList(TABLE_LIST),
+	};
+}
+
+module.exports = {
+	KERNEL_FIELD_AUTHORITIES,
+	KERNEL_STORAGE_CLASSES,
+	KERNEL_TABLES,
+	classifyKernelStorage,
+	cloneTableList,
+	deepFreeze,
+	field,
+	getKernelSchema,
+	index,
+	table,
+	validateKernelSchema,
+};