backend-skeleton 1.1.1 → 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()) {

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

@@ -0,0 +1,174 @@
+package {{BASE_PACKAGE}}.global.observe;
+
+import {{JACKSON_PACKAGE}}.JsonNode;
+import {{JACKSON_PACKAGE}}.node.ObjectNode;
+
+import java.nio.charset.StandardCharsets;
+import java.security.KeyFactory;
+import java.security.PrivateKey;
+import java.security.Signature;
+import java.security.spec.PKCS8EncodedKeySpec;
+import java.util.ArrayList;
+import java.util.Base64;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * D-runtime-conformance-receipts (cryptographic receipt attestation): signs a receipt at emission
+ * time so {@code bskel observe import --pubkey <path>} can prove it genuinely came from this
+ * running app, not a hand-fabricated file. JDK-stdlib-only ({@link Signature}, Ed25519 -- standard
+ * since JDK 15) -- zero new dependency, matching this project's own JDK 17 floor.
+ *
+ * <p>Canonicalization must be byte-identical to {@code bskel observe import}'s own verification
+ * side (Node's {@code lib/attest.mjs} {@code canonicalize()}: deep-sorted keys, compact JSON,
+ * non-ASCII left unescaped) -- proven cross-language-compatible by direct execution against a real
+ * receipt containing a forward slash, a quote, and non-ASCII text (see DECISIONS.md
+ * D-runtime-conformance-receipts). Jackson's own {@code MapperFeature.SORT_PROPERTIES_ALPHABETICALLY}
+ * does NOT sort an {@link ObjectNode}'s own tree-model field order -- confirmed live, it only
+ * affects bean/POJO introspection -- so this class hand-walks the {@link JsonNode} tree instead of
+ * relying on a mapper feature that would silently no-op.
+ *
+ * <p>The private key is never baked into generated source (that would commit a secret to the
+ * repo) -- see {@link #configure(String)}'s own javadoc for how a human wires this in.
+ */
+public final class ReceiptSigner {
+
+	private static volatile PrivateKey privateKey;
+
+	private ReceiptSigner() {
+	}
+
+	/**
+	 * NOT called by any generated code -- a human calls this once, themselves, at application
+	 * startup (see {@code ContractObservationAspect}'s own {@code @PostConstruct} wiring), passing a
+	 * PKCS#8 PEM private key string -- the exact format {@code bskel attest keygen} already writes.
+	 * Never hardcode a real key value in source; read it from wherever you already keep secrets (an
+	 * env var, a mounted file, a secrets manager). Unconfigured (the default) means every receipt
+	 * stays unsigned -- backward compatible with every already-deployed app using this feature
+	 * before signing existed.
+	 */
+	public static void configure(String privateKeyPem) {
+		privateKey = (privateKeyPem == null || privateKeyPem.isBlank()) ? null : parsePkcs8(privateKeyPem);
+	}
+
+	static boolean isConfigured() {
+		return privateKey != null;
+	}
+
+	/**
+	 * Returns the base64 Ed25519 signature over the canonicalized receipt. Callers must pass a node
+	 * that does not yet carry a {@code "signature"} field (this class never strips one itself --
+	 * {@code ContractObservationAspect} only ever calls this before adding one).
+	 */
+	static String sign(ObjectNode receiptWithoutSignature) {
+		try {
+			Signature signer = Signature.getInstance("Ed25519");
+			signer.initSign(privateKey);
+			signer.update(canonicalize(receiptWithoutSignature).getBytes(StandardCharsets.UTF_8));
+			return Base64.getEncoder().encodeToString(signer.sign());
+		} catch (Exception e) {
+			throw new IllegalStateException("could not sign receipt", e);
+		}
+	}
+
+	private static PrivateKey parsePkcs8(String pem) {
+		try {
+			String base64 = pem
+					.replace("-----BEGIN PRIVATE KEY-----", "")
+					.replace("-----END PRIVATE KEY-----", "")
+					.replaceAll("\\s", "");
+			byte[] der = Base64.getDecoder().decode(base64);
+			KeyFactory keyFactory = KeyFactory.getInstance("Ed25519");
+			return keyFactory.generatePrivate(new PKCS8EncodedKeySpec(der));
+		} catch (Exception e) {
+			throw new IllegalArgumentException("not a usable PKCS#8 Ed25519 private key PEM", e);
+		}
+	}
+
+	// Recursively sorts every object's field names, preserves array order (matching lib/gates.mjs's
+	// own sortKeysDeep() semantics exactly on the Node verification side), emits compact JSON by
+	// hand. The schema this signs has exactly one numeric field (a plain integer HTTP status) and
+	// nothing else numeric anywhere -- no float-formatting cross-language risk exists here.
+	static String canonicalize(JsonNode node) {
+		StringBuilder sb = new StringBuilder();
+		canonicalizeInto(node, sb);
+		return sb.toString();
+	}
+
+	private static void canonicalizeInto(JsonNode node, StringBuilder sb) {
+		if (node == null || node.isNull()) {
+			sb.append("null");
+		} else if (node.isObject()) {
+			List<String> names = new ArrayList<>();
+			for (Map.Entry<String, JsonNode> entry : fieldsOf(node)) {
+				names.add(entry.getKey());
+			}
+			Collections.sort(names);
+			sb.append('{');
+			for (int i = 0; i < names.size(); i++) {
+				if (i > 0) sb.append(',');
+				sb.append(jsonString(names.get(i))).append(':');
+				canonicalizeInto(node.get(names.get(i)), sb);
+			}
+			sb.append('}');
+		} else if (node.isArray()) {
+			sb.append('[');
+			for (int i = 0; i < node.size(); i++) {
+				if (i > 0) sb.append(',');
+				canonicalizeInto(node.get(i), sb);
+			}
+			sb.append(']');
+		} else if (node.isTextual()) {
+			sb.append(jsonString(node.asText()));
+		} else if (node.isBoolean()) {
+			sb.append(node.asBoolean());
+		} else if (node.isNumber()) {
+			sb.append(node.numberValue());
+		} else {
+			sb.append(jsonString(node.asText()));
+		}
+	}
+
+	// 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. Mirrors
+	// ObserveSchemaLoader's own identically-named, identically-reasoned helper exactly.
+	private static Iterable<Map.Entry<String, JsonNode>> fieldsOf(JsonNode node) {
+		{{JACKSON_FIELDS_OF_IMPL}}
+	}
+
+	// Standard JSON string escaping (RFC 8259) -- the same set Node's JSON.stringify and Python's
+	// json.dumps(ensure_ascii=False) both already apply, proven byte-identical live. Non-ASCII is
+	// deliberately left UNESCAPED to match (ensure_ascii=False on the Python side is the analogous,
+	// load-bearing requirement there -- Python's own json.dumps default would otherwise diverge).
+	private static String jsonString(String s) {
+		StringBuilder sb = new StringBuilder(s.length() + 2);
+		sb.append('"');
+		for (int i = 0; i < s.length(); i++) {
+			char c = s.charAt(i);
+			switch (c) {
+				case '"' -> sb.append("\\\"");
+				case '\\' -> sb.append("\\\\");
+				case '\b' -> sb.append("\\b");
+				case '\f' -> sb.append("\\f");
+				case '\n' -> sb.append("\\n");
+				case '\r' -> sb.append("\\r");
+				case '\t' -> sb.append("\\t");
+				default -> {
+					if (c < 0x20) {
+						sb.append(String.format("\\u%04x", (int) c));
+					} else {
+						sb.append(c);
+					}
+				}
+			}
+		}
+		sb.append('"');
+		return sb.toString();
+	}
+}

package/handles/providers/python-fastapi/observe.mjs

@@ -26,6 +26,10 @@ const INFRA_FILES = [
 	{ template: 'observed_schema.py.tmpl', target: 'observed_schema.py' },
 	{ template: 'contract_check.py.tmpl', target: 'contract_check.py' },
 	{ template: 'observe_contract.py.tmpl', target: 'observe_contract.py' },
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): Ed25519 signer used by
+	// observe_contract.py -- imports the `cryptography` package lazily, only if actually configured
+	// with a real key (see receipt_sign.py's own docstring for why).
+	{ template: 'receipt_sign.py.tmpl', target: 'receipt_sign.py' },
 ];
 
 function render(templatePath, vars) {
@@ -92,6 +96,7 @@ export function emitObservePythonFastApi({ repoRoot, featureId, contract, plan,
 			'NOT done automatically: route the "bskel.observe.receipts" logger (Python\'s standard logging module) to wherever you want receipt lines collected (a dedicated handler 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 @observe_contract(operation_id="...") to whichever existing route handlers you want observed -- nothing is decorated for you (D-resolver-scope: never guess which function implements which operation). For a request body to be checked, also pass body_param="<the argument name>" explicitly -- Python has no @RequestBody-equivalent marker to infer it from.',
+			'NOT done automatically: to sign receipts, call receipt_sign.configure(os.environ.get("BSKEL_OBSERVE_SIGNING_KEY_PEM")) yourself at application startup, with a PKCS#8 Ed25519 private key PEM -- `bskel attest keygen --out <dir>` already generates one in this exact format. This also requires `pip install cryptography` (Python\'s stdlib has no Ed25519 signing -- receipt_sign.py imports it lazily, only when configure() is actually called with a real key). Unconfigured means every receipt stays unsigned (backward compatible). Verify with `bskel observe import --pubkey <path/to/attest-public.pem>`.',
 		],
 	};
 }

package/handles/providers/python-fastapi/templates/observe_contract.py.tmpl

@@ -32,6 +32,10 @@ return value transparently, unmodified, even without inspecting it) -- FastAPI r
 commonly `async def`, so getting this wrong breaks production traffic, not just the conformance
 check.
 
+Optionally signs each receipt (Ed25519, via receipt_sign.py) once `receipt_sign.configure(...)`
+has been called with a real key -- see that module's own docstring. Unconfigured means every
+receipt stays unsigned, exactly like before this capability existed.
+
 Example:
     @observe_contract(operation_id="items-read_item")
     async def read_item(session: SessionDep, id: str):
@@ -48,6 +52,7 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from . import contract_check
 from . import observed_schema
+from . import receipt_sign
 
 logger = logging.getLogger(__name__)
 _RECEIPTS = logging.getLogger("bskel.observe.receipts")
@@ -102,11 +107,25 @@ def _emit_receipt(op: dict, operation_id: str, request_violations: list, respons
             receipt["status"] = status
         if error_class is not None:
             receipt["error_class"] = error_class
+        _sign_receipt(receipt)
         _RECEIPTS.info(json.dumps(receipt))
     except Exception:
         logger.warning("observe_contract: could not emit a receipt -- the wrapped call already returned unaffected", exc_info=True)
 
 
+def _sign_receipt(receipt: dict) -> None:
+    # D-runtime-conformance-receipts (cryptographic receipt attestation): its OWN inner try/except,
+    # separate from _emit_receipt()'s outer one -- 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 the outer except block would.
+    if not receipt_sign.is_configured():
+        return
+    try:
+        receipt["signature"] = {"algorithm": "ed25519", "value": receipt_sign.sign(receipt)}
+    except Exception:
+        logger.warning("observe_contract: could not sign a receipt -- logging it unsigned instead", exc_info=True)
+
+
 def observe_contract(*, operation_id: str, body_param: str | None = None):
     def decorator(fn):
         signature = inspect.signature(fn)

package/handles/providers/python-fastapi/templates/receipt_sign.py.tmpl

@@ -0,0 +1,68 @@
+"""Generated by backend-skeleton (bskel observe emit). Do not hand-edit -- change the source
+template and regenerate.
+
+D-runtime-conformance-receipts (cryptographic receipt attestation): signs a receipt at emission
+time so `bskel observe import --pubkey <path>` can prove it genuinely came from this running app,
+not a hand-fabricated file. Uses the `cryptography` package's Ed25519 primitives -- Python's
+stdlib has no Ed25519 signing at all, so this is a genuinely new, first-of-its-kind third-party
+dependency for this provider's generated runtime code (same honest framing this project already
+gave `pg`, its own first-ever database dependency -- see DECISIONS.md
+D-runtime-conformance-receipts). The import is deliberately LAZY (inside configure(), not at
+module level) so this module -- and observe_contract.py, which imports it unconditionally --
+stays importable even when `cryptography` is not installed, as long as signing is never
+configured. Only pip-install `cryptography` if you actually call configure() with a real key.
+
+Canonicalization must be byte-identical to `bskel observe import`'s own verification side (Node's
+`lib/attest.mjs` canonicalize(): deep-sorted keys, compact JSON, non-ASCII left unescaped) --
+`json.dumps(receipt, sort_keys=True, separators=(",", ":"), ensure_ascii=False)` is exactly that,
+proven cross-language-compatible by direct execution against a real receipt containing a forward
+slash, a quote, and non-ASCII text (see DECISIONS.md D-runtime-conformance-receipts).
+`ensure_ascii=False` is load-bearing -- Python's own json.dumps default (True) escapes non-ASCII
+as `\\uXXXX`, which neither Node's JSON.stringify nor Jackson's default writer do; without this
+flag, signatures would never cross-verify on any receipt whose message contains non-ASCII text.
+
+The private key is never baked into generated source (that would commit a secret to the repo) --
+see configure()'s own docstring for how a human wires this in.
+"""
+import base64
+import json
+
+_private_key = None
+
+
+def configure(private_key_pem):
+    """NOT called by any generated code -- a human calls this once, themselves, at application
+    startup (e.g. `receipt_sign.configure(os.environ.get("BSKEL_OBSERVE_SIGNING_KEY_PEM"))`),
+    passing a PKCS#8 PEM private key string -- the exact format `bskel attest keygen` already
+    writes. Never hardcode a real key value in source; read it from wherever you already keep
+    secrets (an env var, a mounted file, a secrets manager). Unconfigured (the default, including
+    a None/blank string) means every receipt stays unsigned -- backward compatible with every
+    already-deployed app using this feature before signing existed.
+    """
+    global _private_key
+    if not private_key_pem or not private_key_pem.strip():
+        _private_key = None
+        return
+    from cryptography.hazmat.primitives import serialization
+
+    _private_key = serialization.load_pem_private_key(private_key_pem.encode("utf-8"), password=None)
+
+
+def is_configured():
+    return _private_key is not None
+
+
+def canonicalize(receipt_without_signature):
+    # The schema this signs has exactly one numeric field (a plain integer HTTP status) and
+    # nothing else numeric anywhere -- no float-formatting cross-language risk exists here.
+    return json.dumps(
+        receipt_without_signature, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+
+
+def sign(receipt_without_signature):
+    """Returns the base64 Ed25519 signature over the canonicalized receipt. Callers must pass a
+    dict that does not yet carry a "signature" key -- this module never strips one itself.
+    """
+    signature_bytes = _private_key.sign(canonicalize(receipt_without_signature))
+    return base64.b64encode(signature_bytes).decode("ascii")

package/handles/providers/typescript-express/observe.mjs

@@ -28,6 +28,10 @@ const INFRA_FILES = [
 	{ template: 'contractCheck.ts.tmpl', target: 'contractCheck.ts' },
 	{ template: 'observedSchema.ts.tmpl', target: 'observedSchema.ts' },
 	{ template: 'observeContract.ts.tmpl', target: 'observeContract.ts' },
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): node:crypto-only Ed25519
+	// signer used by observeContract.ts -- a self-contained port of lib/attest.mjs, never imported
+	// directly (this runs inside a deployed target app, a foreign process from this CLI's own).
+	{ template: 'receiptSign.ts.tmpl', target: 'receiptSign.ts' },
 ];
 
 function render(templatePath, vars) {
@@ -97,6 +101,7 @@ export function emitObserveTypeScriptExpress({ repoRoot, featureId, contract, pl
 			'error_class is never populated in this provider\'s receipts (always omitted) -- Express middleware runs BEFORE the route handler and is structurally unable to observe a thrown error the way java\'s @Around/python\'s except block can (by the time a handler throws or calls next(err), this middleware\'s own call frame has already returned). See DECISIONS.md D-runtime-conformance-receipts.',
 			'Response-body checking only covers a handler that calls res.json(...) or res.send(<object>) (Express\'s own res.send delegates to res.json for a plain-object body) -- a handler that calls res.send(<string>)/res.end(...) directly, or whose response is produced by Express\'s own default/generic error handler, has its response check silently skipped, never guessed.',
 			'OpenAPI reconciliation for this adapter matches scanned Express route strings EXACTLY against the OpenAPI document\'s own path keys (contracts/openapi.mjs has no ":id" <-> "{id}" translation) -- a real, standards-compliant OpenAPI document (which must use "{id}") will not match a scanned ":id"/":id([0-9]+)" route unless the document\'s own path key happens to already read that way. Unlike python-fastapi, this is not "for free."',
+			'NOT done automatically: to sign receipts, call setSigningKey(pem) yourself at application startup (import { setSigningKey } from \'./observe/receiptSign\';), with a PKCS#8 Ed25519 private key PEM -- `bskel attest keygen --out <dir>` already generates one in this exact format. Unconfigured means every receipt stays unsigned (backward compatible). Verify with `bskel observe import --pubkey <path/to/attest-public.pem>`.',
 		],
 	};
 }

package/handles/providers/typescript-express/templates/observeContract.ts.tmpl

@@ -34,12 +34,17 @@
 // (req.body is Express's own unambiguous body once body-parsing middleware has run -- no
 // python-style explicit body_param argument needed here).
 //
+// Optionally signs each receipt (Ed25519, via receiptSign.ts) once setSigningKey() has been
+// called with a real key -- see that module's own doc comment. Unconfigured means every
+// receipt stays unsigned, exactly like before this capability existed.
+//
 // Example:
 //   router.get('/users/:id', [checkJwt, observeContract('users-show')], showUser);
 
 import type { RequestHandler, Request, Response } from 'express';
 import * as contractCheck from './contractCheck';
 import * as observedSchema from './observedSchema';
+import * as receiptSign from './receiptSign';
 import type { ObservedOperation } from './observedSchema';
 import type { Violation } from './contractCheck';
 
@@ -90,12 +95,26 @@ function emitReceipt(op: ObservedOperation, operationId: string, requestViolatio
 			recorded_at: new Date().toISOString(),
 			violations: allViolations,
 		};
+		signReceipt(receipt);
 		receiptSink(JSON.stringify(receipt));
 	} catch (err) {
 		console.warn(`observeContract: could not emit a receipt for "${operationId}"`, err);
 	}
 }
 
+// D-runtime-conformance-receipts (cryptographic receipt attestation): its OWN inner try/catch,
+// separate from emitReceipt()'s outer one -- a signing failure (bad/missing key config, malformed
+// PEM) must fall back to sending the receipt UNSIGNED, not silently drop the whole receipt the way
+// sharing the outer catch would.
+function signReceipt(receipt: Record<string, unknown>): void {
+	if (!receiptSign.isConfigured()) return;
+	try {
+		receipt.signature = { algorithm: 'ed25519', value: receiptSign.sign(receipt) };
+	} catch (err) {
+		console.warn('observeContract: could not sign a receipt -- sending it unsigned instead', err);
+	}
+}
+
 export function observeContract(operationId: string): RequestHandler {
 	return (req: Request, res: Response, next) => {
 		let op: ObservedOperation | undefined;

package/handles/providers/typescript-express/templates/receiptSign.ts.tmpl

@@ -0,0 +1,65 @@
+// Generated by backend-skeleton (bskel observe emit). Do not hand-edit -- change the source
+// template and regenerate.
+//
+// D-runtime-conformance-receipts (cryptographic receipt attestation): signs a receipt at emission
+// time so `bskel observe import --pubkey <path>` can prove it genuinely came from this running
+// app, not a hand-fabricated file. A self-contained PORT of lib/attest.mjs's own canonicalize()/
+// signPayload() -- never imported directly. This file runs inside a DEPLOYED target app, a
+// foreign process from this CLI's own even though both happen to be Node -- same "port, don't
+// cross-import into generated code" rule codec.ts.tmpl already established for handles/codec.mjs.
+// node:crypto only, zero new dependency, matching this project's own "no new dependency where the
+// runtime already provides the primitive" discipline (the same reasoning java-spring's own
+// ReceiptSigner.java uses java.security.Signature instead of a Bouncy Castle dependency).
+//
+// Canonicalization must be byte-identical to `bskel observe import`'s own verification side (Node's
+// lib/attest.mjs canonicalize()) -- proven cross-language-compatible by direct execution against a
+// real receipt containing a forward slash, a quote, and non-ASCII text (see DECISIONS.md
+// D-runtime-conformance-receipts). Deep-sorted object keys, array order preserved, compact JSON,
+// non-ASCII left unescaped -- exactly Node's own JSON.stringify default behavior once keys are
+// pre-sorted, so no special-casing is needed here the way Python's ensure_ascii=False is.
+
+import { sign as cryptoSign } from 'node:crypto';
+
+let privateKeyPem: string | null = null;
+
+/**
+ * NOT called by any generated code -- a human calls this once, themselves, at application
+ * startup, passing a PKCS#8 PEM private key string -- the exact format `bskel attest keygen`
+ * already writes. Never hardcode a real key value in source; read it from wherever you already
+ * keep secrets (an env var, a mounted file, a secrets manager). Unconfigured (the default,
+ * including null/blank) means every receipt stays unsigned -- backward compatible with every
+ * already-deployed app using this feature before signing existed.
+ */
+export function setSigningKey(pem: string | null | undefined): void {
+	privateKeyPem = pem && pem.trim().length > 0 ? pem : null;
+}
+
+export function isConfigured(): boolean {
+	return privateKeyPem !== null;
+}
+
+function sortKeysDeep(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(sortKeysDeep);
+	if (value !== null && typeof value === 'object') {
+		const sorted: Record<string, unknown> = {};
+		for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+			sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+		}
+		return sorted;
+	}
+	return value;
+}
+
+function canonicalize(value: unknown): string {
+	return JSON.stringify(sortKeysDeep(value));
+}
+
+/**
+ * Returns the base64 Ed25519 signature over the canonicalized receipt. Callers must pass an
+ * object that does not yet carry a "signature" key -- this module never strips one itself.
+ */
+export function sign(receiptWithoutSignature: unknown): string {
+	if (!privateKeyPem) throw new Error('receiptSign.sign() called before setSigningKey()');
+	const canonical = canonicalize(receiptWithoutSignature);
+	return cryptoSign(null, Buffer.from(canonical), privateKeyPem).toString('base64');
+}

package/lib/cli.mjs

@@ -148,6 +148,13 @@ export const COMMANDS = {
 		},
 		allowPositionals: true,
 	},
+	'scan repair': {
+		usage: 'bskel scan repair --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'scan cross-feature-check': {
 		usage: 'bskel scan cross-feature-check --feature <id> [--db [--database-url-env <NAME>] [--schema public]] [--json]',
 		options: {
@@ -394,12 +401,20 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): --pubkey alone has real
+	// standalone meaning (verify signatures where present, tolerate unsigned receipts) -- mirrors
+	// `serve`'s own `--sign-key` (opt-in signing, no `--require-sign-key` needed), NOT `gate export
+	// --sign`/`--key`'s mutual-requirement (a bare `--key` there is meaningless without `--sign`).
+	// --require-signature without --pubkey is refused -- mirrors `serve`'s own "mandatory signing,
+	// opt-in-to-more-strictness" `--require-sign-key`-without-`--sign-key` precedent exactly.
 	'observe import': {
-		usage: 'bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--json]',
+		usage: 'bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--pubkey <path> [--require-signature]] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			receipts: { type: 'string', default: null, required: true },
 			'fail-on-violation': { type: 'boolean', default: false },
+			pubkey: { type: 'string', default: null },
+			'require-signature': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},

package/lib/field-dependencies.mjs

@@ -11,6 +11,7 @@
 // that gets passed and the token later required can never diverge.
 import path from 'node:path';
 import { readJsonIfExists, writeFileAtomic } from './fsutil.mjs';
+import { hydrateScanReportFilePaths } from './scan-report-paths.mjs';
 import { specPath } from './paths.mjs';
 import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
 import { listFeatures, loadFeatureFile } from './featurelifecycle.mjs';
@@ -119,7 +120,7 @@ export function dependencyKey(dep) {
 // slice doesn't address.
 export function resolveClassFile(root, featureId, resourceType) {
 	const reportPath = specPath(root, featureId, 'brownfield-scan.json');
-	const report = readJsonIfExists(reportPath);
+	const report = hydrateScanReportFilePaths(readJsonIfExists(reportPath), root);
 	if (!report) return { file: null, reason: 'no_scan_report' };
 	const moduleName = report.disposition?.module ?? report.related_modules?.[0]?.module;
 	if (!moduleName) return { file: null, reason: 'no_disposition' };

package/lib/gate-definitions.mjs

@@ -23,6 +23,7 @@ import { specPath, sbfPath } from './paths.mjs';
 import { ADAPTERS, adapterById } from '../scanners/registry.mjs';
 import { loadManifest } from './handles-manifest.mjs';
 import { dependenciesPath, resolveClassFile } from './field-dependencies.mjs';
+import { hydrateScanReportFilePaths } from './scan-report-paths.mjs';
 import { crossFeatureReportPath, crossFeatureResolutionPath } from './cross-feature-collisions.mjs';
 import { listTransactions, transactionPath } from './patch-transactions.mjs';
 
@@ -243,7 +244,7 @@ export const GATE_DEFINITIONS = Object.freeze({
 		verifyPolicy: VERIFY_POLICY.REQUIRED,
 		recompute: (root, featureId) => {
 			const reportPath = specPath(root, featureId, 'brownfield-scan.json');
-			const report = readJsonIfExists(reportPath);
+			const report = hydrateScanReportFilePaths(readJsonIfExists(reportPath), root);
 			const inputs = {
 				scan_report_hash: sha256File(reportPath),
 				contract_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.schema.json`)),
@@ -257,9 +258,12 @@ export const GATE_DEFINITIONS = Object.freeze({
 			// (part 3)" in DECISIONS.md.
 			for (const item of [...(mod?.controllers ?? []), ...(mod?.entities ?? []), ...(mod?.enums ?? []), ...(mod?.dtos ?? [])]) {
 				if (!item.file) continue;
-				// related_modules[].{controllers,entities,enums}[].file are stored ABSOLUTE
-				// (unlike Part 1's own repo-relative files_read) -- confirmed live against a real
-				// scan report before writing this.
+				// D-scan-report-portable-paths: `.file` is repo-relative on disk (adapters write
+				// it that way now); `hydrateScanReportFilePaths()` above already re-anchored it to
+				// THIS root, so a plain path.relative(root, item.file) is correct regardless of
+				// where `bskel scan` originally ran -- no longer sensitive to a stale baked-in
+				// absolute path from a different worktree/clone. See DECISIONS.md for the real
+				// bug this closes (found via a real second-worktree pilot re-verification).
 				const rel = path.relative(root, item.file);
 				inputs[`${MODULE_FILE_PREFIX}${rel}`] = sha256File(item.file);
 			}

package/lib/scan-report-paths.mjs

@@ -0,0 +1,47 @@
+// D-scan-report-portable-paths: every scanner adapter builds `related_modules[].{controllers,
+// entities,enums,dtos}[].file` ABSOLUTE (this is deliberate, unchanged -- it is the shape every
+// in-memory/direct-API consumer has always expected and still does: `runScan()` called directly
+// and handed straight to `provider.plan()`/`planHandles()` is a real, widely-used pattern across
+// this project's own test suite, not just the CLI). The ONLY place an absolute `.file` is a real
+// problem is once it gets COMMITTED to git as part of `specs/<feature>/brownfield-scan.json`
+// (confirmed NOT gitignored for real feature work) -- a value baked in from wherever `bskel scan`
+// originally ran is meaningless once that same committed branch is checked out somewhere else (a
+// second worktree, a different clone, CI). So the fix lives at exactly the disk-persistence
+// boundary, not in the adapters or in every downstream consumer:
+//   - `dehydrateScanReportFilePaths()` converts absolute -> repo-relative, called ONCE, right
+//     before `bin/bskel.mjs`'s `cmdScan` writes the report to disk (mirrors the adapters' own
+//     pre-existing `filesRead` convention -- one `path.relative(repoRoot, f)` call, just applied
+//     at the write boundary instead of duplicated across 4 adapters).
+//   - `hydrateScanReportFilePaths()` converts back, called at every point something RE-LOADS the
+//     on-disk report (`loadHydratedScanReportOrExit`, the `contract` gate, `resolveClassFile`) --
+//     `path.isAbsolute(item.file)` doubles as a legacy-shape guard, so a report committed BEFORE
+//     this fix (already absolute on disk) passes through as a correct no-op rather than a bug;
+//     `bskel scan repair` is the real remedy for a stale-but-still-absolute value from a moved
+//     worktree, not this function.
+//
+// Both functions return a NEW object (via structuredClone), never mutate their input -- `cmdScan`
+// needs the SAME in-memory `report` for both the disk write (dehydrated) and the `--json` stdout
+// print (left absolute, untouched) from ONE scan; mutating in place would make whichever happened
+// first corrupt the other.
+import path from 'node:path';
+
+function mapScanReportFiles(report, transform) {
+	if (!report) return report;
+	const next = structuredClone(report);
+	for (const mod of next.related_modules ?? []) {
+		for (const key of ['controllers', 'entities', 'enums', 'dtos']) {
+			for (const item of mod[key] ?? []) {
+				if (item.file) item.file = transform(item.file);
+			}
+		}
+	}
+	return next;
+}
+
+export function hydrateScanReportFilePaths(report, repoRoot) {
+	return mapScanReportFiles(report, (file) => (path.isAbsolute(file) ? file : path.join(repoRoot, file)));
+}
+
+export function dehydrateScanReportFilePaths(report, repoRoot) {
+	return mapScanReportFiles(report, (file) => (path.isAbsolute(file) ? path.relative(repoRoot, file) : file));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "type": "module",
   "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scaffolding codegen included (Java/Spring, Python/FastAPI, TypeScript/Express).",
   "license": "AGPL-3.0-or-later",

package/scanners/adapters/python-fastapi.mjs

@@ -25,6 +25,12 @@ const FASTAPI_DEP_RE = /(?:^|[\s"'[])fastapi(?:\[[^\]]*\])?(?:[\s"',\]=<>~!;]|$)
 
 const VERB_DECORATOR_RE = /@(\w+)\.(get|post|put|patch|delete)\s*\(/gi;
 const ROUTER_DECL_RE = /(\w+)\s*=\s*APIRouter\s*\(/g;
+
+// D-fastapi-generic-module-name: real evidence only (polarsource/polar), not a speculative list --
+// same "validated against a real oracle" precedent as KNOWN_DTO_SUFFIXES below. 57 real files
+// literally named `endpoints.py`, 1 named `router.py`; no other generic stem (`routes`, `views`,
+// `api`) has ever been observed.
+const GENERIC_ROUTER_STEMS = new Set(['endpoints', 'router']);
 const CLASS_RE = /^class\s+(\w+)\s*\(([^)]*)\)\s*:/gm;
 const INCLUDE_ROUTER_RE = /include_router\s*\(/g;
 
@@ -287,8 +293,59 @@ const API_SURFACE_SOURCE = 'router-local paths only (this scan does not resolve
 	'document via `bskel contract emit --openapi-file <path> --path-prefix <prefix>` for trustworthy ' +
 	'operation identity and schemas.';
 
+// D-fastapi-generic-module-name: real polarsource/polar dogfooding found `path.basename(file,
+// '.py')` (the module-name rule below) collapses to the literal string "endpoints"/"router" for
+// every file using that repo's own real, common convention -- name every router file generically,
+// carry the real domain identity in the PARENT DIRECTORY instead (`organization/endpoints.py`,
+// `member/endpoints.py`). Two CLOSED passes, not interleaved -- a generic file's directory-derived
+// candidate must never be adopted before every non-generic file's own literal name is known, or a
+// later-discovered collision could arrive too late (the wrong merge would already be written).
+// Pass 1: every non-generic-stem file's own literal name is `reserved`, unchanged from today.
+// Pass 2: a generic-stem file's candidate (its own parent directory's basename) is adopted only if
+// it collides with neither `reserved` nor another generic file's already-`claimed` candidate --
+// real evidence found 9 such real collisions in polar alone (e.g. `subscription/endpoints.py`'s
+// candidate "subscription" collides with the real, unrelated, non-generic
+// `customer_portal/endpoints/subscription.py`). On any collision, the file keeps its old literal
+// generic name -- never guess into a silent wrong merge. `files` is already sorted by full path
+// (`listRgFiles`), so processing order (and therefore first-claim-wins) is deterministic.
+function resolveGenericModuleNames(files, readFile, projectRoot) {
+	const routerFiles = [];
+	const reserved = new Set();
+	for (const file of files) {
+		if (!/APIRouter\s*\(/.test(readFile(file))) continue;
+		const stem = path.basename(file, '.py');
+		routerFiles.push(file);
+		if (!GENERIC_ROUTER_STEMS.has(stem)) reserved.add(stem);
+	}
+
+	const moduleNameByFile = new Map();
+	const claimed = new Set();
+	for (const file of routerFiles) {
+		const stem = path.basename(file, '.py');
+		if (!GENERIC_ROUTER_STEMS.has(stem)) {
+			moduleNameByFile.set(file, stem);
+			continue;
+		}
+		const dir = path.dirname(file);
+		const candidate = dir !== projectRoot ? path.basename(dir) : null;
+		if (candidate && !reserved.has(candidate) && !claimed.has(candidate)) {
+			claimed.add(candidate);
+			moduleNameByFile.set(file, candidate);
+		} else {
+			moduleNameByFile.set(file, stem); // collision or no meaningful parent -- keep the old literal name
+		}
+	}
+	return moduleNameByFile;
+}
+
 export function scanPythonFastApi(repoRoot, projectRoot) {
 	const files = listPythonFiles(projectRoot);
+	const fileTextCache = new Map();
+	const readFile = (f) => {
+		if (!fileTextCache.has(f)) fileTextCache.set(f, fs.readFileSync(f, 'utf8'));
+		return fileTextCache.get(f);
+	};
+	const moduleNameByFile = resolveGenericModuleNames(files, readFile, projectRoot);
 	const modules = new Map();
 	const moduleEntry = (name) => {
 		if (!modules.has(name)) modules.set(name, { module: name, controllers: [], entities: [], enums: [], dtos: [] });
@@ -298,13 +355,15 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 	const allEntities = [];
 	const allDtos = [];
 	for (const file of files) {
-		const text = fs.readFileSync(file, 'utf8');
+		const text = readFile(file);
 
 		if (/APIRouter\s*\(/.test(text)) {
 			// module = filename stem, NOT the router's own prefix -- verified against the real oracle's
 			// login.py, which declares `APIRouter(tags=["login"])` with no prefix at all, so a
 			// prefix-derived name fails on a real file while the filename stem works for every one.
-			const moduleName = path.basename(file, '.py');
+			// D-fastapi-generic-module-name: for a GENERIC stem (`endpoints`/`router`), this is the
+			// collision-safe, directory-derived name instead -- see resolveGenericModuleNames() above.
+			const moduleName = moduleNameByFile.get(file);
 			const routerPrefixes = extractRouterPrefixes(text);
 			const rawEndpoints = extractEndpoints(text);
 

package/scanners/index.mjs

@@ -265,7 +265,7 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	}
 
 	return {
-		schema: 'sbf.scan-report/1',
+		schema: 'sbf.scan-report/2',
 		terms,
 		adapter,
 		confidence,

package/schemas/conformance-report.schema.json

@@ -30,7 +30,9 @@
         "matched": { "type": "integer", "minimum": 0, "description": "receipts whose contract_ref equals the CURRENT contract hash -- these count as evidence for the current contract." },
         "stale_contract_ref": { "type": "integer", "minimum": 0, "description": "receipts recorded against a contract_ref that no longer matches -- kept on record for audit/trend purposes, not counted as current evidence." },
         "violations": { "type": "integer", "minimum": 0 },
-        "unsupported": { "type": "integer", "minimum": 0 }
+        "unsupported": { "type": "integer", "minimum": 0 },
+        "unsigned": { "type": "integer", "minimum": 0, "description": "receipts with no signature field -- computed regardless of --pubkey, for forward visibility." },
+        "signature_invalid": { "type": "integer", "minimum": 0, "description": "receipts whose signature field failed verification -- only ever non-zero when --pubkey was given; meaningless (always 0) otherwise. Excluded from matched/violations, same as stale_contract_ref." }
       }
     },
     "by_operation": {
@@ -44,6 +46,15 @@
           "violations": { "type": "integer", "minimum": 0 }
         }
       }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Whether signature verification was even attempted at generation time -- without this, signature_invalid: 0 is ambiguous between 'verified, zero invalid' and 'never checked'. See D-runtime-conformance-receipts.",
+      "properties": {
+        "pubkey_given": { "type": "boolean" },
+        "require_signature": { "type": "boolean" }
+      }
     }
   }
 }

package/schemas/observe-receipt.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "urn:sbf:observe-receipt:1",
   "title": "backend-skeleton runtime contract-conformance receipt",
-  "description": "One JSONL line ContractObservationAspect logs per @ObserveContract-annotated call. Verdict-only, by design -- never carries an observed request/response VALUE, only pointers + constraint kinds. See DECISIONS.md D-runtime-conformance-receipts. `bskel observe import --receipts <path>` reads a stream of these.",
+  "description": "One JSONL line ContractObservationAspect logs per @ObserveContract-annotated call. Verdict-only, by design -- never carries an observed request/response VALUE, only pointers + constraint kinds. See DECISIONS.md D-runtime-conformance-receipts. `bskel observe import --receipts <path>` reads a stream of these. `signature` is optional -- unsigned receipts stay valid; `bskel observe import --pubkey <path>` opts into verifying it where present. See the D-runtime-conformance-receipts 'cryptographic receipt attestation' Update note.",
   "type": "object",
   "additionalProperties": false,
   "required": ["feature_id", "feature_uid", "operation_id", "contract_ref", "verb", "recorded_at", "violations"],
@@ -27,6 +27,15 @@
           "message": { "type": "string", "maxLength": 300 }
         }
       }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algorithm", "value"],
+      "properties": {
+        "algorithm": { "const": "ed25519" },
+        "value": { "type": "string", "description": "base64-encoded raw Ed25519 signature bytes over the canonicalized receipt (this field excluded)." }
+      }
     }
   }
 }

package/schemas/scan-report.schema.json

@@ -6,7 +6,7 @@
   "additionalProperties": false,
   "required": ["schema", "terms", "adapter", "verdict", "related_modules", "collisions", "unknowns", "files_read"],
   "properties": {
-    "schema": { "const": "sbf.scan-report/1" },
+    "schema": { "const": "sbf.scan-report/2" },
     "feature_id": { "type": "string" },
     "terms": { "type": "array", "items": { "type": "string" } },
     "adapter": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },