backend-skeleton 1.1.0 → 1.2.0

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/plan.mjs

@@ -172,11 +172,18 @@ export function plan({ repoRoot, scanReport, module: moduleName, resourceFilter
 	for (const entity of targetModule.entities) {
 		if (resourceFilter && !resourceFilter.includes(entity.className)) continue;
 		const fetchRoute = findFetchRoute(targetModule.controllers, entity.className);
-		const handlerFile = fetchRoute ? resolveHandlerFile(fetchRoute.file, fetchRoute.method, srcRoot) : null;
+		// D-typescript-express-inline-handlers: `method === null` means the scanner found a real
+		// route but its handler is an inline function expression, not a named export -- there is
+		// genuinely nothing for resolveHandlerFile()'s import/barrel-hop search to correlate to, so
+		// this is checked explicitly (a clear, named reason) rather than relying on the incidental
+		// fact that a regex built from the literal string "null" also happens not to match anything.
+		const handlerFile = fetchRoute && fetchRoute.method ? resolveHandlerFile(fetchRoute.file, fetchRoute.method, srcRoot) : null;
 		const selectFields = handlerFile ? findSelectAllowList(handlerFile) : null;
 
 		if (!fetchRoute) {
 			notes.push(`${entity.className}: no single-resource GET route found on a router whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
+		} else if (!fetchRoute.method) {
+			notes.push(`${entity.className}: the single-resource GET route's handler is an inline function expression, not a named export -- nothing to correlate to a defining file, resolver NOT generated.`);
 		} else if (!handlerFile) {
 			notes.push(`${entity.className}: could not resolve ${fetchRoute.method}'s own defining file (import, or one barrel hop, from ${path.relative(repoRoot, fetchRoute.file)}) -- resolver NOT generated.`);
 		} else if (!selectFields) {

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.0",
+  "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/_java-spring-analyzer.mjs

@@ -149,7 +149,22 @@ const MAPPING_VERBS = ['Get', 'Post', 'Put', 'Patch', 'Delete'];
 const MAPPING_ANNOTATION_RE = new RegExp(`@(?:(${MAPPING_VERBS.join('|')})Mapping|RequestMapping)\\b`, 'g');
 const REQUEST_MAPPING_RE = /@RequestMapping\b/g;
 const CLASS_OR_RECORD_START_RE = /^(?:public\s+)?(?:class|record)\b/;
-const REQUEST_MAPPING_METHOD_RE = /\bmethod\s*=\s*RequestMethod\.(\w+)\b/;
+// D-java-spring-static-import-method: `RequestMethod.` prefix made optional -- confirmed live,
+// dogfooding against a real, popular repo (gothinkster/spring-boot-realworld-example-app, 1,584
+// real GitHub stars): its UsersApi.java (register + login, 2 of the RealWorld spec's most
+// fundamental endpoints) uses `import static ... RequestMethod.POST;` then bare
+// `@RequestMapping(path = "/users", method = POST)` -- a real, common Java style (static-import a
+// single enum constant to cut the qualifier) the original prefix-required regex silently missed
+// (0/2 endpoints on this file; the OTHER 15/17 endpoints in this same corpus, using
+// @PostMapping/@GetMapping shorthand elsewhere, were unaffected and already correct). The verb
+// alternation is restricted to Spring's own real `RequestMethod` enum's 8 actual values (GET,
+// HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE) rather than a bare `\w+` -- narrower than
+// "any identifier", so an unrelated `method = someVariable` still correctly fails to match rather
+// than being misread as a verb. Verified live: the existing multi-verb array form (`method =
+// {RequestMethod.GET, RequestMethod.POST}`, still deliberately unresolved/skipped) does NOT
+// accidentally partial-match here -- the array's own `{` breaks the match before any verb name is
+// reached, same as before this change.
+const REQUEST_MAPPING_METHOD_RE = /\bmethod\s*=\s*(?:RequestMethod\.)?(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|TRACE)\b/;
 
 // True when `class`/`record` is the next real declaration after `index`, ONE OR MORE further
 // annotations allowed in between (e.g. a real oracle shape: `@RequestMapping(...)