forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

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,