backend-skeleton 1.0.0-beta.4 → 1.0.0-beta.5

package/README.md

@@ -24,13 +24,17 @@ stable. Split by actual maturity, not by feature list:
   measured verification against a real production Spring Boot repo (see `DECISIONS.md`), plus a
   synthetic fixture corpus for every adapter, run in CI on every change.
 - **`handles`** (the UUID-addressable resolver/codec/router codegen) is functionally complete and
-  tested the same way, but has never been deployed to a real production repo, and two named gaps
-  stay open specifically because of that: generated `fetch()`/`patch()` paths never check
-  `HandleRegistry` for revocation, and generated authorization is inferred from a single
-  `@PreAuthorize(hasRole(...))` shape rather than a real policy contract. Both are tracked as `O3`
-  and `O5` in `CATALOG.md`, explicitly deferred until handles are actually used somewhere real --
-  treat `handles emit`'s output as a scaffold to finish by hand, not a production-ready subsystem,
-  until that work lands.
+  tested the same way, but has never been deployed to a real production repo. Two gaps named in
+  earlier betas have since been partially closed: `O3` (opt-in `--enforce-registry`, checked
+  fetch/patch/recover against `HandleRegistry`, revocation-aware) and `O5` (fetch/patch now derive
+  independently correct roles instead of silently sharing one) are both implemented -- see
+  `DECISIONS.md`'s `D-handle-registry-enforcement`/`D-resolver-authorization-action-aware`. Real
+  gaps remain and are explicitly still open, not closed: registry enforcement is opt-in, off by
+  default; authorization inference still only recognizes a single `@PreAuthorize(hasRole(...))`
+  shape (`hasAuthority`, role lists, ownership/tenant policy are unaddressed); and Java/Python are
+  the only providers either applies to -- TypeScript Express has no persistent handle table at
+  all. Treat `handles emit`'s output as a scaffold to finish by hand, not a production-ready
+  subsystem, until a real deployment happens.
 
 Version numbers, install instructions, and a real feedback path will firm up as this gets used
 against more real repos.

package/bin/bskel.mjs

@@ -9,7 +9,7 @@ import { repoRoot, localDefaultBranch, fileHistory, showFileAtRevision, headSha,
 import { forceNamedGate, revokeNamedGate, requireNamedGate, passNamedGate, awaitNamedGateDisposition, EXIT } from '../lib/gates.mjs';
 import { REPO_GATE_ID, GATE_NAMES, gateScopeId, requireGateDefinition } from '../lib/gate-definitions.mjs';
 import { getGate, loadState, historyPath } from '../lib/state.mjs';
-import { writeFileAtomic } from '../lib/fsutil.mjs';
+import { writeFileAtomic, sha256File } from '../lib/fsutil.mjs';
 import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
 import { withLockSync } from '../lib/lock.mjs';
 import { specDir, specPath } from '../lib/paths.mjs';
@@ -43,6 +43,10 @@ import { buildOpenApiDocument, pathPrefixCandidates, unreflectedPathPrefixes, ST
 import { loadCatalogEntry, listCatalogChoices, planApply, applyPlan } from '../stack/apply.mjs';
 import { PROVIDERS, PROVIDER_LOAD_ERRORS, providerById } from '../handles/registry.mjs';
 import { detectAstHelperAvailable, runAstClassify } from '../handles/providers/java-spring/ast-bridge.mjs';
+import { detectBasePackage } from '../handles/providers/java-spring/plan.mjs';
+import { emitObserveJavaSpring } from '../handles/providers/java-spring/observe.mjs';
+import { plan as planPythonFastApi } from '../handles/providers/python-fastapi/plan.mjs';
+import { emitObservePythonFastApi } from '../handles/providers/python-fastapi/observe.mjs';
 import { collectGateStatuses, runBuildCheck, checkArtifacts, checkResolverConflicts } from '../lib/verify.mjs';
 import { computeWorkflowState } from '../lib/workflow.mjs';
 import { computeDoctorChecks, WORKFLOWS as DOCTOR_WORKFLOWS } from '../lib/doctor.mjs';
@@ -79,6 +83,8 @@ function usage() {
   bskel handles emit --feature <id> [--module <name>] [--resource type1,type2] [--force --reason "..."] [--check] [--diff] [--enforce-registry on|off --reason "..."]
   bskel handles patch approve --feature <id> [--module <name>] --resource <Type> --field <name> --strategy patch-wrapper|null-means-unchanged --reason "..." [--json]
   bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--json]
+  bskel observe emit --feature <id> [--module <name>] [--force --reason "..."] [--check] [--diff] [--json]
+  bskel observe import --feature <id> --receipts <path> [--json]
   bskel verify --feature <id> [--build [--allow-skip-build]] [--json]
   bskel status [--feature <id>] [--json]
   bskel next [--feature <id>] [--json]
@@ -1972,7 +1978,8 @@ function cmdHandlesEmit(args) {
 			}
 			if (dryRun) console.error(`\n${renderFileActions(actions)}`);
 		}
-		// D-process-exit-audit: bounded by 7 + plan.resources.length units, no pipe-truncation risk.
+		// D-process-exit-audit: bounded by 7 + 2*plan.resources.length units (D-resolver-policy-split:
+		// Resolver + Policy per resource), no pipe-truncation risk.
 		// Carries a real payload (already printed above in --json mode) -- no diagnostic envelope.
 		// P4 precedent (catalog lint): reused, not a new exit code -- --check reaching the exact
 		// same verdict a real run would (exit 15) is the point, not a distinct "check found a
@@ -2135,6 +2142,242 @@ async function cmdHandlesAudit(args) {
 	process.exit(0);
 }
 
+// D-runtime-conformance-receipts: mirrors cmdHandlesEmit's own precondition chain and
+// blocked/--check reporting shape closely -- same "contract must be pass first" gate dependency,
+// same O2-style conflict machinery via emitUnits() (reused unmodified inside
+// emitObserveJavaSpring), same --check/--diff/--force/--reason semantics. Does not pass any gate
+// itself -- only `observe import` (real receipts imported) represents evidence worth gating on.
+function cmdObserveEmit(args) {
+	const flags = parseCommand('observe emit', args);
+	if (flags.help) { console.log(renderCommandHelp('observe emit')); process.exit(0); }
+	setContext('observe emit', flags);
+	const root = requireRepoRoot();
+	requirePreflightPassed(root);
+	if (flags.force && (!flags.reason || !flags.reason.trim())) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel observe emit --force requires --reason "..." -- every overwrite of diverged generated code must be auditable');
+	}
+
+	const contractResult = requireNamedGate(root, 'contract', flags.feature);
+	if (contractResult.code !== EXIT.PASS) {
+		const hint = contractResult.status === 'awaiting_disposition'
+			? `resolve it first -- \`bskel contract waive --feature ${flags.feature} --code <CODE> (--subject "..."|--all) --reason "..."\`, or \`bskel gate force contract --feature ${flags.feature} --reason "..."\` if intentional.`
+			: `run \`bskel contract emit --feature ${flags.feature}\` first.`;
+		fail(contractResult.code, gateReasonForCode(contractResult.code), `blocked: \`contract\` gate for ${flags.feature} is ${contractResult.status} -- ${hint}`, {
+			next_actions: [{ command: `bskel contract emit --feature ${flags.feature}`, reason: 'the contract gate has not passed yet', mutating: true }],
+		});
+	}
+
+	const scanReport = loadScanReportOrExit(root, flags.feature);
+	const contract = loadContract(root, flags.feature);
+	const dryRun = flags.check || flags.diff;
+
+	// D-runtime-conformance-receipts: explicit two-branch dispatch, not handles/registry.mjs's own
+	// provider mechanism -- that registry's schema/loader (a closed plan+emit verb pair) is
+	// specifically shaped for the HANDLES feature (per-resource resolver units); observe has no
+	// `plan` verb and operates directly on contract.operations. Matches this project's own
+	// established precedent for a single-other-provider feature (cmdHandlesPlan's --ast flag: a
+	// bare adapter check, no registry involved) rather than adopting a mechanism built for a
+	// different, unrelated concern.
+	let result;
+	if (scanReport.adapter === 'java-spring') {
+		let basePackage;
+		try {
+			basePackage = detectBasePackage(root);
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+		if (!basePackage) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', 'could not detect the base package (no *Application.java found under src/main/java) -- is this a Spring Boot project?');
+		}
+		try {
+			result = emitObserveJavaSpring({ repoRoot: root, featureId: flags.feature, contract, basePackage, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+	} else if (scanReport.adapter === 'python-fastapi') {
+		// python's own package-root detection needs a module to anchor itself (unlike java's
+		// detectBasePackage(), which needs no module/feature context at all) -- a genuine
+		// CLI-surface asymmetry between the two providers, not an oversight. See DECISIONS.md.
+		let fastApiPlan;
+		try {
+			fastApiPlan = planPythonFastApi({ repoRoot: root, scanReport, module: flags.module, resourceFilter: null });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+		try {
+			result = emitObservePythonFastApi({ repoRoot: root, featureId: flags.feature, contract, plan: fastApiPlan, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+	} else {
+		fail(EXIT_CODES.MISSING_CAPABILITY, 'MISSING_CAPABILITY', `bskel observe emit does not support the "${scanReport.adapter}" adapter yet (supported: java-spring, python-fastapi)`);
+	}
+	const { written, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [] } = result;
+	const wouldChange = actions.some((a) => a.action !== 'unchanged' && a.action !== 'adopt-unchanged');
+	const allNotes = [...notes];
+	if (flags.force && forced.length === 0 && conflicts.length === 0) allNotes.push('--force had no effect: 0 conflicts found in this run\'s scope');
+	else if (flags.force && forced.length > 0) allNotes.push(`--force overwrote ${forced.length} diverged file(s): ${forced.join(', ')}`);
+
+	if (blocked) {
+		if (flags.json) {
+			console.log(JSON.stringify({ written, conflicts, orphans, forced, notes: allNotes, actions, blocked: true, check: dryRun }, null, 2));
+		} else {
+			const verb = dryRun ? 'would be blocked' : 'blocked';
+			console.error(`${verb}: ${conflicts.length} generated file(s) diverged from what backend-skeleton last wrote -- ${dryRun ? 'a real run would refuse to overwrite them' : 'refusing to overwrite'} without --force:`);
+			for (const c of conflicts) console.error(`  ${c.path} (${c.kind})\n    ${c.reason}`);
+			if (written.length > 0) {
+				console.error(`\n${written.length} other file(s) ${dryRun ? 'would still be written' : 'were still written this run'}:`);
+				for (const w of written) console.error(`  ${w}`);
+			}
+			if (!dryRun) console.error(`\nre-run with: bskel observe emit --feature ${flags.feature}${flags.module ? ` --module ${flags.module}` : ''} --force --reason "..."`);
+			if (dryRun) console.error(`\n${renderFileActions(actions)}`);
+		}
+		// D-process-exit-audit: same shape/reasoning as `handles emit`'s own blocked path -- reused
+		// exit code, not a new one (D-cli-contract: numbers are a public contract, not renumbered).
+		process.exit(EXIT_CODES.HANDLES_CONFLICT);
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify({ written, conflicts, orphans, forced, notes: allNotes, actions, blocked: false, check: dryRun, postEmitNotes }, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`${dryRun ? 'would write' : 'wrote'} ${written.length} file(s):`);
+		for (const w of written) console.log(`  ${w}`);
+		if (allNotes.length > 0) {
+			console.log('\nnotes:');
+			for (const n of allNotes) console.log(`  - ${n}`);
+		}
+		if (dryRun) {
+			console.log(`\n${renderFileActions(actions)}`);
+		} else {
+			for (const n of postEmitNotes) console.log(`\n${n}`);
+		}
+	}
+	if (dryRun) process.exit(wouldChange ? EXIT_CODES.CHECK_FAILED : EXIT_CODES.OK);
+	process.exit(0);
+}
+
+// D-runtime-conformance-receipts: validation order mirrors `contract emit --openapi-file`'s
+// "compute+validate everything before writing anything" discipline. Two failure classes on a
+// per-line basis, handled differently -- a line that is not valid JSON at all is NOISE (a human's
+// log pipeline realistically is not perfectly scoped to just the receipts logger), counted and
+// warned, not fatal; a line that IS valid JSON but fails observe-receipt.schema.json is real
+// CORRUPTION -- abort the whole import loudly, same "a bad file must not leave a half-updated
+// state" principle `contract emit --openapi-file` already applies.
+const MAX_RECEIPTS_BYTES = 64 * 1024 * 1024; // provisional -- no real oracle to measure against yet, unlike A1's own measured caps (stated explicitly, not pretended-measured)
+const MAX_RECEIPTS_LINES = 200_000;
+
+function cmdObserveImport(args) {
+	const flags = parseCommand('observe import', args);
+	if (flags.help) { console.log(renderCommandHelp('observe import')); process.exit(0); }
+	setContext('observe import', flags);
+	const root = requireRepoRoot();
+	requirePreflightPassed(root);
+
+	const contractResult = requireNamedGate(root, 'contract', flags.feature);
+	if (contractResult.code !== EXIT.PASS) {
+		fail(contractResult.code, gateReasonForCode(contractResult.code), `blocked: \`contract\` gate for ${flags.feature} is ${contractResult.status} -- receipts are only meaningful against an established contract. Run \`bskel contract emit --feature ${flags.feature}\` first.`);
+	}
+	const contract = loadContract(root, flags.feature);
+
+	let stat;
+	try {
+		stat = fs.statSync(flags.receipts);
+	} catch {
+		fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no readable file at ${flags.receipts}`);
+	}
+	if (!stat.isFile()) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `${flags.receipts} is not a regular file`);
+	}
+	if (stat.size > MAX_RECEIPTS_BYTES) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `${flags.receipts} is ${stat.size} bytes, over the provisional ${MAX_RECEIPTS_BYTES}-byte cap`);
+	}
+
+	const rawLines = fs.readFileSync(flags.receipts, 'utf8').split('\n').filter((l) => l.trim().length > 0);
+	if (rawLines.length > MAX_RECEIPTS_LINES) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `${flags.receipts} has ${rawLines.length} non-empty lines, over the provisional ${MAX_RECEIPTS_LINES}-line cap`);
+	}
+
+	let noiseLines = 0;
+	const receipts = [];
+	for (const line of rawLines) {
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			noiseLines++;
+			continue;
+		}
+		const { ok, errors } = validateAgainstSchema('observe-receipt.schema.json', parsed);
+		if (!ok) {
+			fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `${flags.receipts}: a line is valid JSON but not a valid receipt -- ${formatSchemaErrors(errors).join('; ')}. Aborting the whole import (a corrupted receipts file must not partially land).`);
+		}
+		receipts.push(parsed);
+	}
+
+	for (const r of receipts) {
+		if (r.feature_id !== flags.feature || r.feature_uid !== contract.feature_uid) {
+			fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `${flags.receipts}: a receipt is for feature "${r.feature_id}" (${r.feature_uid}), not "${flags.feature}" (${contract.feature_uid}) -- aborting the whole import (a receipts file for the wrong feature must never partially land).`);
+		}
+	}
+
+	const currentContractHash = sha256File(specPath(root, flags.feature, 'contracts', `${flags.feature}.schema.json`));
+	let matched = 0;
+	let staleContractRef = 0;
+	let violationCount = 0;
+	let unsupportedCount = 0;
+	const byOperation = {};
+	for (const r of receipts) {
+		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 };
+		if (isMatched) opStats.matched++; else opStats.stale_contract_ref++;
+		for (const v of r.violations ?? []) {
+			if (v.keyword === 'unsupported') unsupportedCount++; else violationCount++;
+			if (isMatched) opStats.violations++;
+		}
+		byOperation[r.operation_id] = opStats;
+	}
+
+	const report = {
+		sbf_conformance_report: '1',
+		feature_id: flags.feature,
+		feature_uid: contract.feature_uid,
+		generated_at: new Date().toISOString(),
+		source: describeSourceFile(root, flags.receipts),
+		counts: {
+			receipt_lines: receipts.length,
+			noise_lines: noiseLines,
+			matched, stale_contract_ref: staleContractRef,
+			violations: violationCount,
+			unsupported: unsupportedCount,
+		},
+		by_operation: byOperation,
+	};
+	const { ok: reportOk, errors: reportErrors } = validateAgainstSchema('conformance-report.schema.json', report);
+	if (!reportOk) {
+		fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `internal error: the computed conformance report failed its own schema -- ${formatSchemaErrors(reportErrors).join('; ')}`);
+	}
+
+	const reportPath = specPath(root, flags.feature, 'observe', `${flags.feature}.conformance-report.json`);
+	writeFileAtomic(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+
+	// Evidence-first, not verdict-first (same as `contract`'s own precedent: a `partial` contract
+	// is still passable via waiver) -- passes on a successful STRUCTURAL import, never on "zero
+	// violations found". Whether violation counts should block CI is a policy question for whoever
+	// reads the report, deliberately not decided here -- see DECISIONS.md's own deferred list.
+	const gateState = passNamedGate(root, 'conformance', flags.feature, { receipt_count: receipts.length, matched, violations: violationCount });
+
+	if (flags.json) {
+		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)`);
+		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}`);
+	}
+	process.exit(0);
+}
+
 // S2: "stale" alone sends a human/agent re-running steps until one happens to stick. Name the
 // input that actually moved, using the exact reason requireGate()'s explainStaleness() reports.
 function describeStale(g) {
@@ -2628,6 +2871,13 @@ async function dispatchCommand(cmd, rest) {
 			process.exit(14);
 			break;
 		}
+		case 'observe': {
+			if (rest[0] === 'emit') return cmdObserveEmit(rest.slice(1));
+			if (rest[0] === 'import') return cmdObserveImport(rest.slice(1));
+			usage();
+			process.exit(14);
+			break;
+		}
 		case 'verify':
 			cmdVerify(rest);
 			break;

package/handles/_engine.mjs

@@ -277,5 +277,7 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 
 	if (!dryRun && manifestChanged) saveManifest(repoRoot, manifest);
 
-	return { written, resolverStubs, conflicts, orphans, notes, forced, blocked: conflicts.length > 0, actions };
+	// D-resolver-policy-split: two units (Resolver + Policy) now share one resourceType, so
+	// resolverStubs.push above runs twice per resource -- dedupe here rather than at every push site.
+	return { written, resolverStubs: [...new Set(resolverStubs)], conflicts, orphans, notes, forced, blocked: conflicts.length > 0, actions };
 }

package/handles/observe-schema-projection.mjs

@@ -0,0 +1,92 @@
+// D-runtime-conformance-receipts: pure functions projecting a feature contract's own
+// `operations[opId]` shape down to the bounded, checkable-only structure every observe provider's
+// generated runtime checker understands. Extracted out of handles/providers/java-spring/observe.mjs
+// (the first provider to need this) once python-fastapi needed the identical logic -- nothing here
+// touches java-specific or python-specific concepts, it operates only on the contract's own
+// JSON-schema-shaped fields (contracts/emit.mjs's own output). See DECISIONS.md
+// D-runtime-conformance-receipts, Decision B, for the full "what's checkable is decided ONCE here"
+// reasoning.
+
+// A property this project's own contracts already fully control the generation of when there's
+// nothing deeper than a directly-checkable value -- string/number/integer/boolean with no nested
+// properties/items/$ref/anyOf/allOf/oneOf. What's checkable is decided ONCE here, in JS, at
+// `observe emit` time (baked into a projected, pre-simplified resource for the target runtime);
+// each provider's own generated checker is a dumb, mechanical executor of an already-simplified
+// instruction set, never a second independent JSON-Schema interpreter.
+const SCALAR_TYPES = new Set(['string', 'number', 'integer', 'boolean']);
+
+export function isScalarLeaf(schema) {
+	if (!schema || typeof schema !== 'object') return false;
+	if (schema.properties || schema.items || schema.$ref || schema.anyOf || schema.allOf || schema.oneOf) return false;
+	return typeof schema.type === 'string' && SCALAR_TYPES.has(schema.type);
+}
+
+// Projects a real (possibly arbitrarily deep) JSON Schema object -- contract.operations[id]'s own
+// requestBodySchema/responseSchema/errorSchema, present only when `contract emit --openapi-file`
+// was used and something resolved (contracts/emit.mjs) -- down to the bounded, checkable-only
+// shape every generated checker understands: top-level `required`, scalar-leaf `properties` kept
+// as {type, pattern?}, everything else marked `unsupported` at its own JSON Pointer rather than
+// silently treated as pass. A non-object root (anyOf/allOf/oneOf/$ref/any non-'object' type -- the
+// real shape a multi-status-unioned responseSchema can take) is marked unsupported at the root
+// pointer "" wholesale, rather than guessed into a partial projection.
+export function projectBodySchema(schema) {
+	if (!schema || typeof schema !== 'object') return null;
+	if (schema.anyOf || schema.allOf || schema.oneOf || schema.$ref || schema.type !== 'object') {
+		return { required: [], properties: {}, unsupported: [''] };
+	}
+	const required = Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === 'string') : [];
+	const properties = {};
+	const unsupported = [];
+	for (const [key, propSchema] of Object.entries(schema.properties ?? {})) {
+		if (isScalarLeaf(propSchema)) {
+			properties[key] = { type: propSchema.type, ...(typeof propSchema.pattern === 'string' ? { pattern: propSchema.pattern } : {}) };
+		} else {
+			unsupported.push(`/${key}`);
+		}
+	}
+	return { required, properties, unsupported };
+}
+
+// pathParams is ALWAYS the narrow, bskel-controlled vocabulary contracts/emit.mjs's own
+// pathParamsSchema() produces (type:'object', additionalProperties:false, properties/required,
+// each property {type:'string', pattern?}) -- passed through structurally rather than re-derived,
+// but still routed through the same scalar-leaf check as body properties, defensively, in case a
+// hand-edited contract ever puts something deeper there.
+export function projectPathParams(pathParamsSchema) {
+	const required = Array.isArray(pathParamsSchema?.required) ? pathParamsSchema.required.filter((r) => typeof r === 'string') : [];
+	const properties = {};
+	const unsupported = [];
+	for (const [key, propSchema] of Object.entries(pathParamsSchema?.properties ?? {})) {
+		if (isScalarLeaf(propSchema)) {
+			properties[key] = { type: propSchema.type, ...(typeof propSchema.pattern === 'string' ? { pattern: propSchema.pattern } : {}) };
+		} else {
+			unsupported.push(`/${key}`);
+		}
+	}
+	return { required, properties, unsupported };
+}
+
+// A8: sourceResponses' own keys are literal status codes/ranges/"default" straight from a real
+// source document (schemas/feature-contract.schema.json's own propertyNames pattern), never
+// re-bucketed here -- matching status against them at runtime (a real observed code against
+// "4XX"/"default") is a bounded, mechanical string comparison, not JSON-Schema interpretation, so
+// doing it in each provider's own generated checker doesn't violate the "one interpreter" boundary.
+export function projectStatuses(sourceResponses) {
+	return sourceResponses ? Object.keys(sourceResponses) : null;
+}
+
+export function projectOperation(opContract) {
+	return {
+		verb: opContract.verb,
+		path: opContract.path,
+		pathParams: projectPathParams(opContract.pathParams),
+		// Normalized to always a JSON string ("true"/"false"/"unknown") -- opContract.body is a
+		// true|false|'unknown' tri-state (mixed boolean/string), awkward for a generated checker to
+		// parse unambiguously; String() keeps the projected shape uniformly typed.
+		body: String(opContract.body),
+		request: opContract.body === false ? null : projectBodySchema(opContract.requestBodySchema),
+		response: projectBodySchema(opContract.responseSchema),
+		error: projectBodySchema(opContract.errorSchema),
+		statuses: projectStatuses(opContract.sourceResponses),
+	};
+}

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

@@ -12,6 +12,11 @@ const PROVIDER_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(PROVIDER_ROOT, 'templates');
 const MIGRATION_TEMPLATE = path.join(TEMPLATES_DIR, 'migration.sql.tmpl');
 const RESOLVER_TEMPLATE = path.join(TEMPLATES_DIR, 'ResourceResolverStub.java.tmpl');
+// D-resolver-policy-split: a resource's live-derived, security-relevant declarations
+// (type/requiredAuthority/requiredAuthorityForPatch/contractRef/featureUid) are generated into
+// this separate, always-safe-to-regenerate companion file rather than the same file as the
+// hand-editable patchField() body -- see the template's own javadoc and DECISIONS.md.
+const RESOLVER_POLICY_TEMPLATE = path.join(TEMPLATES_DIR, 'ResourceResolverPolicyStub.java.tmpl');
 
 const INFRA_FILES = [
 	{ template: 'HandleCodec.java.tmpl', target: 'global/handle/HandleCodec.java' },
@@ -146,7 +151,7 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 
 	const resolverUnits = plan.resources
 		.filter((r) => r.willGenerateResolver) // see plan.mjs: no broken imports generated on purpose
-		.map((resource) => {
+		.flatMap((resource) => {
 			const patchable = resource.patchable ?? [];
 			// A blocked update service (see plan.mjs's updateServiceBlockedReason) means NO field of
 			// this resource can be auto-generated regardless of approvals -- ignore any recorded
@@ -155,21 +160,17 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 			const approvedFields = resource.updateServiceBlockedReason ? new Set() : currentlyApprovedFields(patchApprovals, resource.type, patchable);
 			const { needsValidation, needsPatchFieldImport } = computeCodegenNeeds(patchable, approvedFields);
 			const serviceField = lowerFirst(resource.service.serviceType);
-			const vars = {
-				BASE_PACKAGE: basePackage,
-				MODULE: plan.module,
-				RESOURCE_TYPE: resource.type,
+			const sharedVars = { BASE_PACKAGE: basePackage, MODULE: plan.module, RESOURCE_TYPE: resource.type, FEATURE_ID: featureId };
+			// D-resolver-policy-split: the resolver's own vars no longer include the four
+			// live-derived/security-relevant tokens -- those move to policyVars below, into a
+			// separate generated file, specifically so a hand-edited patchField() (which stales
+			// THIS file's own template render) can never block one of those values from updating.
+			const resolverVars = {
+				...sharedVars,
 				SERVICE_IMPORT: `${basePackage}.domain.${plan.module}.application.${resource.service.serviceType}`,
 				SERVICE_TYPE: resource.service.serviceType,
 				SERVICE_FIELD: serviceField,
 				FETCH_METHOD: resource.fetchOperation.method,
-				REQUIRED_AUTHORITY: resource.requiredAuthority,
-				// O5 (D-resolver-authorization-action-aware): independently derived from the UPDATE
-				// endpoint's own @PreAuthorize -- see plan.mjs's own computation.
-				REQUIRED_AUTHORITY_PATCH: resource.requiredAuthorityForPatch,
-				FEATURE_ID: featureId,
-				CONTRACT_REF: contractRef,
-				FEATURE_UID: featureUid,
 				PATCH_IMPORTS: needsValidation ? buildPatchImports({ basePackage, module: plan.module, dtoTypeName: resource.dtoTypeName, needsPatchFieldImport, jacksonPackage }) : '',
 				PATCH_FIELDS: needsValidation ? buildPatchFields() : '',
 				PATCH_FIELD_BODY: renderPatchFieldBody({
@@ -182,27 +183,50 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 					blockedReason: resource.updateServiceBlockedReason,
 				}),
 			};
-			return {
-				id: 'ResourceResolverStub.java.tmpl',
-				resourceType: resource.type,
-				module: plan.module,
-				templatePath: RESOLVER_TEMPLATE,
-				targetAbs: path.join(javaSrcRoot, 'domain', plan.module, 'infrastructure', `${resource.type}Resolver.java`),
-				rendered: render(RESOLVER_TEMPLATE, vars),
-				pristineRenderFor: (ownerId) => render(RESOLVER_TEMPLATE, {
-				...vars,
-				FEATURE_ID: ownerId,
-				CONTRACT_REF: ownerId === featureId ? contractRef : contractRefFor(ownerId),
-				FEATURE_UID: ownerId === featureId ? featureUid : featureUidFor(ownerId),
-			}),
+			const policyVars = {
+				...sharedVars,
+				REQUIRED_AUTHORITY: resource.requiredAuthority,
+				// O5 (D-resolver-authorization-action-aware): independently derived from the UPDATE
+				// endpoint's own @PreAuthorize -- see plan.mjs's own computation.
+				REQUIRED_AUTHORITY_PATCH: resource.requiredAuthorityForPatch,
+				CONTRACT_REF: contractRef,
+				FEATURE_UID: featureUid,
 			};
+			return [
+				{
+					id: 'ResourceResolverStub.java.tmpl',
+					resourceType: resource.type,
+					module: plan.module,
+					templatePath: RESOLVER_TEMPLATE,
+					targetAbs: path.join(javaSrcRoot, 'domain', plan.module, 'infrastructure', `${resource.type}Resolver.java`),
+					rendered: render(RESOLVER_TEMPLATE, resolverVars),
+					// Only FEATURE_ID varies by owner now -- the four moved tokens no longer live here.
+					pristineRenderFor: (ownerId) => render(RESOLVER_TEMPLATE, { ...resolverVars, FEATURE_ID: ownerId }),
+				},
+				{
+					id: 'ResourceResolverPolicyStub.java.tmpl',
+					resourceType: resource.type,
+					module: plan.module,
+					templatePath: RESOLVER_POLICY_TEMPLATE,
+					targetAbs: path.join(javaSrcRoot, 'domain', plan.module, 'infrastructure', `${resource.type}ResolverPolicy.java`),
+					rendered: render(RESOLVER_POLICY_TEMPLATE, policyVars),
+					pristineRenderFor: (ownerId) => render(RESOLVER_POLICY_TEMPLATE, {
+						...policyVars,
+						FEATURE_ID: ownerId,
+						CONTRACT_REF: ownerId === featureId ? contractRef : contractRefFor(ownerId),
+						FEATURE_UID: ownerId === featureId ? featureUid : featureUidFor(ownerId),
+					}),
+				},
+			];
 		});
 
 	const orphanScan = (!resourceFilter && plan.module) ? {
 		dir: path.join(javaSrcRoot, 'domain', plan.module, 'infrastructure'),
 		module: plan.module,
-		matchesFile: (file) => file.endsWith('Resolver.java'),
-		resourceTypeOf: (file, _content) => file.replace(/Resolver\.java$/, ''),
+		// D-resolver-policy-split: recognize both generated suffixes -- longest-first so
+		// 'FooResolverPolicy.java' isn't misclassified as a plain '...Policy' resource type.
+		matchesFile: (file) => file.endsWith('ResolverPolicy.java') || file.endsWith('Resolver.java'),
+		resourceTypeOf: (file, _content) => file.replace(/ResolverPolicy\.java$|Resolver\.java$/, ''),
 	} : null;
 
 	const result = emitUnits({ repoRoot, featureId, provider: 'java-spring', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff });

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

@@ -0,0 +1,93 @@
+// D-runtime-conformance-receipts: the emit-side half of opt-in runtime contract-conformance
+// checking. Kept as its own file, sibling to emit.mjs, rather than folded into it -- observe and
+// handles are orthogonal capabilities (one validates real traffic shape, the other exposes/patches
+// UUID-addressable fields) that happen to share the same repo-wide "generated infra" pattern, not
+// the same feature. See DECISIONS.md for the full WHY.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { emitUnits, unifiedDiff } from '../../_engine.mjs';
+import { sha256File } from '../../../lib/fsutil.mjs';
+import { specPath } from '../../../lib/paths.mjs';
+import { detectJacksonPackage } from './emit.mjs';
+import { projectOperation } from '../../observe-schema-projection.mjs';
+
+const PROVIDER_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(PROVIDER_ROOT, 'templates');
+
+// Repo-wide, shared across every feature that ever runs `bskel observe emit` -- ObserveSchemaLoader
+// discovers every `bskel/*.observed-schema.json` classpath resource at startup rather than being
+// regenerated per feature, so these four files are true infra (create-once-per-repo, all-or-nothing
+// conflict unit), same treatment INFRA_FILES gives handles' own global/handle/* files.
+const INFRA_FILES = [
+	{ template: 'ObserveContract.java.tmpl', target: 'global/observe/ObserveContract.java' },
+	{ 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' },
+];
+
+function render(templatePath, vars) {
+	let content = fs.readFileSync(templatePath, 'utf8');
+	for (const [key, value] of Object.entries(vars)) {
+		content = content.replaceAll(`{{${key}}}`, String(value));
+	}
+	return content;
+}
+
+function writeUnit(target, content) {
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.writeFileSync(target, content);
+}
+
+// isScalarLeaf/projectBodySchema/projectPathParams/projectStatuses/projectOperation moved to
+// handles/observe-schema-projection.mjs (D-runtime-conformance-receipts) -- pure contract-shape
+// logic shared verbatim with python-fastapi/observe.mjs, nothing java-specific about it.
+
+// See DECISIONS.md D-runtime-conformance-receipts. `contract` is the already-loaded, already
+// schema-validated feature contract (bin/bskel.mjs's loadContract) -- this function does not read
+// specs/ itself. `resolverUnits: []`/`orphanScan: null`: there is no per-resource generated file
+// here (a human applies @ObserveContract directly to arbitrary existing methods), so emitUnits()'s
+// resolver/orphan machinery has nothing to do -- confirmed its signature tolerates both.
+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);
+
+	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 }),
+	}));
+
+	const result = emitUnits({ repoRoot, featureId, provider: 'java-spring', force, reason, infraUnits, resolverUnits: [], orphanScan: null, dryRun, computeDiff });
+
+	// The projected observed-schema.json classpath resource -- regenerated unconditionally every
+	// run, like handles' own migration.sql, and for the identical reason: nobody hand-finishes a
+	// generated data file the way they hand-finish a resolver stub, so O2-style conflict tracking
+	// buys nothing here. `kind: 'spec'` matches migration.sql's own action-reporting convention.
+	const operations = {};
+	for (const [opId, opContract] of Object.entries(contract.operations)) {
+		operations[opId] = projectOperation(opContract);
+	}
+	const contractRef = sha256File(specPath(repoRoot, featureId, 'contracts', `${featureId}.schema.json`));
+	const schemaContent = `${JSON.stringify({ sbf_observed_schema: '1', feature_id: featureId, feature_uid: contract.feature_uid, contract_ref: contractRef, operations }, null, '\t')}\n`;
+	const schemaPath = path.join(repoRoot, 'src', 'main', 'resources', 'bskel', `${featureId}.observed-schema.json`);
+	const schemaRelPath = path.relative(repoRoot, schemaPath);
+	const schemaDiskContent = fs.existsSync(schemaPath) ? fs.readFileSync(schemaPath, 'utf8') : null;
+	const schemaAction = schemaDiskContent === null ? 'create' : (schemaDiskContent === schemaContent ? 'unchanged' : 'update');
+	if (!dryRun) writeUnit(schemaPath, schemaContent);
+	result.written.push(schemaRelPath);
+	const schemaActionEntry = { path: schemaRelPath, kind: 'spec', action: schemaAction };
+	if (computeDiff && schemaAction === 'update') schemaActionEntry.diff = unifiedDiff(schemaRelPath, schemaDiskContent, schemaContent);
+	result.actions.push(schemaActionEntry);
+
+	return {
+		...result,
+		postEmitNotes: [
+			'NOT done automatically: ContractObservationAspect.java requires spring-boot-starter-aop on your own build.gradle classpath -- if you already added it for @RecordHandleSnapshot (O4/handles), no new dependency is needed here.',
+			'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).',
+		],
+	};
+}