backend-skeleton 1.5.0 → 1.7.0

package/lib/attest.mjs

@@ -4,7 +4,7 @@
 // sign, and verify a JSON payload -- it has no opinion about WHERE a key lives (bin/bskel.mjs's
 // `--key`/`--pubkey` flags are the only interface, per the user's own explicit choice to reject a
 // new home-directory key-storage convention for this slice -- see DECISIONS.md).
-import { generateKeyPairSync, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { generateKeyPairSync, createPublicKey, createHash, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
 import { sortKeysDeep } from './gates.mjs';
 
 export function generateKeypair() {
@@ -15,6 +15,13 @@ export function generateKeypair() {
 	};
 }
 
+// D-attestation-payload-completeness (K1): the named canonicalization algorithm this module
+// implements -- recorded in a signed payload's own `tool.canonicalization` field so a verifier on
+// a future bskel build can tell whether it's speaking the same dialect. Kept as `sortkeysdeep-json`
+// forever (never silently redefined) -- see K1 in DECISIONS.md for why RFC 8785/JCS was considered
+// and rejected for this codebase's value space.
+export const CANONICALIZATION_ID = 'sortkeysdeep-json';
+
 // Deep-sorted, whitespace-free JSON -- the ONLY thing that's ever actually signed/verified.
 // Reusing lib/gates.mjs's own sortKeysDeep() (already proven correct via every gate's `inputs`
 // field) rather than a second, possibly-subtly-different implementation.
@@ -22,7 +29,58 @@ export function canonicalize(value) {
 	return JSON.stringify(sortKeysDeep(value));
 }
 
+// D-attestation-payload-completeness (K1): fail-closed guard, called ONLY from signPayload() --
+// verifyPayload() keeps its shipped never-throws contract. A NaN/Infinity/undefined/BigInt/Date/
+// function/symbol reaching JSON.stringify would silently serialize to something other than
+// itself (or be dropped entirely) -- signing that payload would be signing a lie about what the
+// value actually was. Walks the value with the exact JSON path of the first offending node in the
+// thrown message, so a caller can find it without a second investigation.
+export function assertCanonicalizable(value, jsonPath = '$') {
+	if (value === null) return;
+	const t = typeof value;
+	if (t === 'string' || t === 'boolean') return;
+	if (t === 'number') {
+		if (!Number.isFinite(value)) throw new Error(`assertCanonicalizable: ${jsonPath} is ${Number.isNaN(value) ? 'NaN' : value}, not a finite JSON number`);
+		return;
+	}
+	if (t === 'undefined') throw new Error(`assertCanonicalizable: ${jsonPath} is undefined`);
+	if (t === 'bigint') throw new Error(`assertCanonicalizable: ${jsonPath} is a BigInt, which JSON.stringify cannot represent`);
+	if (t === 'function') throw new Error(`assertCanonicalizable: ${jsonPath} is a function`);
+	if (t === 'symbol') throw new Error(`assertCanonicalizable: ${jsonPath} is a symbol`);
+	if (Array.isArray(value)) {
+		value.forEach((item, i) => assertCanonicalizable(item, `${jsonPath}[${i}]`));
+		return;
+	}
+	// t === 'object' from here -- reject anything whose prototype isn't a plain object (Date, Map,
+	// Set, a class instance, ...): JSON.stringify would silently call .toJSON() or drop it instead
+	// of representing its real shape.
+	const proto = Object.getPrototypeOf(value);
+	if (proto !== Object.prototype && proto !== null) {
+		throw new Error(`assertCanonicalizable: ${jsonPath} is a non-plain object (${value?.constructor?.name ?? 'unknown'}), not a plain {} or []`);
+	}
+	for (const [key, v] of Object.entries(value)) assertCanonicalizable(v, `${jsonPath}.${key}`);
+}
+
+// D-attestation-payload-completeness (K6): 'ed25519:<32 hex chars>' -- sha256 over the public
+// key's SPKI DER bytes, first 16 bytes hex-encoded. A SELECTION HINT for `attest verify`'s error
+// message, never a trust claim: it lives OUTSIDE the signed bytes (only `report` is signed), so it
+// is exactly as attacker-modifiable as any other envelope field. See K6 in DECISIONS.md.
+function keyIdFromDer(der) {
+	return `ed25519:${createHash('sha256').update(der).digest('hex').slice(0, 32)}`;
+}
+
+export function publicKeyIdFromPublic(publicKeyPem) {
+	const der = createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+	return keyIdFromDer(der);
+}
+
+export function publicKeyIdFromPrivate(privateKeyPem) {
+	const der = createPublicKey(privateKeyPem).export({ type: 'spki', format: 'der' });
+	return keyIdFromDer(der);
+}
+
 export function signPayload(payload, privateKeyPem) {
+	assertCanonicalizable(payload);
 	const canonical = canonicalize(payload);
 	return cryptoSign(null, Buffer.from(canonical), privateKeyPem).toString('base64');
 }

package/lib/cli.mjs

@@ -84,13 +84,16 @@ export const COMMANDS = {
 	},
 	// D-gate-export: unlike `gate show`, always feature-scoped -- the whole point is one feature's
 	// own evidence trail across all 5 gates, not a single gate/repo-level snapshot.
+	// D-attestation-payload-completeness (K4): --allow-dirty only has an effect together with
+	// --sign (bskel gate export enforces this itself -- see cmdGateExport's own BAD_ARGS check).
 	'gate export': {
-		usage: 'bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath>] [--json]',
+		usage: 'bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath> [--allow-dirty]] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			out: { type: 'string', default: null },
 			sign: { type: 'boolean', default: false },
 			key: { type: 'string', default: null },
+			'allow-dirty': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -103,11 +106,16 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-attestation-payload-completeness (K5): three OPT-IN, default-off assertions, evaluated
+	// purely against fields already inside the (offline, repo-independent) report.
 	'attest verify': {
-		usage: 'bskel attest verify --file <path> --pubkey <path> [--json]',
+		usage: 'bskel attest verify --file <path> --pubkey <path> [--expect-head <sha>] [--max-age-minutes N] [--reject-dirty] [--json]',
 		options: {
 			file: { type: 'string', default: null, required: true },
 			pubkey: { type: 'string', default: null, required: true },
+			'expect-head': { type: 'string', default: null },
+			'max-age-minutes': { type: 'string', default: null, numeric: { min: 0 } },
+			'reject-dirty': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -179,6 +187,20 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke` -- removes the
+	// waiver entry (its absence is the state) and appends a `withdraw` decision event. Never a
+	// snapshot restore.
+	'scan cross-feature-unwaive': {
+		usage: 'bskel scan cross-feature-unwaive --feature <id> --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			signal: { type: 'string', default: null, required: true },
+			identifier: { type: 'string', default: null, required: true },
+			'other-feature': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'feature init': {
 		usage: 'bskel feature init --slug <name>',
 		options: { slug: { type: 'string', default: null, required: true } },
@@ -291,6 +313,20 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke` -- removes the
+	// waiver entry (its absence is the state) and appends a `withdraw` decision event. Never a
+	// snapshot restore (the entry's prior reason/expiry is preserved only in the decision log, not
+	// restorable through this command).
+	'contract unwaive': {
+		usage: 'bskel contract unwaive --feature <id> --code <CODE> --subject "VERB /path" --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			code: { type: 'string', default: null, required: true },
+			subject: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'contract validate': {
 		usage: 'bskel contract validate --feature <id> --file <envelope.json>',
 		options: {
@@ -339,6 +375,72 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-cross-feature-impact-graph: `check` is read-mostly (writes impact-report.json, never
+	// advances the baseline); `accept` is the only command that advances impact-baseline.json, and
+	// refuses (exit 3) if any proven outbound impact is undisposed or inbound migration
+	// unacknowledged. `--all` (check only) sweeps every active feature -- the only thing that closes
+	// the brand-new-counterparty narrowing gap the `impact` gate's own recompute() accepts (see D4/D7
+	// in DECISIONS.md).
+	'impact check': {
+		usage: 'bskel impact check (--feature <id> | --all) [--json]',
+		options: {
+			feature: { type: 'string', default: null },
+			all: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'impact accept': {
+		usage: 'bskel impact accept --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-cross-feature-impact-graph (D6): three modes, three mechanically different consequences --
+	// `migrate` requires --tracked-by, `waive` requires --expires-days. `compatible` needs neither.
+	// D-decision-event-log (D6): --withdraw is a flag variant of this same command, not a separate
+	// subcommand -- a withdrawal needs no --mode, so `mode` is NOT `required: true` at the parse
+	// layer (recordDisposition() itself still refuses a missing/invalid mode on the record path --
+	// see cmdImpactDisposition's own comment for why this split is deliberate).
+	'impact disposition': {
+		usage: 'bskel impact disposition --feature <id> --change <change_key> --downstream <id> (--mode compatible|migrate|waive [--tracked-by "<ref>"] [--expires-days <N>] | --withdraw) --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			change: { type: 'string', default: null, required: true },
+			downstream: { type: 'string', default: null, required: true },
+			mode: { type: 'string', default: null },
+			reason: { type: 'string', default: '' },
+			'tracked-by': { type: 'string', default: null },
+			'expires-days': { type: 'string', default: null, numeric: { min: 1 } },
+			withdraw: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'impact ack': {
+		usage: 'bskel impact ack --feature <id> --from <upstream_id> --change <change_key> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			from: { type: 'string', default: null, required: true },
+			change: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-cross-feature-impact-graph (IG8): the one LLM-free seam to the exploration layer -- `--format
+	// graphify` writes graphify's own native extraction file shape directly (bypassing its own
+	// install/detect/extract steps), `--format json` writes the raw sbf.impact-graph/1 document,
+	// `--format mermaid` mirrors `bskel db erd`'s own posture. `--focus`/`--rings` implement IG9's
+	// Focus+Context data projection (ring/detail), written only into the export, never read back by
+	// any gate.
+	'impact export': {
+		usage: 'bskel impact export --format graphify|json|mermaid [--out <path>] [--focus <node-id>] [--rings <N>]',
+		options: {
+			format: { type: 'string', default: null, required: true },
+			out: { type: 'string', default: null },
+			focus: { type: 'string', default: null },
+			rings: { type: 'string', default: null, numeric: { min: 0 } },
+		},
+	},
 	// D-business-rules: `check` compiles + verifies + establishes the `rules` gate; `list`/`explain`
 	// are read-only. `--init` writes a starter rules.yaml only when none exists (never overwrites).
 	'rules check': {
@@ -576,26 +678,42 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke` -- removes the
+	// approval entry (its absence is the state) and appends a `withdraw` decision event. Never a
+	// snapshot restore.
+	'handles patch unapprove': {
+		usage: 'bskel handles patch unapprove --feature <id> --resource <Type> --field <name> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			resource: { type: 'string', default: null, required: true },
+			field: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	// D-patch-transactions: content-addressed patch transactions, Slice 1 (config_check ->
 	// config_apply). `propose`/`approve` only touch specs/, so no --force escape exists on either --
 	// re-propose is the only remediation for a stale target. `rollback` alone gets --force (reverting
 	// to a known-good, git-recoverable prior state is materially lower-risk than forcing a forward
 	// edit whose collateral effects were never re-verified).
 	'patch propose': {
-		usage: 'bskel patch propose --feature <id> [--kind config-apply --choice <stackChoiceId> --target <config_check target path> | --kind ddl-apply --database-url-env <NAME> --sql-file <path> [--schema public]] [--json]',
+		usage: 'bskel patch propose --feature <id> [--kind config-apply --choice <stackChoiceId> --target <config_check target path> | --kind ddl-apply --database-url-env <NAME> --sql-file <path> [--schema public] | --kind java-source-splice --splice-file <path>] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			// D-ddl-apply: default 'config-apply' -- omitting --kind entirely is byte-identical to
-			// this project's prior behavior. choice/target/database-url-env/sql-file are validated
-			// by hand inside cmdPatchPropose (kind-conditional requirements aren't expressible via
-			// this table's own unconditional `required: true`), matching this file's existing
-			// convention for kind-conditional flags (e.g. --reason on approve/rollback).
+			// this project's prior behavior. choice/target/database-url-env/sql-file/splice-file are
+			// validated by hand inside cmdPatchPropose (kind-conditional requirements aren't
+			// expressible via this table's own unconditional `required: true`), matching this file's
+			// existing convention for kind-conditional flags (e.g. --reason on approve/rollback).
 			kind: { type: 'string', default: 'config-apply' },
 			choice: { type: 'string', default: null },
 			target: { type: 'string', default: null },
 			'database-url-env': { type: 'string', default: null },
 			schema: { type: 'string', default: 'public' },
 			'sql-file': { type: 'string', default: null },
+			// D-java-source-splice: a JSON request document, not raw text like --sql-file -- a method
+			// body cannot live in a shell flag, and the edit list itself needs real structure.
+			'splice-file': { type: 'string', default: null },
 			json: { type: 'boolean', default: false },
 		},
 	},

package/lib/decision-log.mjs

@@ -0,0 +1,58 @@
+// D-decision-event-log: an append-only audit trail for the four spec-side decision files
+// (contract waivers, cross-feature waivers, impact dispositions, patch approvals) -- mirrors
+// lib/state.mjs's appendGateEvent()/readGateHistory() shape exactly (same file family, same
+// schema-validated-JSONL contract, same corrupt-line-is-skipped-not-fatal resilience). A sibling
+// to .sbf/<featureId>.history.jsonl, not a replacement for it -- gates keep their own log.
+//   WHY: F2 (found during this item's own grounding) -- all four decision files silently
+//   OVERWRITE the prior decision (reason/actor/timestamp) on re-decision, and none of the four had
+//   any retraction command. `gate revoke` is the only retraction primitive in the whole tool.
+//   COST: one more .sbf/ file per feature. Machine-local, gitignored-by-convention -- this log is
+//   NOT tamper-evident on its own (see schemas/decision-event.schema.json's own description);
+//   its evidentiary value comes from being rolled into a SIGNED gate-export attestation.
+//   EXIT: no cross-feature aggregate view; per-feature only, matching gate history's own scoping.
+import fs from 'node:fs';
+import { sbfDir } from './state.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+
+export function decisionLogPath(repoRoot, featureId) {
+	return `${sbfDir(repoRoot)}/${featureId}.decisions.jsonl`;
+}
+
+// Called from inside the SAME withLockSync(root, 'state', ...) each of the four write paths
+// already holds -- never opens its own lock, so the decision write and the log append can never
+// observe each other out of order (same discipline setGate() already applies to gate writes).
+export function appendDecisionEvent(repoRoot, featureId, event) {
+	const line = { schema: 'sbf.decision-event/1', ...event };
+	const { ok, errors } = validateAgainstSchema('decision-event.schema.json', line);
+	if (!ok) {
+		throw new Error(`refusing to append an invalid decision event for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	fs.mkdirSync(sbfDir(repoRoot), { recursive: true });
+	fs.appendFileSync(decisionLogPath(repoRoot, featureId), `${JSON.stringify(line)}\n`);
+}
+
+// Mirrors lib/gate-export.mjs's readGateHistory() resilience contract exactly: a corrupt/invalid
+// line is skipped with a warning, never a hard failure.
+export function readDecisionLog(repoRoot, featureId, { kind = null, onWarning } = {}) {
+	const file = decisionLogPath(repoRoot, featureId);
+	if (!fs.existsSync(file)) return [];
+	const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+	const events = [];
+	for (const [i, line] of lines.entries()) {
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			onWarning?.(`${file}:${i + 1}: not valid JSON, skipped`);
+			continue;
+		}
+		const { ok, errors } = validateAgainstSchema('decision-event.schema.json', parsed);
+		if (!ok) {
+			onWarning?.(`${file}:${i + 1}: does not match schemas/decision-event.schema.json, skipped`, errors);
+			continue;
+		}
+		if (kind && parsed.kind !== kind) continue;
+		events.push(parsed);
+	}
+	return events;
+}

package/lib/doctor.mjs

@@ -94,6 +94,28 @@ function astHelperCheck() {
 	};
 }
 
+// D-java-source-splice: combines the two real prerequisites `bskel patch propose --kind
+// java-source-splice` needs beyond the base install -- the AST helper (reuses
+// detectAstHelperAvailable(), same function astHelperCheck() and the real command both call, so
+// this can never disagree with them) AND a recognized build command (detectBuildCommand()) to run
+// the compile postcondition against. Either missing means the whole kind is unusable, so this
+// check fails if EITHER is unavailable, naming which one(s).
+function javaSourceSpliceCheck(root) {
+	const ast = detectAstHelperAvailable();
+	const build = root ? detectBuildCommand(root) : null;
+	const ok = ast.available && build !== null;
+	const missing = [];
+	if (!ast.available) missing.push(`AST helper (${ast.reason})`);
+	if (!build) missing.push('a recognized build command (gradlew/pom.xml/package.json)');
+	return {
+		name: 'java-source-splice prerequisites',
+		required: false,
+		ok,
+		detail: ok ? `ready (build tool: ${build.tool})` : missing.join('; '),
+		remediation: ok ? null : `${missing.join('; ')} -- only needed for \`bskel patch propose --kind java-source-splice\`, never for the base install.`,
+	};
+}
+
 // D5: sourced from stack/catalog/*.yml's own `runtime.requires` field (schemas/stack-choice.
 // schema.json) rather than a hardcoded ["curl", "ngrok"] list here -- a future catalog entry
 // declares its own runtime binaries and doctor picks them up with zero code changes, the same
@@ -187,6 +209,7 @@ export function computeDoctorChecks(root, { workflow = null } = {}) {
 	}
 	if (workflow === null || workflow === 'handles') {
 		checks.push(astHelperCheck());
+		checks.push(javaSourceSpliceCheck(root));
 	}
 	if (root && (workflow === null || workflow === 'stack')) {
 		checks.push(...stackToolChecks(root));

package/lib/exit-codes.mjs

@@ -39,6 +39,23 @@ export const EXIT_CODES = Object.freeze({
 	// can find -- distinct from HANDLES_CONFLICT(15), which is about a GENERATED file diverging;
 	// this is about a hand-written file bskel never touches lacking an annotation it can't add.
 	HANDLES_REGISTRATION_GAP: 21,
+	// D-attestation-payload-completeness (K5): `attest verify`'s OPT-IN assertions (--expect-head /
+	// --max-age-minutes / --reject-dirty) failing on a document whose signature is genuinely VALID.
+	// Deliberately not a reuse of CHECK_FAILED(1): D-gate-attestation-signing's shipped contract is
+	// that exit 1 means, and only ever means, "the signature does not verify". Folding "authentic
+	// but not what you asked for" into the same number would destroy exactly the distinction that
+	// entry was written to preserve.
+	ATTESTATION_ASSERTION_FAILED: 22,
+	// D-resolver-policy-contract (PC9): `handles emit` refusing to proceed (without --force
+	// --reason) because at least one resource's fetch/patch authorization could not be safely
+	// auto-derived (see plan.mjs's derivePolicy() refusal ladder) -- an AuthorizationPolicy.java
+	// interface was still written (the human needs to see it), but nothing implements it yet, so
+	// the target app will not start once this resolver's bean is wired. Not a reuse of
+	// HANDLES_REGISTRATION_GAP(21), which is about a hand-written file lacking an annotation bskel
+	// can't add; this is about a generated file that is itself an unresolved authorization decision.
+	// Orthogonal to --enforce-registry (that axis produces 404s; this one produces 403s/boot
+	// failures) -- unconditional, not gated on enforceRegistry.
+	HANDLES_UNRESOLVED_POLICY: 23,
 });
 
 // `reason` values a `sbf.cli-diagnostic/1` envelope (lib/cli.mjs) can carry. Deliberately does

package/lib/gate-definitions.mjs

@@ -65,6 +65,23 @@ const OTHER_FEATURE_CONTRACT_PREFIX = 'other_feature_contract:';
 // specifically rather than reported as a generic "stale".
 const APPLIED_TARGET_PREFIX = 'applied_target:';
 const TRANSACTION_RECORD_PREFIX = 'transaction_record:';
+// D-cross-feature-impact-graph: same OTHER_FEATURE_*_PREFIX narrowing convention as
+// `cross_feature` above -- one pair of keys per OTHER feature the LAST persisted impact-report.json
+// actually named (either as an outbound downstream or an inbound upstream), not every feature in
+// the repo. Same accepted limitation: a brand-new counterparty is only caught at the next explicit
+// `bskel impact check --all` (see D-cross-feature-impact-graph's D4/D7 in DECISIONS.md).
+const IMPACT_DOWNSTREAM_DEPS_PREFIX = 'impact_downstream_deps:';
+const IMPACT_UPSTREAM_RESOLUTION_PREFIX = 'impact_upstream_resolution:';
+// D-cross-feature-impact-graph: path builders duplicated here rather than imported from
+// lib/impact-surface.mjs/lib/impact.mjs -- importing either would close a real circular-import
+// loop (gate-definitions.mjs -> lib/impact.mjs -> lib/impact-graph.mjs ->
+// lib/field-dependencies.mjs -> lib/gates.mjs -> gate-definitions.mjs), the SAME tradeoff
+// TARGET_FIELD_FILE_PREFIX's own header comment above already accepts for a two-line duplication
+// rather than a real coupling. If any of these three literal filenames ever changes, this must
+// change with it.
+const impactBaselineFilePath = (root, featureId) => specPath(root, featureId, 'impact-baseline.json');
+const impactReportFilePath = (root, featureId) => specPath(root, featureId, 'impact-report.json');
+const impactResolutionFilePath = (root, featureId) => specPath(root, featureId, 'impact-resolution.json');
 
 // The preflight and stack gates are repo-scoped, not feature-scoped -- preflight runs before a
 // feature_id exists at all, and a stack choice is a project-wide decision, not per-feature.
@@ -295,6 +312,47 @@ export const GATE_DEFINITIONS = Object.freeze({
 			return inputs;
 		},
 	},
+	// D-cross-feature-impact-graph: a change to THIS feature's own public surface (operations,
+	// resources, declared-dependency fields) that a downstream feature is provably wired to, with
+	// no recorded disposition yet. Complements `dependencies` above (which blocks the DOWNSTREAM
+	// side when what it depends on moves) by blocking the UPSTREAM side -- the feature that
+	// CHANGED, which is Codex's literal ask ("the next gate identifies downstream features and
+	// requires an explicit disposition"). Deliberately NOT a hard prerequisite of `handles emit`
+	// (see D7 in DECISIONS.md, citing this repo's own real CI incident from the `cross_feature`
+	// gate's identical mistake) -- gated only at `bskel verify`.
+	//
+	// recompute() is intentionally the cheapest possible: pure sha256File() over three already-
+	// persisted files plus the SAME artifacts `contract`/`dependencies`/`scan` already hash, never
+	// lib/impact-graph.mjs's buildImpactGraph() (real work -- O(features x artifacts) file reads,
+	// kept entirely out of the fast verify/require path, only ever called from `bskel impact
+	// check`/`export`). This is also what T6 (test/gate-definitions.test.mjs) asserts: this
+	// module's own transitive import closure contains no node:http/node:child_process/pg, and
+	// calling recompute() twice over an unchanged tree returns byte-identical inputs.
+	impact: {
+		name: 'impact',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		recompute: (root, featureId) => {
+			const inputs = {
+				impact_baseline_hash: sha256File(impactBaselineFilePath(root, featureId)),
+				impact_report_hash: sha256File(impactReportFilePath(root, featureId)),
+				impact_resolution_hash: sha256File(impactResolutionFilePath(root, featureId)),
+				contract_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.schema.json`)),
+				dependencies_hash: sha256File(dependenciesPath(root, featureId)),
+				scan_report_hash: sha256File(specPath(root, featureId, 'brownfield-scan.json')),
+			};
+			const report = readJsonIfExists(impactReportFilePath(root, featureId));
+			const others = new Set([
+				...(report?.outbound ?? []).map((o) => o.downstream_feature),
+				...(report?.inbound ?? []).map((i) => i.upstream_feature),
+			]);
+			for (const other of others) {
+				inputs[`${IMPACT_DOWNSTREAM_DEPS_PREFIX}${other}`] = sha256File(dependenciesPath(root, other));
+				inputs[`${IMPACT_UPSTREAM_RESOLUTION_PREFIX}${other}`] = sha256File(impactResolutionFilePath(root, other));
+			}
+			return inputs;
+		},
+	},
 	// D-business-rules (R7): a feature's compiled business rules. Its own gate rather than a
 	// widening of `dependencies` -- the same call cross_feature/dependencies/patch_transactions/
 	// conformance each made rather than overloading a neighbour, and the two genuinely differ:
@@ -394,7 +452,12 @@ export const GATE_DEFINITIONS = Object.freeze({
 			const inputs = {};
 			for (const txn of listTransactions(root, featureId)) {
 				if (txn.status !== 'applied') continue; // only a LIVE edit is drift-risk
-				if (txn.kind === 'config-apply') {
+				// D-java-source-splice: a second filesystem-targeting kind, added to this explicit list
+				// deliberately -- NOT via a dynamic getPatchKind(txn.kind) lookup, which would make
+				// lib/gate-definitions.mjs import lib/patch-kinds.mjs and, transitively, `pg`
+				// (scanners/db/ddl-apply.mjs) into EVERY gate recomputation, the exact live-dependency-
+				// in-a-gate coupling this gate's own header comment already refuses.
+				if (txn.kind === 'config-apply' || txn.kind === 'java-source-splice') {
 					const abs = resolveWithinRoot(root, txn.target.file);
 					if (!abs) continue; // a path escaping the repo is not something this feature applied
 					inputs[`${APPLIED_TARGET_PREFIX}${txn.transaction_id}`] = sha256File(abs); // null == deleted -> stale
@@ -429,7 +492,7 @@ export const GATE_DEFINITIONS = Object.freeze({
 // test/gate-definitions.test.mjs asserts this stays exactly in sync with GATE_DEFINITIONS' own
 // key set, so a gate added to one and not the other fails loudly instead of silently vanishing
 // from `bskel verify` the way `stack` did before this module existed.
-export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'cross_feature', 'contract', 'dependencies', 'rules', 'handles', 'stack', 'patch_transactions', 'conformance']);
+export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'cross_feature', 'contract', 'dependencies', 'impact', 'rules', 'handles', 'stack', 'patch_transactions', 'conformance']);
 
 export function getGateDefinition(name) {
 	return Object.hasOwn(GATE_DEFINITIONS, name) ? GATE_DEFINITIONS[name] : null;