forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/kernel/cli-broker-factory.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * CLI kernel broker factory.
+ *
+ * Assembles the kernel issue `deps` the CLI path needs so `createKernelIssueBackend`
+ * (lib/forge-issues.js) can construct a working broker:
+ *
+ *   B1 — No real driver on the CLI path. We construct `createBuiltinSQLiteDriver`
+ *        and inject it as `kernelDriver`, so the broker stops hitting
+ *        `requireGuardedDriverMethods(undefined)`.
+ *   B2 — Migrations never run on the runtime path. `ensureKernelMigrated` wraps
+ *        `broker.initialize()` (pragmas + idempotent migration DDL).
+ *
+ * The factory does NOT change `createKernelIssueBackend`'s contract — it only
+ * supplies the `deps.kernelDriver` / `deps.kernelDatabasePath` it already reads.
+ *
+ * D19 coordination: the filesystem-doctor (read-only DB-location check) belongs
+ * just before the driver opens the file. We expose `resolveKernelDatabasePath`
+ * as that seam — D19 hooks the path, this factory does not reimplement it.
+ *
+ * @module kernel/cli-broker-factory
+ */
+
+const path = require('node:path');
+const {
+  createBuiltinSQLiteDriver,
+  selectBuiltinSQLiteRuntime,
+} = require('./sqlite-driver');
+const { resolveGitCommonDir, createLocalBroker } = require('./broker');
+
+const KERNEL_DB_FILE = 'kernel.sqlite';
+const KERNEL_DB_SUBDIR = 'forge';
+
+/**
+ * Resolve the kernel database path. Mirrors `buildLocalBrokerConfig`:
+ * explicit `databasePath` wins; otherwise `<gitCommonDir>/forge/kernel.sqlite`,
+ * where `gitCommonDir` defaults to the resolved git common dir for `projectRoot`.
+ *
+ * @param {Object} options
+ * @param {string} [options.projectRoot]
+ * @param {string} [options.gitCommonDir]
+ * @param {string} [options.databasePath]
+ * @returns {string}
+ */
+function resolveKernelDatabasePath(options = {}) {
+  if (typeof options.databasePath === 'string' && options.databasePath) {
+    return options.databasePath;
+  }
+  const gitCommonDir = options.gitCommonDir
+    || resolveGitCommonDir(options.projectRoot, options);
+  return path.join(gitCommonDir, KERNEL_DB_SUBDIR, KERNEL_DB_FILE);
+}
+
+/**
+ * Build the kernel issue deps for the CLI path.
+ *
+ * @param {Object} options
+ * @param {string} [options.projectRoot] - Repo root (used to resolve the git common dir).
+ * @param {string} [options.gitCommonDir] - Git common dir (overrides resolution).
+ * @param {string} [options.databasePath] - Explicit kernel DB path (overrides default).
+ * @param {Object} [options.runtime] - Pre-selected SQLite runtime (tests inject this).
+ * @param {Function} [options.requireModule] - Module loader for runtime detection (tests).
+ * @returns {{ useKernelBroker: true, kernelDriver: Object, kernelDatabasePath: string, gitCommonDir?: string }}
+ * @throws {Error} when no builtin SQLite runtime is available (message names the runtimes).
+ */
+function buildKernelIssueDeps(options = {}) {
+  const databasePath = resolveKernelDatabasePath(options);
+  const runtime = options.runtime
+    || selectBuiltinSQLiteRuntime({ requireModule: options.requireModule });
+
+  const kernelDriver = createBuiltinSQLiteDriver({ databasePath, runtime });
+
+  return {
+    useKernelBroker: true,
+    kernelDriver,
+    kernelDatabasePath: databasePath,
+    gitCommonDir: options.gitCommonDir,
+  };
+}
+
+/**
+ * Run the broker's migrations/pragmas (B2). Idempotent: per-invocation policy —
+ * the CLI process is short-lived and `broker.initialize()` swallows
+ * duplicate-column DDL, so calling it on every kernel CLI invocation is safe.
+ *
+ * @param {{ initialize?: Function }} broker
+ * @returns {Promise<Object>} the broker.initialize() result.
+ * @throws {Error} when the broker cannot be initialized.
+ */
+async function ensureKernelMigrated(broker) {
+  if (!broker || typeof broker.initialize !== 'function') {
+    throw new Error('Cannot initialize kernel broker: broker is missing initialize().');
+  }
+  return broker.initialize();
+}
+
+/**
+ * Build the kernel deps AND a migrated broker ready for issue ops. Constructs the
+ * driver (B1), builds the broker over it, runs `broker.initialize()` so pragmas +
+ * migrations are applied (B2), and returns deps carrying the initialized broker as
+ * `kernelBroker` — which `createKernelIssueBackend` (forge-issues.js) uses directly
+ * instead of constructing a second broker.
+ *
+ * @param {Object} options - Same shape as buildKernelIssueDeps.
+ * @returns {Promise<{ useKernelBroker: true, kernelBroker: Object, kernelDriver: Object, kernelDatabasePath: string }>}
+ */
+async function buildMigratedKernelIssueDeps(options = {}) {
+  const deps = buildKernelIssueDeps(options);
+  const broker = createLocalBroker({
+    projectRoot: options.projectRoot,
+    gitCommonDir: options.gitCommonDir,
+    databasePath: deps.kernelDatabasePath,
+    driver: deps.kernelDriver,
+  });
+  await ensureKernelMigrated(broker);
+  return {
+    useKernelBroker: true,
+    kernelBroker: broker,
+    kernelDriver: deps.kernelDriver,
+    kernelDatabasePath: deps.kernelDatabasePath,
+  };
+}
+
+module.exports = {
+  buildKernelIssueDeps,
+  buildMigratedKernelIssueDeps,
+  ensureKernelMigrated,
+  resolveKernelDatabasePath,
+};

package/lib/kernel/conflict-signal.js

@@ -0,0 +1,82 @@
+'use strict';
+
+// Typed conflict-signal classification (issues 89bf8930 / d4ce47bb).
+//
+// The broker used to classify write conflicts by substring-parsing raw SQLite
+// error text (`/UNIQUE constraint failed/`, `kernel_claims.issue_id`, ...) inline.
+// That coupled the broker to one driver's error dialect and was fragile across
+// SQLite versions/runtimes and future backends (libSQL/Turso/CF).
+//
+// This module is the SINGLE place that owns that driver-boundary knowledge. It
+// maps a raw driver/SQLite error into a stable TYPED code; the broker branches on
+// the code and never parses strings. It mirrors the driver's existing structural
+// signal (`error.kernelRevisionConflict`, set by applyAcceptedIssueMutation's
+// row-level CAS) and generalizes it to every conflict class.
+//
+// When a new backend is added, only classifyConflictSignal changes — the broker's
+// branching stays put. A CI integration test (test/kernel/conflict-signal.test.js)
+// provokes real conflicts against the deployed driver and asserts the mapping,
+// converting the standing "error text" assumption into a build-time contract.
+
+const CONFLICT_SIGNAL = Object.freeze({
+	// Optimistic-CAS lost update: the row-level revision guard matched 0 rows because
+	// the entity's revision moved between the evaluator's out-of-transaction pre-read
+	// and the serialized commit. Driver-tagged structurally (never string-derived).
+	CAS_STALE: 'CAS_STALE',
+	// Duplicate idempotency key — a same-key event replay collided on the events
+	// UNIQUE(idempotency_key) index. The broker replays the committed winner.
+	UNIQUE_IDEMPOTENCY: 'UNIQUE_IDEMPOTENCY',
+	// Two active leases raced on one issue: the partial UNIQUE active-lease index
+	// (kernel_claims.issue_id WHERE state='active') rejected the second. The broker
+	// quarantines it as a claim_conflict.
+	UNIQUE_CLAIM_LEASE: 'UNIQUE_CLAIM_LEASE',
+	// Transient lock contention (SQLITE_BUSY / "database is locked"). Part of the
+	// typed vocabulary; the broker does not currently branch on it (behavior parity).
+	BUSY: 'BUSY',
+	// Transient table-level lock (SQLITE_LOCKED). Typed for completeness as above.
+	LOCKED: 'LOCKED',
+});
+
+// Map a raw driver/SQLite error → typed conflict code, or null if it is not a
+// recognized conflict. Precedence: an already-typed signal (driver-supplied or a
+// prior classification) wins over any string inspection, so once the driver tags
+// an error at its boundary this never re-parses text.
+function classifyConflictSignal(error) {
+	if (!error) return null;
+
+	// 1. Already-typed, driver-supplied signals take priority over any string parse.
+	if (typeof error === 'object') {
+		if (error.conflictSignal && isKnownSignal(error.conflictSignal)) {
+			return error.conflictSignal;
+		}
+		// The driver's row-level CAS backstop tags this structurally.
+		if (error.kernelRevisionConflict) return CONFLICT_SIGNAL.CAS_STALE;
+	}
+
+	// 2. Fallback for un-tagged native errors: inspect the driver's error surface.
+	//    This is the ONLY place any error-text/code inspection is permitted.
+	const message = String(error && error.message != null ? error.message : error);
+	const code = String((error && error.code) || '');
+
+	if (/UNIQUE constraint failed/i.test(message)) {
+		// Match ONLY the active-lease partial index (kernel_claims.issue_id), not the
+		// table PK (kernel_claims.id): a duplicate-id violation is a distinct bug.
+		if (/kernel_claims\.issue_id/i.test(message)) return CONFLICT_SIGNAL.UNIQUE_CLAIM_LEASE;
+		if (/idempotency_key/i.test(message)) return CONFLICT_SIGNAL.UNIQUE_IDEMPOTENCY;
+		return null;
+	}
+
+	if (/^SQLITE_BUSY/i.test(code) || /database is locked/i.test(message)) return CONFLICT_SIGNAL.BUSY;
+	if (/^SQLITE_LOCKED/i.test(code) || /database table is locked/i.test(message)) return CONFLICT_SIGNAL.LOCKED;
+
+	return null;
+}
+
+function isKnownSignal(value) {
+	return Object.prototype.hasOwnProperty.call(CONFLICT_SIGNAL, value);
+}
+
+module.exports = {
+	CONFLICT_SIGNAL,
+	classifyConflictSignal,
+};

package/lib/kernel/evaluators.js

@@ -0,0 +1,195 @@
+'use strict';
+
+function stableStringify(value) {
+	if (value === undefined) return '{}';
+	if (value === null || typeof value !== 'object') {
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map(stableStringify).join(',')}]`;
+	}
+
+	return `{${Object.keys(value).sort((left, right) => left.localeCompare(right))
+		.map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+		.join(',')}}`;
+}
+
+function normalizePayload(event) {
+	if (event.payload_json) {
+		try {
+			return JSON.parse(event.payload_json);
+		} catch {
+			return event.payload_json;
+		}
+	}
+	return event.payload || {};
+}
+
+function payloadJsonFor(event) {
+	return stableStringify(normalizePayload(event));
+}
+
+function isForgeProjectionEcho(event, entity = {}) {
+	if (event.origin !== 'beads_import') return false;
+
+	const payload = normalizePayload(event);
+	const projectionOrigin = payload.projection_origin;
+	if (!projectionOrigin || typeof projectionOrigin !== 'object') return false;
+	if (projectionOrigin.source !== 'forge-kernel' || projectionOrigin.target !== 'beads') return false;
+	if (projectionOrigin.entity_type !== event.entity_type || projectionOrigin.entity_id !== event.entity_id) return false;
+	if (!projectionOrigin.payload_hash || projectionOrigin.payload_hash !== projectionOrigin.imported_payload_hash) return false;
+	if (!entity || entity.entity_revision === undefined || entity.entity_revision === null) return false;
+
+	const actualRevision = Number(entity.entity_revision || 0);
+	const projectedRevision = Number(projectionOrigin.entity_revision);
+	return Number.isFinite(projectedRevision) && projectedRevision === actualRevision;
+}
+
+function findOriginalIdempotencyEvent(event, priorEvents = []) {
+	return priorEvents.find(priorEvent => priorEvent.idempotency_key === event.idempotency_key);
+}
+
+function findEquivalentEvent(event, priorEvents = []) {
+	const payloadJson = payloadJsonFor(event);
+	return priorEvents.find(priorEvent => (
+		priorEvent.idempotency_key !== event.idempotency_key
+		&& priorEvent.expected_revision !== undefined
+		&& Number(priorEvent.expected_revision) === Number(event.expected_revision || 0)
+		&& priorEvent.entity_type === event.entity_type
+		&& priorEvent.entity_id === event.entity_id
+		&& priorEvent.event_type === event.event_type
+		&& payloadJsonFor(priorEvent) === payloadJson
+	));
+}
+
+function isBlockingDependency(dependency = {}) {
+	return !dependency.dependency_type || dependency.dependency_type === 'blocks';
+}
+
+function dependencyCreatesCycle(payload, dependencies = []) {
+	const issueId = payload.issue_id;
+	const blocksIssueId = payload.blocks_issue_id;
+	if (!issueId || !blocksIssueId) return false;
+	if (!isBlockingDependency(payload)) return false;
+
+	const edges = new Map();
+	for (const dependency of [...dependencies, { issue_id: issueId, blocks_issue_id: blocksIssueId }].filter(isBlockingDependency)) {
+		if (!edges.has(dependency.issue_id)) edges.set(dependency.issue_id, []);
+		edges.get(dependency.issue_id).push(dependency.blocks_issue_id);
+	}
+
+	const seen = new Set();
+	const stack = [blocksIssueId];
+	while (stack.length > 0) {
+		const candidate = stack.pop();
+		if (candidate === issueId) return true;
+		if (seen.has(candidate)) continue;
+		seen.add(candidate);
+		for (const next of edges.get(candidate) || []) {
+			stack.push(next);
+		}
+	}
+
+	return false;
+}
+
+function buildConflict(event, reason, actualRevision) {
+	const payload = normalizePayload(event);
+	return {
+		entity_type: event.entity_type,
+		entity_id: event.entity_id,
+		expected_revision: Number(event.expected_revision || 0),
+		actual_revision: Number(actualRevision || 0),
+		status: 'quarantined',
+		reason,
+		payload,
+		payload_json: stableStringify({
+			reason,
+			event: {
+				entity_type: event.entity_type,
+				entity_id: event.entity_id,
+				event_type: event.event_type,
+				idempotency_key: event.idempotency_key,
+				payload,
+			},
+		}),
+		created_at: event.created_at,
+	};
+}
+
+function evaluateKernelEvent(input = {}) {
+	const event = input.event || {};
+	if (!event.entity_type) throw new Error('Kernel event entity_type is required');
+	if (!event.entity_id) throw new Error('Kernel event entity_id is required');
+	if (!event.event_type) throw new Error('Kernel event event_type is required');
+	if (!event.idempotency_key) throw new Error('Kernel event idempotency_key is required');
+
+	const priorEvents = input.priorEvents || [];
+	const originalEvent = findOriginalIdempotencyEvent(event, priorEvents);
+	if (originalEvent) {
+		return {
+			decision: 'duplicate',
+			reason: 'idempotency_replay',
+			originalEvent,
+			projection: false,
+		};
+	}
+
+	const equivalentEvent = findEquivalentEvent(event, priorEvents);
+	if (equivalentEvent) {
+		return {
+			decision: 'dedupe',
+			reason: 'equivalent_write',
+			originalEvent: equivalentEvent,
+			projection: false,
+		};
+	}
+
+	if (isForgeProjectionEcho(event, input.entity)) {
+		return {
+			decision: 'projection_echo',
+			reason: 'forge_projection_echo',
+			projection: false,
+		};
+	}
+
+	const actualRevision = Number(input.entity?.entity_revision || 0);
+	const expectedRevision = Number(event.expected_revision || 0);
+	if (expectedRevision !== actualRevision) {
+		return {
+			decision: 'quarantine',
+			reason: 'stale_revision',
+			conflict: buildConflict(event, 'stale_revision', actualRevision),
+			projection: false,
+		};
+	}
+
+	const payload = normalizePayload(event);
+	if (event.event_type === 'dependency.add' && dependencyCreatesCycle(payload, input.dependencies || [])) {
+		return {
+			decision: 'quarantine',
+			reason: 'dependency_cycle',
+			conflict: buildConflict(event, 'dependency_cycle', actualRevision),
+			projection: false,
+		};
+	}
+
+	return {
+		decision: 'accept',
+		reason: 'accepted',
+		event: {
+			...event,
+			expected_revision: Number(event.expected_revision || 0),
+			payload_json: payloadJsonFor(event),
+		},
+		projection: true,
+	};
+}
+
+module.exports = {
+	buildConflict,
+	dependencyCreatesCycle,
+	evaluateKernelEvent,
+	normalizePayload,
+	stableStringify,
+};