backend-skeleton 1.0.0-beta.9 → 1.0.0

package/lib/http-server.mjs

@@ -15,6 +15,14 @@ import { isValidFeatureId } from './featureid.mjs';
 import {
 	buildDependencyListReport, buildDependencyGraph, declareDependency, removeDependency, DependencyOperationError,
 } from './field-dependencies.mjs';
+import { introspectSchema, describeConnectionError } from '../scanners/db/introspect.mjs';
+import {
+	proposeTransaction, approveTransaction, applyTransaction, rollbackTransaction, loadTransaction, listTransactions, transactionsDir,
+} from './patch-transactions.mjs';
+import { getPatchKind, replanTransaction, PATCH_KIND_NAMES } from './patch-kinds.mjs';
+import { requireNamedGate, passNamedGate, EXIT } from './gates.mjs';
+import { signPayload } from './attest.mjs';
+import { writeFileAtomic } from './fsutil.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const UI_HTML_PATH = path.join(__dirname, 'serve-ui.html');
@@ -90,7 +98,173 @@ function serveUiPage(res) {
 const FEATURE_STATUS_RE = /^\/api\/features\/([^/]+)\/status$/;
 const FEATURE_DEPENDENCIES_RE = /^\/api\/features\/([^/]+)\/dependencies$/;
 
-async function handleRequest(root, req, res) {
+// D-ddl-apply: every route below is gated behind `dbConfig` being non-null (only true when
+// `bskel serve --database-url-env <NAME>` was given) -- a plain `bskel serve` never even matches
+// these paths (falls through to the existing 404), matching --host's own "safe default, explicit
+// override" convention. NONE of these routes ever get CORS, GET included -- a deliberate deviation
+// from CORS_METHODS' plain-GET-gets-wildcard convention above: live schema/table names and raw SQL
+// text are not the same sensitivity class as the git-tracked JSON dependency record that
+// convention was scoped against (see DECISIONS.md D-ddl-apply).
+const DB_SCHEMA_RE = /^\/api\/db\/schema$/;
+const PATCH_TRANSACTIONS_RE = /^\/api\/features\/([^/]+)\/patch-transactions$/;
+const PATCH_PROPOSE_RE = /^\/api\/features\/([^/]+)\/patch-transactions\/propose$/;
+const PATCH_TXN_ACTION_RE = /^\/api\/features\/([^/]+)\/patch-transactions\/([^/]+)\/(approve|apply|rollback)$/;
+const TRANSACTION_ID_RE = /^pt-[0-9a-f-]{36}$/;
+
+function paramsAndSourceFromProposeBody(kind, body) {
+	if (kind === 'config-apply') {
+		if (!body.choice || !body.target) {
+			throw new DependencyOperationError('propose --kind config-apply requires {choice, target}', { httpStatus: 400, reasonCode: 'BAD_ARGS' });
+		}
+		return { params: { choice: body.choice, target: body.target }, source: { choice: body.choice } };
+	}
+	if (kind === 'ddl-apply') {
+		if (!body.databaseUrlEnv || !body.sqlText) {
+			throw new DependencyOperationError('propose --kind ddl-apply requires {databaseUrlEnv, sqlText}', { httpStatus: 400, reasonCode: 'BAD_ARGS' });
+		}
+		const schema = body.schema || 'public';
+		return { params: { databaseUrlEnv: body.databaseUrlEnv, schema, sqlText: body.sqlText }, source: { database_url_env: body.databaseUrlEnv, schema } };
+	}
+	throw new DependencyOperationError(`unknown kind "${kind}" -- known kinds: ${PATCH_KIND_NAMES.join(', ')}`, { httpStatus: 400, reasonCode: 'BAD_ARGS' });
+}
+
+// D-ddl-apply audit trail: optional (only when `--sign-key` was given at `bskel serve` startup),
+// server-held-key signing of every propose/approve/apply/rollback-refusal touching a `ddl-apply`
+// transaction -- the browser can never hold a private key, so the server process itself signs, per
+// this feature's own design (see DECISIONS.md D-ddl-apply). lib/attest.mjs itself needs no changes
+// -- it's already genuinely payload-shape-agnostic. Deliberately best-effort/non-fatal: a signing
+// failure must not roll back or hide an otherwise-successful propose/approve/apply.
+let signKeyCache = null;
+function loadSignKey(signKeyPath) {
+	if (signKeyCache === null) signKeyCache = fs.readFileSync(signKeyPath, 'utf8');
+	return signKeyCache;
+}
+
+function maybeSignStep(root, dbConfig, txn, step) {
+	if (!dbConfig?.signKeyPath || txn.kind !== 'ddl-apply') return;
+	try {
+		const privateKeyPem = loadSignKey(dbConfig.signKeyPath);
+		const payload = {
+			transaction_id: txn.transaction_id,
+			feature_id: txn.feature_id,
+			kind: txn.kind,
+			status: txn.status,
+			sql_text: txn.target.sql_text,
+			schema_hash: txn.preimage.region_hash,
+			reason: txn.approval?.reason ?? txn.rollback?.reason ?? null,
+			at: new Date().toISOString(),
+		};
+		const signature = signPayload(payload, privateKeyPem);
+		const sigPath = path.join(transactionsDir(root, txn.feature_id), `${txn.transaction_id}.${step}.sig.json`);
+		writeFileAtomic(sigPath, `${JSON.stringify({ payload, signature: { algorithm: 'ed25519', value: signature } }, null, 2)}\n`);
+	} catch (err) {
+		console.error(`warning: could not sign patch-transaction step "${step}" for "${txn.transaction_id}": ${err.message}`);
+	}
+}
+
+function requirePreflightPassedHttp(root) {
+	const result = requireNamedGate(root, 'preflight', null);
+	if (result.code !== EXIT.PASS) {
+		throw new DependencyOperationError(`blocked: \`preflight\` gate is ${result.status} -- run \`bskel preflight\` first`, { httpStatus: 409, reasonCode: 'GATE_NOT_PASSED' });
+	}
+}
+
+async function handleDbRoutes(root, dbConfig, method, pathname, req, res) {
+	if (method === 'GET' && DB_SCHEMA_RE.test(pathname)) {
+		const connectionString = process.env[dbConfig.databaseUrlEnv];
+		let live;
+		try {
+			live = await introspectSchema({ connectionString, schema: dbConfig.schema });
+		} catch (err) {
+			throw new DependencyOperationError(`could not introspect the live database: ${describeConnectionError(err)}`, { httpStatus: 502, reasonCode: 'REFRESH_FAILED' });
+		}
+		sendJson(res, 200, live, { cors: false });
+		return true;
+	}
+
+	const listMatch = pathname.match(PATCH_TRANSACTIONS_RE);
+	if (method === 'GET' && listMatch) {
+		const featureId = decodeURIComponent(listMatch[1]);
+		if (!isValidFeatureId(featureId)) { sendJson(res, 400, { error: `invalid feature id "${featureId}"` }, { cors: false }); return true; }
+		sendJson(res, 200, { feature: featureId, transactions: listTransactions(root, featureId) }, { cors: false });
+		return true;
+	}
+
+	const proposeMatch = pathname.match(PATCH_PROPOSE_RE);
+	if (method === 'POST' && proposeMatch) {
+		const featureId = decodeURIComponent(proposeMatch[1]);
+		if (!isValidFeatureId(featureId)) { sendJson(res, 400, { error: `invalid feature id "${featureId}"` }, { cors: false }); return true; }
+		const body = await readJsonBody(req);
+		const kind = body.kind || 'config-apply';
+		const { params, source } = paramsAndSourceFromProposeBody(kind, body);
+		const plan = await getPatchKind(kind).planFresh(root, params);
+		const txn = proposeTransaction(root, featureId, kind, plan, source);
+		maybeSignStep(root, dbConfig, txn, 'propose');
+		sendJson(res, 201, txn, { cors: false });
+		return true;
+	}
+
+	const actionMatch = pathname.match(PATCH_TXN_ACTION_RE);
+	if (method === 'POST' && actionMatch) {
+		const featureId = decodeURIComponent(actionMatch[1]);
+		const transactionId = decodeURIComponent(actionMatch[2]);
+		const action = actionMatch[3];
+		if (!isValidFeatureId(featureId)) { sendJson(res, 400, { error: `invalid feature id "${featureId}"` }, { cors: false }); return true; }
+		if (!TRANSACTION_ID_RE.test(transactionId)) { sendJson(res, 400, { error: `invalid transaction id "${transactionId}"` }, { cors: false }); return true; }
+		const txn = loadTransaction(root, featureId, transactionId);
+		if (!txn) { sendJson(res, 404, { error: `no patch transaction "${transactionId}" for feature "${featureId}"` }, { cors: false }); return true; }
+		const body = await readJsonBody(req);
+
+		if (action === 'approve') {
+			if (!body.reason || !String(body.reason).trim()) {
+				throw new DependencyOperationError('approve requires {reason}', { httpStatus: 400, reasonCode: 'BAD_ARGS' });
+			}
+			const freshPlan = await replanTransaction(root, txn);
+			const updated = approveTransaction(root, featureId, transactionId, body.reason, freshPlan);
+			maybeSignStep(root, dbConfig, updated, 'approve');
+			sendJson(res, 200, updated, { cors: false });
+			return true;
+		}
+		if (action === 'apply') {
+			// D-ddl-apply: {confirm} must exactly equal getPatchKind(kind).requiredConfirmValue(txn)
+			// -- the transaction id for a non-drop ddl-apply transaction, or the sorted, comma-joined
+			// dropped-table name(s) for one that drops a table (null/never-checked for config-apply).
+			// The same human-factors friction cmdPatchApply enforces at the CLI boundary, checked
+			// here BEFORE applyTransaction() is ever called, layered on top of (not instead of) the
+			// engine's own preimage-hash TOCTOU re-check.
+			const requiredConfirm = getPatchKind(txn.kind).requiredConfirmValue(txn);
+			if (requiredConfirm !== null && body.confirm !== requiredConfirm) {
+				throw new DependencyOperationError(`apply requires {confirm} to exactly equal ${JSON.stringify(requiredConfirm)} for kind "${txn.kind}"`, { httpStatus: 400, reasonCode: 'BAD_ARGS' });
+			}
+			requirePreflightPassedHttp(root);
+			const freshPlan = await replanTransaction(root, txn);
+			const updated = await applyTransaction(root, featureId, transactionId, freshPlan, getPatchKind(txn.kind).apply);
+			maybeSignStep(root, dbConfig, updated, 'apply');
+			passNamedGate(root, 'patch_transactions', featureId, { transaction_id: updated.transaction_id, kind: updated.kind, applied_at: updated.apply.at });
+			sendJson(res, 200, updated, { cors: false });
+			return true;
+		}
+		if (action === 'rollback') {
+			if (!body.reason || !String(body.reason).trim()) {
+				throw new DependencyOperationError('rollback requires {reason}', { httpStatus: 400, reasonCode: 'BAD_ARGS' });
+			}
+			requirePreflightPassedHttp(root);
+			const updated = await rollbackTransaction(root, featureId, transactionId, body.reason, { force: Boolean(body.force) }, getPatchKind(txn.kind).rollback);
+			maybeSignStep(root, dbConfig, updated, 'rollback');
+			passNamedGate(root, 'patch_transactions', featureId, { transaction_id: updated.transaction_id, kind: updated.kind, rolled_back_at: updated.rollback.at });
+			sendJson(res, 200, updated, { cors: false });
+			return true;
+		}
+	}
+
+	return false;
+}
+
+function isDbRoutePath(pathname) {
+	return DB_SCHEMA_RE.test(pathname) || PATCH_TRANSACTIONS_RE.test(pathname) || PATCH_PROPOSE_RE.test(pathname) || PATCH_TXN_ACTION_RE.test(pathname);
+}
+
+async function handleRequest(root, req, res, dbConfig) {
 	let url;
 	try {
 		url = new URL(req.url, `http://${req.headers.host ?? 'localhost'}`);
@@ -100,13 +274,17 @@ async function handleRequest(root, req, res) {
 	}
 	const { pathname } = url;
 	const method = req.method ?? 'GET';
-	const cors = CORS_METHODS.has(method);
+	// D-ddl-apply: CORS withheld unconditionally on every DB/patch-transaction route, GET included
+	// -- see the comment above DB_SCHEMA_RE for why this deviates from CORS_METHODS' plain-GET-
+	// gets-wildcard convention.
+	const cors = CORS_METHODS.has(method) && !isDbRoutePath(pathname);
 
 	if (method === 'OPTIONS') {
 		const headers = { 'Access-Control-Allow-Methods': 'GET, HEAD, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type' };
 		// Only ever grant a preflight for GET-eligible routes -- a POST/DELETE preflight gets no
 		// Access-Control-Allow-Origin, so the browser refuses to send the real cross-origin write.
-		if (pathname === '/' || pathname.startsWith('/api/')) headers['Access-Control-Allow-Origin'] = '*';
+		// DB/patch-transaction routes never grant it either, regardless of method (see above).
+		if ((pathname === '/' || pathname.startsWith('/api/')) && !isDbRoutePath(pathname)) headers['Access-Control-Allow-Origin'] = '*';
 		res.writeHead(204, headers);
 		res.end();
 		return;
@@ -146,6 +324,13 @@ async function handleRequest(root, req, res) {
 			}
 		}
 
+		// D-ddl-apply: only reachable at all when `bskel serve --database-url-env` was given --
+		// otherwise dbConfig is null and every one of these paths simply falls through to the same
+		// 404 below as any other unmatched route (not a 403 -- matches --host's own "safe default,
+		// explicit override" convention: a plain `bskel serve` behaves exactly as it did before
+		// this feature existed).
+		if (dbConfig && (await handleDbRoutes(root, dbConfig, method, pathname, req, res))) return;
+
 		sendJson(res, 404, { error: `not found: ${method} ${pathname}` }, { cors });
 	} catch (err) {
 		sendError(res, err, { cors });
@@ -156,10 +341,11 @@ async function handleRequest(root, req, res) {
 // matching this project's established "safe default, explicit override" convention (e.g.
 // --enforce-registry). Returns once the server has actually bound (server.address() is real), not
 // merely once listen() was called -- callers (bin/bskel.mjs's cmdServe, tests) need the REAL bound
-// port when 0 was requested.
-export function createHttpServer(root, { host = '127.0.0.1', port = 4747 } = {}) {
+// port when 0 was requested. `dbConfig` (null by default) opts into the D-ddl-apply DB/patch-
+// transaction routes -- see handleDbRoutes() above.
+export function createHttpServer(root, { host = '127.0.0.1', port = 4747, dbConfig = null } = {}) {
 	const server = http.createServer((req, res) => {
-		handleRequest(root, req, res).catch((err) => sendError(res, err));
+		handleRequest(root, req, res, dbConfig).catch((err) => sendError(res, err));
 	});
 	return new Promise((resolve, reject) => {
 		server.once('error', reject);

package/lib/lock.mjs

@@ -6,13 +6,21 @@
 // dependency, and needs no cleanup daemon -- a crashed holder just leaves a directory a human can
 // `rm -rf`, which the timeout error message below points at directly.
 //
-// Deliberately SYNCHRONOUS, not Promise-based: setGate() (and every passGate/awaitDispositionGate/
-// forceGate/passNamedGate caller above it, all the way up through bin/bskel.mjs's cmdXxx functions
-// and main()) is synchronous today. Making the lock async would force `async`/`await` through that
-// entire call chain for a correctness property that doesn't need it -- this is a short-lived CLI
-// process, not a server, so blocking the (single) event loop for up to a few seconds while polling
-// for a lock is not a real cost. `Atomics.wait` gives a genuine synchronous blocking sleep on
-// Node's main thread (confirmed directly: not restricted to worker threads).
+// withLockSync is deliberately SYNCHRONOUS, not Promise-based: setGate() (and every
+// passGate/awaitDispositionGate/forceGate/passNamedGate caller above it, all the way up through
+// bin/bskel.mjs's cmdXxx functions and main()) is synchronous today. Making the lock async would
+// force `async`/`await` through that entire call chain for a correctness property that doesn't
+// need it -- this is a short-lived CLI process, not a server, so blocking the (single) event loop
+// for up to a few seconds while polling for a lock is not a real cost. `Atomics.wait` gives a
+// genuine synchronous blocking sleep on Node's main thread (confirmed directly: not restricted to
+// worker threads).
+//
+// D-ddl-apply added withLockAsync -- a genuinely separate acquire loop (a non-blocking
+// `await new Promise(setTimeout)` sleep, not Atomics.wait), needed once `bskel serve` became a
+// long-running process handling concurrent requests: withLockSync's synchronous, event-loop-
+// blocking wait is fine for a short-lived CLI process racing another short-lived CLI process, but
+// deadlocks a server racing itself (see withLockAsync's own comment below for the real bug this
+// closes, found live while writing this item's own concurrency test).
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -38,31 +46,76 @@ function tryAcquire(lockPath) {
 	}
 }
 
+function timeoutMessage(lockName, timeoutMs, lockPath) {
+	return `could not acquire lock "${lockName}" within ${timeoutMs}ms (${lockPath} already exists) -- ` +
+		'another bskel process may be running against this repo, or a previous run crashed and left ' +
+		`this lock behind. If nothing else is running, remove ${lockPath} and try again.`;
+}
+
 // Runs `fn` with an exclusive lock named `lockName`, scoped to this repo. Retries acquisition
 // with a short fixed backoff until `timeoutMs` elapses, then throws with a message naming the
 // exact stale-lock path to remove -- this tool is a short-lived CLI, not a daemon, so "another
 // bskel process is stuck or crashed" is the only realistic cause, and the fix is always the same
 // (confirm nothing else is running, then delete the lock directory).
-export function withLockSync(repoRoot, lockName, fn, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+function acquireOrThrow(repoRoot, lockName, timeoutMs) {
 	const dir = locksDir(repoRoot);
 	fs.mkdirSync(dir, { recursive: true });
 	const lockPath = path.join(dir, `${lockName}.lock`);
 
 	const deadline = Date.now() + timeoutMs;
 	while (!tryAcquire(lockPath)) {
-		if (Date.now() >= deadline) {
-			throw new Error(
-				`could not acquire lock "${lockName}" within ${timeoutMs}ms (${lockPath} already exists) -- ` +
-				'another bskel process may be running against this repo, or a previous run crashed and left ' +
-				`this lock behind. If nothing else is running, remove ${lockPath} and try again.`,
-			);
-		}
+		if (Date.now() >= deadline) throw new Error(timeoutMessage(lockName, timeoutMs, lockPath));
 		sleepSync(RETRY_INTERVAL_MS);
 	}
+	return lockPath;
+}
 
+export function withLockSync(repoRoot, lockName, fn, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+	const lockPath = acquireOrThrow(repoRoot, lockName, timeoutMs);
 	try {
 		return fn();
 	} finally {
 		fs.rmSync(lockPath, { recursive: true, force: true });
 	}
 }
+
+// D-ddl-apply: the async counterpart, needed because a live DDL apply/rollback executor is
+// inherently a Promise-returning `pg` round trip.
+//
+// Deliberately does NOT reuse acquireOrThrow()'s synchronous poll loop -- a real bug found live
+// while writing this item's own concurrency test, not assumed: acquireOrThrow()'s wait step
+// (sleepSync -> Atomics.wait) BLOCKS THE ENTIRE EVENT LOOP synchronously between mkdir attempts.
+// Called from an async function, that's fatal -- while a waiter spins inside that synchronous
+// loop, nothing else on the event loop can run, INCLUDING the current lock holder's own pending
+// I/O (e.g. the `pg` query it's awaiting), so the holder can never finish and release the lock the
+// waiter is spinning for. A single-process `bskel serve` handling two concurrent requests that both
+// touch the 'state' lock would deadlock the whole server, not just wait. This async acquire loop
+// uses `await new Promise(setTimeout)` instead -- a real, non-blocking sleep that yields control
+// back to the event loop on every retry, so concurrent I/O (including the current holder's) can
+// keep making progress while this call waits its turn.
+async function acquireAsyncOrThrow(repoRoot, lockName, timeoutMs) {
+	const dir = locksDir(repoRoot);
+	fs.mkdirSync(dir, { recursive: true });
+	const lockPath = path.join(dir, `${lockName}.lock`);
+
+	const deadline = Date.now() + timeoutMs;
+	while (!tryAcquire(lockPath)) {
+		if (Date.now() >= deadline) throw new Error(timeoutMessage(lockName, timeoutMs, lockPath));
+		await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL_MS));
+	}
+	return lockPath;
+}
+
+// withLockSync's own `finally { fn() has already returned }` release timing would be WRONG for an
+// async callback: if a caller passed an async fn to withLockSync, `finally` would fire (releasing
+// the lock) the instant the Promise was RETURNED, not once it RESOLVED -- releasing the lock before
+// the actual DB write even finishes. `await fn()` inside this function's own try means `finally`
+// cannot run until the Promise settles, making that mistake structurally impossible.
+export async function withLockAsync(repoRoot, lockName, fn, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+	const lockPath = await acquireAsyncOrThrow(repoRoot, lockName, timeoutMs);
+	try {
+		return await fn();
+	} finally {
+		fs.rmSync(lockPath, { recursive: true, force: true });
+	}
+}

package/lib/patch-kinds.mjs

@@ -0,0 +1,52 @@
+// D-ddl-apply: the single, shared per-kind dispatch table for lib/patch-transactions.mjs's
+// propose/approve/apply/rollback lifecycle -- imported by both bin/bskel.mjs (CLI) and
+// lib/http-server.mjs (the new DDL routes), so there is exactly one copy of "which planner/
+// executor goes with which kind" (matching D-http-serving-layer's own "no second copy of business
+// logic" rule). Before this module existed, bin/bskel.mjs's cmdPatchPropose and
+// replanFromTransaction both hardcoded a direct call to planConfigApply() -- this generalizes that
+// into a real lookup, without lib/patch-transactions.mjs's own engine ever importing a kind-specific
+// module or branching on `kind` itself.
+import { loadCatalogEntry } from '../stack/apply.mjs';
+import { planConfigApply, executeConfigApply, executeConfigRollback } from '../stack/config-apply.mjs';
+import { planDdlApply, executeDdlApply, executeDdlRollback, requiredConfirmValue } from '../scanners/db/ddl-apply.mjs';
+
+const PATCH_KINDS = {
+	'config-apply': {
+		// params: {choice, target}. planFresh loads the catalog entry itself (never trusts a stored
+		// plan) so a catalog change is caught here too, not just by the engine's own region_hash
+		// TOCTOU check.
+		planFresh: (root, params) => planConfigApply(root, loadCatalogEntry(params.choice), params.target),
+		paramsFromTxn: (txn) => ({ choice: txn.source.choice, target: txn.target.file }),
+		apply: executeConfigApply,
+		rollback: executeConfigRollback,
+		// null == no confirm required at all -- config-apply never has, unchanged.
+		requiredConfirmValue: () => null,
+	},
+	'ddl-apply': {
+		// params: {databaseUrlEnv, schema, sqlText}.
+		planFresh: (root, params) => planDdlApply(root, params),
+		paramsFromTxn: (txn) => ({ databaseUrlEnv: txn.source.database_url_env, schema: txn.source.schema, sqlText: txn.target.sql_text }),
+		apply: executeDdlApply,
+		rollback: executeDdlRollback,
+		// transaction id for a non-drop transaction; the sorted, comma-joined dropped-table name(s)
+		// for one that drops a table -- see requiredConfirmValue()'s own comment for why.
+		requiredConfirmValue,
+	},
+};
+
+export const PATCH_KIND_NAMES = Object.freeze(Object.keys(PATCH_KINDS));
+
+export function getPatchKind(kind) {
+	const entry = PATCH_KINDS[kind];
+	if (!entry) throw new Error(`unknown patch-transaction kind "${kind}" -- known kinds: ${PATCH_KIND_NAMES.join(', ')}`);
+	return entry;
+}
+
+// Re-runs the SAME kind's planner fresh from the transaction's own recorded source/target --
+// never trusts the stored plan -- so a stale preimage (the target moved since propose/approve) is
+// caught by the engine's own region_hash comparison, AND the underlying reference (a catalog
+// choice; a live DB connection) is re-validated as still resolving at all, in case IT changed.
+export async function replanTransaction(root, txn) {
+	const kind = getPatchKind(txn.kind);
+	return kind.planFresh(root, kind.paramsFromTxn(txn));
+}

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