backend-skeleton 1.0.0-beta.8 → 1.0.0

package/lib/patch-transactions.mjs

@@ -0,0 +1,206 @@
+// D-patch-transactions: the general, kind-agnostic content-addressed patch-transaction primitive.
+// Generalizes lib/patch-approvals.mjs's (A3/D-patch-strategy) per-{resource,field} approval shape
+// into a real lifecycle (propose -> approve -> apply -> rollback) with preimage-hash verification
+// re-checked at every step and content-addressed rollback material saved BEFORE any edit is ever
+// applied. Slice 1 wires exactly one `kind` ("config-apply", stack/config-apply.mjs) -- a later
+// slice can add a second kind without touching this state machine at all.
+//
+// One file per transaction (specs/<featureId>/patch-transactions/<transaction_id>.json), not one
+// growing array like patch-approvals.json -- each record carries real state transitions and
+// references a potentially large rollback blob, so appending to one shared JSON array under a
+// lock on every transition would be worse for both concurrency and the "content-addressed"
+// framing this feature is named for. Blobs (specs/<featureId>/patch-transactions/blobs/<sha256>.
+// blob) dedupe automatically: two transactions proposed against the same preimage produce the
+// identical filename.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readJsonIfExists, writeFileAtomic, sha256String } from './fsutil.mjs';
+import { specPath } from './paths.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+import { withLockSync, withLockAsync } from './lock.mjs';
+
+const TRANSACTION_SCHEMA = 'sbf.patch-transaction/1';
+
+export function transactionsDir(root, featureId) {
+	return specPath(root, featureId, 'patch-transactions');
+}
+
+export function blobsDir(root, featureId) {
+	return path.join(transactionsDir(root, featureId), 'blobs');
+}
+
+export function transactionPath(root, featureId, transactionId) {
+	return path.join(transactionsDir(root, featureId), `${transactionId}.json`);
+}
+
+export function blobPath(root, featureId, hash) {
+	return path.join(blobsDir(root, featureId), `${hash}.blob`);
+}
+
+export function newTransactionId() {
+	return `pt-${randomUUID()}`;
+}
+
+// Idempotent -- identical content always produces the identical path, so re-saving the same
+// preimage (e.g. a second propose against a target nothing has touched since) is a harmless no-op
+// write, never a duplicate.
+export function saveBlob(root, featureId, content) {
+	const hash = sha256String(content);
+	writeFileAtomic(blobPath(root, featureId, hash), content);
+	return hash;
+}
+
+export function readBlob(root, featureId, hash) {
+	return fs.readFileSync(blobPath(root, featureId, hash), 'utf8');
+}
+
+export function loadTransaction(root, featureId, transactionId) {
+	const p = transactionPath(root, featureId, transactionId);
+	const parsed = readJsonIfExists(p);
+	if (parsed === null) return null;
+	const { ok, errors } = validateAgainstSchema('patch-transaction.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${p}: does not match schemas/patch-transaction.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveTransaction(root, featureId, txn) {
+	const { ok, errors } = validateAgainstSchema('patch-transaction.schema.json', txn);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid patch transaction for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	writeFileAtomic(transactionPath(root, featureId, txn.transaction_id), `${JSON.stringify(txn, null, 2)}\n`);
+	return txn;
+}
+
+export function listTransactions(root, featureId) {
+	const dir = transactionsDir(root, featureId);
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir)
+		.filter((name) => name.endsWith('.json'))
+		.map((name) => loadTransaction(root, featureId, name.slice(0, -'.json'.length)))
+		.filter(Boolean)
+		.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+
+// `kindPlan` is whatever a kind-specific planner (e.g. stack/config-apply.mjs's planConfigApply())
+// returns -- this module never inspects `kind`-specific fields beyond the ones every plan must
+// carry (target/preimage/proposed_value/postcondition/originalContent/renderedContent).
+// `source` is kind-specific, opaque bookkeeping this module never inspects -- for kind
+// "config-apply" it's `{choice}`, the stack catalog choice id needed to re-locate the same
+// config_check/apply block at approve/apply time (the record's own target.file alone is not
+// enough, since a catalog choice is what the CLI's --choice flag resolves, not stored per-file).
+export function proposeTransaction(root, featureId, kind, kindPlan, source) {
+	return withLockSync(root, 'state', () => {
+		const transactionId = newTransactionId();
+		// The blob is keyed by its OWN content hash, never trusted from kindPlan.preimage.file_hash
+		// blindly -- if a planner ever computed that field differently than a plain sha256 of the
+		// same bytes, silently trusting it here would save a rollback blob under the WRONG filename,
+		// making rollback impossible later. Fail loudly instead; this should never actually fire.
+		const blobHash = saveBlob(root, featureId, kindPlan.originalContent);
+		if (blobHash !== kindPlan.preimage.file_hash) {
+			throw new Error(`internal error: kindPlan.preimage.file_hash ("${kindPlan.preimage.file_hash}") does not match the original content's own hash ("${blobHash}") -- refusing to propose a transaction whose rollback blob would be unrecoverable`);
+		}
+		const txn = {
+			schema: TRANSACTION_SCHEMA,
+			transaction_id: transactionId,
+			feature_id: featureId,
+			kind,
+			source,
+			target: kindPlan.target,
+			preimage: kindPlan.preimage,
+			current_value: kindPlan.current_value,
+			proposed_value: kindPlan.proposed_value,
+			postcondition: kindPlan.postcondition,
+			status: 'proposed',
+			created_at: new Date().toISOString(),
+		};
+		return saveTransaction(root, featureId, txn);
+	});
+}
+
+class StaleTransactionError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = 'StaleTransactionError';
+	}
+}
+
+function requireFreshPreimage(txn, freshKindPlan) {
+	if (freshKindPlan.preimage.region_hash !== txn.preimage.region_hash) {
+		throw new StaleTransactionError(
+			`transaction "${txn.transaction_id}"'s target has changed since it was proposed -- re-propose it against the current content`,
+		);
+	}
+}
+
+// `freshKindPlan` MUST come from re-running the same kind's planner against the CURRENT on-disk
+// state, never from the stored transaction record -- this is what makes "re-verify preimage at
+// every step" real rather than assumed.
+export function approveTransaction(root, featureId, transactionId, reason, freshKindPlan) {
+	if (!reason || !reason.trim()) {
+		throw new Error('approving a patch transaction requires a reason -- every approval must be auditable');
+	}
+	return withLockSync(root, 'state', () => {
+		const txn = loadTransaction(root, featureId, transactionId);
+		if (!txn) throw new Error(`no patch transaction "${transactionId}" for feature "${featureId}"`);
+		requireFreshPreimage(txn, freshKindPlan);
+		txn.approval = { reason, at: new Date().toISOString() };
+		txn.status = 'approved';
+		return saveTransaction(root, featureId, txn);
+	});
+}
+
+// No --force escape here (mirrors cmdHandlesPatchApprove's permanent "a stale approval is
+// rejected outright, never bypassed" precedent) -- a stale forward edit's collateral effects have
+// never been re-verified, unlike a rollback restoring a known-good, git-recoverable prior state.
+//
+// D-ddl-apply: `executeApply(root, featureId, txn, freshKindPlan)` is an INJECTED, kind-specific
+// async function that performs the actual mutation and returns the fields to merge into `txn.apply`
+// (alongside `at`, added here uniformly). This module still never imports a kind-specific module
+// and never branches on `kind` -- it only calls whatever executor its caller (lib/patch-kinds.mjs)
+// injected, so the "kind-agnostic" framing stays literally true; this is dependency injection, not
+// a switch statement. Uses withLockAsync, not withLockSync -- a naive `async` callback passed to
+// withLockSync would release the lock the instant the callback RETURNS a Promise, not once that
+// Promise RESOLVES, releasing the lock before a live DB write (or any other async executor) has
+// actually finished. withLockAsync's `try { return await fn() } finally { ... }` makes that
+// ordering bug structurally impossible.
+export async function applyTransaction(root, featureId, transactionId, freshKindPlan, executeApply) {
+	return withLockAsync(root, 'state', async () => {
+		const txn = loadTransaction(root, featureId, transactionId);
+		if (!txn) throw new Error(`no patch transaction "${transactionId}" for feature "${featureId}"`);
+		if (txn.status !== 'approved') {
+			throw new Error(`transaction "${transactionId}" is "${txn.status}", not "approved" -- approve it first`);
+		}
+		requireFreshPreimage(txn, freshKindPlan);
+		const applyResult = await executeApply(root, featureId, txn, freshKindPlan);
+		txn.apply = { at: new Date().toISOString(), ...applyResult };
+		txn.status = 'applied';
+		return saveTransaction(root, featureId, txn);
+	});
+}
+
+// `executeRollback(root, featureId, txn, {force})` is the injected, kind-specific async restore --
+// for config-apply it re-validates the file-hash drift check and restores from the CAS blob
+// exactly as before (moved verbatim, not reimplemented); for ddl-apply it always throws (rollback
+// of a live DDL apply is out of scope for Slice 1 -- see scanners/db/ddl-apply.mjs's
+// executeDdlRollback). This function itself no longer knows what "restore" means for any kind --
+// the drift-check-then-restore logic lives entirely in the executor now.
+export async function rollbackTransaction(root, featureId, transactionId, reason, { force = false } = {}, executeRollback) {
+	if (!reason || !reason.trim()) {
+		throw new Error('rolling back a patch transaction requires a reason -- every rollback must be auditable');
+	}
+	return withLockAsync(root, 'state', async () => {
+		const txn = loadTransaction(root, featureId, transactionId);
+		if (!txn) throw new Error(`no patch transaction "${transactionId}" for feature "${featureId}"`);
+		if (txn.status !== 'applied') {
+			throw new Error(`transaction "${transactionId}" is "${txn.status}", not "applied" -- only an applied transaction can be rolled back`);
+		}
+		const rollbackResult = await executeRollback(root, featureId, txn, { force });
+		txn.rollback = { reason, at: new Date().toISOString(), ...(force ? { forced: true } : {}), ...rollbackResult };
+		txn.status = 'rolled_back';
+		return saveTransaction(root, featureId, txn);
+	});
+}

package/lib/serve-ui.html

@@ -0,0 +1,328 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>bskel serve</title>
+<style>
+	:root { color-scheme: light dark; }
+	body { font-family: ui-monospace, Menlo, Consolas, monospace; max-width: 960px; margin: 2rem auto; padding: 0 1rem; line-height: 1.4; }
+	h1 { font-size: 1.1rem; }
+	h2 { font-size: 1rem; margin-top: 2rem; }
+	table { border-collapse: collapse; width: 100%; margin-top: 0.5rem; }
+	th, td { text-align: left; padding: 0.3rem 0.6rem; border-bottom: 1px solid #8884; font-size: 0.85rem; }
+	.resolution-synced { color: #2a2; }
+	.resolution-stale { color: #c90; }
+	.resolution-unresolved { color: #d33; }
+	form { margin-top: 0.5rem; display: grid; grid-template-columns: repeat(3, 1fr); gap: 0.4rem; max-width: 720px; }
+	form label { display: flex; flex-direction: column; font-size: 0.75rem; gap: 0.15rem; }
+	form input { font: inherit; padding: 0.25rem; }
+	form button { grid-column: 1 / -1; padding: 0.4rem; font: inherit; cursor: pointer; }
+	#formStatus { font-size: 0.85rem; margin-top: 0.4rem; }
+	.muted { opacity: 0.6; }
+</style>
+</head>
+<body>
+<h1>bskel serve -- functionality check</h1>
+<p class="muted">Not a redesign of the original Fieldwire mockup -- this exists to prove the API actually works, nothing more.</p>
+
+<h2>Nodes</h2>
+<table id="nodesTable"><thead><tr><th>feature</th><th>resourceType</th><th>file</th><th>resolved</th></tr></thead><tbody></tbody></table>
+
+<h2>Wires</h2>
+<table id="wiresTable"><thead><tr><th>target</th><th>source</th><th>resolution</th><th>memo</th></tr></thead><tbody></tbody></table>
+
+<h2>Declare a new dependency</h2>
+<form id="declareForm">
+	<label>feature <input name="feature" required></label>
+	<label>resource <input name="resource" required></label>
+	<label>field <input name="field" required></label>
+	<label>source feature <input name="sourceFeature" required></label>
+	<label>source resource <input name="sourceResource" required></label>
+	<label>source field <input name="sourceField" required></label>
+	<label style="grid-column: 1 / -1">reason <input name="reason" required></label>
+	<button type="submit">Declare</button>
+</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
+// to inject as markup. Every cell here is built via textContent, never innerHTML/insertAdjacentHTML,
+// so a value like `<script>...` or `<img onerror=...>` renders as inert text, not executes.
+function td(text) {
+	const cell = document.createElement('td');
+	cell.textContent = text;
+	return cell;
+}
+
+async function loadGraph() {
+	const res = await fetch('/api/graph');
+	const graph = await res.json();
+
+	const nodesBody = document.querySelector('#nodesTable tbody');
+	nodesBody.replaceChildren();
+	for (const n of graph.nodes) {
+		const tr = document.createElement('tr');
+		tr.append(td(n.feature), td(n.resourceType), td(n.file ?? '(unresolved)'), td(String(n.resolved)));
+		nodesBody.appendChild(tr);
+	}
+
+	const wiresBody = document.querySelector('#wiresTable tbody');
+	wiresBody.replaceChildren();
+	for (const w of graph.wires) {
+		const tr = document.createElement('tr');
+		const target = `${w.feature}/${w.target.resourceType}.${w.target.fieldName}`;
+		const source = `${w.source.feature}/${w.source.resourceType}.${w.source.fieldName}`;
+		const resolutionCell = td(`${w.resolution}${w.unresolvedReason ? ` (${w.unresolvedReason})` : ''}`);
+		resolutionCell.className = `resolution-${w.resolution}`;
+		tr.append(td(target), td(source), resolutionCell, td(w.hasMemo ? w.memo : ''));
+		wiresBody.appendChild(tr);
+	}
+}
+
+document.getElementById('declareForm').addEventListener('submit', async (ev) => {
+	ev.preventDefault();
+	const form = new FormData(ev.target);
+	const feature = form.get('feature');
+	const statusEl = document.getElementById('formStatus');
+	statusEl.textContent = 'declaring...';
+	try {
+		const res = await fetch(`/api/features/${encodeURIComponent(feature)}/dependencies`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				resource: form.get('resource'), field: form.get('field'),
+				sourceFeature: form.get('sourceFeature'), sourceResource: form.get('sourceResource'), sourceField: form.get('sourceField'),
+				reason: form.get('reason'),
+			}),
+		});
+		const body = await res.json();
+		if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+		statusEl.textContent = `declared, gate: ${body.gate.status}`;
+		ev.target.reset();
+		await loadGraph();
+	} catch (err) {
+		statusEl.textContent = `error: ${err.message}`;
+	}
+});
+
+// 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';
+	p.textContent = `failed to load /api/graph: ${err.message}`;
+	document.body.appendChild(p);
+});
+</script>
+</body>
+</html>

package/lib/workflow.mjs

@@ -31,9 +31,26 @@ 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
+	// been exercised through `next` on a stale REQUIRED_WHEN_PRESENT gate (no test covered it) --
+	// without an entry here, `computeWorkflowState()` calls `ESTABLISH_COMMAND[gateName](featureId)`
+	// directly on the first real stale occurrence and throws a raw TypeError instead of a clean
+	// stale report.
+	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>`,
 };
 
 // awaiting_disposition needs a genuinely different remediation per gate, not a re-run --
@@ -47,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 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.8",
+  "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;
 }