backend-skeleton 1.0.0-beta.9 → 1.0.0

package/scanners/db/introspect.mjs

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

package/scanners/db/migrations.mjs

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

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

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

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

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

package/schemas/gate-attestation.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:gate-attestation:1",
+  "title": "backend-skeleton signed gate attestation (bskel gate export --sign / bskel attest verify)",
+  "description": "D-gate-attestation-signing: the combined envelope `bskel gate export --sign` writes -- a gate-export report (schemas/gate-export.schema.json's own shape) plus a detached Ed25519 signature over that report's canonical (deep-key-sorted, whitespace-free) JSON serialization. Signature validity is the ONLY thing `bskel attest verify`'s exit code reflects -- whether the gates inside `report` themselves passed is a separate, printed-but-not-exit-code-driving question (a legitimately-signed, all-failing report must not look like a tool error).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "report", "signature"],
+  "properties": {
+    "schema": { "const": "sbf.gate-attestation/1" },
+    "report": { "type": "object" },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algorithm", "value"],
+      "properties": {
+        "algorithm": { "const": "ed25519" },
+        "value": { "type": "string", "description": "base64-encoded raw Ed25519 signature bytes over canonicalize(report)." }
+      }
+    }
+  }
+}

package/schemas/gate-export.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:gate-export:1",
+  "title": "backend-skeleton gate export report (bskel gate export)",
+  "description": "D-gate-attestation-signing: this schema was written FROM cmdGateExport's real, already-shipped report shape (bin/bskel.mjs) -- it did not exist before this item and the report itself is unchanged by adding it. `current` mirrors schemas/state.schema.json's own per-gate record shape exactly (the same raw, stored record getGate() returns -- status is constrained to the 3 values ever WRITTEN to disk, never the read-time-derived not_run/stale/pass (forced)). `additionalProperties` is intentionally open on `gates` itself (keyed by gate name) so this schema never needs editing when a new gate is added -- GATE_NAMES in lib/gate-definitions.mjs is the one place that list lives.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "generated_at", "git", "gates"],
+  "properties": {
+    "schema": { "const": "sbf.gate-export/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "git": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["branch", "head_sha", "dirty"],
+      "properties": {
+        "branch": { "type": ["string", "null"], "description": "lib/repo.mjs's currentBranch() -- null on failure, or the literal string \"HEAD\" for a detached HEAD (not a real branch name)." },
+        "head_sha": { "type": "string" },
+        "dirty": { "type": ["boolean", "null"], "description": "lib/repo.mjs's isDirty() -- null on failure. true covers BOTH modified tracked files and untracked files (git status --porcelain, no -uno)." }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["scope", "current", "history"],
+        "properties": {
+          "scope": { "type": "string", "description": "the resolved scope id this gate was read from -- REPO_GATE_ID (\"_repo\") for a repo-scoped gate, or the feature_id itself." },
+          "current": {
+            "anyOf": [
+              { "type": "null" },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["status", "token", "at"],
+                "properties": {
+                  "status": { "enum": ["pass", "awaiting_disposition", "revoked"] },
+                  "token": { "type": "string" },
+                  "at": { "type": "string" },
+                  "forced": { "type": "boolean" },
+                  "reason": { "type": "string" },
+                  "evidence": { "type": "object" },
+                  "inputs": { "type": "object" }
+                }
+              }
+            ]
+          },
+          "history": {
+            "type": "array",
+            "items": { "type": "object" }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/patch-transaction.schema.json

@@ -0,0 +1,182 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:patch-transaction:1",
+  "title": "backend-skeleton content-addressed patch transaction (specs/<feature_id>/patch-transactions/<transaction_id>.json)",
+  "description": "D-patch-transactions: generalizes A3/D-patch-strategy's per-{resource,field} patch-approvals.json shape into a kind-agnostic propose/approve/apply/rollback transaction. One file per transaction (not one growing array) -- each record carries a lifecycle with real state transitions and references a content-addressed rollback blob under this same feature's patch-transactions/blobs/ directory. D-ddl-apply added a second kind ('ddl-apply') -- kind-specific source/target/postcondition/apply shapes are enforced by the allOf/if-then branches below, keyed on `kind`. The config-apply branch is byte-identical to this schema's pre-D-ddl-apply shape (existing config-apply records validate unchanged).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "transaction_id", "feature_id", "kind", "source", "target", "preimage", "proposed_value", "postcondition", "status", "created_at"],
+  "properties": {
+    "schema": { "const": "sbf.patch-transaction/1" },
+    "transaction_id": { "type": "string", "pattern": "^pt-[0-9a-f-]{36}$" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "kind": { "enum": ["config-apply", "ddl-apply"] },
+    "source": {
+      "type": "object",
+      "description": "Kind-specific opaque context needed to re-plan this transaction fresh at approve/apply time. Shape enforced per-kind by the allOf/if-then branches below."
+    },
+    "target": {
+      "type": "object",
+      "description": "Kind-specific description of what this transaction acts on. Shape enforced per-kind by the allOf/if-then branches below."
+    },
+    "preimage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["region_hash", "file_hash"],
+      "properties": {
+        "region_hash": { "type": "string" },
+        "file_hash": { "type": "string" }
+      }
+    },
+    "current_value": { "type": "string" },
+    "proposed_value": { "type": "string" },
+    "postcondition": {
+      "type": "object",
+      "description": "Kind-specific re-check applied before the record is allowed to transition to 'applied'. Shape enforced per-kind by the allOf/if-then branches below."
+    },
+    "status": { "enum": ["proposed", "approved", "applied", "rolled_back"] },
+    "created_at": { "type": "string", "format": "date-time" },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason", "at"],
+      "properties": {
+        "reason": { "type": "string" },
+        "at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "apply": {
+      "type": "object",
+      "description": "Kind-specific record of what actually happened at apply time. Shape enforced per-kind by the allOf/if-then branches below."
+    },
+    "rollback": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason", "at"],
+      "properties": {
+        "reason": { "type": "string" },
+        "at": { "type": "string", "format": "date-time" },
+        "forced": { "type": "boolean" }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "kind": { "const": "config-apply" } } },
+      "then": {
+        "properties": {
+          "source": {
+            "additionalProperties": false,
+            "required": ["choice"],
+            "properties": {
+              "choice": { "type": "string" }
+            }
+          },
+          "target": {
+            "additionalProperties": false,
+            "required": ["file", "key_path"],
+            "properties": {
+              "file": { "type": "string" },
+              "key_path": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+            }
+          },
+          "postcondition": {
+            "additionalProperties": false,
+            "required": ["kind", "pattern"],
+            "properties": {
+              "kind": { "const": "regex-match" },
+              "pattern": { "type": "string" }
+            }
+          },
+          "apply": {
+            "additionalProperties": false,
+            "required": ["at", "postimage_file_hash"],
+            "properties": {
+              "at": { "type": "string", "format": "date-time" },
+              "postimage_file_hash": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "ddl-apply" } } },
+      "then": {
+        "properties": {
+          "source": {
+            "additionalProperties": false,
+            "required": ["database_url_env", "schema"],
+            "properties": {
+              "database_url_env": { "type": "string" },
+              "schema": { "type": "string" }
+            }
+          },
+          "target": {
+            "additionalProperties": false,
+            "required": ["database_url_env", "schema", "sql_text"],
+            "properties": {
+              "database_url_env": { "type": "string" },
+              "schema": { "type": "string" },
+              "sql_text": { "type": "string" }
+            }
+          },
+          "postcondition": {
+            "additionalProperties": false,
+            "required": ["kind", "schema", "expected_tables"],
+            "properties": {
+              "kind": { "const": "db-schema-diff" },
+              "schema": { "type": "string" },
+              "expected_tables": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "expect"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "expect": { "enum": ["present", "absent"] }
+                  }
+                }
+              },
+              "expected_indexes": {
+                "description": "D-ddl-apply (INDEX/SCHEMA postcondition precision): optional, not required -- absent on any ddl-apply record persisted before this field existed, and empty for a statement batch with no CREATE/DROP INDEX in it.",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "expect"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "expect": { "enum": ["present", "absent"] }
+                  }
+                }
+              },
+              "expected_schemas": {
+                "description": "D-ddl-apply (INDEX/SCHEMA postcondition precision): optional, not required -- same reasoning as expected_indexes, for CREATE/DROP SCHEMA.",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "expect"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "expect": { "enum": ["present", "absent"] }
+                  }
+                }
+              }
+            }
+          },
+          "apply": {
+            "additionalProperties": false,
+            "required": ["at", "postimage_schema_hash", "executed_statements"],
+            "properties": {
+              "at": { "type": "string", "format": "date-time" },
+              "postimage_schema_hash": { "type": "string" },
+              "executed_statements": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    }
+  ]
+}