backend-skeleton 1.0.0-beta.8 → 1.0.0

package/scanners/adapters/typescript-express.mjs

@@ -195,6 +195,12 @@ function extractTableEntities(text, file) {
 		entities.push({
 			className,
 			table: m[1] || className.toLowerCase(),
+			// D-cross-feature-collision: m[1] is ENTITY_CLASS_RE's own captured explicit
+			// `@Entity('table_name')` literal argument -- already extracted above, just never
+			// separately flagged as the confidence signal it actually is (vs. the lowercased-
+			// classname fallback on the same line, which is a guess TypeORM's own real default-
+			// naming convention happens to often match, but not always).
+			tableSource: m[1] ? 'explicit' : 'inferred',
 			idField: idMatch ? idMatch[2] : null,
 			idFieldIsUuid: idMatch ? /['"]uuid['"]/.test(idMatch[1]) : false,
 			file,

package/scanners/db/ddl-apply.mjs

@@ -0,0 +1,253 @@
+// D-ddl-apply: the "ddl-apply" kind for lib/patch-transactions.mjs -- a human-authored DDL
+// statement (or `;`-separated statements) proposed, approved, and applied against a REAL live
+// Postgres database. This is this project's first live-DB WRITE path, deliberately crossing
+// D-migration-scope's "bskel never applies a migration automatically" boundary -- see
+// DECISIONS.md's D-ddl-apply for why that boundary is judged safe to lift here specifically, and
+// for why this kind's own safety story (real Postgres transaction wrapping with automatic
+// rollback on postcondition failure, no automated rollback of an already-applied transaction) is
+// deliberately stricter than config-apply's, given the larger blast radius.
+//
+// Mirrors stack/config-apply.mjs's planConfigApply() contract exactly (the same five required
+// plan fields: target/preimage/postcondition/originalContent/renderedContent), reusing
+// scanners/db/introspect.mjs's introspectSchema()/introspectWithClient()/describeConnectionError()
+// as-is -- Plane C's read machinery, extended here to a write.
+import pg from 'pg';
+import { sha256String } from '../../lib/fsutil.mjs';
+import { introspectSchema, introspectWithClient, describeConnectionError, listSchemaNames } from './introspect.mjs';
+import { extractTablesFromSql } from './migrations.mjs';
+
+const { Client } = pg;
+
+export class DdlApplyPlanError extends Error {}
+export class DdlApplyExecutionError extends Error {}
+
+// Deliberately a regex allowlist, not a real SQL parser -- same "good-enough regex, not a real
+// parser" restraint scanners/db/migrations.mjs's own header already names as this project's
+// established restraint for SQL text.
+const ALLOWED_STATEMENT_RE = /^\s*(CREATE|ALTER|DROP)\s+(TABLE|INDEX|UNIQUE\s+INDEX|SCHEMA)\b/i;
+// CONCURRENTLY forms (CREATE/DROP INDEX CONCURRENTLY) are refused explicitly, HERE, at propose
+// time, before any write connection ever opens -- those forms cannot run inside a transaction
+// block at all (Postgres itself refuses them there). ALLOWED_STATEMENT_RE alone does NOT exclude
+// them (it only anchors what the statement STARTS with, not what follows) -- found live by this
+// item's own test suite, not assumed: a first draft relied on ALLOWED_STATEMENT_RE alone and
+// silently accepted "CREATE INDEX CONCURRENTLY ..." as allowlisted. This second, independent check
+// is the actual enforcement.
+const CONCURRENTLY_RE = /\bCONCURRENTLY\b/i;
+const DROP_TABLE_RE = /^\s*DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?"?(\w+)"?/i;
+// Fine-grained postcondition precision for INDEX/SCHEMA DDL (closing the gap D-ddl-apply's own
+// EXIT list named -- these two forms previously only got the coarser "did schema_hash change at
+// all" check, unlike TABLE's exact per-name verification).
+const CREATE_INDEX_RE = /^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(\w+)"?/i;
+const DROP_INDEX_RE = /^\s*DROP\s+INDEX\s+(?:IF\s+EXISTS\s+)?"?(\w+)"?/i;
+const CREATE_SCHEMA_RE = /^\s*CREATE\s+SCHEMA\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(\w+)"?/i;
+const DROP_SCHEMA_RE = /^\s*DROP\s+SCHEMA\s+(?:IF\s+EXISTS\s+)?"?(\w+)"?/i;
+
+export function splitStatements(sqlText) {
+	return sqlText.split(';').map((s) => s.trim()).filter(Boolean);
+}
+
+export function assertLooksLikeDdl(sqlText) {
+	const statements = splitStatements(sqlText);
+	if (statements.length === 0) {
+		throw new DdlApplyPlanError('sql_text has no non-empty statements');
+	}
+	for (const stmt of statements) {
+		if (!ALLOWED_STATEMENT_RE.test(stmt) || CONCURRENTLY_RE.test(stmt)) {
+			throw new DdlApplyPlanError(
+				`statement is not in the Slice 1 allowlist (CREATE/ALTER/DROP TABLE/INDEX/SCHEMA, no CONCURRENTLY): "${stmt.slice(0, 80)}${stmt.length > 80 ? '...' : ''}"`,
+			);
+		}
+	}
+	return statements;
+}
+
+function resolveConnectionString(databaseUrlEnv) {
+	const connectionString = process.env[databaseUrlEnv];
+	if (!connectionString) {
+		throw new DdlApplyPlanError(`--database-url-env ${databaseUrlEnv} names an environment variable that isn't set -- export it first (never read from .env directly; see D-db-schema-plane in DECISIONS.md)`);
+	}
+	return connectionString;
+}
+
+// Classifies every table named by a DROP TABLE statement as expected to be 'absent' afterward,
+// and every table named by a CREATE TABLE/ALTER TABLE ADD COLUMN statement (via Plane A's own
+// extractTablesFromSql -- reused, not reimplemented) as expected to be 'present'. Other DDL forms
+// (CREATE/DROP INDEX, CREATE/DROP SCHEMA, and any ALTER TABLE variant other than ADD COLUMN)
+// contribute no entries here -- Slice 1 only checks their effect via the coarser
+// schema-hash-changed check (see executeDdlApply below), named explicitly, not hidden.
+export function classifyTableExpectations(statements) {
+	const expectations = new Map();
+	for (const stmt of statements) {
+		const dropMatch = stmt.match(DROP_TABLE_RE);
+		if (dropMatch) {
+			expectations.set(dropMatch[1], 'absent');
+			continue;
+		}
+		for (const t of extractTablesFromSql(`${stmt};`, '(ddl-apply proposal)')) {
+			expectations.set(t.name, 'present');
+		}
+	}
+	return [...expectations.entries()].map(([name, expect]) => ({ name, expect })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// Same shape and reasoning as classifyTableExpectations(), for CREATE/DROP INDEX statements.
+export function classifyIndexExpectations(statements) {
+	const expectations = new Map();
+	for (const stmt of statements) {
+		const dropMatch = stmt.match(DROP_INDEX_RE);
+		if (dropMatch) { expectations.set(dropMatch[1], 'absent'); continue; }
+		const createMatch = stmt.match(CREATE_INDEX_RE);
+		if (createMatch) expectations.set(createMatch[1], 'present');
+	}
+	return [...expectations.entries()].map(([name, expect]) => ({ name, expect })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// Same shape and reasoning as classifyTableExpectations(), for CREATE/DROP SCHEMA statements.
+export function classifySchemaExpectations(statements) {
+	const expectations = new Map();
+	for (const stmt of statements) {
+		const dropMatch = stmt.match(DROP_SCHEMA_RE);
+		if (dropMatch) { expectations.set(dropMatch[1], 'absent'); continue; }
+		const createMatch = stmt.match(CREATE_SCHEMA_RE);
+		if (createMatch) expectations.set(createMatch[1], 'present');
+	}
+	return [...expectations.entries()].map(([name, expect]) => ({ name, expect })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// D-ddl-apply (DROP-TABLE-specific confirmation): a non-drop ddl-apply transaction keeps the
+// original design (confirm = transaction id). Any transaction whose SQL drops one or more tables
+// requires retyping the sorted, comma-joined dropped-table name(s) instead -- a materially
+// stronger attention check than a random-looking UUID for the one statement type in the Slice 1
+// allowlist that causes real, irreversible data loss. Consulted by both bin/bskel.mjs's
+// cmdPatchApply and lib/http-server.mjs's apply route via lib/patch-kinds.mjs's dispatch table --
+// neither hardcodes this logic itself.
+export function requiredConfirmValue(txn) {
+	const droppedTables = (txn.postcondition.expected_tables ?? [])
+		.filter((t) => t.expect === 'absent')
+		.map((t) => t.name)
+		.sort();
+	if (droppedTables.length > 0) return droppedTables.join(',');
+	return txn.transaction_id;
+}
+
+// Planner. Mirrors planConfigApply(root, catalogEntry, targetPath)'s contract exactly. Opens a
+// READ-ONLY introspection connection (introspectSchema(), unchanged) purely to compute the
+// preimage -- this function itself never writes to the database; the actual DDL execution only
+// ever happens inside executeDdlApply(), which lib/patch-transactions.mjs calls after its own
+// TOCTOU re-check (comparing a freshly re-planned preimage against the stored one) has passed.
+export async function planDdlApply(root, { databaseUrlEnv, schema = 'public', sqlText }) {
+	const statements = assertLooksLikeDdl(sqlText);
+	const connectionString = resolveConnectionString(databaseUrlEnv);
+
+	let live;
+	try {
+		live = await introspectSchema({ connectionString, schema });
+	} catch (err) {
+		throw new DdlApplyPlanError(`could not introspect the live database: ${describeConnectionError(err)}`);
+	}
+
+	const originalContent = JSON.stringify(live.tables);
+	return {
+		target: { database_url_env: databaseUrlEnv, schema, sql_text: sqlText },
+		// region_hash === file_hash today, honestly -- Slice 1 has no sub-schema "region" concept
+		// for DDL (unlike config-apply's single-key-within-a-file span); both are the whole live
+		// schema's own hash. See DECISIONS.md D-ddl-apply.
+		preimage: { region_hash: live.schema_hash, file_hash: sha256String(originalContent) },
+		current_value: `schema_hash ${live.schema_hash.slice(0, 12)}...`,
+		proposed_value: sqlText,
+		postcondition: {
+			kind: 'db-schema-diff',
+			schema,
+			expected_tables: classifyTableExpectations(statements),
+			expected_indexes: classifyIndexExpectations(statements),
+			expected_schemas: classifySchemaExpectations(statements),
+		},
+		originalContent,
+		renderedContent: sqlText,
+	};
+}
+
+// The apply executor lib/patch-transactions.mjs's applyTransaction() calls (via lib/patch-kinds.mjs's
+// injection) once its own preimage TOCTOU re-check has already passed. Opens ONE read-write
+// `pg.Client`, runs every allowlisted statement inside a single real Postgres transaction,
+// re-introspects using that SAME open, uncommitted transaction (introspectWithClient()) to check
+// the postcondition, and COMMITs only if it holds -- ROLLBACKs (the SQL never takes effect at
+// all) and throws otherwise, leaving the patch-transaction record `approved`, unchanged.
+export async function executeDdlApply(root, featureId, txn, freshKindPlan) {
+	const statements = splitStatements(txn.target.sql_text);
+	const connectionString = resolveConnectionString(txn.target.database_url_env);
+	const schema = txn.target.schema;
+
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query('BEGIN');
+		try {
+			for (const stmt of statements) {
+				await client.query(stmt);
+			}
+			const after = await introspectWithClient(client, schema);
+
+			if (after.schema_hash === freshKindPlan.preimage.region_hash) {
+				throw new DdlApplyExecutionError('the proposed DDL executed without error, but the live schema is byte-identical to before -- refusing to report this transaction as applied when nothing observably changed (this usually means the statement(s) were already no-ops, e.g. re-running an idempotent IF NOT EXISTS against a schema that already has it)');
+			}
+
+			const liveTableNames = new Set(after.tables.map((t) => t.name));
+			for (const { name, expect } of txn.postcondition.expected_tables ?? []) {
+				const present = liveTableNames.has(name);
+				if (expect === 'present' && !present) {
+					throw new DdlApplyExecutionError(`postcondition failed: table "${name}" does not exist live after execution`);
+				}
+				if (expect === 'absent' && present) {
+					throw new DdlApplyExecutionError(`postcondition failed: table "${name}" was targeted by a DROP TABLE statement but still exists live after execution`);
+				}
+			}
+
+			const liveIndexNames = new Set(after.tables.flatMap((t) => t.indexes));
+			for (const { name, expect } of txn.postcondition.expected_indexes ?? []) {
+				const present = liveIndexNames.has(name);
+				if (expect === 'present' && !present) {
+					throw new DdlApplyExecutionError(`postcondition failed: index "${name}" does not exist live after execution`);
+				}
+				if (expect === 'absent' && present) {
+					throw new DdlApplyExecutionError(`postcondition failed: index "${name}" was targeted by a DROP INDEX statement but still exists live after execution`);
+				}
+			}
+
+			const expectedSchemas = txn.postcondition.expected_schemas ?? [];
+			if (expectedSchemas.length > 0) {
+				const liveSchemaNames = await listSchemaNames(client);
+				for (const { name, expect } of expectedSchemas) {
+					const present = liveSchemaNames.has(name);
+					if (expect === 'present' && !present) {
+						throw new DdlApplyExecutionError(`postcondition failed: schema "${name}" does not exist live after execution`);
+					}
+					if (expect === 'absent' && present) {
+						throw new DdlApplyExecutionError(`postcondition failed: schema "${name}" was targeted by a DROP SCHEMA statement but still exists live after execution`);
+					}
+				}
+			}
+
+			await client.query('COMMIT');
+			return { postimage_schema_hash: after.schema_hash, executed_statements: statements };
+		} catch (err) {
+			await client.query('ROLLBACK').catch(() => {}); // best-effort -- the connection may already be unusable
+			throw err;
+		}
+	} finally {
+		await client.end();
+	}
+}
+
+// D-ddl-apply: rollback of an APPLIED ddl-apply transaction is explicitly out of scope for Slice
+// 1 -- there is no live-DB equivalent of config-apply's "restore exact original bytes from a
+// blob" (a dropped table's rows are gone; reversing an ALTER COLUMN TYPE can lose precision), and
+// auto-generating reverse DDL is itself a lossy, risky guess this project has repeatedly refused
+// to ship elsewhere (patchField()'s permanent manual stub, D-config-patch's own "a wrong automatic
+// edit is worse than asking a human" framing). Refuses immediately and always, naming the real
+// mitigation.
+export async function executeDdlRollback() {
+	throw new DdlApplyExecutionError(
+		'rollback is not supported for kind "ddl-apply" in Slice 1 -- propose a new forward ddl-apply transaction containing the reverse DDL instead, and run it through the same propose/approve/apply/confirm flow (see D-ddl-apply in DECISIONS.md)',
+	);
+}

package/scanners/db/introspect.mjs

@@ -36,6 +36,12 @@ const FOREIGN_KEYS_SQL = `
 	ORDER BY tc.table_name, kcu.column_name`;
 const INDEXES_SQL = `SELECT tablename AS table_name, indexname AS index_name FROM pg_indexes WHERE schemaname = $1 ORDER BY tablename, indexname`;
 const RLS_POLICIES_SQL = `SELECT tablename AS table_name, policyname AS policy_name FROM pg_policies WHERE schemaname = $1 ORDER BY tablename, policyname`;
+// D-ddl-apply (INDEX/SCHEMA postcondition precision): NOT schema-scoped, deliberately -- a
+// `CREATE SCHEMA X` statement creates a schema that is NOT the `schema` param every query above is
+// scoped to (typically `public`), so none of those queries can ever observe "does schema X now
+// exist". information_schema.schemata lists every schema in the database, which is exactly what's
+// needed here.
+const SCHEMA_NAMES_SQL = `SELECT schema_name FROM information_schema.schemata`;
 
 function groupByTable(rows, tableKey = 'table_name') {
 	const map = new Map();
@@ -60,49 +66,72 @@ export function describeConnectionError(err) {
 	return err.code ?? String(err);
 }
 
+// D-ddl-apply (INDEX/SCHEMA postcondition precision): used by executeDdlApply() to verify a
+// CREATE/DROP SCHEMA statement's real effect against a live re-introspection -- the same open,
+// uncommitted client/transaction its DDL just ran in, mirroring introspectWithClient()'s own
+// contract exactly (caller owns connect/BEGIN/COMMIT/ROLLBACK/end).
+export async function listSchemaNames(client) {
+	const res = await client.query(SCHEMA_NAMES_SQL);
+	return new Set(res.rows.map((r) => r.schema_name));
+}
+
+// D-ddl-apply: split out of introspectSchema() so scanners/db/ddl-apply.mjs's write path can
+// re-introspect using the SAME open, uncommitted `pg.Client`/transaction its DDL just ran in --
+// observing the not-yet-committed effect of its own statements, without a second connection and
+// without ever exposing a way to introspect outside of a transaction. Callers own connect()/
+// BEGIN.../COMMIT/ROLLBACK/end() -- this function only ever runs the six read queries and shapes
+// the result, identically regardless of which transaction mode the caller opened.
+export async function introspectWithClient(client, schema = 'public') {
+	// Sequential, not Promise.all -- a single pg.Client processes one query at a time over one
+	// connection; issuing several concurrently on the same client is deprecated (pg queues them
+	// internally today, but warns, and that queuing behavior is going away in pg 9). A Pool
+	// would allow real concurrency, but this is a one-shot CLI invocation, not a long-lived
+	// server -- the simplicity of one client, one connection, sequential queries is the right
+	// trade-off here, not premature optimization for concurrency nothing needs.
+	const tablesRes = await client.query(TABLES_SQL, [schema]);
+	const columnsRes = await client.query(COLUMNS_SQL, [schema]);
+	const pkRes = await client.query(PRIMARY_KEYS_SQL, [schema]);
+	const fkRes = await client.query(FOREIGN_KEYS_SQL, [schema]);
+	const indexesRes = await client.query(INDEXES_SQL, [schema]);
+	const policiesRes = await client.query(RLS_POLICIES_SQL, [schema]);
+
+	const columnsByTable = groupByTable(columnsRes.rows);
+	const pkByTable = groupByTable(pkRes.rows);
+	const fkByTable = groupByTable(fkRes.rows);
+	const indexesByTable = groupByTable(indexesRes.rows);
+	const policiesByTable = groupByTable(policiesRes.rows);
+
+	const tables = tablesRes.rows.map(({ table_name: name }) => ({
+		name,
+		columns: (columnsByTable.get(name) ?? []).map((c) => ({ name: c.column_name, type: c.data_type, nullable: c.is_nullable === 'YES' })),
+		primary_key: (pkByTable.get(name) ?? []).map((r) => r.column_name),
+		foreign_keys: (fkByTable.get(name) ?? []).map((r) => ({ column: r.column_name, references_table: r.foreign_table_name, references_column: r.foreign_column_name })),
+		indexes: (indexesByTable.get(name) ?? []).map((r) => r.index_name),
+		rls_policies: (policiesByTable.get(name) ?? []).map((r) => r.policy_name),
+	}));
+
+	// D-cross-feature-fk-inference (staleness/freshness token): stamped AFTER the queries complete,
+	// reflecting when introspection actually ran -- never included in schema_hash's own input (that
+	// hashes `tables` alone), so adding this field cannot change what schema_hash means or perturb
+	// any existing hash-equality check.
+	return { schema, tables, schema_hash: sha256String(JSON.stringify(tables)), generated_at: new Date().toISOString() };
+}
+
 // Entry point. `connectionString` is whatever `process.env[databaseUrlEnv]` resolved to -- the
 // caller (scanners/index.mjs) owns reading that env var and failing loudly if it's unset; this
 // function only ever receives an already-resolved string. `BEGIN TRANSACTION READ ONLY` is
 // structural defense-in-depth -- every query here is already a SELECT, but a read-only
 // transaction means the database itself refuses any write this connection could ever attempt,
-// not just "we didn't write any queries that would".
+// not just "we didn't write any queries that would". A thin connect/BEGIN-READ-ONLY/COMMIT/end
+// wrapper around introspectWithClient() -- the query/shaping logic itself lives there now.
 export async function introspectSchema({ connectionString, schema = 'public' }) {
 	const client = new Client({ connectionString });
 	await client.connect();
 	try {
 		await client.query('BEGIN TRANSACTION READ ONLY');
-
-		// Sequential, not Promise.all -- a single pg.Client processes one query at a time over one
-		// connection; issuing several concurrently on the same client is deprecated (pg queues them
-		// internally today, but warns, and that queuing behavior is going away in pg 9). A Pool
-		// would allow real concurrency, but this is a one-shot CLI invocation, not a long-lived
-		// server -- the simplicity of one client, one connection, sequential queries is the right
-		// trade-off here, not premature optimization for concurrency nothing needs.
-		const tablesRes = await client.query(TABLES_SQL, [schema]);
-		const columnsRes = await client.query(COLUMNS_SQL, [schema]);
-		const pkRes = await client.query(PRIMARY_KEYS_SQL, [schema]);
-		const fkRes = await client.query(FOREIGN_KEYS_SQL, [schema]);
-		const indexesRes = await client.query(INDEXES_SQL, [schema]);
-		const policiesRes = await client.query(RLS_POLICIES_SQL, [schema]);
-
+		const result = await introspectWithClient(client, schema);
 		await client.query('COMMIT');
-
-		const columnsByTable = groupByTable(columnsRes.rows);
-		const pkByTable = groupByTable(pkRes.rows);
-		const fkByTable = groupByTable(fkRes.rows);
-		const indexesByTable = groupByTable(indexesRes.rows);
-		const policiesByTable = groupByTable(policiesRes.rows);
-
-		const tables = tablesRes.rows.map(({ table_name: name }) => ({
-			name,
-			columns: (columnsByTable.get(name) ?? []).map((c) => ({ name: c.column_name, type: c.data_type, nullable: c.is_nullable === 'YES' })),
-			primary_key: (pkByTable.get(name) ?? []).map((r) => r.column_name),
-			foreign_keys: (fkByTable.get(name) ?? []).map((r) => ({ column: r.column_name, references_table: r.foreign_table_name, references_column: r.foreign_column_name })),
-			indexes: (indexesByTable.get(name) ?? []).map((r) => r.index_name),
-			rls_policies: (policiesByTable.get(name) ?? []).map((r) => r.policy_name),
-		}));
-
-		return { schema, tables, schema_hash: sha256String(JSON.stringify(tables)) };
+		return result;
 	} finally {
 		await client.end();
 	}

package/scanners/db/migrations.mjs

@@ -59,8 +59,38 @@ const ALTER_ADD_COLUMN_RE = /ALTER\s+TABLE\s+"?(\w+)"?\s+ADD\s+COLUMN\s+(?:IF\s+
 const CONSTRAINT_LEAD_RE = /^(PRIMARY\s+KEY|FOREIGN\s+KEY|UNIQUE|CHECK|CONSTRAINT)\b/i;
 const COLUMN_NAME_RE = /^"?(\w+)"?/;
 
-function extractTablesFromSql(sqlText, sourceFile) {
-	const tables = new Map(); // name -> Set<column>
+// D-cross-feature-fk-inference (Plane A FK extraction): closes this project's own named EXIT item
+// ("Plane A (migration-file) FK extraction is out of scope") -- `--db` alone (no
+// `--database-url-env`) now contributes real FK data to the `db_foreign_key` cross-feature signal
+// via a real, disposable Postgres connection's absence, using nothing but migration-file text.
+// Same "good-enough regex, not a real parser" restraint as everything else in this module --
+// single-column FKs only; a composite `FOREIGN KEY (a, b) REFERENCES ...` segment simply doesn't
+// match either regex below and is silently skipped, the same fail-safe-by-omission behavior
+// CONSTRAINT_LEAD_RE's own unmatched segments already have.
+//
+// Table-level: `FOREIGN KEY (col) REFERENCES other_table (ocol)` -- ocol is optional (references
+// the parent's PK when omitted; genuinely rare in real migrations, still handled).
+const TABLE_LEVEL_FK_RE = /^FOREIGN\s+KEY\s*\(\s*"?(\w+)"?\s*\)\s+REFERENCES\s+"?(\w+)"?\s*(?:\(\s*"?(\w+)"?\s*\))?/i;
+// Inline column-level: applied to a column-definition segment ALREADY matched by COLUMN_NAME_RE --
+// `col_name TYPE ... REFERENCES other_table(ocol)` or bare `REFERENCES other_table`. When ocol is
+// omitted, references_column is left `null` -- the referenced PK's real column name is genuinely
+// unknowable from the migration file alone, and guessing "id" would be a false-confidence
+// fabrication this project has repeatedly refused to ship elsewhere.
+const INLINE_REFERENCES_RE = /REFERENCES\s+"?(\w+)"?\s*(?:\(\s*"?(\w+)"?\s*\))?/i;
+// `ALTER TABLE t ADD CONSTRAINT name FOREIGN KEY (col) REFERENCES other_table (ocol)` -- a very
+// common Flyway pattern for adding a constraint in a LATER migration than the table's own CREATE.
+const ALTER_ADD_FK_RE = /ALTER\s+TABLE\s+"?(\w+)"?\s+ADD\s+CONSTRAINT\s+"?\w+"?\s+FOREIGN\s+KEY\s*\(\s*"?(\w+)"?\s*\)\s+REFERENCES\s+"?(\w+)"?\s*(?:\(\s*"?(\w+)"?\s*\))?/gi;
+
+function newTableEntry() {
+	return { columns: new Set(), foreignKeys: [] };
+}
+
+// D-ddl-apply: exported (was module-private) so scanners/db/ddl-apply.mjs's postcondition check
+// can reuse this exact extraction instead of a second copy -- it needs to know which table
+// name(s) a proposed CREATE TABLE/ALTER TABLE ADD COLUMN statement declares, to assert the live,
+// re-introspected schema actually reflects them after apply.
+export function extractTablesFromSql(sqlText, sourceFile) {
+	const tables = new Map(); // name -> {columns: Set, foreignKeys: Array}
 
 	CREATE_TABLE_RE.lastIndex = 0;
 	let m;
@@ -70,37 +100,62 @@ function extractTablesFromSql(sqlText, sourceFile) {
 		const closeParen = matchBalancedParens(sqlText, openParen);
 		if (closeParen === -1) continue; // malformed -- skip, don't misattribute
 		const body = sqlText.slice(openParen + 1, closeParen);
-		const columns = new Set();
+		if (!tables.has(tableName)) tables.set(tableName, newTableEntry());
+		const entry = tables.get(tableName);
 		for (const segment of splitTopLevelCommas(body)) {
-			if (CONSTRAINT_LEAD_RE.test(segment)) continue;
+			if (CONSTRAINT_LEAD_RE.test(segment)) {
+				const fkMatch = segment.match(TABLE_LEVEL_FK_RE);
+				if (fkMatch) {
+					entry.foreignKeys.push({ column: fkMatch[1], references_table: fkMatch[2], references_column: fkMatch[3] ?? null });
+				}
+				continue;
+			}
 			const colMatch = segment.match(COLUMN_NAME_RE);
-			if (colMatch) columns.add(colMatch[1]);
+			if (!colMatch) continue;
+			entry.columns.add(colMatch[1]);
+			const inlineMatch = segment.match(INLINE_REFERENCES_RE);
+			if (inlineMatch) {
+				entry.foreignKeys.push({ column: colMatch[1], references_table: inlineMatch[1], references_column: inlineMatch[2] ?? null });
+			}
 		}
-		if (!tables.has(tableName)) tables.set(tableName, new Set());
-		for (const c of columns) tables.get(tableName).add(c);
 	}
 
 	ALTER_ADD_COLUMN_RE.lastIndex = 0;
 	while ((m = ALTER_ADD_COLUMN_RE.exec(sqlText))) {
 		const [, tableName, columnName] = m;
-		if (!tables.has(tableName)) tables.set(tableName, new Set());
-		tables.get(tableName).add(columnName);
+		if (!tables.has(tableName)) tables.set(tableName, newTableEntry());
+		tables.get(tableName).columns.add(columnName);
+	}
+
+	ALTER_ADD_FK_RE.lastIndex = 0;
+	while ((m = ALTER_ADD_FK_RE.exec(sqlText))) {
+		const [, tableName, column, referencesTable, referencesColumn] = m;
+		if (!tables.has(tableName)) tables.set(tableName, newTableEntry());
+		tables.get(tableName).foreignKeys.push({ column, references_table: referencesTable, references_column: referencesColumn ?? null });
 	}
 
-	return [...tables.entries()].map(([name, columns]) => ({ name, columns: [...columns].sort(), source_file: sourceFile }));
+	return [...tables.entries()].map(([name, entry]) => ({
+		name,
+		columns: [...entry.columns].sort(),
+		foreign_keys: entry.foreignKeys,
+		source_file: sourceFile,
+	}));
 }
 
-// Entry point. Returns `{ tool, files, tables }` -- `tool: 'none'` (empty files/tables) is a real,
-// expected, and reported outcome, not an error -- most real repos (including the oracle repo
-// itself) have no migration-file convention at all; their schema lives elsewhere (JPA ddl-auto,
-// or -- the oracle repo's actual case -- entirely outside this repo, in an external Supabase
-// project).
+// Entry point. Returns `{ tool, files, tables, generated_at }` -- `tool: 'none'` (empty
+// files/tables) is a real, expected, and reported outcome, not an error -- most real repos
+// (including the oracle repo itself) have no migration-file convention at all; their schema lives
+// elsewhere (JPA ddl-auto, or -- the oracle repo's actual case -- entirely outside this repo, in
+// an external Supabase project). `generated_at` (D-cross-feature-fk-inference, staleness/freshness
+// token) reflects when THIS scan ran -- stamped once, reused across all 3 return sites below, so a
+// single call always reports one consistent timestamp regardless of which branch it takes.
 export function scanMigrations(repoRoot) {
+	const generatedAt = new Date().toISOString();
 	const flywayFiles = listRgFiles(repoRoot, '**/db/migration/**/*.sql');
 	const liquibaseFiles = listRgFiles(repoRoot, '**/db/changelog/**/*.{xml,yaml,yml,sql}');
 
 	if (flywayFiles.length === 0 && liquibaseFiles.length === 0) {
-		return { tool: 'none', files: [], tables: [] };
+		return { tool: 'none', files: [], tables: [], generated_at: generatedAt };
 	}
 
 	if (flywayFiles.length > 0) {
@@ -109,7 +164,7 @@ export function scanMigrations(repoRoot) {
 			const text = fs.readFileSync(file, 'utf8');
 			tables.push(...extractTablesFromSql(text, path.relative(repoRoot, file)));
 		}
-		return { tool: 'flyway', files: flywayFiles.map((f) => path.relative(repoRoot, f)), tables };
+		return { tool: 'flyway', files: flywayFiles.map((f) => path.relative(repoRoot, f)), tables, generated_at: generatedAt };
 	}
 
 	// Liquibase changelogs are DETECTED (filenames recorded) but not deep-parsed in this first
@@ -122,5 +177,5 @@ export function scanMigrations(repoRoot) {
 		const text = fs.readFileSync(file, 'utf8');
 		tables.push(...extractTablesFromSql(text, path.relative(repoRoot, file)));
 	}
-	return { tool: 'liquibase', files: liquibaseFiles.map((f) => path.relative(repoRoot, f)), tables };
+	return { tool: 'liquibase', files: liquibaseFiles.map((f) => path.relative(repoRoot, f)), tables, generated_at: generatedAt };
 }

package/schemas/cross-feature-report.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:cross-feature-report:1",
+  "title": "backend-skeleton cross-feature identity-collision report",
+  "description": "Validates specs/<feature_id>/cross-feature-report.json, written by `bskel scan cross-feature-check`. Mirrors feature-contract.schema.json's own report-artifact precedent (always written, even when it finds nothing) -- see D-cross-feature-collision in DECISIONS.md. `findings` were originally NAME-identity collisions only; D-cross-feature-fk-inference added a 4th signal, `db_foreign_key`, a REAL live-DB foreign-key edge correlated against declared table ownership (see `fk_check`/`unknowns` below) -- resource_type/table/operation_id remain pure NAME-identity, never a dependency-direction claim (see lib/field-dependencies.mjs's own declared-dependency system for that).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "generated_at", "findings", "fk_check", "unknowns"],
+  "properties": {
+    "schema": { "const": "sbf.cross-feature-report/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["signal", "identifier", "other_feature", "confidence"],
+        "properties": {
+          "signal": { "enum": ["resource_type", "table", "operation_id", "db_foreign_key"] },
+          "identifier": {
+            "description": "The colliding string itself -- a resourceType/DTO className, a DB table name, an operationId, or (for db_foreign_key) a 'child.column -> parent.column' edge description -- copied verbatim from whichever side this finding was computed FROM (this feature's own scan report/contract/live schema).",
+            "type": "string"
+          },
+          "other_feature": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+          "confidence": {
+            "description": "'high': the identifier was copied verbatim from a real source annotation on both sides (resource_type/operation_id always; table/db_foreign_key only when BOTH sides had an explicit @Table/__tablename__-equivalent). 'medium': at least one side's table name was INFERRED (an adapter's classname-lowercase fallback guess, not a real annotation) -- reported, but does not by itself block the gate. For db_foreign_key, the FK edge itself is never in doubt (a live, Postgres-enforced constraint) -- confidence scores only which FEATURE each side was attributed to, the same table-name-inference risk the table signal already scores.",
+            "enum": ["high", "medium"]
+          },
+          "direction": {
+            "description": "db_foreign_key only, absent for the other 3 signals. 'references': THIS feature's table has the FK column, pointing at other_feature's table. 'referenced_by': other_feature's table has the FK column, pointing at THIS feature's table.",
+            "enum": ["references", "referenced_by"]
+          }
+        }
+      }
+    },
+    "fk_check": {
+      "description": "D-cross-feature-fk-inference: always present, names how (if at all) live FK data was obtained for this check -- never silent about the difference between a fresh live connection and a possibly-stale persisted snapshot.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "schema", "source_feature", "generated_at"],
+      "properties": {
+        "mode": {
+          "description": "'live': --db --database-url-env <NAME> was given, this run opened a fresh connection. 'persisted': no live connection this run -- reused a db_schema.live snapshot already on disk from a PRIOR `bskel scan --db --database-url-env` run (possibly stale -- see generated_at). 'migrations': no Plane C (live or persisted) data at all -- fell back to Plane A migration-file-derived FK data (a migration FILE existing is not proof it was ever actually applied, a materially lower-trust source than any live/persisted introspection). 'unavailable': no live connection, no persisted snapshot, and no migration-file data found anywhere -- zero db_foreign_key findings are possible this run (see unknowns).",
+          "enum": ["live", "persisted", "migrations", "unavailable"]
+        },
+        "schema": { "type": ["string", "null"] },
+        "source_feature": {
+          "description": "Which feature's OWN persisted brownfield-scan.json the snapshot came from, when mode is 'persisted' or 'migrations' (sourced from a persisted snapshot rather than a fresh --db pass). Null for 'live' and 'unavailable'.",
+          "type": ["string", "null"],
+          "pattern": "^([0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*)?$"
+        },
+        "generated_at": {
+          "description": "D-cross-feature-fk-inference (staleness/freshness token): when the underlying Plane A/C data this check used was actually captured -- lets a human bound how stale a 'persisted'/'migrations'-mode correlation is, rather than only knowing WHICH snapshot was used. Null only for 'unavailable'.",
+          "type": ["string", "null"],
+          "format": "date-time"
+        }
+      }
+    },
+    "unknowns": {
+      "description": "Plain-string notes for real gaps this check found but could not turn into a finding -- an FK edge whose other side matches no active feature's declared table, or (fk_check.mode === 'unavailable') a single note explaining no live FK data was available at all. Same 'detect and warn, never silently omit' discipline scan-report.schema.json's own unknowns already establishes.",
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/schemas/cross-feature-resolution.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:cross-feature-resolution:1",
+  "title": "backend-skeleton cross-feature collision waiver resolution",
+  "description": "Documentation only, like contract-resolution.schema.json -- nothing loads this at runtime beyond a direct JSON parse (see the analogous contracts/completeness.mjs's loadResolution). Validates specs/<feature_id>/cross-feature-resolution.json, written by `bskel scan cross-feature-waive`. Deliberately separate from cross-feature-report.schema.json's own artifact, mirroring D-contract-completeness's own reasoning for keeping waivers out of the report they apply to. Each waiver is a specific {signal, identifier, other_feature} triple, never a wildcard -- a collision that doesn't exist yet is never silently covered, same discipline contract-resolution.schema.json's own {code, subject} waivers already establish.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "waivers"],
+  "properties": {
+    "schema": { "const": "sbf.cross-feature-resolution/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "waivers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["signal", "identifier", "other_feature", "reason", "at"],
+        "properties": {
+          "signal": { "enum": ["resource_type", "table", "operation_id", "db_foreign_key"] },
+          "identifier": { "type": "string" },
+          "other_feature": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+          "reason": { "type": "string" },
+          "at": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}