backend-skeleton 1.0.0-beta.8 → 1.0.0

package/lib/cli.mjs

@@ -85,10 +85,29 @@ export const COMMANDS = {
 	// D-gate-export: unlike `gate show`, always feature-scoped -- the whole point is one feature's
 	// own evidence trail across all 5 gates, not a single gate/repo-level snapshot.
 	'gate export': {
-		usage: 'bskel gate export --feature <id> [--out <path>] [--json]',
+		usage: 'bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath>] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			out: { type: 'string', default: null },
+			sign: { type: 'boolean', default: false },
+			key: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-gate-attestation-signing.
+	'attest keygen': {
+		usage: 'bskel attest keygen --out <dir> [--force] [--json]',
+		options: {
+			out: { type: 'string', default: null, required: true },
+			force: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'attest verify': {
+		usage: 'bskel attest verify --file <path> --pubkey <path> [--json]',
+		options: {
+			file: { type: 'string', default: null, required: true },
+			pubkey: { type: 'string', default: null, required: true },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -129,6 +148,30 @@ export const COMMANDS = {
 		},
 		allowPositionals: true,
 	},
+	'scan cross-feature-check': {
+		usage: 'bskel scan cross-feature-check --feature <id> [--db [--database-url-env <NAME>] [--schema public]] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			// D-cross-feature-fk-inference: byte-identical shape to `scan`'s own --db/--database-url-env/
+			// --schema (resolved via the SAME resolveDbSchemaOrExit() helper) -- omitting them entirely
+			// is the exact prior behavior, unchanged.
+			db: { type: 'boolean', default: false },
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'scan cross-feature-waive': {
+		usage: 'bskel scan cross-feature-waive --feature <id> --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			signal: { type: 'string', default: null, required: true },
+			identifier: { type: 'string', default: null, required: true },
+			'other-feature': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'feature init': {
 		usage: 'bskel feature init --slug <name>',
 		options: { slug: { type: 'string', default: null, required: true } },
@@ -228,6 +271,40 @@ export const COMMANDS = {
 			operation: { type: 'string', default: null, required: true },
 		},
 	},
+	'dependency declare': {
+		usage: 'bskel dependency declare --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--memo "..."] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			resource: { type: 'string', default: null, required: true },
+			field: { type: 'string', default: null, required: true },
+			'source-feature': { type: 'string', default: null, required: true },
+			'source-resource': { type: 'string', default: null, required: true },
+			'source-field': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			memo: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'dependency remove': {
+		usage: 'bskel dependency remove --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			resource: { type: 'string', default: null, required: true },
+			field: { type: 'string', default: null, required: true },
+			'source-feature': { type: 'string', default: null, required: true },
+			'source-resource': { type: 'string', default: null, required: true },
+			'source-field': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'dependency list': {
+		usage: 'bskel dependency list --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'stack apply': {
 		usage: 'bskel stack apply --choice <id> [--apply] [--port N] [--json]',
 		options: {
@@ -309,10 +386,11 @@ export const COMMANDS = {
 		},
 	},
 	'observe import': {
-		usage: 'bskel observe import --feature <id> --receipts <path> [--json]',
+		usage: 'bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			receipts: { type: 'string', default: null, required: true },
+			'fail-on-violation': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -376,6 +454,70 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-patch-transactions: content-addressed patch transactions, Slice 1 (config_check ->
+	// config_apply). `propose`/`approve` only touch specs/, so no --force escape exists on either --
+	// re-propose is the only remediation for a stale target. `rollback` alone gets --force (reverting
+	// to a known-good, git-recoverable prior state is materially lower-risk than forcing a forward
+	// edit whose collateral effects were never re-verified).
+	'patch propose': {
+		usage: 'bskel patch propose --feature <id> [--kind config-apply --choice <stackChoiceId> --target <config_check target path> | --kind ddl-apply --database-url-env <NAME> --sql-file <path> [--schema public]] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			// D-ddl-apply: default 'config-apply' -- omitting --kind entirely is byte-identical to
+			// this project's prior behavior. choice/target/database-url-env/sql-file are validated
+			// by hand inside cmdPatchPropose (kind-conditional requirements aren't expressible via
+			// this table's own unconditional `required: true`), matching this file's existing
+			// convention for kind-conditional flags (e.g. --reason on approve/rollback).
+			kind: { type: 'string', default: 'config-apply' },
+			choice: { type: 'string', default: null },
+			target: { type: 'string', default: null },
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			'sql-file': { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch approve': {
+		usage: 'bskel patch approve --feature <id> --transaction <id> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch apply': {
+		usage: 'bskel patch apply --feature <id> --transaction <id> [--confirm <id-or-dropped-table-name>] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			// D-ddl-apply: required for any kind other than config-apply -- what value it must
+			// exactly equal is kind- AND transaction-specific (getPatchKind(kind).requiredConfirmValue(txn)):
+			// the transaction id for a non-drop ddl-apply transaction, or the sorted, comma-joined
+			// dropped-table name(s) for one that drops a table. Checked by hand inside cmdPatchApply
+			// once the transaction's own kind/shape is known, not declaratively here. Ignored for
+			// config-apply.
+			confirm: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch rollback': {
+		usage: 'bskel patch rollback --feature <id> --transaction <id> --reason "..." [--force] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			force: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch list': {
+		usage: 'bskel patch list --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	verify: {
 		usage: 'bskel verify --feature <id> [--build [--allow-skip-build]] [--json]',
 		options: {
@@ -409,6 +551,31 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	serve: {
+		usage: 'bskel serve [--port N] [--host <addr>] [--database-url-env <NAME> [--schema public] [--sign-key <path>] [--require-sign-key]] [--json]',
+		options: {
+			// min:0 (unlike stack apply --port's min:1) -- 0 is the standard "let the OS pick a free
+			// ephemeral port" sentinel, genuinely useful both for tests and for a user who doesn't care
+			// which port they get, not just a testing convenience.
+			port: { type: 'string', default: '4747', numeric: { min: 0, max: 65535 } },
+			host: { type: 'string', default: '127.0.0.1' },
+			// D-ddl-apply: every new DB-schema/patch-transaction route is gated behind this one flag
+			// being present -- a plain `bskel serve` (no --database-url-env) stays byte-identical to
+			// today, those paths simply don't exist (404, not 403), mirroring --host's own "safe
+			// default, explicit override" convention. --sign-key is optional even when the DB surface
+			// is enabled (see D-ddl-apply's "detect and warn, never hard-require" signing posture).
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			'sign-key': { type: 'string', default: null },
+			// D-ddl-apply: opt-in-to-MORE-strictness -- refuses to even start the DDL surface without
+			// --sign-key also given, closing this feature's own named "mandatory signing... cheap,
+			// well-justified near-term addition" EXIT item. A no-op when --database-url-env wasn't
+			// given at all (nothing to enforce on a surface that isn't running), same as --schema/
+			// --sign-key themselves already being inert outside that case.
+			'require-sign-key': { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
 };
 
 function describeParseArgsError(err, spec) {

package/lib/cross-feature-collisions.mjs

@@ -0,0 +1,286 @@
+// D-cross-feature-collision: detects NAME-identity collisions between features -- two DIFFERENT
+// features whose scan reports declare the same resourceType/DTO className, the same DB table name,
+// or the same contract operationId. Originally NOT a dependency-direction or FK claim (see
+// lib/field-dependencies.mjs's own declared-dependency system for that, a separate, complementary
+// concern) -- it existed because the runtime handle-resolver dispatch system (java-spring/python-
+// fastapi/typescript-express, all three) already implicitly assumes resourceType is unique across
+// a whole target repo, and nothing detected or protected against that assumption being silently
+// violated before this. See DECISIONS.md for the full design and the real collision this was found
+// against.
+//
+// D-cross-feature-fk-inference: closed this entry's own named EXIT item -- a 4th signal,
+// `db_foreign_key`, correlates a REAL live Postgres foreign-key edge (Plane C,
+// scanners/db/introspect.mjs) against which feature declares each side's table, reusing this same
+// per-other-feature loop (ownClasses/otherClasses) rather than a new subsystem or a persisted
+// "table -> feature" index. See resolveLiveTables()/findCollisions() below and DECISIONS.md.
+import { readJsonIfExists, writeFileAtomic } from './fsutil.mjs';
+import { specPath } from './paths.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+import { listFeatures } from './featurelifecycle.mjs';
+
+const REPORT_SCHEMA = 'sbf.cross-feature-report/1';
+const RESOLUTION_SCHEMA = 'sbf.cross-feature-resolution/1';
+
+export function crossFeatureReportPath(root, featureId) {
+	return specPath(root, featureId, 'cross-feature-report.json');
+}
+
+export function crossFeatureResolutionPath(root, featureId) {
+	return specPath(root, featureId, 'cross-feature-resolution.json');
+}
+
+// Reads the PERSISTED report from the last `bskel scan cross-feature-check` run -- `bskel scan
+// cross-feature-waive` validates against this snapshot, never a live re-computation, matching
+// `contract waive`'s own established precedent (contracts/completeness.mjs's loadContract): a
+// waiver targets what was actually reported, and if reality has moved since, the gate's own
+// staleness token (which already covers every OTHER feature named in this same report) is what
+// surfaces that, not a silent re-check inside the waive command itself.
+export function loadCrossFeatureReport(root, featureId) {
+	return readJsonIfExists(crossFeatureReportPath(root, featureId));
+}
+
+export function loadCrossFeatureResolution(root, featureId) {
+	const path = crossFeatureResolutionPath(root, featureId);
+	const parsed = readJsonIfExists(path);
+	if (parsed === null) return { schema: RESOLUTION_SCHEMA, feature_id: featureId, waivers: [] };
+	const { ok, errors } = validateAgainstSchema('cross-feature-resolution.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${path}: does not match schemas/cross-feature-resolution.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveCrossFeatureResolution(root, featureId, resolution) {
+	const { ok, errors } = validateAgainstSchema('cross-feature-resolution.schema.json', resolution);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid cross-feature resolution for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	writeFileAtomic(crossFeatureResolutionPath(root, featureId), `${JSON.stringify(resolution, null, 2)}\n`);
+	return resolution;
+}
+
+// The waiver key -- deliberately signal+identifier+other_feature only, never a message/reason, so
+// rephrasing a --reason later never silently stops a waiver from matching (same discipline
+// contracts/completeness.mjs's own warningKey() already established).
+export function waiverKey(w) {
+	return `${w.signal}::${w.identifier}::${w.other_feature}`;
+}
+
+// Own-module accessors -- reads THIS feature's own disposed module (className list + table names),
+// mirroring resolveClassFile()'s own lookup shape (lib/field-dependencies.mjs) but returning every
+// candidate at once instead of resolving one resourceType.
+function ownDisposedModule(root, featureId) {
+	const report = readJsonIfExists(specPath(root, featureId, 'brownfield-scan.json'));
+	if (!report) return null;
+	const moduleName = report.disposition?.module ?? report.related_modules?.[0]?.module;
+	if (!moduleName) return null;
+	return report.related_modules?.find((m) => m.module === moduleName) ?? null;
+}
+
+function ownOperationIds(root, featureId) {
+	const contract = readJsonIfExists(specPath(root, featureId, 'contracts', `${featureId}.schema.json`));
+	return contract ? Object.keys(contract.operations ?? {}) : [];
+}
+
+// D-cross-feature-fk-inference (Plane A FK extraction): Plane A is strictly LOWER priority than
+// any Plane C (live/persisted) source -- a migration FILE existing is not proof it was ever
+// actually applied (D-migration-scope's own standing caveat), so Plane C is always more
+// trustworthy when available. Migration files are repo-wide, not feature-scoped, so any ONE
+// feature's persisted db_schema.migrations carries the same content as any other's -- "first one
+// found" is sufficient, matching the persisted-live tier's own "first found" logic exactly.
+function migrationsTables(dbSchema) {
+	return dbSchema?.migrations?.tool && dbSchema.migrations.tool !== 'none' ? dbSchema.migrations.tables : null;
+}
+
+// D-cross-feature-fk-inference: resolves ONE usable live-table snapshot to correlate FK edges
+// against, in four tiers (live > this feature's own persisted live > another feature's persisted
+// live > migration-file-derived, Plane A). `liveDbSchema` is whatever the CLI boundary already
+// resolved (the SAME resolveDbSchemaOrExit() result `cmdScan` itself uses -- this function never
+// opens a connection itself). Plane C is already schema-wide (every table in `--schema`, not
+// filtered to any one feature), so there is nothing to MERGE across features' own snapshots --
+// locating one usable snapshot is enough; it already contains every table in that schema.
+function resolveLiveTables(root, featureId, liveDbSchema) {
+	// D-cross-feature-fk-inference (staleness/freshness token): `generated_at` threaded into
+	// `fk_check` at every tier below, read from whichever source that tier actually used --
+	// `introspectWithClient()`/`scanMigrations()` both stamp it at the real point of capture, this
+	// function only ever passes it through, never invents or re-derives it.
+	if (liveDbSchema?.live) {
+		return { tables: liveDbSchema.live.tables, fk_check: { mode: 'live', schema: liveDbSchema.live.schema, source_feature: null, generated_at: liveDbSchema.live.generated_at ?? null } };
+	}
+	const ownReport = readJsonIfExists(specPath(root, featureId, 'brownfield-scan.json'));
+	if (ownReport?.db_schema?.live) {
+		return { tables: ownReport.db_schema.live.tables, fk_check: { mode: 'persisted', schema: ownReport.db_schema.live.schema, source_feature: featureId, generated_at: ownReport.db_schema.live.generated_at ?? null } };
+	}
+	// Deterministic by feature_id sort order -- listFeatures() itself already returns records
+	// sorted by directory name, so "first other feature with a persisted live snapshot" is a
+	// stable, repeatable choice, not an arbitrary one. Reused below for the migrations tier too.
+	const otherFeatures = listFeatures(root).filter((record) => record.feature_id !== featureId);
+	for (const record of otherFeatures) {
+		const otherReport = readJsonIfExists(specPath(root, record.feature_id, 'brownfield-scan.json'));
+		if (otherReport?.db_schema?.live) {
+			return { tables: otherReport.db_schema.live.tables, fk_check: { mode: 'persisted', schema: otherReport.db_schema.live.schema, source_feature: record.feature_id, generated_at: otherReport.db_schema.live.generated_at ?? null } };
+		}
+	}
+
+	if (migrationsTables(liveDbSchema)) {
+		return { tables: migrationsTables(liveDbSchema), fk_check: { mode: 'migrations', schema: null, source_feature: null, generated_at: liveDbSchema.migrations.generated_at ?? null } };
+	}
+	if (migrationsTables(ownReport?.db_schema)) {
+		return { tables: migrationsTables(ownReport.db_schema), fk_check: { mode: 'migrations', schema: null, source_feature: featureId, generated_at: ownReport.db_schema.migrations.generated_at ?? null } };
+	}
+	for (const record of otherFeatures) {
+		const otherReport = readJsonIfExists(specPath(root, record.feature_id, 'brownfield-scan.json'));
+		if (migrationsTables(otherReport?.db_schema)) {
+			return { tables: migrationsTables(otherReport.db_schema), fk_check: { mode: 'migrations', schema: null, source_feature: record.feature_id, generated_at: otherReport.db_schema.migrations.generated_at ?? null } };
+		}
+	}
+
+	return { tables: null, fk_check: { mode: 'unavailable', schema: null, source_feature: null, generated_at: null } };
+}
+
+// Flattens Plane C's PER-TABLE foreign_keys[] (scanners/db/introspect.mjs) into one flat edge list
+// -- {table, column, references_table, references_column}, `table` being the CONSTRAINED
+// (child/referencing) side.
+function flattenLiveForeignKeys(liveTables) {
+	const edges = [];
+	for (const t of liveTables) {
+		for (const fk of t.foreign_keys ?? []) {
+			edges.push({ table: t.name, column: fk.column, references_table: fk.references_table, references_column: fk.references_column });
+		}
+	}
+	return edges;
+}
+
+// D-cross-feature-collision: the core comparison -- for the GIVEN feature's own disposed module,
+// checks every OTHER active feature (listFeatures() excludes archived by default, same reasoning
+// D-dependency-propagation-notice's own listDownstreamDependents() already established: an archived
+// feature's naming collision isn't worth blocking a human over) for a resourceType/table/operationId
+// match. One level only, symmetric-but-independent per feature -- feature B finding a collision
+// against feature A does not automatically waive feature A's own, separate check against B (each
+// feature's own cross-feature-resolution.json is its own record, matching contract waive's own
+// per-feature-file precedent).
+//
+// D-cross-feature-fk-inference: `liveDbSchema` (optional, `null` by default -- callers that never
+// pass it get the exact prior behavior for the first 3 signals, plus a `fk_check: {mode:
+// 'unavailable', ...}` and possibly one `unknowns` entry) is the ALREADY-RESOLVED
+// resolveDbSchemaOrExit() result. Returns {findings, fk_check, unknowns} -- a superset of the old
+// bare array, not a rename; findings for the existing 3 signals are byte-identical to before.
+export function findCollisions(root, featureId, { liveDbSchema = null } = {}) {
+	const ownModule = ownDisposedModule(root, featureId);
+	const ownClasses = ownModule ? [...(ownModule.entities ?? []), ...(ownModule.dtos ?? [])] : [];
+	const ownOperationIdSet = new Set(ownOperationIds(root, featureId));
+
+	const { tables: liveTables, fk_check } = resolveLiveTables(root, featureId, liveDbSchema);
+	const liveEdges = liveTables ? flattenLiveForeignKeys(liveTables) : [];
+	// This feature's own table -> entity map (case-folded), matching computeDbDrift()'s own
+	// established case-folding convention (scanners/index.mjs).
+	const ownTablesByName = new Map(ownClasses.filter((c) => c.table).map((c) => [c.table.toLowerCase(), c]));
+	// Every table name (own + every OTHER feature seen) that matched SOME feature, accumulated
+	// across the whole loop below -- used only to report FK edges touching an UNattributed table
+	// (see the unknowns pass after the loop). In-memory, local to this one call -- not a new
+	// persisted "table -> feature" index.
+	const matchedTableNames = new Set(ownTablesByName.keys());
+
+	const findings = [];
+	for (const record of listFeatures(root)) {
+		if (record.feature_id === featureId) continue;
+		const otherModule = ownDisposedModule(root, record.feature_id);
+		const otherClasses = otherModule ? [...(otherModule.entities ?? []), ...(otherModule.dtos ?? [])] : [];
+		const otherTablesByName = new Map(otherClasses.filter((c) => c.table).map((c) => [c.table.toLowerCase(), c]));
+		for (const name of otherTablesByName.keys()) matchedTableNames.add(name);
+
+		for (const ownClass of ownClasses) {
+			const match = otherClasses.find((c) => c.className === ownClass.className);
+			if (match) {
+				findings.push({ signal: 'resource_type', identifier: ownClass.className, other_feature: record.feature_id, confidence: 'high' });
+			}
+		}
+
+		// Table names: only compared when BOTH sides actually have one (a class with no table --
+		// e.g. a DTO, or an entity with no @Table and no fallback -- has nothing to collide on).
+		// Case-folded for comparison, matching computeDbDrift()'s own established convention
+		// (scanners/index.mjs) -- the ONE place in this codebase that already case-folds a `.table`
+		// value before comparing it.
+		for (const ownEntity of ownClasses.filter((c) => c.table)) {
+			const match = otherClasses.find((c) => c.table && c.table.toLowerCase() === ownEntity.table.toLowerCase());
+			if (match) {
+				const confidence = ownEntity.tableSource === 'explicit' && match.tableSource === 'explicit' ? 'high' : 'medium';
+				findings.push({ signal: 'table', identifier: ownEntity.table.toLowerCase(), other_feature: record.feature_id, confidence });
+			}
+		}
+
+		const otherOperationIds = ownOperationIds(root, record.feature_id);
+		for (const opId of ownOperationIdSet) {
+			if (otherOperationIds.includes(opId)) {
+				findings.push({ signal: 'operation_id', identifier: opId, other_feature: record.feature_id, confidence: 'high' });
+			}
+		}
+
+		// D-cross-feature-fk-inference: a real, live FK edge where ONE side is a table THIS
+		// feature declares and the OTHER side is a table `record` declares. Confidence reuses the
+		// exact `table` signal's own tableSource rule -- the FK itself is never in doubt (a live,
+		// Postgres-enforced constraint), what's uncertain is whether the source-derived table name
+		// on each side was a real annotation or an adapter's guessed fallback, the SAME risk the
+		// `table` signal already scores this way. Self-referencing/same-feature edges never reach
+		// here at all -- this only ever compares ownClasses against a DIFFERENT feature's classes.
+		for (const edge of liveEdges) {
+			const childName = edge.table.toLowerCase();
+			const parentName = edge.references_table.toLowerCase();
+			const identifier = `${edge.table}.${edge.column} -> ${edge.references_table}.${edge.references_column}`;
+
+			if (ownTablesByName.has(childName) && otherTablesByName.has(parentName)) {
+				const ownEntity = ownTablesByName.get(childName);
+				const otherEntity = otherTablesByName.get(parentName);
+				const confidence = ownEntity.tableSource === 'explicit' && otherEntity.tableSource === 'explicit' ? 'high' : 'medium';
+				findings.push({ signal: 'db_foreign_key', identifier, other_feature: record.feature_id, confidence, direction: 'references' });
+			}
+			if (ownTablesByName.has(parentName) && otherTablesByName.has(childName)) {
+				const ownEntity = ownTablesByName.get(parentName);
+				const otherEntity = otherTablesByName.get(childName);
+				const confidence = ownEntity.tableSource === 'explicit' && otherEntity.tableSource === 'explicit' ? 'high' : 'medium';
+				findings.push({ signal: 'db_foreign_key', identifier, other_feature: record.feature_id, confidence, direction: 'referenced_by' });
+			}
+		}
+	}
+
+	// D-cross-feature-fk-inference: honest, explicit reporting for the two "no useful FK signal"
+	// cases -- never a silent gap, matching this project's own repeated "no silent caps" discipline
+	// (see D-db-schema-plane's own unknowns precedent for the same reasoning on a different check).
+	const unknowns = [];
+	if (liveTables) {
+		for (const edge of liveEdges) {
+			const childName = edge.table.toLowerCase();
+			const parentName = edge.references_table.toLowerCase();
+			const identifier = `${edge.table}.${edge.column} -> ${edge.references_table}.${edge.references_column}`;
+			if (ownTablesByName.has(childName) && !matchedTableNames.has(parentName)) {
+				unknowns.push(`FK ${identifier}: referenced table "${edge.references_table}" is not declared by any active feature (untracked/external table)`);
+			} else if (ownTablesByName.has(parentName) && !matchedTableNames.has(childName)) {
+				unknowns.push(`FK ${identifier}: referencing table "${edge.table}" is not declared by any active feature (untracked/external table)`);
+			}
+		}
+	} else {
+		unknowns.push('no live DB foreign-key data available to check -- pass --db --database-url-env <NAME> to `bskel scan cross-feature-check`, or run `bskel scan --feature <id> --db --database-url-env <NAME>` at least once to persist a snapshot this check can reuse');
+	}
+
+	return { findings, fk_check, unknowns };
+}
+
+// Mirrors contracts/completeness.mjs's own evaluateResolution() exactly, for a different axis:
+// there, the split is by warning SEVERITY (error vs warn); here, it's by finding CONFIDENCE (high
+// vs medium) -- only a `high`-confidence, unwaived finding blocks. A `medium`-confidence finding
+// (an inferred/guessed table name on at least one side) is always reported, never blocking on its
+// own -- the named mitigation for python-fastapi/typescript-express's own table-name-guessing false-
+// match risk (see DECISIONS.md), not a silently dropped signal.
+export function evaluateCrossFeatureFindings(findings, resolution) {
+	const waivers = resolution.waivers ?? [];
+	const waivedKeys = new Set(waivers.map(waiverKey));
+
+	const highConfidence = findings.filter((f) => f.confidence === 'high');
+	const unwaived = highConfidence.filter((f) => !waivedKeys.has(waiverKey(f)));
+	const waived = highConfidence.filter((f) => waivedKeys.has(waiverKey(f)));
+
+	const currentKeys = new Set(findings.map(waiverKey));
+	const staleWaivers = waivers.filter((w) => !currentKeys.has(waiverKey(w)));
+
+	return { blocking: unwaived.length > 0, unwaived, waived, staleWaivers };
+}

package/lib/diff.mjs

@@ -0,0 +1,35 @@
+// D-patch-transactions: promoted verbatim from handles/_engine.mjs (D4/D-handles-dryrun's own
+// unifiedDiff()) -- pure code motion, zero behavior change. Generic enough that stack/config-apply.
+// mjs needs the identical mechanism for its own collateral-diff safety gate, and there was no
+// existing stack <-> handles import in either direction to introduce by leaving it where it was.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// D4 (D-handles-dryrun): a real unified diff via `git diff --no-index`, not a hand-rolled diff
+// algorithm -- `git` is already a hard dependency elsewhere in this codebase, so this adds zero
+// new dependencies. `cwd: tmpDir` + relative `a/<relPath>`/`b/<relPath>` paths (rather than
+// absolute temp paths) keep the diff header clean and reproducible -- the random tmpdir name
+// never leaks into the output. `git diff --no-index` exits 1 when the two sides differ (the
+// expected, common case here, not a failure) -- only a status other than 0/1 is a genuine error
+// worth throwing.
+export function unifiedDiff(relPath, before, after) {
+	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bskel-diff-'));
+	try {
+		const beforeAbs = path.join(tmpDir, 'a', relPath);
+		const afterAbs = path.join(tmpDir, 'b', relPath);
+		fs.mkdirSync(path.dirname(beforeAbs), { recursive: true });
+		fs.mkdirSync(path.dirname(afterAbs), { recursive: true });
+		fs.writeFileSync(beforeAbs, before ?? '');
+		fs.writeFileSync(afterAbs, after ?? '');
+		try {
+			return execFileSync('git', ['diff', '--no-index', '--no-color', '--', `a/${relPath}`, `b/${relPath}`], { cwd: tmpDir, encoding: 'utf8' });
+		} catch (err) {
+			if (err.status === 1 && typeof err.stdout === 'string') return err.stdout;
+			throw err;
+		}
+	} finally {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	}
+}