backend-skeleton 1.0.0-beta.9 → 1.0.0

package/lib/serve-ui.html

@@ -44,6 +44,34 @@
 </form>
 <div id="formStatus"></div>
 
+<h2>Live DB schema</h2>
+<div id="dbSchemaPanel">
+	<p class="muted" id="dbSchemaNote">loading...</p>
+	<table id="dbSchemaTable" hidden><thead><tr><th>table</th><th>columns</th><th>primary key</th><th>foreign keys</th><th>indexes</th></tr></thead><tbody></tbody></table>
+</div>
+
+<h2>DDL patch transactions</h2>
+<div id="ddlPanel">
+	<form id="ddlFeatureForm" style="grid-template-columns: 1fr auto;">
+		<label>feature <input name="feature" id="ddlFeatureInput" required></label>
+		<button type="submit">Load transactions</button>
+	</form>
+	<table id="ddlTable"><thead><tr><th>transaction</th><th>kind</th><th>status</th><th>sql</th><th>created</th><th>action</th></tr></thead><tbody></tbody></table>
+	<div id="ddlActionStatus"></div>
+
+	<h3 style="font-size: 0.9rem; margin-top: 1.2rem;">Propose a DDL change</h3>
+	<form id="ddlProposeForm">
+		<label>feature <input name="feature" id="ddlProposeFeature" required></label>
+		<label>database_url_env <input name="databaseUrlEnv" placeholder="e.g. BSKEL_DDL_DATABASE_URL" required></label>
+		<label>schema <input name="schema" value="public" required></label>
+		<label style="grid-column: 1 / -1">sql_text
+			<textarea name="sqlText" rows="4" required style="font: inherit; padding: 0.4rem;" placeholder="CREATE TABLE widgets (id uuid PRIMARY KEY);"></textarea>
+		</label>
+		<button type="submit">Propose</button>
+	</form>
+	<div id="ddlProposeStatus"></div>
+</div>
+
 <script>
 // D-http-serving-layer: `reason`/`memo` (and every other string field) are free text a human types
 // via `bskel dependency declare --reason/--memo` or this page's own POST form -- never assumed safe
@@ -106,6 +134,189 @@ document.getElementById('declareForm').addEventListener('submit', async (ev) =>
 	}
 });
 
+// D-ddl-apply: mirrors td()'s own comment above -- every value rendered here (table/column names,
+// raw sql_text, error messages) is free text this tool never assumes is safe to inject as markup.
+// All via td()/textContent, never innerHTML.
+function tdList(items) {
+	return td(items.length ? items.join(', ') : '(none)');
+}
+
+// D-ddl-apply (DROP-TABLE-specific confirmation): mirrors scanners/db/ddl-apply.mjs's own
+// requiredConfirmValue() exactly -- the transaction id for a non-drop transaction, or the sorted,
+// comma-joined dropped-table name(s) for one that drops a table. Computed here purely so the
+// placeholder can SHOW the human what to type; the server independently re-derives and enforces
+// the same value, this is not the source of truth.
+function requiredConfirmValue(t) {
+	const droppedTables = (t.postcondition?.expected_tables ?? [])
+		.filter((x) => x.expect === 'absent')
+		.map((x) => x.name)
+		.sort();
+	return droppedTables.length > 0 ? droppedTables.join(',') : t.transaction_id;
+}
+
+async function loadDbSchema() {
+	const note = document.getElementById('dbSchemaNote');
+	const table = document.getElementById('dbSchemaTable');
+	try {
+		const res = await fetch('/api/db/schema');
+		if (res.status === 404) {
+			note.hidden = false;
+			note.textContent = 'DDL features are disabled -- start `bskel serve --database-url-env NAME` to enable them.';
+			table.hidden = true;
+			return;
+		}
+		const body = await res.json();
+		if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+		note.hidden = true;
+		table.hidden = false;
+		const tbody = table.querySelector('tbody');
+		tbody.replaceChildren();
+		for (const t of body.tables) {
+			const tr = document.createElement('tr');
+			tr.append(
+				td(t.name),
+				td(t.columns.map((c) => `${c.name} ${c.type}${c.nullable ? '' : ' NOT NULL'}`).join(', ') || '(none)'),
+				tdList(t.primary_key),
+				td(t.foreign_keys.map((f) => `${f.column} -> ${f.references_table}.${f.references_column}`).join(', ') || '(none)'),
+				tdList(t.indexes),
+			);
+			tbody.appendChild(tr);
+		}
+		if (body.tables.length === 0) {
+			const tr = document.createElement('tr');
+			tr.appendChild(td('(no tables)'));
+			tbody.appendChild(tr);
+		}
+	} catch (err) {
+		note.hidden = false;
+		note.textContent = `failed to load /api/db/schema: ${err.message}`;
+		table.hidden = true;
+	}
+}
+
+async function loadDdlTransactions(feature) {
+	const tbody = document.querySelector('#ddlTable tbody');
+	tbody.replaceChildren();
+	if (!feature) return;
+	const res = await fetch(`/api/features/${encodeURIComponent(feature)}/patch-transactions`);
+	const body = await res.json();
+	if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+	for (const t of body.transactions) {
+		const tr = document.createElement('tr');
+		const sqlOrTarget = t.kind === 'ddl-apply' ? t.target.sql_text : `${t.target.file} @ ${(t.target.key_path || []).join('.')}`;
+		tr.append(td(t.transaction_id), td(t.kind), td(t.status), td(sqlOrTarget), td(t.created_at));
+
+		const actionCell = document.createElement('td');
+		if (t.status === 'proposed') {
+			const form = document.createElement('form');
+			form.style.gridTemplateColumns = 'none';
+			form.style.display = 'flex';
+			form.style.gap = '0.3rem';
+			const reasonInput = document.createElement('input');
+			reasonInput.placeholder = 'reason';
+			reasonInput.required = true;
+			const btn = document.createElement('button');
+			btn.type = 'submit';
+			btn.textContent = 'Approve';
+			form.append(reasonInput, btn);
+			form.addEventListener('submit', async (ev) => {
+				ev.preventDefault();
+				await runDdlAction(feature, t.transaction_id, 'approve', { reason: reasonInput.value });
+			});
+			actionCell.appendChild(form);
+		} else if (t.status === 'approved') {
+			const form = document.createElement('form');
+			form.style.gridTemplateColumns = 'none';
+			form.style.display = 'flex';
+			form.style.gap = '0.3rem';
+			const confirmInput = document.createElement('input');
+			// Deliberately starts EMPTY, never pre-filled -- a pre-filled confirm field would let a
+			// click submit this whole flow (applying a live DDL change) without the human actually
+			// re-reading/re-typing anything, defeating the entire point of this friction. The
+			// placeholder names the REQUIRED value -- the dropped table name(s), not the opaque
+			// transaction id, when this transaction drops a table (see requiredConfirmValue() above).
+			confirmInput.placeholder = `type "${requiredConfirmValue(t)}" to confirm`;
+			confirmInput.required = true;
+			const btn = document.createElement('button');
+			btn.type = 'submit';
+			btn.textContent = 'Apply';
+			form.append(confirmInput, btn);
+			form.addEventListener('submit', async (ev) => {
+				ev.preventDefault();
+				await runDdlAction(feature, t.transaction_id, 'apply', { confirm: confirmInput.value });
+			});
+			actionCell.appendChild(form);
+		} else {
+			actionCell.textContent = '(none)';
+		}
+		tr.appendChild(actionCell);
+		tbody.appendChild(tr);
+	}
+	if (body.transactions.length === 0) {
+		const tr = document.createElement('tr');
+		tr.appendChild(td('(none proposed)'));
+		tbody.appendChild(tr);
+	}
+}
+
+async function runDdlAction(feature, transactionId, action, body) {
+	const statusEl = document.getElementById('ddlActionStatus');
+	statusEl.textContent = `${action}ing...`;
+	try {
+		const res = await fetch(`/api/features/${encodeURIComponent(feature)}/patch-transactions/${encodeURIComponent(transactionId)}/${action}`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify(body),
+		});
+		const responseBody = await res.json();
+		if (!res.ok) throw new Error(responseBody.error ?? `HTTP ${res.status}`);
+		statusEl.textContent = `${action} succeeded: ${transactionId} -> ${responseBody.status}`;
+		await loadDdlTransactions(feature);
+	} catch (err) {
+		statusEl.textContent = `error: ${err.message}`;
+	}
+}
+
+document.getElementById('ddlFeatureForm').addEventListener('submit', async (ev) => {
+	ev.preventDefault();
+	const feature = document.getElementById('ddlFeatureInput').value;
+	try {
+		await loadDdlTransactions(feature);
+	} catch (err) {
+		document.getElementById('ddlActionStatus').textContent = `error: ${err.message}`;
+	}
+});
+
+document.getElementById('ddlProposeForm').addEventListener('submit', async (ev) => {
+	ev.preventDefault();
+	const form = new FormData(ev.target);
+	const feature = form.get('feature');
+	const statusEl = document.getElementById('ddlProposeStatus');
+	statusEl.textContent = 'proposing...';
+	try {
+		const res = await fetch(`/api/features/${encodeURIComponent(feature)}/patch-transactions/propose`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				kind: 'ddl-apply',
+				databaseUrlEnv: form.get('databaseUrlEnv'),
+				schema: form.get('schema'),
+				sqlText: form.get('sqlText'),
+			}),
+		});
+		const body = await res.json();
+		if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+		statusEl.textContent = `proposed: ${body.transaction_id}`;
+		ev.target.reset();
+		document.getElementById('ddlFeatureInput').value = feature;
+		await loadDdlTransactions(feature);
+	} catch (err) {
+		statusEl.textContent = `error: ${err.message}`;
+	}
+});
+
+loadDbSchema();
+
 loadGraph().catch((err) => {
 	const p = document.createElement('p');
 	p.style.color = '#d33';

package/lib/workflow.mjs

@@ -31,6 +31,11 @@ export function listFeatures(root) {
 const ESTABLISH_COMMAND = {
 	preflight: () => 'bskel preflight',
 	scan: (id) => `bskel scan --feature ${id} --terms <a,b,c>`,
+	// D-cross-feature-collision: added in the SAME commit as the gate itself this time -- the
+	// ESTABLISH_COMMAND/MUTATING_PREFIXES gap was found live twice already this session for other
+	// gates (dependencies/conformance below), so this one is wired up immediately rather than
+	// discovered later.
+	cross_feature: (id) => `bskel scan cross-feature-check --feature ${id}`,
 	contract: (id) => `bskel contract emit --feature ${id}`,
 	// D-field-dependency: this and `conformance` immediately below were BOTH missing before this
 	// item -- found live while adding this one, same crash class, fixed together. Neither had ever
@@ -41,6 +46,10 @@ const ESTABLISH_COMMAND = {
 	dependencies: (id) => `bskel dependency declare --feature ${id} --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."`,
 	handles: (id) => `bskel handles plan --feature ${id}   # then: bskel handles emit --feature ${id}`,
 	stack: () => 'bskel stack apply --choice <id> --apply',
+	// D-patch-transactions: added in the SAME commit as the gate itself -- per the
+	// `D-cross-feature-collision` entry's own explicit warning above (this exact ESTABLISH_COMMAND
+	// gap), already found live twice for other gates before it could recur a third time here.
+	patch_transactions: (id) => `bskel patch propose --feature ${id} --choice <id> --target <config_check target path>   # then: bskel patch approve ... then bskel patch apply ...`,
 	conformance: (id) => `bskel observe emit --feature ${id}   # then: run the target app, then bskel observe import --feature ${id} --receipts <path>`,
 };
 
@@ -55,17 +64,36 @@ function awaitingDispositionCommand(gateName, featureId) {
 	if (gateName === 'contract') {
 		return `bskel contract waive --feature ${featureId} --code <CODE> (--subject "..."|--all) --reason "..."   # or: bskel gate force contract --feature ${featureId} --reason "..." if intentional`;
 	}
+	if (gateName === 'cross_feature') {
+		return `bskel scan cross-feature-waive --feature ${featureId} --signal resource_type|table|operation_id --identifier <name> --other-feature <id> --reason "..."   # or: bskel gate force cross_feature --feature ${featureId} --reason "..." if intentional`;
+	}
 	return `bskel gate force ${gateName} --feature ${featureId} --reason "..."`;
 }
 
 // Whether a recommended command WRITES anything (gate state, generated files, applied files) as
 // opposed to being a pure read (bskel verify, bskel status, bskel next itself). Matched by the
 // command's own leading "bskel <verb...>" prefix so this can't silently drift from the actual
-// command names above.
-const MUTATING_PREFIXES = ['bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive', 'bskel gate force', 'bskel dependency declare', 'bskel dependency remove', 'bskel handles emit', 'bskel handles plan', 'bskel stack apply'];
+// command names above. `bskel observe emit`/`bskel observe import` were BOTH missing until found
+// live while fixing the identical ESTABLISH_COMMAND gap above (same bug class: neither had ever
+// been exercised through `next` recommending the real `conformance`-gate command, so a real
+// `mutating: false` misclassification on a command that actually writes files + passes a gate went
+// unnoticed) -- see D-field-dependency's COST section in DECISIONS.md.
+const MUTATING_PREFIXES = [
+	'bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive',
+	'bskel gate force', 'bskel dependency declare', 'bskel dependency remove', 'bskel handles emit',
+	'bskel handles plan', 'bskel stack apply', 'bskel observe emit', 'bskel observe import',
+	'bskel patch propose', 'bskel patch approve', 'bskel patch apply', 'bskel patch rollback',
+];
+
+// Exported (not just inlined into action()) so lib/workflow.mjs's own test suite can assert the
+// classification directly, without needing a full end-to-end fixture that drives a feature all the
+// way to a stale `conformance` gate just to observe one boolean.
+export function isMutatingCommand(command) {
+	return MUTATING_PREFIXES.some((p) => command.startsWith(p));
+}
 
 function action(command, reason) {
-	return { command, reason, mutating: MUTATING_PREFIXES.some((p) => command.startsWith(p)) };
+	return { command, reason, mutating: isMutatingCommand(command) };
 }
 
 // featureId === null means "repo scope only" -- feature-scoped gates (scan/contract/handles)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.0",
   "type": "module",
   "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scaffolding codegen included (Java/Spring, Python/FastAPI, TypeScript/Express).",
   "license": "AGPL-3.0-or-later",
@@ -38,11 +38,14 @@
     "test:java-compile": "node scripts/java-compile-smoke.mjs",
     "test:python-import": "node scripts/python-import-smoke.mjs",
     "test:db-introspect": "node scripts/db-introspect-smoke.mjs",
+    "test:ddl-apply": "node scripts/ddl-apply-smoke.mjs",
+    "test:cross-feature-fk": "node scripts/cross-feature-fk-smoke.mjs",
     "test:java-integration": "node scripts/java-integration-smoke.mjs",
     "test:java-ast": "node scripts/java-ast-smoke.mjs",
     "test:python-integration": "node scripts/python-integration-smoke.mjs",
     "test:typescript-compile": "node scripts/typescript-typecheck-smoke.mjs",
-    "test:spring-initializr-canary": "node scripts/spring-initializr-canary.mjs"
+    "test:spring-initializr-canary": "node scripts/spring-initializr-canary.mjs",
+    "test:all-smoke": "npm test && npm run test:pack && npm run test:java-compile && npm run test:java-integration && npm run test:python-import && npm run test:python-integration && npm run test:db-introspect && npm run test:ddl-apply && npm run test:cross-feature-fk && npm run test:java-ast && npm run test:typescript-compile"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/scanners/adapters/java-spring.mjs

@@ -141,6 +141,12 @@ function extractEntity(text, filePath) {
 	return {
 		className: classDecl ? classDecl.name : path.basename(filePath, '.java'),
 		table: tableMatch ? tableMatch[1] : null,
+		// D-cross-feature-collision: this adapter never GUESSES a table name -- `table: null` above
+		// already means "no explicit @Table(name=...)", so tableSource is 'explicit' whenever
+		// `table` is non-null and null otherwise. Added only for a consistent field shape with the
+		// two adapters that DO guess (python-fastapi/typescript-express) -- cross-feature collision
+		// detection reads this field, not each adapter's own null-vs-guessed convention.
+		tableSource: tableMatch ? 'explicit' : null,
 		idField: idFieldMatch ? idFieldMatch[1] : null,
 		file: filePath,
 		line: classDecl ? lineNumberAt(text, classDecl.index) : null,

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

@@ -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)',
+	);
+}