forge-workflow 0.1.0-beta.5 → 0.1.0-beta.7

package/lib/kernel/live-claim-projection.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { isLeaseExpired, isValidExpiresAt } = require('./lease-enforcer');
+const { isTerminalStatus } = require('./taxonomy-validator');
+
+// One authority definition for every user-facing lease projection. Null expiry is
+// the compatibility form for a durable lease; malformed expiry cannot prove liveness.
+function isLiveClaim(claim, issue, now) {
+	if (!claim || !issue) return false;
+	if (claim.state !== 'active') return false;
+	if (isTerminalStatus(issue.status)) return false;
+	if (!isValidExpiresAt(claim.expires_at)) return false;
+	return !isLeaseExpired(claim, now);
+}
+
+function projectLiveClaims(claims, issues, now) {
+	const claimRows = claims ?? [];
+	const issueRows = issues ?? [];
+	const issuesById = new Map(issueRows.map(issue => [issue.id, issue]));
+	return claimRows.filter(claim => isLiveClaim(claim, issuesById.get(claim.issue_id), now));
+}
+
+module.exports = {
+	isLiveClaim,
+	projectLiveClaims,
+};

package/lib/kernel/migrations.js

@@ -1,4 +1,5 @@
 const { getKernelSchema, validateKernelSchema } = require('./schema');
+const { USAGE_EVIDENCE_MIGRATION } = require('@forge/memory');
 
 function assertIdentifier(identifier, label) {
 	if (!/^[a-z][a-z0-9_]*$/.test(identifier)) {
@@ -24,12 +25,21 @@ function renderColumn(field) {
 	if (field.primaryKey) parts.push('PRIMARY KEY');
 	if (field.default !== undefined) parts.push(`DEFAULT ${field.default}`);
 	if (field.references) parts.push(renderReference(field.references));
+	if (field.check) parts.push(`CHECK (${field.check})`);
 	return parts.join(' ');
 }
 
 function renderCreateTable(table) {
 	assertIdentifier(table.sqlName, 'table');
-	const columns = table.fields.map(field => `  ${renderColumn(field)}`).join(',\n');
+	const definitions = table.fields.map(field => `  ${renderColumn(field)}`);
+	if (table.primaryKey) {
+		const columns = table.primaryKey.map(column => {
+			assertIdentifier(column, 'primary key column');
+			return column;
+		}).join(', ');
+		definitions.push(`  PRIMARY KEY (${columns})`);
+	}
+	const columns = definitions.join(',\n');
 	return `CREATE TABLE IF NOT EXISTS ${table.sqlName} (\n${columns}\n);`;
 }
 
@@ -57,8 +67,13 @@ function renderDropTable(table) {
 // 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 ; pr → 009
-const MIGRATION_ADDED_TABLES = ['memories', 'pr'];
+//   memories → 005 ; pr → 009 ; PR watch ownership → 012
+const MIGRATION_ADDED_TABLES = [
+	'memories',
+	'pr',
+	'pr_watch_owners',
+	'pr_watch_migration_gate',
+];
 
 function getInitialKernelSchema() {
 	const schema = getKernelSchema();
@@ -304,6 +319,100 @@ function buildPrLinkageMigration() {
 	};
 }
 
+// 010: Memory-owned durable monitor evidence. This is intentionally additive and
+// isolated from Kernel authority tables. Rollback is non-destructive: it turns off
+// new monitor writes while retaining every event, outbox row, receipt, and cursor.
+function buildMonitorDurabilityMigration() {
+	return {
+		id: '010_memory_monitor_durability',
+		apply: [
+			`CREATE TABLE IF NOT EXISTS memory_monitor_writer_state (
+  singleton INTEGER NOT NULL PRIMARY KEY CHECK (singleton = 1),
+  enabled INTEGER NOT NULL CHECK (enabled IN (0, 1))
+);`,
+			'INSERT OR IGNORE INTO memory_monitor_writer_state (singleton, enabled) VALUES (1, 1);',
+			`CREATE TABLE IF NOT EXISTS memory_monitor_events (
+  event_id TEXT NOT NULL PRIMARY KEY,
+  monitor_id TEXT NOT NULL,
+  sequence INTEGER NOT NULL,
+  content_hash TEXT NOT NULL,
+  envelope_json TEXT NOT NULL,
+  artifact_digest TEXT,
+  created_at TEXT NOT NULL,
+  UNIQUE (monitor_id, sequence)
+);`,
+			`CREATE TABLE IF NOT EXISTS memory_monitor_outbox (
+  id TEXT NOT NULL PRIMARY KEY,
+  event_id TEXT NOT NULL REFERENCES memory_monitor_events(event_id),
+  target TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at TEXT,
+  created_at TEXT NOT NULL,
+  UNIQUE (event_id, target)
+);`,
+			`CREATE TABLE IF NOT EXISTS memory_monitor_delivery_receipts (
+  event_id TEXT NOT NULL REFERENCES memory_monitor_events(event_id),
+  target TEXT NOT NULL,
+  attempt INTEGER NOT NULL,
+  content_hash TEXT NOT NULL,
+  envelope_json TEXT NOT NULL,
+  acknowledged INTEGER NOT NULL,
+  delivered_at TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  PRIMARY KEY (event_id, target, attempt)
+);`,
+			`CREATE TABLE IF NOT EXISTS memory_monitor_cursors (
+  monitor_id TEXT NOT NULL,
+  target TEXT NOT NULL,
+  sequence INTEGER NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (monitor_id, target)
+);`,
+			`CREATE TABLE IF NOT EXISTS memory_monitor_receipts (
+  monitor_id TEXT NOT NULL PRIMARY KEY,
+  content_hash TEXT NOT NULL,
+  envelope_json TEXT NOT NULL,
+  owner_run_id TEXT NOT NULL,
+  terminal_state TEXT NOT NULL,
+  last_sequence INTEGER NOT NULL,
+  evidence_digest TEXT NOT NULL,
+  undelivered_cursor INTEGER,
+  created_at TEXT NOT NULL
+);`,
+			'CREATE INDEX IF NOT EXISTS idx_memory_monitor_events_monitor_sequence ON memory_monitor_events (monitor_id, sequence);',
+			'CREATE INDEX IF NOT EXISTS idx_memory_monitor_outbox_pending ON memory_monitor_outbox (target, status, next_attempt_at, created_at);',
+			'CREATE INDEX IF NOT EXISTS idx_memory_monitor_delivery_receipts_event_target_attempt ON memory_monitor_delivery_receipts (event_id, target, attempt);',
+		],
+		rollback: [
+			'UPDATE memory_monitor_writer_state SET enabled = 0 WHERE singleton = 1;',
+		],
+	};
+}
+
+// 011: usage evidence is append-only and rollback-retained. The public Memory
+// contract owns the DDL; Kernel only places it in its ledgered migration sequence.
+function buildUsageEvidenceMigration() {
+	return {
+		id: USAGE_EVIDENCE_MIGRATION.id,
+		apply: [...USAGE_EVIDENCE_MIGRATION.apply],
+		rollback: [...USAGE_EVIDENCE_MIGRATION.rollback],
+	};
+}
+
+function buildPrWatchOwnershipMigration() {
+	const ownerTableNames = new Set(['pr_watch_owners', 'pr_watch_migration_gate']);
+	const tables = getKernelSchema().tables.filter(table => ownerTableNames.has(table.name));
+	const migration = buildSchemaMigration({ version: 1, tables });
+	return {
+		id: '012_kernel_pr_watch_ownership',
+		apply: migration.apply,
+		rollback: [
+			"INSERT INTO kernel_pr_watch_migration_gate (singleton, state, snapshot_hash, conflict_code, updated_at) VALUES (1, 'quarantined', NULL, NULL, strftime('%Y-%m-%dT%H:%M:%fZ', 'now')) ON CONFLICT(singleton) DO UPDATE SET state = 'quarantined', conflict_code = NULL, updated_at = excluded.updated_at;",
+		],
+	};
+}
+
 function validateKernelMigrations(migrations) {
 	const ids = new Set();
 	for (const migration of migrations) {
@@ -335,6 +444,9 @@ function buildKernelMigrationPlan(migrations = [
 	buildWorktreeLinkageColumnsMigration(),
 	buildMemoryFtsMigration(),
 	buildPrLinkageMigration(),
+	buildMonitorDurabilityMigration(),
+	buildUsageEvidenceMigration(),
+	buildPrWatchOwnershipMigration(),
 ]) {
 	validateKernelMigrations(migrations);
 
@@ -353,6 +465,9 @@ module.exports = {
 	buildKernelMigrationPlan,
 	buildMemoryFtsMigration,
 	buildMemoryProjectionMigration,
+	buildMonitorDurabilityMigration,
+	buildPrWatchOwnershipMigration,
+	buildUsageEvidenceMigration,
 	buildPrLinkageMigration,
 	buildSchemaMigration,
 	buildWorktreeLinkageColumnsMigration,

package/lib/kernel/readiness-model.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { getTypeBehavior, isTerminalStatus, normalizeRank, toEpochMillis } = require('./taxonomy-validator');
+const { isLiveClaim } = require('./live-claim-projection');
 
 // Readiness is a DERIVED read model (D18). `ready`/`blocked` are computed on demand
 // from dependencies, claims, quarantine/conflicts, gates, defer windows, and policy —
@@ -18,6 +19,11 @@ const READINESS_REASONS = Object.freeze({
 	CLAIM: 'claimed',
 	DEFERRED: 'deferred',
 	POLICY: 'policy_disabled',
+	CONTRACT_MISSING: 'contract_missing',
+	CONTRACT_INVALID: 'contract_invalid',
+	CONTRACT_MISMATCH: 'contract_mismatch',
+	CONTRACT_ADOPTION_REQUIRED: 'contract_adoption_required',
+	CONTRACT_ADOPTION_UNVERIFIED: 'contract_adoption_unverified',
 });
 
 const READINESS_STATES = Object.freeze([
@@ -65,17 +71,11 @@ function isDeferred(issue, now) {
 	return deferMillis > nowMillis;
 }
 
-function findConflictingClaim(issueId, claims, actor, now) {
-	const nowMillis = toEpochMillis(now);
+function findConflictingClaim(issue, claims, actor, now) {
 	for (const claim of claims || []) {
-		if (claim.issue_id !== issueId) continue;
-		if ((claim.state || 'active') !== 'active') continue;
+		if (claim.issue_id !== issue.id) continue;
+		if (!isLiveClaim(claim, issue, now)) 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;
@@ -129,6 +129,149 @@ function collectGateBlockers(context, reasons) {
 	return hasGate;
 }
 
+function nonEmptyText(value) {
+	if (typeof value === 'string') return value.trim() !== '';
+	return Array.isArray(value)
+		&& value.length > 0
+		&& value.every(item => typeof item === 'string' && item.trim() !== '');
+}
+
+function isPlainJsonObject(value) {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+function ownDataProperty(object, key) {
+	if (!isPlainJsonObject(object)) return undefined;
+	const descriptor = Object.getOwnPropertyDescriptor(object, key);
+	return descriptor && Object.prototype.hasOwnProperty.call(descriptor, 'value')
+		? descriptor.value
+		: undefined;
+}
+
+function parseMetadata(issue) {
+	const metadata = ownDataProperty(issue, 'metadata');
+	if (metadata == null) return {};
+	if (isPlainJsonObject(metadata)) {
+		return metadata;
+	}
+	if (typeof metadata !== 'string' || metadata.trim() === '') return {};
+	try {
+		const parsed = JSON.parse(metadata);
+		return isPlainJsonObject(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+function getIssueContract(issue) {
+	const metadata = parseMetadata(issue);
+	const candidate = ownDataProperty(metadata, 'forge.contract');
+	const contract = isPlainJsonObject(candidate) ? candidate : {};
+	return {
+		contract: contract && typeof contract === 'object' && !Array.isArray(contract) ? contract : {},
+		metadata,
+	};
+}
+
+function normalizeIds(ids) {
+	return [...new Set((Array.isArray(ids) ? ids : []).map(String))]
+		.sort((left, right) => left.localeCompare(right));
+}
+
+function collectContractFieldReasons(issue, contract, context) {
+	const reasons = [];
+	if (!nonEmptyText(issue.body)) reasons.push({ code: READINESS_REASONS.CONTRACT_MISSING, field: 'purpose' });
+	if (!nonEmptyText(issue.acceptance_criteria)) {
+		reasons.push({ code: READINESS_REASONS.CONTRACT_MISSING, field: 'acceptance_criteria' });
+	}
+	const risk = ownDataProperty(contract, 'risk');
+	const dependencies = ownDataProperty(contract, 'dependencies');
+	const outOfScope = ownDataProperty(contract, 'out_of_scope');
+	const version = ownDataProperty(contract, 'version');
+	if (!nonEmptyText(risk)) reasons.push({ code: READINESS_REASONS.CONTRACT_MISSING, field: 'risk' });
+	if (!Array.isArray(dependencies)) {
+		reasons.push({ code: READINESS_REASONS.CONTRACT_MISSING, field: 'dependencies' });
+	}
+	if (!nonEmptyText(outOfScope)) {
+		reasons.push({ code: READINESS_REASONS.CONTRACT_MISSING, field: 'out_of_scope' });
+	}
+	if (version !== 1) {
+		reasons.push({
+			code: READINESS_REASONS.CONTRACT_INVALID,
+			field: 'version',
+			expected: 1,
+			actual: version ?? null,
+		});
+	}
+	if (Array.isArray(dependencies) && Array.isArray(context.dependencyIds)) {
+		const declared = normalizeIds(dependencies);
+		const expected = normalizeIds(context.dependencyIds);
+		if (JSON.stringify(declared) !== JSON.stringify(expected)) {
+			reasons.push({
+				code: READINESS_REASONS.CONTRACT_MISMATCH,
+				field: 'dependencies',
+				expected,
+				declared,
+			});
+		}
+	}
+	return reasons;
+}
+
+function isTrustedContractAdoption(issue, metadata, adoptedBy, version, context) {
+	const revision = ownDataProperty(issue, 'revision') ?? ownDataProperty(issue, 'entity_revision');
+	const issueId = ownDataProperty(issue, 'id');
+	if (typeof context.isTrustedAdoption !== 'function'
+		|| !nonEmptyText(issueId)
+		|| !Number.isInteger(revision)) return false;
+	try {
+		return context.isTrustedAdoption({
+			actor: adoptedBy,
+			issue_id: issueId,
+			revision,
+			metadata,
+			contract_version: version,
+		}) === true;
+	} catch {
+		return false;
+	}
+}
+
+function collectAdoptionReasons(issue, metadata, contract, context) {
+	const origin = ownDataProperty(issue, 'origin')
+		?? ownDataProperty(metadata, 'origin')
+		?? ownDataProperty(metadata, 'source');
+	if (!['import', 'imported', 'fork', 'fork_pr'].includes(origin)) return [];
+	const adoptedBy = ownDataProperty(contract, 'adopted_by');
+	if (!nonEmptyText(adoptedBy)) {
+		return [{ code: READINESS_REASONS.CONTRACT_ADOPTION_REQUIRED }];
+	}
+	const version = ownDataProperty(contract, 'version');
+	return isTrustedContractAdoption(issue, metadata, adoptedBy, version, context)
+		? []
+		: [{ code: READINESS_REASONS.CONTRACT_ADOPTION_UNVERIFIED, adopter: adoptedBy }];
+}
+
+/**
+ * Validate only the presence, shape, and authority agreement of an issue contract.
+ * The policy deliberately does not score prose, dictate reasoning, or require headings.
+ */
+function evaluateIssueContract(issue = {}, policy = {}, context = {}) {
+	const workClasses = Array.isArray(policy.workClasses) ? policy.workClasses : [];
+	const applicable = policy.enabled === true && workClasses.includes(issue.type);
+	if (!applicable) return { applicable: false, valid: true, reasons: [] };
+
+	const { contract, metadata } = getIssueContract(issue);
+	const reasons = [
+		...collectContractFieldReasons(issue, contract, context),
+		...collectAdoptionReasons(issue, metadata, contract, context),
+	];
+
+	return { applicable: true, valid: reasons.length === 0, reasons };
+}
+
 // 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.
@@ -156,15 +299,30 @@ function deriveReadiness(issue = {}, context = {}) {
 		return { id, status, ready: false, blocked: false, blocked_by: [], reasons: [], state: 'closed' };
 	}
 
+	const contract = evaluateIssueContract(issue, context.contractPolicy, {
+		dependencyIds: context.dependencyIds,
+		isTrustedAdoption: context.isTrustedAdoption,
+	});
+
 	// 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' };
+		return {
+			id,
+			status,
+			ready: false,
+			blocked: false,
+			blocked_by: [],
+			reasons: contract.reasons,
+			state: 'backlog',
+			contract_applicable: contract.applicable,
+		};
 	}
 
 	const reasons = [];
 	const blockedBy = [];
+	reasons.push(...contract.reasons);
 
 	collectDependencyBlockers(context, reasons, blockedBy);
 	const hasConflict = collectConflictBlockers(issue, context, reasons);
@@ -180,7 +338,7 @@ function deriveReadiness(issue = {}, context = {}) {
 		reasons.push({ code: READINESS_REASONS.POLICY });
 	}
 
-	const conflictingClaim = findConflictingClaim(id, context.claims, context.actor, context.now);
+	const conflictingClaim = findConflictingClaim(issue, context.claims, context.actor, context.now);
 	if (conflictingClaim) {
 		reasons.push({ code: READINESS_REASONS.CLAIM, actor: conflictingClaim.actor });
 	}
@@ -191,6 +349,7 @@ function deriveReadiness(issue = {}, context = {}) {
 		&& !deferred
 		&& !policyDisabled
 		&& !conflictingClaim
+		&& contract.valid
 		&& isWorkableStatus(status)
 		&& isReadyEligibleType(issue.type);
 
@@ -203,7 +362,16 @@ function deriveReadiness(issue = {}, context = {}) {
 		ready,
 	});
 
-	return { id, status, ready, blocked, blocked_by: blockedBy, reasons, state };
+	return {
+		id,
+		status,
+		ready,
+		blocked,
+		blocked_by: blockedBy,
+		reasons,
+		state,
+		contract_applicable: contract.applicable,
+	};
 }
 
 // BETA stop-gap for claim thundering-herd (kernel 369c43d7): concurrent `forge ready`
@@ -302,6 +470,9 @@ function buildReadinessIndex(input = {}) {
 			claims: claimsByIssue.get(issue.id) || [],
 			gates: gatesByIssue.get(issue.id) || [],
 			policyDisabled: policyDisabledIds.has(issue.id),
+			contractPolicy: input.contractPolicy,
+			dependencyIds: (dependencyStatusesByIssue.get(issue.id) || []).map(dependency => dependency.id),
+			isTrustedAdoption: input.isTrustedAdoption,
 		});
 	}
 
@@ -325,5 +496,6 @@ module.exports = {
 	DEFAULT_TOP_K_READY_PICK,
 	buildReadinessIndex,
 	deriveReadiness,
+	evaluateIssueContract,
 	isWorkableStatus,
 };

package/lib/kernel/schema.js

@@ -34,6 +34,7 @@ function field(name, type, options = {}) {
 		notNull: Boolean(options.notNull || options.primaryKey),
 		default: options.default,
 		references: options.references,
+		check: options.check,
 	};
 }
 
@@ -45,7 +46,7 @@ function index(name, columns, options = {}) {
 	};
 }
 
-function table(name, storageClass, fields, indexes = []) {
+function table(name, storageClass, fields, indexes = [], options = {}) {
 	return {
 		name,
 		sqlName: `kernel_${name}`,
@@ -56,6 +57,7 @@ function table(name, storageClass, fields, indexes = []) {
 			storageClass: fieldDefinition.storageClass || storageClass,
 		})),
 		indexes,
+		...(options.primaryKey === undefined ? {} : { primaryKey: options.primaryKey }),
 	};
 }
 
@@ -313,6 +315,28 @@ const TABLE_LIST = deepFreeze([
 		index('idx_pr_common_dir_state_repo_number', ['git_common_dir', 'state', 'repo', 'number']),
 		index('idx_pr_common_dir_repo_number', ['git_common_dir', 'repo', 'number'], { unique: true }),
 	]),
+	table('pr_watch_owners', 'authority', [
+		field('repo', 'TEXT', { notNull: true }),
+		field('pr', 'INTEGER', { notNull: true }),
+		field('version', 'INTEGER', { notNull: true, default: '1' }),
+		field('generation', 'TEXT', { notNull: true }),
+		field('phase', 'TEXT', { notNull: true }),
+		field('controller_pid', 'INTEGER'),
+		field('watcher_pid', 'INTEGER'),
+		field('started_at', 'TEXT', { notNull: true }),
+		field('updated_at', 'TEXT', { notNull: true }),
+		field('heartbeat_at', 'TEXT'),
+		field('terminal_receipt_id', 'TEXT'),
+		field('block_reason', 'TEXT'),
+		field('legacy_evidence_hash', 'TEXT'),
+	], [], { primaryKey: ['repo', 'pr'] }),
+	table('pr_watch_migration_gate', 'authority', [
+		field('singleton', 'INTEGER', { primaryKey: true, check: 'singleton = 1' }),
+		field('state', 'TEXT', { notNull: true }),
+		field('snapshot_hash', 'TEXT'),
+		field('conflict_code', 'TEXT'),
+		field('updated_at', 'TEXT', { notNull: true }),
+	]),
 ]);
 
 const KERNEL_TABLES = deepFreeze(Object.fromEntries(TABLE_LIST.map(candidate => [candidate.name, candidate])));
@@ -344,6 +368,29 @@ function validateKernelSchema(schema = getKernelSchema()) {
 		if (!KERNEL_FIELD_AUTHORITIES.includes(tableDefinition.authority)) {
 			throw new Error(`Invalid table authority for ${tableDefinition.name}: ${tableDefinition.authority}`);
 		}
+		if (tableDefinition.primaryKey !== undefined) {
+			if (!Array.isArray(tableDefinition.primaryKey) || tableDefinition.primaryKey.length === 0) {
+				throw new Error(`Invalid table primary key for ${tableDefinition.name}: expected a non-empty column array`);
+			}
+			const primaryKeyColumns = new Set();
+			const fieldsByName = new Map(tableDefinition.fields.map(fieldDefinition => [fieldDefinition.name, fieldDefinition]));
+			if (tableDefinition.fields.some(fieldDefinition => fieldDefinition.primaryKey)) {
+				throw new Error(`Mixed field and table primary keys for ${tableDefinition.name}`);
+			}
+			for (const column of tableDefinition.primaryKey) {
+				if (primaryKeyColumns.has(column)) {
+					throw new Error(`Duplicate table primary key column for ${tableDefinition.name}: ${column}`);
+				}
+				primaryKeyColumns.add(column);
+				const primaryKeyField = fieldsByName.get(column);
+				if (!primaryKeyField) {
+					throw new Error(`Unknown table primary key column for ${tableDefinition.name}: ${column}`);
+				}
+				if (!primaryKeyField.notNull) {
+					throw new Error(`Nullable table primary key column for ${tableDefinition.name}: ${column}`);
+				}
+			}
+		}
 		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}`);
@@ -361,6 +408,7 @@ function validateKernelSchema(schema = getKernelSchema()) {
 function cloneTableList(tableList) {
 	return tableList.map(tableDefinition => ({
 		...tableDefinition,
+		...(Array.isArray(tableDefinition.primaryKey) ? { primaryKey: [...tableDefinition.primaryKey] } : {}),
 		fields: tableDefinition.fields.map(fieldDefinition => ({ ...fieldDefinition })),
 		indexes: tableDefinition.indexes.map(indexDefinition => ({
 			...indexDefinition,