backend-skeleton 1.1.0 → 1.2.0

package/README.md

@@ -39,6 +39,7 @@ check for a specific failure mode found the same way — see `DECISIONS.md` for
   - [Declaring field-to-field dependencies (optional)](#declaring-field-to-field-dependencies-optional)
   - [Patching a config file (optional)](#patching-a-config-file-optional)
   - [Signed gate attestations (optional)](#signed-gate-attestations-optional)
+  - [Signed observe receipts (optional)](#signed-observe-receipts-optional)
 - [Compatibility](#compatibility)
 - [Generated-file policy](#generated-file-policy)
 - [Security model](#security-model)
@@ -344,6 +345,32 @@ bskel attest verify --file attestation.json --pubkey ~/.bskel-keys/attest-public
 `attest verify`'s exit code reflects signature validity only — whether the gates inside actually
 passed is a separate, printed summary. See `D-gate-attestation-signing` in `DECISIONS.md`.
 
+### Signed observe receipts (optional)
+
+`bskel observe emit` generates opt-in runtime middleware that checks real traffic against a
+feature's contract and logs a verdict-only receipt per call (JSON Pointer + constraint kind, never
+an observed value); `bskel observe import --receipts <path>` turns a stream of those receipts into
+a committed report backing the `conformance` gate. By default a receipts file is trusted at face
+value once it's structurally valid — a human could hand-fabricate one. Add `--pubkey <path>` to
+`observe import` to verify each receipt's optional signature instead, reusing the same
+`bskel attest keygen`-generated keypair signed gate attestations use:
+
+```bash
+bskel attest keygen --out ~/.bskel-keys        # same command as above -- one keypair, multiple uses
+# then, per deployed app (one-time, at the app's own startup):
+#   TypeScript: import { setSigningKey } from './observe/receiptSign'; setSigningKey(pem);
+#   Java:       set the bskel.observe.signing-key-pem Spring property (e.g. an env var)
+#   Python:     receipt_sign.configure(os.environ.get("BSKEL_OBSERVE_SIGNING_KEY_PEM"))
+bskel observe import --feature 001-organization-management --receipts receipts.jsonl \
+  --pubkey ~/.bskel-keys/attest-public.pem [--require-signature]
+```
+
+Unset/no key configured means every receipt stays unsigned — fully backward compatible with every
+app already using this feature. `--pubkey` alone verifies signatures where present and tolerates
+unsigned receipts (excluding them from the report's `matched` counts, with a printed warning);
+`--require-signature` makes any unsigned or invalid receipt abort the whole import. See the
+"cryptographic receipt attestation" update in `D-runtime-conformance-receipts` in `DECISIONS.md`.
+
 Every command is read-only until you explicitly run one of the mutating steps above — `bskel
 status`/`bskel next` (no arguments needed) tell you which gate is next and print the exact
 copy-pasteable command for it, without touching anything.

package/bin/bskel.mjs

@@ -10,6 +10,7 @@ import { forceNamedGate, revokeNamedGate, requireNamedGate, passNamedGate, await
 import { REPO_GATE_ID, GATE_NAMES, gateScopeId, requireGateDefinition } from '../lib/gate-definitions.mjs';
 import { getGate, loadState, historyPath } from '../lib/state.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';
 import { withLockSync } from '../lib/lock.mjs';
 import { specDir, specPath, sbfPath } from '../lib/paths.mjs';
@@ -80,6 +81,7 @@ function usage() {
   bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]
   bskel scan disposition --feature <id> --mode reuse|extend|replace|parallel [--module <name>] [--note "..."] [--breaking-approved]
   bskel scan explain <module> --feature <id> [--json]
+  bskel scan repair --feature <id> [--json]
   bskel scan cross-feature-check --feature <id> [--db [--database-url-env <NAME>] [--schema public]] [--json]
   bskel scan cross-feature-waive --feature <id> --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..."
   bskel feature init --slug <name>
@@ -109,7 +111,7 @@ function usage() {
   bskel patch rollback --feature <id> --transaction <id> --reason "..." [--force] [--json]
   bskel patch list --feature <id> [--json]
   bskel observe emit --feature <id> [--module <name>] [--force --reason "..."] [--check] [--diff] [--json]
-  bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--json]
+  bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--pubkey <path> [--require-signature]] [--json]
   bskel verify --feature <id> [--build [--allow-skip-build]] [--json]
   bskel status [--feature <id>] [--json]
   bskel next [--feature <id>] [--json]
@@ -668,7 +670,12 @@ async function cmdScan(args) {
 
 	const dir = specDir(root, flags.feature);
 	fs.mkdirSync(dir, { recursive: true });
-	writeScanReportOrExit(specPath(root, flags.feature, 'brownfield-scan.json'), report);
+	// D-scan-report-portable-paths: `report`'s `.file` fields stay absolute in memory (every
+	// consumer's expected shape, including this same function's OWN JSON stdout print below) --
+	// only the ON-DISK copy is converted to repo-relative, so the committed artifact survives
+	// being checked out somewhere else (a second worktree, a different clone, CI) without
+	// requiring any change to how `.file` is read back in memory once re-hydrated.
+	writeScanReportOrExit(specPath(root, flags.feature, 'brownfield-scan.json'), dehydrateScanReportFilePaths(report, root));
 	writeFileAtomic(specPath(root, flags.feature, 'brownfield-scan.md'), renderScanMarkdown(report));
 
 	let gateState;
@@ -748,7 +755,7 @@ function cmdScanExplain(args) {
 	if (!moduleName) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'usage: bskel scan explain <module> --feature <id> [--json]');
 	}
-	const report = loadScanReportOrExit(root, flags.feature);
+	const report = loadHydratedScanReportOrExit(root, flags.feature);
 	const mod = report.related_modules.find((m) => m.module === moduleName);
 	if (!mod) {
 		const known = report.related_modules.map((m) => m.module).join(', ') || '(none)';
@@ -762,6 +769,60 @@ function cmdScanExplain(args) {
 	process.exit(0);
 }
 
+// D-scan-report-portable-paths: a one-time, non-destructive migration for a committed
+// brownfield-scan.json written BEFORE this fix (schema "sbf.scan-report/1", `.file` absolute) --
+// `bskel scan`'s own re-run is NOT a substitute here: runScan() never carries `disposition`
+// forward, so re-scanning would silently wipe an already-disposed feature's disposition and
+// cascade `scan`/`contract`/`handles` gates back to stale/awaiting_disposition. This command
+// touches ONLY `.file` strings and `schema` -- `disposition` and everything else stay
+// byte-identical. Must run from the SAME location the original `bskel scan` ran from (a fresh
+// worktree's absolute paths won't resolve to anything real) -- fails closed, naming the exact
+// file, rather than guessing at a mapping.
+function cmdScanRepair(args) {
+	const flags = parseCommand('scan repair', args);
+	if (flags.help) { console.log(renderCommandHelp('scan repair')); process.exit(0); }
+	setContext('scan repair', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+
+	// Deliberately NOT loadScanReportOrExit() -- that validates against the CURRENT schema const
+	// ("sbf.scan-report/2"), which a genuinely old ("/1") report can never match by definition.
+	// This command's whole job is repairing exactly that mismatch, so it reads raw here.
+	const reportPath = specPath(root, flags.feature, 'brownfield-scan.json');
+	if (!fs.existsSync(reportPath)) {
+		fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no scan report at ${reportPath} -- run \`bskel scan --feature ${flags.feature}\` first`);
+	}
+	const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+	if (report.schema !== 'sbf.scan-report/1') {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `${flags.feature}'s scan report is already schema "${report.schema}" -- nothing to repair (this command only migrates a "sbf.scan-report/1" report's absolute \`.file\` paths to repo-relative).`);
+	}
+
+	const unresolvable = [];
+	for (const mod of report.related_modules ?? []) {
+		for (const key of ['controllers', 'entities', 'enums', 'dtos']) {
+			for (const item of mod[key] ?? []) {
+				if (item.file && !fs.existsSync(item.file)) unresolvable.push(item.file);
+			}
+		}
+	}
+	if (unresolvable.length > 0) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `refusing to guess: ${unresolvable.length} file(s) referenced in this scan report do not exist under the CURRENT root -- re-run this command from the exact location \`bskel scan\` originally ran from:\n${unresolvable.map((f) => `  ${f}`).join('\n')}`);
+	}
+
+	// D-scan-report-portable-paths: same transform `cmdScan` applies at every real write -- a
+	// legacy report is, by definition, exactly the "still absolute" case that needs converting.
+	const repaired = dehydrateScanReportFilePaths(report, root);
+	repaired.schema = 'sbf.scan-report/2';
+	writeScanReportOrExit(reportPath, repaired);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ feature_id: flags.feature, schema: repaired.schema, repaired: true }, null, 2));
+	} else {
+		console.log(`repaired: ${flags.feature}'s scan report is now schema "${repaired.schema}" (disposition and every other field untouched)`);
+	}
+	process.exit(0);
+}
+
 // D-cross-feature-collision: mirrors cmdContractEmit's own "always write the artifact, gate
 // blocks only if unresolved issues remain" shape exactly, for a different data source (NAME-
 // identity collisions against every OTHER feature, not this feature's own contract completeness).
@@ -1194,11 +1255,11 @@ function cmdContractEmit(args) {
 		});
 	}
 
+	// D-scan-report-portable-paths: was its own inline fs.existsSync/JSON.parse here, duplicating
+	// (and bypassing) loadScanReportOrExit()'s schema validation -- consolidated onto the shared,
+	// hydrated loader, closing both that gap and the portability bug the hydration itself fixes.
 	const scanReportPath = specPath(root, flags.feature, 'brownfield-scan.json');
-	if (!fs.existsSync(scanReportPath)) {
-		fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no scan report at ${scanReportPath} -- run \`bskel scan --feature ${flags.feature}\` first`);
-	}
-	const scanReport = JSON.parse(fs.readFileSync(scanReportPath, 'utf8'));
+	const scanReport = loadHydratedScanReportOrExit(root, flags.feature);
 	requireCapabilitiesOrExit(scanReport, 'contract emit', {
 		featureId: flags.feature,
 		scanReportPath,
@@ -2101,6 +2162,19 @@ function loadScanReportOrExit(root, featureId) {
 	return parsed;
 }
 
+// D-scan-report-portable-paths: the read-only sibling of loadScanReportOrExit() -- every consumer
+// that only READS the report (never writes it back) should go through this instead, so its
+// `related_modules[].{controllers,entities,enums,dtos}[].file` values are correctly re-anchored to
+// THIS root before anything downstream (handles codegen, contract emission, gate recomputation)
+// touches them. Deliberately NOT folded into loadScanReportOrExit() itself: cmdScanDisposition()
+// does load -> mutate `.disposition` -> write back the WHOLE object -- if hydration lived in the
+// base loader, that round trip would silently re-persist re-absolutized paths to disk, resurrecting
+// the exact portability bug this closes. Any future read-modify-write command must stay on the raw
+// loader for the same reason.
+function loadHydratedScanReportOrExit(root, featureId) {
+	return hydrateScanReportFilePaths(loadScanReportOrExit(root, featureId), root);
+}
+
 // S5 (D-persistence-integrity): the write-side sibling of loadScanReportOrExit() above -- validated
 // before it ever touches disk, same "fail loud here, not as a confusing error somewhere later"
 // reasoning as lib/state.mjs's saveState(). Used by both cmdScan()'s own write and
@@ -2225,7 +2299,7 @@ async function cmdHandlesPlan(args) {
 	if (flags.help) { console.log(renderCommandHelp('handles plan')); process.exit(0); }
 	setContext('handles plan', flags);
 	const root = requireRepoRoot();
-	const scanReport = loadScanReportOrExit(root, flags.feature);
+	const scanReport = loadHydratedScanReportOrExit(root, flags.feature);
 	const scanReportPath = specPath(root, flags.feature, 'brownfield-scan.json');
 	requireCapabilitiesOrExit(scanReport, 'handles plan', { featureId: flags.feature, scanReportPath });
 	const provider = selectProviderOrExit(scanReport);
@@ -2360,7 +2434,7 @@ function cmdHandlesEmit(args) {
 		});
 	}
 
-	const scanReport = loadScanReportOrExit(root, flags.feature);
+	const scanReport = loadHydratedScanReportOrExit(root, flags.feature);
 	const scanReportPath = specPath(root, flags.feature, 'brownfield-scan.json');
 	requireCapabilitiesOrExit(scanReport, 'handles emit', { featureId: flags.feature, scanReportPath });
 	const provider = selectProviderOrExit(scanReport);
@@ -2524,7 +2598,7 @@ function cmdHandlesPatchApprove(args) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel handles patch approve requires --reason "..." -- every approval must be auditable');
 	}
 
-	const scanReport = loadScanReportOrExit(root, flags.feature);
+	const scanReport = loadHydratedScanReportOrExit(root, flags.feature);
 	const scanReportPath = specPath(root, flags.feature, 'brownfield-scan.json');
 	requireCapabilitiesOrExit(scanReport, 'handles patch approve', { featureId: flags.feature, scanReportPath });
 	const provider = selectProviderOrExit(scanReport);
@@ -2800,7 +2874,7 @@ async function cmdHandlesAudit(args) {
 	// live database rather than a static regex proxy.
 	let registryCoverage = null;
 	if (flags['check-registry-coverage']) {
-		const scanReport = loadScanReportOrExit(root, flags.feature);
+		const scanReport = loadHydratedScanReportOrExit(root, flags.feature);
 		const scanReportPath = specPath(root, flags.feature, 'brownfield-scan.json');
 		requireCapabilitiesOrExit(scanReport, 'handles audit --check-registry-coverage', { featureId: flags.feature, scanReportPath });
 		const provider = selectProviderOrExit(scanReport);
@@ -2875,7 +2949,7 @@ function cmdObserveEmit(args) {
 		});
 	}
 
-	const scanReport = loadScanReportOrExit(root, flags.feature);
+	const scanReport = loadHydratedScanReportOrExit(root, flags.feature);
 	const contract = loadContract(root, flags.feature);
 	const dryRun = flags.check || flags.diff;
 
@@ -2993,6 +3067,20 @@ function cmdObserveImport(args) {
 	const flags = parseCommand('observe import', args);
 	if (flags.help) { console.log(renderCommandHelp('observe import')); process.exit(0); }
 	setContext('observe import', flags);
+	if (flags['require-signature'] && !flags.pubkey) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--require-signature was given but --pubkey was not -- refusing to require a signature this command has no way to check. Pass --pubkey <path>, or drop --require-signature to allow unsigned/unverified receipts (with a warning).');
+	}
+	// Mirrors `cmdAttestVerify`'s own pubkey-read pattern exactly. `null` (not given) means: don't
+	// verify at all -- a signature field, if present on a receipt, is simply ignored, matching
+	// today's behavior byte-for-byte (full backward compatibility with every already-deployed app).
+	let pubkeyPem = null;
+	if (flags.pubkey) {
+		try {
+			pubkeyPem = fs.readFileSync(path.resolve(process.cwd(), flags.pubkey), 'utf8');
+		} catch (err) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read --pubkey "${flags.pubkey}": ${err.message}`);
+		}
+	}
 	const root = requireRepoRoot();
 	requirePreflightPassed(root);
 
@@ -3044,12 +3132,50 @@ function cmdObserveImport(args) {
 	}
 
 	const currentContractHash = sha256File(specPath(root, flags.feature, 'contracts', `${flags.feature}.schema.json`));
+
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): verification always
+	// happens here, in Node, regardless of which language's runtime produced+signed the receipt --
+	// lib/attest.mjs's verifyPayload() is reused completely unmodified (already payload-shape-
+	// agnostic, the same reuse D-ddl-apply's own maybeSignStep() already established for a
+	// different payload shape). `unsigned` is computed regardless of --pubkey (forward visibility);
+	// `signature_invalid` is only ever non-zero when --pubkey was given -- there is no key to judge
+	// a signature against otherwise. Without --pubkey, every receipt is trusted exactly like today
+	// (a signature field, if present, is never even looked at) -- full backward compatibility.
+	let unsignedCount = 0;
+	let signatureInvalidCount = 0;
+	const trustedByIndex = receipts.map((r) => {
+		const hasSignature = Boolean(r.signature);
+		if (!hasSignature) unsignedCount++;
+		if (!pubkeyPem) return true;
+		if (!hasSignature) return false;
+		const { signature, ...unsigned } = r;
+		const valid = verifyPayload(unsigned, signature.value, pubkeyPem);
+		if (!valid) signatureInvalidCount++;
+		return valid;
+	});
+	if (flags['require-signature']) {
+		const badIndex = trustedByIndex.findIndex((trusted) => !trusted);
+		if (badIndex !== -1) {
+			const bad = receipts[badIndex];
+			const reason = bad.signature ? 'its signature does not verify against --pubkey' : 'it has no signature at all';
+			fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `${flags.receipts}: a receipt for operation "${bad.operation_id}" is untrusted -- ${reason}. Aborting the whole import (--require-signature demands every receipt verify, and a corrupted/untrusted receipts file must not partially land).`);
+		}
+	}
+	if (pubkeyPem && unsignedCount > 0 && !flags.quiet) {
+		console.error(`WARNING: ${unsignedCount} receipt(s) have no signature -- excluded from matched/violation counts now that --pubkey is checking signatures. Pass --require-signature to make this a hard failure instead.`);
+	}
+
+	// Untrusted receipts (unsigned or signature-invalid, only possible when --pubkey was given)
+	// are excluded from EVERY count below -- not "noise" (non-JSON garbage) and not "corruption"
+	// (schema-invalid, aborts the whole import), a genuinely new third tier alongside
+	// stale_contract_ref's own existing "kept on record, excluded from current evidence" precedent.
 	let matched = 0;
 	let staleContractRef = 0;
 	let violationCount = 0;
 	let unsupportedCount = 0;
 	const byOperation = {};
-	for (const r of receipts) {
+	receipts.forEach((r, i) => {
+		if (!trustedByIndex[i]) return;
 		const isMatched = r.contract_ref === currentContractHash;
 		if (isMatched) matched++; else staleContractRef++;
 		const opStats = byOperation[r.operation_id] ?? { matched: 0, stale_contract_ref: 0, violations: 0 };
@@ -3059,7 +3185,7 @@ function cmdObserveImport(args) {
 			if (isMatched) opStats.violations++;
 		}
 		byOperation[r.operation_id] = opStats;
-	}
+	});
 
 	const report = {
 		sbf_conformance_report: '1',
@@ -3073,8 +3199,11 @@ function cmdObserveImport(args) {
 			matched, stale_contract_ref: staleContractRef,
 			violations: violationCount,
 			unsupported: unsupportedCount,
+			unsigned: unsignedCount,
+			signature_invalid: signatureInvalidCount,
 		},
 		by_operation: byOperation,
+		verification: { pubkey_given: Boolean(pubkeyPem), require_signature: Boolean(flags['require-signature']) },
 	};
 	const { ok: reportOk, errors: reportErrors } = validateAgainstSchema('conformance-report.schema.json', report);
 	if (!reportOk) {
@@ -3103,6 +3232,9 @@ function cmdObserveImport(args) {
 		console.log(JSON.stringify({ report, noise_lines: noiseLines, gate: gateState.gates.conformance }, null, 2));
 	} else {
 		console.log(`imported ${receipts.length} receipt(s) (${matched} matched the current contract, ${staleContractRef} stale, ${noiseLines} noise line(s) skipped)`);
+		if (pubkeyPem) {
+			console.log(`signatures: ${unsignedCount} unsigned, ${signatureInvalidCount} invalid (both excluded from the counts above)`);
+		}
 		console.log(`${violationCount} violation(s), ${unsupportedCount} unsupported field(s) across matched receipts`);
 		console.log(`wrote ${path.relative(root, reportPath)}`);
 		console.log(`gate: conformance -> ${gateState.gates.conformance.status}`);
@@ -3625,6 +3757,7 @@ async function dispatchCommand(cmd, rest) {
 		case 'scan': {
 			if (rest[0] === 'disposition') return cmdScanDisposition(rest.slice(1));
 			if (rest[0] === 'explain') return cmdScanExplain(rest.slice(1));
+			if (rest[0] === 'repair') return cmdScanRepair(rest.slice(1));
 			if (rest[0] === 'cross-feature-check') return cmdScanCrossFeatureCheck(rest.slice(1));
 			if (rest[0] === 'cross-feature-waive') return cmdScanCrossFeatureWaive(rest.slice(1));
 			await cmdScan(rest);

package/handles/providers/java-spring/observe.mjs

@@ -24,6 +24,10 @@ const INFRA_FILES = [
 	{ template: 'ContractCheck.java.tmpl', target: 'global/observe/ContractCheck.java' },
 	{ template: 'ObserveSchemaLoader.java.tmpl', target: 'global/observe/ObserveSchemaLoader.java' },
 	{ template: 'ContractObservationAspect.java.tmpl', target: 'global/observe/ContractObservationAspect.java' },
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): JDK-stdlib-only Ed25519
+	// signer, used by ContractObservationAspect -- see that template's own javadoc for why this is
+	// a hand-rolled canonicalizer, not a Jackson mapper feature.
+	{ template: 'ReceiptSigner.java.tmpl', target: 'global/observe/ReceiptSigner.java' },
 ];
 
 function render(templatePath, vars) {
@@ -51,12 +55,21 @@ function writeUnit(target, content) {
 export function emitObserveJavaSpring({ repoRoot, featureId, contract, basePackage, force = false, reason = '', dryRun = false, computeDiff = false }) {
 	const javaSrcRoot = path.join(repoRoot, 'src', 'main', 'java', ...basePackage.split('.'));
 	const jacksonPackage = detectJacksonPackage(repoRoot);
+	// D-runtime-conformance-receipts (Jackson 2/3 JsonNode field-iteration parity): Jackson 3's
+	// JsonNode has no #fields()/#fieldNames() at all (confirmed live via javap against real
+	// jackson-databind 3.1.5 -- only #properties(), a Set); Jackson 2's #fields() exists across
+	// every real version checked (2.14 through 2.21), but #properties() does NOT exist on the
+	// older ones (2.14 lacks it, 2.17+ has it) -- so the safe, version-spanning choice per major is
+	// #fields() for Jackson 2, #properties() for Jackson 3, never the other way around.
+	const jacksonFieldsOfImpl = jacksonPackage === 'tools.jackson.databind'
+		? 'return node.properties();'
+		: 'return () -> node.fields();';
 
 	const infraUnits = INFRA_FILES.map((f) => ({
 		id: f.template,
 		templatePath: path.join(TEMPLATES_DIR, f.template),
 		targetAbs: path.join(javaSrcRoot, f.target),
-		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage }),
+		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage, JACKSON_FIELDS_OF_IMPL: jacksonFieldsOfImpl }),
 	}));
 
 	const result = emitUnits({ repoRoot, featureId, provider: 'java-spring', force, reason, infraUnits, resolverUnits: [], orphanScan: null, dryRun, computeDiff });
@@ -89,6 +102,7 @@ export function emitObserveJavaSpring({ repoRoot, featureId, contract, basePacka
 			'NOT done automatically: route the "bskel.observe.receipts" SLF4J logger to wherever you want receipt lines collected (a dedicated logback/log4j2 appender to a file, your existing log pipeline, etc.) -- bskel never edits your logging config. Point `bskel observe import --receipts <path>` at whatever that logger\'s output ends up as.',
 			`Contract-conformance checking only covers path params always, plus a bounded slice of request/response/error body shape -- and only when this contract was emitted with --openapi-file. See the emitted ${path.relative(repoRoot, schemaPath)}'s own "unsupported" markers for exactly what is skipped for this feature.`,
 			'NOT done automatically: apply @ObserveContract(operationId = "...") to whichever existing controller/service methods you want observed -- nothing is annotated for you (D-resolver-scope: never guess which method implements which operation).',
+			'NOT done automatically: to sign receipts, set the `bskel.observe.signing-key-pem` Spring property (e.g. an env var via Spring\'s own relaxed binding: BSKEL_OBSERVE_SIGNING_KEY_PEM=...) to a PKCS#8 Ed25519 private key PEM -- `bskel attest keygen --out <dir>` already generates one in this exact format. Unset means every receipt stays unsigned (backward compatible). Verify with `bskel observe import --pubkey <path/to/attest-public.pem>`.',
 		],
 	};
 }

package/handles/providers/java-spring/templates/ContractObservationAspect.java.tmpl

@@ -5,11 +5,13 @@ import {{JACKSON_PACKAGE}}.ObjectMapper;
 import {{JACKSON_PACKAGE}}.node.ArrayNode;
 import {{JACKSON_PACKAGE}}.node.ObjectNode;
 import {{BASE_PACKAGE}}.global.observe.ObserveSchemaLoader.ObservedOperation;
+import jakarta.annotation.PostConstruct;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.aspectj.lang.ProceedingJoinPoint;
 import org.aspectj.lang.annotation.Around;
 import org.aspectj.lang.annotation.Aspect;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
 import org.springframework.stereotype.Component;
 import org.springframework.web.bind.annotation.RequestBody;
@@ -49,6 +51,10 @@ import java.util.Map;
  * deliberately deferred, same unexamined assumption {@code HandleAspect} already carries for
  * {@code @Around} advice generally. See DECISIONS.md D-runtime-conformance-receipts.
  *
+ * <p>Optionally signs each receipt (Ed25519, via {@link ReceiptSigner}) when {@code
+ * bskel.observe.signing-key-pem} is set -- see that class's own javadoc. Unset means every
+ * receipt stays unsigned, exactly like before this capability existed.
+ *
  * <p>Generated by backend-skeleton ({@code bskel observe emit}). Requires {@code
  * spring-boot-starter-aop} on the classpath -- see {@link ObserveContract}'s own javadoc.
  */
@@ -63,6 +69,21 @@ public class ContractObservationAspect {
 	private final ObserveSchemaLoader schemaLoader;
 	private final ObjectMapper objectMapper;
 
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): a plain, non-final,
+	// separately field-injected member -- NOT routed through the @RequiredArgsConstructor-generated
+	// constructor above. @Value on a `final` constructor-injected field alongside
+	// @RequiredArgsConstructor is a documented Lombok/Spring interop gap (the generated constructor
+	// does not reliably propagate the annotation); this is the standard, real-world-safe pattern for
+	// @Value-injected simple config even in classes that otherwise use constructor injection.
+	// Empty (the default) means every receipt stays unsigned -- see ReceiptSigner's own javadoc.
+	@Value("${bskel.observe.signing-key-pem:}")
+	private String signingKeyPem;
+
+	@PostConstruct
+	private void configureReceiptSigning() {
+		ReceiptSigner.configure(signingKeyPem);
+	}
+
 	@Around("@annotation(observeContract)")
 	public Object observe(ProceedingJoinPoint joinPoint, ObserveContract observeContract) throws Throwable {
 		String operationId = observeContract.operationId();
@@ -159,9 +180,26 @@ public class ContractObservationAspect {
 			vn.put("keyword", v.keyword());
 			vn.put("message", v.message());
 		}
+		safelySign(receipt);
 		safelyLog(receipt);
 	}
 
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): its OWN inner try/catch,
+	// separate from safelyLog()'s -- a signing failure (bad/missing key config, malformed PEM) must
+	// fall back to logging the receipt UNSIGNED, not silently drop the whole receipt the way sharing
+	// safelyLog()'s catch block would.
+	private void safelySign(ObjectNode receipt) {
+		if (!ReceiptSigner.isConfigured()) return;
+		try {
+			String signatureValue = ReceiptSigner.sign(receipt);
+			ObjectNode signature = receipt.putObject("signature");
+			signature.put("algorithm", "ed25519");
+			signature.put("value", signatureValue);
+		} catch (Exception e) {
+			log.warn("ContractObservationAspect: could not sign a receipt -- logging it unsigned instead", e);
+		}
+	}
+
 	private void safelyLog(Object receipt) {
 		try {
 			RECEIPTS.info(objectMapper.writeValueAsString(receipt));

package/handles/providers/java-spring/templates/ObserveSchemaLoader.java.tmpl

@@ -11,7 +11,6 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.HashMap;
-import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.regex.Pattern;
@@ -69,9 +68,7 @@ public class ObserveSchemaLoader {
 			String featureId = root.path("feature_id").asText(null);
 			String featureUid = root.path("feature_uid").asText(null);
 			String contractRef = root.path("contract_ref").asText(null);
-			Iterator<Map.Entry<String, JsonNode>> ops = root.path("operations").fields();
-			while (ops.hasNext()) {
-				Map.Entry<String, JsonNode> entry = ops.next();
+			for (Map.Entry<String, JsonNode> entry : fieldsOf(root.path("operations"))) {
 				String operationId = entry.getKey();
 				JsonNode op = entry.getValue();
 				String body = op.path("body").asText("unknown");
@@ -99,9 +96,7 @@ public class ObserveSchemaLoader {
 		List<String> required = parseStringList(node.path("required"));
 		List<String> unsupported = new ArrayList<>(parseStringList(node.path("unsupported")));
 		Map<String, ObservedProperty> properties = new HashMap<>();
-		Iterator<Map.Entry<String, JsonNode>> props = node.path("properties").fields();
-		while (props.hasNext()) {
-			Map.Entry<String, JsonNode> entry = props.next();
+		for (Map.Entry<String, JsonNode> entry : fieldsOf(node.path("properties"))) {
 			JsonNode propSchema = entry.getValue();
 			String type = propSchema.path("type").asText(null);
 			String patternText = propSchema.has("pattern") ? propSchema.get("pattern").asText() : null;
@@ -119,6 +114,17 @@ public class ObserveSchemaLoader {
 		return new ObservedObject(required, properties, unsupported);
 	}
 
+	// D-runtime-conformance-receipts (Jackson 2/3 JsonNode field-iteration parity): Jackson 2's
+	// JsonNode#fields() (an Iterator) does not exist on Jackson 3's JsonNode at all -- Jackson 3
+	// replaced it with #properties() (a Set, no Iterator wrapper needed). Neither API exists on
+	// EVERY version of the other major (older Jackson 2.x, e.g. 2.14, has no #properties() either),
+	// so this can't be unified into one call safely -- {{JACKSON_PACKAGE}} already tells us which
+	// major is on this target's real classpath (detectJacksonPackage() in emit.mjs), so that same
+	// signal picks the one real, correct implementation body at emit time.
+	private static Iterable<Map.Entry<String, JsonNode>> fieldsOf(JsonNode node) {
+		{{JACKSON_FIELDS_OF_IMPL}}
+	}
+
 	private static List<String> parseStringList(JsonNode node) {
 		List<String> values = new ArrayList<>();
 		if (node != null && node.isArray()) {