backend-skeleton 1.0.0-beta.9 → 1.1.0

package/scanners/adapters/javascript-express.mjs

@@ -226,10 +226,40 @@ function resolveEsmImport(fromFile, specifier, suffixes) {
 	return null;
 }
 
-// `export default router;` -- which locally-declared mountable a file hands to whoever imports it.
-function defaultExportedMountable(text, mountables) {
-	const m = text.match(/export\s+default\s+([\w$]+)\s*;?/);
-	return m && mountables.has(m[1]) ? m[1] : null;
+// D-javascript-express-adapter (Update): found by the same shadow-validation-style audit that
+// closed D-module-attribution-base-package's own EXIT item for this adapter -- cross-file mount
+// resolution only ever recognized `export default router;`, a real but narrower limitation than
+// java-spring's own moduleOf() bug (endpoints still get FOUND either way, only their prefix goes
+// unresolved). A router handed off via a bare named export (`export { router };`) or an
+// export-prefixed declaration (`export const router = Router();`, ordinary and common) previously
+// had no path to being recognized as this file's "the" exported mountable at all.
+//
+// Three real ways a module hands a locally-declared mountable to whoever imports it -- `export
+// { router as r }` aliasing is deliberately NOT resolved, same restraint as this file's own
+// `Router as R` import-aliasing decision (D-javascript-express-adapter COST): a documented, narrow
+// limitation, not a silent guess at which local name an alias refers to.
+function exportedMountableName(text, mountables) {
+	const defaultMatch = text.match(/export\s+default\s+([\w$]+)\s*;?/);
+	if (defaultMatch && mountables.has(defaultMatch[1])) return defaultMatch[1];
+	const namedMatch = text.match(/export\s*\{\s*([\w$]+)\s*\}/);
+	if (namedMatch && mountables.has(namedMatch[1])) return namedMatch[1];
+	const exportedDeclMatch = text.match(/\bexport\s+(?:const|let|var)\s+([\w$]+)\s*=/);
+	if (exportedDeclMatch && mountables.has(exportedDeclMatch[1])) return exportedDeclMatch[1];
+	return null;
+}
+
+// `import target from '...'` (default) OR `import { target } from '...'` (named, unaliased) --
+// two real ways an imported mountable's LOCAL name reaches this file. `import { target as alias }`
+// is deliberately not resolved, same restraint as exportedMountableName's own aliasing decision
+// above -- a bare, unaliased single-name clause only, matching this file's existing default-import
+// regex's own narrow scope (never a general multi-specifier import-clause parser).
+function importSourceFor(text, target) {
+	const defaultImportRe = new RegExp(`import\\s+${target}\\s*(?:,\\s*\\{[^}]*\\})?\\s*from\\s*["']([^"']+)["']`);
+	const defaultMatch = text.match(defaultImportRe);
+	if (defaultMatch) return defaultMatch[1];
+	const namedImportRe = new RegExp(`import\\s*\\{\\s*${target}\\s*\\}\\s*from\\s*["']([^"']+)["']`);
+	const namedMatch = text.match(namedImportRe);
+	return namedMatch ? namedMatch[1] : null;
 }
 
 // Builds the mount graph over (file, variable) nodes. Two edge kinds, both from the same
@@ -261,13 +291,12 @@ function buildMountEdges(files, fileInfo, suffixes) {
 				edges.push({ from: nodeKey(file, fromVar), to: nodeKey(file, target), prefix: pathMatch[1] });
 				continue;
 			}
-			const importRe = new RegExp(`import\\s+${target}\\s*(?:,\\s*\\{[^}]*\\})?\\s*from\\s*["']([^"']+)["']`);
-			const importMatch = info.text.match(importRe);
-			if (!importMatch) continue;
-			const toFile = resolveEsmImport(file, importMatch[1], suffixes);
+			const importSource = importSourceFor(info.text, target);
+			if (!importSource) continue;
+			const toFile = resolveEsmImport(file, importSource, suffixes);
 			if (!toFile || !fileInfo.has(toFile)) continue;
 			const toInfo = fileInfo.get(toFile);
-			const toVar = defaultExportedMountable(toInfo.text, toInfo.mountables);
+			const toVar = exportedMountableName(toInfo.text, toInfo.mountables);
 			if (!toVar) continue;
 			edges.push({ from: nodeKey(file, fromVar), to: nodeKey(toFile, toVar), prefix: pathMatch[1] });
 		}
@@ -391,10 +420,14 @@ export const adapter = {
 	// walk), not how many capabilities it can offer. generic-grep is `low` because it has no module
 	// inference and no prefix resolution at all -- this adapter has both.
 	confidence: 'high',
-	// D-adapter-verification-basis: no real-world oracle at all, unlike every other real framework
-	// adapter -- the real target repository was deliberately never touched, and the committed
-	// synthetic fixture carries all of the regression weight. Named honestly, not hidden.
-	verificationBasis: 'synthetic-only',
+	// D-oracle-corpus-pinning: promoted from synthetic-only -- 3 real, pinned community repos
+	// now exist in test/fixtures/oracle-manifest.json (JeanCaicedo/employees-api-mysql,
+	// Serkanbyx/chat-app-backend, nekesam/helloworld), found via a genuine search effort that
+	// contradicted this adapter's own prior 'may be structurally unpromotable' hedge. The
+	// committed synthetic fixture still carries the exact-count regression weight; the real
+	// corpus is diagnostic/diversity coverage on top, same role every other adapter's real
+	// oracle plays.
+	verificationBasis: 'community-sample',
 	capabilities: {
 		// false: plain Express has no operationId concept at all. --openapi-file is the honest path
 		// forward for an app that has one; see CAPABILITY_SATISFIERS in scanners/capabilities.mjs.

package/scanners/adapters/python-fastapi.mjs

@@ -155,7 +155,15 @@ function extractTableEntities(text, file) {
 		const bodyEnd = i + 1 < classMatches.length ? classMatches[i + 1].index : text.length;
 		const body = text.slice(bodyStart, bodyEnd);
 		const idMatch = body.match(/(\w+)\s*:[^=\n]+=\s*Field\([^)]*primary_key\s*=\s*True/);
-		entities.push({ className: m[1], table: m[1].toLowerCase(), idField: idMatch ? idMatch[1] : null, file, line: lineNumberAt(text, m.index) });
+		// D-cross-feature-collision: a real `__tablename__ = "..."` override, previously never
+		// checked at all -- `table` fell back to the lowercased class name unconditionally, which
+		// silently mis-derives the real table name whenever a class overrides it. Cross-feature
+		// collision detection needs to know which case this was: 'explicit' (the real, trustworthy
+		// name) vs 'inferred' (a guess that could be wrong), not just a bare string either way.
+		const tablenameMatch = body.match(/__tablename__\s*(?::\s*\w+\s*)?=\s*["']([^"']+)["']/);
+		const table = tablenameMatch ? tablenameMatch[1] : m[1].toLowerCase();
+		const tableSource = tablenameMatch ? 'explicit' : 'inferred';
+		entities.push({ className: m[1], table, tableSource, idField: idMatch ? idMatch[1] : null, file, line: lineNumberAt(text, m.index) });
 	}
 	return entities;
 }

package/scanners/adapters/typescript-express.mjs

@@ -41,6 +41,17 @@ const ENTITY_CLASS_RE = /@Entity\s*\(\s*(?:["'`]([^"'`]*)["'`])?\s*\)\s*\n?\s*ex
 // exported symbol -- same file-level granularity java's own DTO tracking already settled for.
 const DTO_DIR_SEGMENT = `${path.sep}dto${path.sep}`;
 
+// D-module-attribution-base-package (Update): found by the same shadow-validation pass that fixed
+// java-spring's own moduleOf() -- a real project not using a `dto/` folder at all (flat `CreateUserDto.ts` files, or
+// NestJS's own common `create-user.dto.ts` naming) had every DTO silently invisible, the same class
+// of single-convention overfit, just on a narrower surface (DTO tracking only, not module/entity/
+// controller extraction). This does NOT reopen the CONTENT-detection problem the comment above
+// explicitly rejected (interface/type/class-validator/Zod/undecorated class all have different
+// shapes) -- it's an independent, NAME-only signal: the file's own basename ends in "dto"
+// (case-insensitive), the same near-definitional marker this file's own entity-matching step below
+// already leans on for MATCHING. Catches both `CreateUserDto.ts` and `create-user.dto.ts`.
+const DTO_NAME_SUFFIX_RE = /dto$/i;
+
 // Two independent signals required, mirroring java-spring's "build file AND src layout" /
 // python-fastapi's "dependency declared AND source-confirmed" combined bar: (a) package.json
 // declares express, (b) at least one .ts file actually imports Router from 'express' and calls
@@ -195,6 +206,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,
@@ -245,8 +262,8 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 				moduleEntry(moduleName).controllers.push({ className, basePath: prefix, operationIds: [], endpoints, file });
 			}
 		}
-		if (file.includes(DTO_DIR_SEGMENT)) {
-			allDtos.push({ className: path.basename(file, '.ts'), file }); // no `line` -- path-based, no content parsed
+		if (file.includes(DTO_DIR_SEGMENT) || DTO_NAME_SUFFIX_RE.test(path.basename(file, '.ts'))) {
+			allDtos.push({ className: path.basename(file, '.ts'), file }); // no `line` -- path/name-based, no content parsed
 		}
 		allEntities.push(...extractTableEntities(text, 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();
 	}