backend-skeleton 1.4.0 → 1.6.0

package/bin/bskel.mjs

@@ -9,6 +9,7 @@ import { repoRoot, localDefaultBranch, fileHistory, showFileAtRevision, headSha,
 import { forceNamedGate, revokeNamedGate, requireNamedGate, passNamedGate, awaitNamedGateDisposition, EXIT } from '../lib/gates.mjs';
 import { REPO_GATE_ID, GATE_NAMES, gateScopeId, requireGateDefinition } from '../lib/gate-definitions.mjs';
 import { getGate, loadState, historyPath } from '../lib/state.mjs';
+import { buildGateExportReport, readGateHistory } from '../lib/gate-export.mjs';
 import { writeFileAtomic, sha256File, readJsonIfExists } from '../lib/fsutil.mjs';
 import { hydrateScanReportFilePaths, dehydrateScanReportFilePaths } from '../lib/scan-report-paths.mjs';
 import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
@@ -33,13 +34,18 @@ import { evaluateResolution, loadResolution, saveResolution, requireWarningCode,
 import { loadPatchApprovals, savePatchApprovals, approvalKey } from '../lib/patch-approvals.mjs';
 import { proposeTransaction, approveTransaction, applyTransaction, rollbackTransaction, loadTransaction, listTransactions } from '../lib/patch-transactions.mjs';
 import { getPatchKind, replanTransaction, PATCH_KIND_NAMES } from '../lib/patch-kinds.mjs';
-import { generateKeypair, signPayload, verifyPayload } from '../lib/attest.mjs';
+import { generateKeypair, signPayload, verifyPayload, publicKeyIdFromPrivate, publicKeyIdFromPublic } from '../lib/attest.mjs';
 import { loadManifest, saveManifest } from '../lib/handles-manifest.mjs';
 import { createHttpServer } from '../lib/http-server.mjs';
 import {
 	resolveClassFile, listDownstreamDependents, DependencyOperationError,
 	declareDependency, removeDependency, buildDependencyListReport,
 } from '../lib/field-dependencies.mjs';
+import {
+	ImpactOperationError, checkImpact, acceptImpact, recordDisposition, acknowledgeInbound,
+} from '../lib/impact.mjs';
+import { buildImpactGraph } from '../lib/impact-graph.mjs';
+import { toGraphifyExtraction, toMermaid } from '../lib/impact-export-graphify.mjs';
 import {
 	findCollisions, evaluateCrossFeatureFindings, waiverKey,
 	crossFeatureReportPath, loadCrossFeatureReport, loadCrossFeatureResolution, saveCrossFeatureResolution,
@@ -114,6 +120,11 @@ function usage() {
   bskel dependency declare --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--memo "..."]
   bskel dependency remove --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."
   bskel dependency list --feature <id> [--json]
+  bskel impact check --feature <id> [--all] [--json]
+  bskel impact accept --feature <id> [--json]
+  bskel impact disposition --feature <id> --change <change_key> --downstream <id> --mode <compatible|migrate|waive> --reason "..." [--tracked-by "..."] [--expires-days <N>] [--json]
+  bskel impact ack --feature <id> --from <id> --change <change_key> --reason "..." [--json]
+  bskel impact export --format <graphify|json|mermaid> [--out <path>] [--focus <id>] [--rings <N>]
   bskel rules check --feature <id> [--init] [--json]
   bskel rules list --feature <id> [--json]
   bskel rules explain --feature <id> --rule <id> [--json]
@@ -124,7 +135,7 @@ function usage() {
   bskel handles emit --feature <id> [--module <name>] [--resource type1,type2] [--force --reason "..."] [--check] [--diff] [--enforce-registry on|off --reason "..."]
   bskel handles patch approve --feature <id> [--module <name>] --resource <Type> --field <name> --strategy patch-wrapper|null-means-unchanged --reason "..." [--json]
   bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--module <name>] [--check-registry-coverage] [--json]
-  bskel patch propose --feature <id> [--kind config-apply|ddl-apply] --choice <stackChoiceId> --target <config_check target path> --database-url-env <NAME> --schema <name> --sql-file <path> [--json]
+  bskel patch propose --feature <id> [--kind config-apply|ddl-apply|java-source-splice] --choice <stackChoiceId> --target <config_check target path> --database-url-env <NAME> --schema <name> --sql-file <path> --splice-file <path> [--json]
   bskel patch approve --feature <id> --transaction <id> --reason "..." [--json]
   bskel patch apply --feature <id> --transaction <id> [--confirm <id-or-dropped-table-name>] [--json]
   bskel patch rollback --feature <id> --transaction <id> --reason "..." [--force] [--json]
@@ -139,9 +150,9 @@ function usage() {
   bskel gate revoke <name> --reason "..." [--feature <id>]
   bskel gate history <name> [--feature <id>] [--json]
   bskel gate show [<name>] [--feature <id>]
-  bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath>] [--json]
+  bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath> [--allow-dirty]] [--json]
   bskel attest keygen --out <dir> [--force] [--json]
-  bskel attest verify --file <path> --pubkey <path> [--json]
+  bskel attest verify --file <path> --pubkey <path> [--expect-head <sha>] [--max-age-minutes N] [--reject-dirty] [--json]
   bskel doctor [--workflow ${DOCTOR_WORKFLOWS.join('|')}] [--json]
   bskel serve [--port N] [--host <addr>] [--database-url-env <NAME>] [--schema <name>] [--sign-key <path>] [--require-sign-key] [--json]
 `);
@@ -352,32 +363,6 @@ function cmdGateRevoke(args) {
 	process.exit(EXIT_CODES.NOT_PASSED);
 }
 
-// S4 (D-gate-history): reads the append-only .sbf/<feature>.history.jsonl -- a corrupt/invalid
-// line is skipped with a warning, not a hard failure, matching JSONL's own resilience rationale
-// (see lib/state.mjs's appendGateEvent).
-function readGateHistory(root, featureId, gateName) {
-	const file = historyPath(root, 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 {
-			console.error(`warning: ${file}:${i + 1}: not valid JSON, skipped`);
-			continue;
-		}
-		const { ok, errors } = validateAgainstSchema('gate-event.schema.json', parsed);
-		if (!ok) {
-			console.error(`warning: ${file}:${i + 1}: does not match schemas/gate-event.schema.json, skipped:\n${formatSchemaErrors(errors).join('\n')}`);
-			continue;
-		}
-		if (parsed.gate === gateName) events.push(parsed);
-	}
-	return events;
-}
-
 function cmdGateHistory(args) {
 	const flags = parseCommand('gate history', args);
 	if (flags.help) { console.log(renderCommandHelp('gate history')); process.exit(0); }
@@ -386,7 +371,11 @@ function cmdGateHistory(args) {
 	const gateName = flags._[0];
 	if (!gateName) fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'usage: bskel gate history <name> [--feature <id>] [--json]');
 	resolveGateArg(gateName, flags.feature);
-	const events = readGateHistory(root, flags.feature, gateName);
+	// S4 (D-gate-history): a corrupt/invalid history line is skipped with a warning, not a hard
+	// failure, matching JSONL's own resilience rationale (see lib/state.mjs's appendGateEvent).
+	const events = readGateHistory(root, flags.feature, gateName, {
+		onWarning: (msg, errors) => console.error(`warning: ${msg}${errors ? `:\n${formatSchemaErrors(errors).join('\n')}` : ''}`),
+	});
 	if (flags.json) {
 		console.log(JSON.stringify(events, null, 2));
 	} else if (events.length === 0) {
@@ -439,20 +428,15 @@ function cmdGateExport(args) {
 	if (flags.key && !flags.sign) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--key only has an effect together with --sign');
 	}
-
-	const gates = {};
-	for (const name of GATE_NAMES) {
-		const scopeId = gateScopeId(name, flags.feature);
-		gates[name] = { scope: scopeId, current: getGate(root, scopeId, name), history: readGateHistory(root, scopeId, name) };
+	// D-attestation-payload-completeness (K4): --allow-dirty only means something alongside --sign
+	// -- an unsigned export never refuses a dirty tree (unchanged behavior), so a bare --allow-dirty
+	// would otherwise be a silently-ignored flag, the exact failure mode D-cli-contract already
+	// refuses everywhere else.
+	if (flags['allow-dirty'] && !flags.sign) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--allow-dirty only has an effect together with --sign -- an unsigned gate export never refuses a dirty tree');
 	}
 
-	const report = {
-		schema: 'sbf.gate-export/1',
-		feature_id: flags.feature,
-		generated_at: new Date().toISOString(),
-		git: { branch: currentBranch(root), head_sha: headSha(root), dirty: isDirty(root) },
-		gates,
-	};
+	const report = buildGateExportReport(root, flags.feature, { dirtyAcknowledged: Boolean(flags['allow-dirty']) });
 	// D-gate-attestation-signing: validated unconditionally, signed or not -- a document that can
 	// be exported unsigned should be exactly as trustworthy in shape as one that gets signed later.
 	{
@@ -464,6 +448,20 @@ function cmdGateExport(args) {
 
 	let payload = report;
 	if (flags.sign) {
+		// D-attestation-payload-completeness (K4): refuses to sign over a dirty working tree unless
+		// explicitly acknowledged -- direct reuse of scripts/preflight-base-ref.sh's own already-
+		// shipped --allow-dirty convention (same flag name, same DIRTY exit code, same reasoning: "so
+		// evidence can honestly distinguish 'clean tree, passed' from 'dirty tree, --allow-dirty
+		// overrode it'"). Signing is a strictly stronger claim than preflighting, so it cannot be
+		// laxer. `report.git.dirty === true` is checked specifically, not truthiness -- isDirty()
+		// (and therefore this field) can be `null` when git itself failed, and "we could not
+		// determine dirtiness" must not silently pass this refusal.
+		if (report.git.dirty === null) {
+			fail(EXIT_CODES.DIRTY, 'DIRTY', 'refusing to sign an attestation: could not determine whether the working tree is dirty (git status failed) -- fix the git error, or pass --allow-dirty to sign anyway.');
+		}
+		if (report.git.dirty === true && !flags['allow-dirty']) {
+			fail(EXIT_CODES.DIRTY, 'DIRTY', `refusing to sign an attestation over a dirty working tree (${report.git.dirty_file_count} uncommitted change(s)) -- commit/stash them, or pass --allow-dirty to sign anyway (the acknowledgement is recorded inside the signed payload). The same refusal \`bskel preflight\` already makes.`);
+		}
 		let privateKeyPem;
 		try {
 			privateKeyPem = fs.readFileSync(path.resolve(process.cwd(), flags.key), 'utf8');
@@ -471,12 +469,14 @@ function cmdGateExport(args) {
 			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read --key "${flags.key}": ${err.message}`);
 		}
 		let signatureValue;
+		let keyId;
 		try {
 			signatureValue = signPayload(report, privateKeyPem);
+			keyId = publicKeyIdFromPrivate(privateKeyPem);
 		} catch (err) {
 			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--key "${flags.key}" is not a usable Ed25519 private key: ${err.message}`);
 		}
-		const attestation = { schema: 'sbf.gate-attestation/1', report, signature: { algorithm: 'ed25519', value: signatureValue } };
+		const attestation = { schema: 'sbf.gate-attestation/1', report, signature: { algorithm: 'ed25519', value: signatureValue, key_id: keyId } };
 		const { ok, errors } = validateAgainstSchema('gate-attestation.schema.json', attestation);
 		if (!ok) {
 			fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `internal error: the computed gate attestation failed its own schema -- ${formatSchemaErrors(errors).join('; ')}`);
@@ -489,9 +489,11 @@ function cmdGateExport(args) {
 		const outPath = path.resolve(process.cwd(), flags.out);
 		writeFileAtomic(outPath, rendered);
 		if (!flags.quiet) {
-			const passCount = GATE_NAMES.filter((n) => gates[n].current?.status === 'pass').length;
+			const passCount = report.verdict.passing;
 			const signedNote = flags.sign ? ' (signed)' : '';
-			console.log(`wrote ${flags.out}${signedNote} -- ${passCount}/${GATE_NAMES.length} gate(s) currently passing, ${report.git.branch}@${report.git.head_sha?.slice(0, 12) ?? '(unknown)'}${report.git.dirty ? ' (dirty)' : ''}`);
+			const dirtyNote = report.git.dirty ? (report.git.dirty_acknowledged ? ', dirty (acknowledged)' : ', dirty') : '';
+			const blockingNote = report.verdict.blocking_gates.length > 0 ? ` -- blocking: ${report.verdict.blocking_gates.join(', ')}` : '';
+			console.log(`wrote ${flags.out}${signedNote} -- ${passCount}/${GATE_NAMES.length} gate(s) currently passing, ${report.git.branch}@${report.git.head_sha?.slice(0, 12) ?? '(unknown)'}${dirtyNote}${blockingNote}`);
 		}
 	} else {
 		console.log(rendered);
@@ -562,13 +564,64 @@ function cmdAttestVerify(args) {
 	const valid = verifyPayload(attestation.report, attestation.signature.value, publicKeyPem);
 	const passCount = GATE_NAMES.filter((n) => attestation.report.gates[n]?.current?.status === 'pass').length;
 
+	// D-attestation-payload-completeness (K5): three OPT-IN, default-off assertions, evaluated
+	// purely against fields already inside the report (so verification stays fully offline and
+	// repo-independent). They exist for both sbf.gate-export/1 and /2 reports -- head_sha/
+	// generated_at/dirty are unchanged fields from /1, nothing here needed a /2-only field.
+	const assertions = [];
+	if (flags['expect-head']) {
+		const actual = attestation.report.git?.head_sha ?? null;
+		const ok = actual === flags['expect-head'];
+		assertions.push({ name: 'expect-head', ok, detail: ok ? `head_sha matches ${flags['expect-head']}` : `report's head_sha is "${actual}", expected "${flags['expect-head']}"` });
+	}
+	const maxAgeMinutes = flags['max-age-minutes'] != null ? Number(flags['max-age-minutes']) : 0;
+	if (maxAgeMinutes > 0) {
+		const generatedAtMs = Date.parse(attestation.report.generated_at);
+		const ageSeconds = Number.isFinite(generatedAtMs) ? Math.max(0, Math.round((Date.now() - generatedAtMs) / 1000)) : null;
+		const ok = ageSeconds !== null && ageSeconds <= maxAgeMinutes * 60;
+		assertions.push({ name: 'max-age-minutes', ok, detail: ageSeconds === null ? `report's generated_at ("${attestation.report.generated_at}") is not a parseable timestamp` : `age ${ageSeconds}s, limit ${maxAgeMinutes * 60}s` });
+	}
+	if (flags['reject-dirty']) {
+		const dirty = attestation.report.git?.dirty ?? null;
+		const ok = dirty !== true;
+		assertions.push({ name: 'reject-dirty', ok, detail: ok ? 'report is not dirty' : 'report.git.dirty === true' });
+	}
+	const assertionsOk = assertions.every((a) => a.ok);
+
+	// D-attestation-payload-completeness (K6): key_id is a SELECTION HINT only -- it sits OUTSIDE
+	// the signed bytes (only `report` is signed), so it cannot change whether `valid` is true. It
+	// exists purely to make a wrong---pubkey mistake legible instead of an unexplained INVALID.
+	let keyIdNote = null;
+	if (attestation.signature.key_id) {
+		try {
+			const actualKeyId = publicKeyIdFromPublic(publicKeyPem);
+			if (attestation.signature.key_id !== actualKeyId) {
+				keyIdNote = `this attestation declares key_id ${attestation.signature.key_id}, but --pubkey is ${actualKeyId} -- you may have the wrong public key`;
+			}
+		} catch {
+			// A --pubkey that isn't even a parseable key already drives verifyPayload() to false
+			// above; nothing more useful to say here.
+		}
+	}
+	const legacyReport = attestation.report.schema === 'sbf.gate-export/1';
+
 	if (flags.json) {
-		console.log(JSON.stringify({ valid, report_summary: { feature_id: attestation.report.feature_id, generated_at: attestation.report.generated_at, gates_passing: `${passCount}/${GATE_NAMES.length}` } }, null, 2));
+		console.log(JSON.stringify({
+			valid,
+			report_format: attestation.report.schema ?? 'sbf.gate-export/1',
+			report_summary: { feature_id: attestation.report.feature_id, generated_at: attestation.report.generated_at, gates_passing: `${passCount}/${GATE_NAMES.length}` },
+			assertions,
+			key_id_note: keyIdNote,
+		}, null, 2));
 	} else if (!flags.quiet) {
 		console.log(valid ? 'VALID: this attestation was genuinely signed by the holder of the matching private key' : 'INVALID: signature does not match this report + public key');
+		if (legacyReport) console.log('report format: sbf.gate-export/1 (pre-D-attestation-payload-completeness -- no tool version, no live gate verdict)');
+		if (keyIdNote) console.log(`note: ${keyIdNote}`);
 		console.log(`report says: feature ${attestation.report.feature_id}, ${passCount}/${GATE_NAMES.length} gate(s) passing, generated ${attestation.report.generated_at}`);
+		for (const a of assertions) console.log(`assertion ${a.name}: ${a.ok ? 'ok' : 'FAILED'} -- ${a.detail}`);
 	}
-	process.exit(valid ? EXIT_CODES.OK : EXIT_CODES.CHECK_FAILED);
+	if (!valid) process.exit(EXIT_CODES.CHECK_FAILED);
+	process.exit(assertionsOk ? EXIT_CODES.OK : EXIT_CODES.ATTESTATION_ASSERTION_FAILED);
 }
 
 // Structural enforcement of "preflight blocks everything below it" (see the workflow table in
@@ -2026,6 +2079,143 @@ function cmdDependencyList(args) {
 	process.exit(0);
 }
 
+// D-cross-feature-impact-graph: `bskel impact check` -- read-mostly, never advances the baseline.
+// `--all` sweeps every active feature; this is the only thing that closes the `impact` gate's own
+// counterparty-narrowing limitation (a brand-new downstream feature is otherwise only caught at the
+// next explicit check, see D4/D7 in DECISIONS.md) -- the recommended CI invocation.
+function cmdImpactCheck(args) {
+	const flags = parseCommand('impact check', args);
+	if (flags.help) { console.log(renderCommandHelp('impact check')); process.exit(0); }
+	setContext('impact check', flags);
+	const root = requireRepoRoot();
+	if (!flags.all && !flags.feature) fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel impact check requires --feature <id> or --all');
+	const featureIds = flags.all ? listFeatures(root).map((r) => r.feature_id) : [flags.feature];
+
+	const results = [];
+	for (const featureId of featureIds) {
+		let outcome;
+		try {
+			outcome = checkImpact(root, featureId);
+		} catch (err) {
+			if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+			throw err;
+		}
+		results.push({ feature_id: featureId, ...outcome });
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify(flags.all ? results : results[0], null, 2));
+	} else {
+		for (const r of results) {
+			console.log(`impact check -- ${r.feature_id}`);
+			console.log(`  changes: ${r.report.changes.length}, outbound: ${r.report.outbound.length}, inbound: ${r.report.inbound.length}`);
+			console.log(`  gate: ${r.evaluation.blocking ? 'awaiting_disposition' : 'pass'}`);
+			for (const o of r.evaluation.blockingOutbound) console.log(`    BLOCKING: ${o.change_key} -> ${o.downstream_feature} (${o.via}, ${o.confidence})`);
+			for (const i of r.evaluation.blockingInbound) console.log(`    BLOCKING (inbound): ${i.change_key} from ${i.upstream_feature}, unacknowledged`);
+		}
+	}
+	const anyBlocking = results.some((r) => r.evaluation.blocking);
+	process.exit(anyBlocking ? EXIT_CODES.AWAITING_DISPOSITION : EXIT.PASS);
+}
+
+// D-cross-feature-impact-graph: the DECIDE half -- refuses (exit 3) if anything proven is
+// undisposed, otherwise atomically rewrites impact-baseline.json from the CURRENT surface.
+function cmdImpactAccept(args) {
+	const flags = parseCommand('impact accept', args);
+	if (flags.help) { console.log(renderCommandHelp('impact accept')); process.exit(0); }
+	setContext('impact accept', flags);
+	const root = requireRepoRoot();
+	let result;
+	try {
+		result = acceptImpact(root, flags.feature);
+	} catch (err) {
+		if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+	const gateState = passNamedGate(root, 'impact', flags.feature);
+	if (flags.json) {
+		console.log(JSON.stringify({ ...result, gate: gateState.gates.impact }, null, 2));
+	} else {
+		console.log(`accepted: ${flags.feature} -- baseline captured at ${result.baseline.captured_at}`);
+		console.log(`gate: impact -> ${gateState.gates.impact.status}`);
+	}
+	process.exit(EXIT.PASS);
+}
+
+function cmdImpactDisposition(args) {
+	const flags = parseCommand('impact disposition', args);
+	if (flags.help) { console.log(renderCommandHelp('impact disposition')); process.exit(0); }
+	setContext('impact disposition', flags);
+	const root = requireRepoRoot();
+	let result;
+	try {
+		result = recordDisposition(root, {
+			feature: flags.feature, changeKey: flags.change, downstreamFeature: flags.downstream,
+			mode: flags.mode, reason: flags.reason, trackedBy: flags['tracked-by'],
+			expiresDays: flags['expires-days'] != null ? Number(flags['expires-days']) : null,
+		});
+	} catch (err) {
+		if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+	if (flags.json) {
+		console.log(JSON.stringify(result, null, 2));
+	} else {
+		console.log(`disposition recorded: ${flags.change} -> ${flags.downstream} (${flags.mode})`);
+	}
+	process.exit(EXIT.PASS);
+}
+
+function cmdImpactAck(args) {
+	const flags = parseCommand('impact ack', args);
+	if (flags.help) { console.log(renderCommandHelp('impact ack')); process.exit(0); }
+	setContext('impact ack', flags);
+	const root = requireRepoRoot();
+	let result;
+	try {
+		result = acknowledgeInbound(root, { feature: flags.feature, from: flags.from, changeKey: flags.change, reason: flags.reason });
+	} catch (err) {
+		if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+	if (flags.json) {
+		console.log(JSON.stringify(result, null, 2));
+	} else {
+		console.log(`acknowledged: ${flags.change} from ${flags.from}`);
+	}
+	process.exit(EXIT.PASS);
+}
+
+// D-cross-feature-impact-graph (IG8/IG9): the one seam to the LLM-driven exploration layer -- writes
+// data only, spawns nothing, never touches a gate. `--format graphify` writes graphify's own native
+// extraction shape directly (see lib/impact-export-graphify.mjs's header for why this bypasses its
+// own Steps 1-3 entirely).
+function cmdImpactExport(args) {
+	const flags = parseCommand('impact export', args);
+	if (flags.help) { console.log(renderCommandHelp('impact export')); process.exit(0); }
+	setContext('impact export', flags);
+	const root = requireRepoRoot();
+	if (!['graphify', 'json', 'mermaid'].includes(flags.format)) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--format must be one of graphify|json|mermaid (got "${flags.format}")`);
+	}
+	const graph = buildImpactGraph(root);
+	const rings = flags.rings != null ? Number(flags.rings) : null;
+	if (rings != null && !flags.focus) fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--rings only has an effect together with --focus');
+
+	let output;
+	if (flags.format === 'json') output = `${JSON.stringify(graph, null, 2)}\n`;
+	else if (flags.format === 'mermaid') output = `${toMermaid(graph)}\n`;
+	else output = `${JSON.stringify(toGraphifyExtraction(graph, { focus: flags.focus, rings }), null, 2)}\n`;
+
+	if (flags.out) {
+		writeFileAtomic(flags.out, output);
+		console.log(`wrote ${flags.out}`);
+	} else {
+		process.stdout.write(output);
+	}
+	process.exit(EXIT.PASS);
+}
+
 // D-business-rules (R6): compiles specs/<id>/rules.yaml (optional) plus the feature's own contract
 // into specs/<id>/rules/<id>.rules.json, and establishes the `rules` gate.
 //
@@ -2719,6 +2909,15 @@ function renderHandlesPlan(plan, actions) {
 		lines.push(`- read via: ${r.readPath ?? '(not found)'}`);
 		lines.push(`- requiredAuthority (fetch/recover): ${r.requiredAuthority}`);
 		if (r.requiredAuthorityForPatch !== undefined) lines.push(`- requiredAuthorityForPatch: ${r.requiredAuthorityForPatch}`);
+		// D-resolver-policy-contract (PC2): one line per policies[] record -- java-spring only
+		// (the field is absent on python-fastapi/typescript-express plans).
+		for (const p of r.policies ?? []) {
+			if (p.status === 'materialized') {
+				lines.push(`- policy[${p.action}]: materialized (${p.mode}) ${p.authority} -- ${p.evidence.kind}${p.evidence.file ? ` @ ${p.evidence.file}${p.evidence.line ? `:${p.evidence.line}` : ''}` : ''}`);
+			} else {
+				lines.push(`- policy[${p.action}]: UNRESOLVED (${p.mode}) -- ${p.evidence.kind}${p.evidence.file ? ` @ ${p.evidence.file}${p.evidence.line ? `:${p.evidence.line}` : ''}` : ''} -- ${p.reason}`);
+			}
+		}
 		lines.push('');
 	}
 	if (plan.notes.length > 0) {
@@ -2959,7 +3158,7 @@ function cmdHandlesEmit(args) {
 	// a diff" that also means "and actually write it", so --diff forces dryRun the same as --check
 	// does, without requiring both flags together.
 	const dryRun = flags.check || flags.diff;
-	const { written, resolverStubs, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [], registrationGaps = [] } = provider.emit({
+	const { written, resolverStubs, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [], registrationGaps = [], unresolvedPolicies = [] } = provider.emit({
 		repoRoot: root, featureId: flags.feature, plan, resourceFilter, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff, enforceRegistry,
 	});
 
@@ -3039,6 +3238,24 @@ function cmdHandlesEmit(args) {
 		process.exit(EXIT_CODES.HANDLES_REGISTRATION_GAP);
 	}
 
+	// D-resolver-policy-contract (PC9): unconditional -- NOT gated on enforceRegistry (orthogonal
+	// axis: that one is about revocation/lifecycle and produces 404s; this one is about
+	// authorization and produces 403s/boot failures). Same acknowledgement mechanism as
+	// registrationGaps above (--force --reason, no new flag) -- the AuthorizationPolicy.java
+	// file(s) ARE still written either way; only the overall command's reported success, and the
+	// `handles` gate passing, are gated on acknowledging the gap.
+	if (unresolvedPolicies.length > 0 && !flags.force) {
+		if (flags.json) {
+			console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, unresolvedPolicies, blocked: true, gate: null, check: dryRun }, null, 2));
+		} else {
+			const verb = dryRun ? 'would refuse to report success' : 'refusing to report success';
+			console.error(`${verb}: ${unresolvedPolicies.length} resource action(s) could not have their authorization safely auto-derived:`);
+			for (const u of unresolvedPolicies) console.error(`  ${u.resourceType} [${u.action}] (${u.kind}${u.file ? ` @ ${u.file}${u.line ? `:${u.line}` : ''}` : ''})\n    ${u.note}`);
+			if (!dryRun) console.error(`\nthe resolver/AuthorizationPolicy file(s) above were still written -- nothing about their content is wrong. Implement the generated AuthorizationPolicy interface(s) by hand and re-run, or acknowledge and proceed with: bskel handles emit --feature ${flags.feature}${flags.module ? ` --module ${flags.module}` : ''}${flags.resource ? ` --resource ${flags.resource}` : ''} --force --reason "..."`);
+		}
+		process.exit(EXIT_CODES.HANDLES_UNRESOLVED_POLICY);
+	}
+
 	// D4: dryRun never marks the gate passed -- nothing real happened this run.
 	const gateState = dryRun ? null : passNamedGate(root, 'handles', flags.feature, { resolverStubs });
 
@@ -3048,7 +3265,7 @@ function cmdHandlesEmit(args) {
 	postEmitNotes.push(...describeDownstreamImpact(root, flags.feature));
 
 	if (flags.json) {
-		console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, blocked: false, gate: gateState?.gates.handles ?? null, check: dryRun, postEmitNotes }, null, 2));
+		console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, unresolvedPolicies, blocked: false, gate: gateState?.gates.handles ?? null, check: dryRun, postEmitNotes }, null, 2));
 	} else if (!flags.quiet) {
 		console.log(`${dryRun ? 'would write' : 'wrote'} ${written.length} file(s):`);
 		for (const w of written) console.log(`  ${w}`);
@@ -3164,7 +3381,7 @@ async function cmdPatchPropose(args) {
 		}
 		params = { choice: flags.choice, target: flags.target };
 		source = { choice: flags.choice };
-	} else {
+	} else if (kind === 'ddl-apply') {
 		if (!flags['database-url-env'] || !flags['sql-file']) {
 			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel patch propose --kind ddl-apply requires --database-url-env <NAME> --sql-file <path>');
 		}
@@ -3176,6 +3393,23 @@ async function cmdPatchPropose(args) {
 		}
 		params = { databaseUrlEnv: flags['database-url-env'], schema: flags.schema, sqlText };
 		source = { database_url_env: flags['database-url-env'], schema: flags.schema };
+	} else {
+		// java-source-splice
+		if (!flags['splice-file']) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel patch propose --kind java-source-splice requires --splice-file <path>');
+		}
+		let spliceDoc;
+		try {
+			spliceDoc = JSON.parse(fs.readFileSync(flags['splice-file'], 'utf8'));
+		} catch (err) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read/parse --splice-file "${flags['splice-file']}": ${err.message}`);
+		}
+		const { ok: spliceOk, errors: spliceErrors } = validateAgainstSchema('java-source-splice.schema.json', spliceDoc);
+		if (!spliceOk) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `"${flags['splice-file']}" does not match schemas/java-source-splice.schema.json:\n${formatSchemaErrors(spliceErrors).join('\n')}`);
+		}
+		params = { file: spliceDoc.file, edits: spliceDoc.edits };
+		source = { request_file: flags['splice-file'] };
 	}
 
 	let plan;
@@ -3202,6 +3436,12 @@ function describePatchTransaction(txn) {
 	if (txn.kind === 'config-apply') {
 		return `${txn.target.file} @ ${txn.target.key_path.join('.')}: "${txn.current_value}" -> "${txn.proposed_value}"`;
 	}
+	if (txn.kind === 'java-source-splice') {
+		const members = txn.target.edits
+			.map((e) => (e.locator ? `${e.op}:${e.locator.member_name}` : `add-import:${e.imports?.[0]}`))
+			.join(', ');
+		return `[java-source-splice] ${txn.target.file}: ${members}`;
+	}
 	const sql = txn.target.sql_text.replace(/\s+/g, ' ').trim();
 	return `[${txn.kind}] ${txn.target.database_url_env}/${txn.target.schema}: ${sql.slice(0, 100)}${sql.length > 100 ? '...' : ''}`;
 }
@@ -3231,12 +3471,33 @@ async function cmdPatchApprove(args) {
 	} catch (err) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
 	}
-	const updated = approveTransaction(root, flags.feature, flags.transaction, flags.reason, freshPlan);
+	let updated;
+	try {
+		updated = approveTransaction(root, flags.feature, flags.transaction, flags.reason, freshPlan);
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', describeStaleTransactionError(err, root, txn, freshPlan));
+	}
 
 	console.log(flags.json ? JSON.stringify(updated, null, 2) : `approved: ${flags.transaction}`);
 	process.exit(0);
 }
 
+// D-java-source-splice: enriches a StaleTransactionError with the kind's own optional
+// describeStaleness() hook (only java-source-splice defines one today) -- never changes WHETHER
+// the transaction is rejected, only the diagnostic text. Checked by `.name`, not `instanceof`
+// (StaleTransactionError is intentionally not exported from lib/patch-transactions.mjs -- this is
+// its only consumer, and importing the class just to narrow a catch is unnecessary coupling).
+function describeStaleTransactionError(err, root, txn, freshPlan) {
+	if (err.name !== 'StaleTransactionError') return err.message;
+	const describe = getPatchKind(txn.kind).describeStaleness;
+	if (!describe) return err.message;
+	try {
+		return describe(root, txn, freshPlan);
+	} catch {
+		return err.message;
+	}
+}
+
 // D-ddl-apply: --confirm is required (and must exactly equal --transaction) for any kind other
 // than 'config-apply' -- deliberately checked here, at the CLI boundary, before applyTransaction()
 // is ever called, as human-factors friction layered ON TOP of the engine's own load-bearing
@@ -3262,7 +3523,12 @@ async function cmdPatchApply(args) {
 	} catch (err) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
 	}
-	const updated = await applyTransaction(root, flags.feature, flags.transaction, freshPlan, getPatchKind(txn.kind).apply);
+	let updated;
+	try {
+		updated = await applyTransaction(root, flags.feature, flags.transaction, freshPlan, getPatchKind(txn.kind).apply);
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', describeStaleTransactionError(err, root, txn, freshPlan));
+	}
 
 	const evidence = { transaction_id: updated.transaction_id, kind: updated.kind, applied_at: updated.apply.at };
 	const gateState = passNamedGate(root, 'patch_transactions', flags.feature, evidence);
@@ -4453,6 +4719,18 @@ async function dispatchCommand(cmd, rest) {
 			process.exit(14);
 			break;
 		}
+		case 'impact': {
+			const sub = rest[0];
+			const subArgs = rest.slice(1);
+			if (sub === 'check') return cmdImpactCheck(subArgs);
+			if (sub === 'accept') return cmdImpactAccept(subArgs);
+			if (sub === 'disposition') return cmdImpactDisposition(subArgs);
+			if (sub === 'ack') return cmdImpactAck(subArgs);
+			if (sub === 'export') return cmdImpactExport(subArgs);
+			usage();
+			process.exit(14);
+			break;
+		}
 		case 'rules': {
 			const sub = rest[0];
 			const subArgs = rest.slice(1);

package/contracts/emit.mjs

@@ -15,12 +15,12 @@ import { pathPrefixCandidates, unreflectedPathPrefixes } from './export.mjs';
 // a path param. Direction stays one-way (openapi.mjs imports from emit.mjs, never the reverse).
 export const BARE_UUID_PATTERN = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$';
 
-// A7/A8/A9/A10: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
+// A7/A8/A9/A10/X2: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
 // const -- bin/bskel.mjs's loadContract() imports this too, so the friendly "re-emit with the
-// current bskel" message and the value actually written here cannot drift apart. Bumped "7" -> "8"
-// for this item (sourceDescription) -- again cheap, the friendly re-emit pre-check needs zero
-// code change -- see D-openapi-description.
-export const CONTRACT_SCHEMA_VERSION = '8';
+// current bskel" message and the value actually written here cannot drift apart. Bumped "8" -> "9"
+// for this item (the `expansion` field, D-route-expansion-provenance) -- again cheap, the friendly
+// re-emit pre-check needs zero code change.
+export const CONTRACT_SCHEMA_VERSION = '9';
 
 // A9 (D-openapi-path-params): `sourcePathParamSchemas` (a Map<name, schema>, contracts/openapi.mjs's
 // applyPathParameterSchemas -- present only for a matched/adopted operation whose source document
@@ -66,7 +66,11 @@ function pathParamsSchema(routePath, sourcePathParamSchemas = null) {
 // Object>>`) -- findMethodParams() shares the same balanced-delimiter analyzer that fixes the
 // scanner's identical GenericWithSpaceController case.
 function detectRequestBody(filePath, methodName) {
-	if (!filePath || !fs.existsSync(filePath)) return null;
+	// X5 (D-route-expansion-provenance): explicit guard, not the incidental fact that a regex built
+	// from the literal string "null" also happens not to match anything -- a null methodName means
+	// there is genuinely no literal per-action source method to look in (see the same reasoning
+	// D-typescript-express-inline-handlers already established for resolveHandlerFile()).
+	if (!filePath || !methodName || !fs.existsSync(filePath)) return null;
 	const text = fs.readFileSync(filePath, 'utf8');
 	const params = findMethodParams(text, methodName);
 	if (params === null) return null;
@@ -377,6 +381,15 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 					}));
 				}
 				const { pathParams, pathParamsHeuristic } = pathParamsSchema(route, pathParamSchemas);
+				// X2 (D-route-expansion-provenance): present only when the scan adapter recorded which
+				// multi-route declaration this endpoint came from (ep.declarationIndex) AND that
+				// declaration actually resolves on the owning controller -- omitted for every ordinary
+				// 1:1 endpoint, the same "absent unless it applies" discipline A9's pathParamsHeuristic
+				// already established. No adapter populates declarationIndex yet (forward-compatible
+				// shape only) -- see test/contract.test.mjs's expansion-field tests for a hand-built
+				// fixture exercising this.
+				const declaration = ep.declarationIndex != null ? (controller.declarations?.[ep.declarationIndex] ?? null) : null;
+				const expansion = declaration ? { rule: declaration.rule, declarationLine: declaration.line, label: declaration.label ?? null } : null;
 				operations[operationId] = {
 					verb,
 					path: route,
@@ -397,6 +410,9 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 					...(sourceRequestBody ? { sourceRequestBody } : {}),
 					// A9: omitted (not []) when every segment resolved from source, or the route has none.
 					...(pathParamsHeuristic ? { pathParamsHeuristic } : {}),
+					// X2: omitted entirely when this endpoint wasn't expanded from a multi-route
+					// declaration -- see the computation above.
+					...(expansion ? { expansion } : {}),
 					// A10: omitted entirely when --descriptions was not passed, the source had none, or
 					// it failed the length cap -- same "omitted, never null/false" discipline as every
 					// other field above.