backend-skeleton 1.0.0-beta.9 → 1.0.0

package/contracts/emit.mjs

@@ -31,8 +31,12 @@ export const CONTRACT_SCHEMA_VERSION = '8';
 // item. `pathParamsHeuristic` names every segment that still fell back, so a downstream consumer
 // (contracts/export.mjs's collectOmissions()) can tell, per operation, whether ANY segment is still
 // a guess -- `null` (never `[]`) when every segment was source-resolved or the route has none.
+// Update (D-openapi-path-params, closing the O8 typescript-express port's own Finding 2): the
+// regex also recognizes Express's own `:name`/`:name(...)` segment syntax now, not just OpenAPI/
+// Spring/FastAPI-style `{name}` -- additive-only for java-spring/python-fastapi (their own route
+// strings never contain a colon in this position).
 function pathParamsSchema(routePath, sourcePathParamSchemas = null) {
-	const params = [...routePath.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+	const params = [...routePath.matchAll(/\{(\w+)\}|:(\w+)(?:\([^)]*\))?/g)].map((m) => m[1] ?? m[2]);
 	const properties = {};
 	const heuristicNames = [];
 	for (const p of params) {

package/contracts/export.mjs

@@ -239,20 +239,37 @@ function renderDescription(contract, omissions, statusCodes) {
 	return lines.join('\n');
 }
 
+// Update (D-openapi-export, closing the gap named in D-openapi-reconciliation's own Update note):
+// rewrites Express's own `:name`/`:name(...)` segments into OpenAPI's `{name}` templating -- an
+// OpenAPI Paths Object key must use `{name}` (verified against the real 3.1 meta-schema), but
+// `op.path` for an unmatched/document-less typescript-express operation is still the scan's own
+// colon syntax. A true no-op for java-spring/python-fastapi (their own paths never contain a colon
+// in this position, confirmed live -- no behavior change).
+function colonPathToBraceSyntax(routePath) {
+	return routePath.replace(/:(\w+)(?:\([^)]*\))?/g, '{$1}');
+}
+
 // Every `{name}` in the path template, in order, deduplicated (OpenAPI forbids two parameters
 // sharing name+location). The schema comes from the contract's own `pathParams.properties`; the
 // `{}` fallback for a name the contract has no property for is "unconstrained", which is both
 // honest and the minimum the 3.1 meta-schema accepts (`$defs.parameter`'s
 // `oneOf: [{required:["schema"]}, {required:["content"]}]` means a parameter MUST carry one or the
 // other -- confirmed by executing the real schema).
+//
+// Update (D-openapi-export, closing the gap named in D-openapi-reconciliation's own Update note):
+// also recognizes Express's own `:name`/`:name(...)` syntax -- `op.path` for a typescript-express
+// operation that never matched/adopted against an OpenAPI document (drift/missing/unresolved/
+// ambiguous, or a document-less scan-only contract) is still the scan's own colon syntax, and this
+// function would otherwise silently list zero path parameters for it. The existing `{name}`
+// branch's own character class (`[^{}/]+`, more permissive than `\w+`) stays untouched.
 function buildPathParameters(op) {
 	const props = op.pathParams && typeof op.pathParams === 'object' && !Array.isArray(op.pathParams)
 		? (op.pathParams.properties ?? {})
 		: {};
 	const seen = new Set();
 	const params = [];
-	for (const match of String(op.path).matchAll(/\{([^{}/]+)\}/g)) {
-		const name = match[1];
+	for (const match of String(op.path).matchAll(/\{([^{}/]+)\}|:(\w+)(?:\([^)]*\))?/g)) {
+		const name = match[1] ?? match[2];
 		if (seen.has(name)) continue;
 		seen.add(name);
 		params.push({
@@ -500,7 +517,13 @@ export function buildOpenApiDocument({ contract, snapshot = null, options = {} }
 
 	for (const operationId of operationIds) {
 		const op = contract.operations[operationId];
-		const route = String(op.path);
+		// Update (D-openapi-export): op.path can still be Express's own colon syntax (a
+		// typescript-express operation that never matched/adopted against an OpenAPI document) --
+		// an OpenAPI Paths Object key must use {name} templating (verified against the real 3.1
+		// meta-schema), so this is rewritten unconditionally here, once, before it becomes both the
+		// document's own path key AND every downstream use of `route` in this loop. A no-op for
+		// java-spring/python-fastapi (their own paths never contain a colon in this position).
+		const route = colonPathToBraceSyntax(String(op.path));
 		if (!route.startsWith('/')) {
 			return { ok: false, error: `operation "${operationId}" has path "${route}", which does not start with "/" -- an OpenAPI Paths Object key must (verified against the official 3.1 meta-schema)` };
 		}

package/contracts/openapi.mjs

@@ -329,6 +329,32 @@ export function normalizeRoute(routePath) {
 	return normalized;
 }
 
+// A1/Finding-1 fix (D-openapi-reconciliation, closing D-runtime-conformance-receipts' own
+// Finding 1, 0047e85): a route MATCH KEY collapses every parameter segment -- both OpenAPI/
+// Spring/FastAPI-style `{name}` and Express's own `:name`/`:name(...)` -- to the identical
+// placeholder, reusing the EXACT SAME two-alternative regex `contracts/emit.mjs`'s
+// pathParamsSchema() already added for the sibling problem (A9, D-openapi-path-params: PARAM-NAME
+// extraction from the scan's own route string). This is for MATCHING two route STRINGS as the same
+// shape, not for naming a parameter -- the name is always discarded (":param" regardless of which
+// name), unlike pathParamsSchema()'s own capture-group use of the same regex. Only ever used to
+// build/read a `byRoute` MAP KEY -- the document's own raw path string (its own `{name}`/`:name`
+// syntax, verbatim) is always what's stored/returned as `entry.path`/`docEntry.path`; no
+// downstream consumer ever sees a literal ":param" segment.
+//
+// Additive-only for java-spring/python-fastapi's existing {name}-only matching: two `{name}`-syntax
+// paths that were string-equal under the old normalizeRoute()-only key stay equal here (every
+// {anyName} collapses to the same placeholder regardless of name); two that were string-UNEQUAL
+// (different LITERAL segments) stay unequal (only parameter segments are touched). The one new
+// theoretical collision -- two really-different real params at the exact same position/verb --
+// was already an inherent REST-design conflict before this fix (no two real routes can coexist
+// that way), and the existing `hits.length > 1 -> kind: 'ambiguous'` handling (reconcileModule,
+// below) already covers a same-key collision safely, never silently picking one -- confirmed no
+// existing fixture in test/contract-openapi.test.mjs or test/contract-cli.test.mjs relies on the
+// opposite.
+export function canonicalRouteShape(routePath) {
+	return normalizeRoute(routePath.replace(/\{(\w+)\}|:(\w+)(?:\([^)]*\))?/g, ':param'));
+}
+
 // Reads and parses exactly once. Every failure mode returns {ok:false, error}, never throws --
 // this is the one function in the module that touches the filesystem, so it's the one place that
 // has to be defensive about a file that's huge, unreadable, not JSON, or JSON-but-not-an-object.
@@ -446,7 +472,7 @@ export function indexOpenApiDocument(doc) {
 			continue;
 		}
 		stats.path_count++;
-		const normalizedRoute = normalizeRoute(routeKey);
+		const routeShape = canonicalRouteShape(routeKey);
 
 		for (const methodKey of Object.keys(pathItem)) {
 			const verbLower = methodKey.toLowerCase();
@@ -498,7 +524,7 @@ export function indexOpenApiDocument(doc) {
 			const description = typeof operation.description === 'string' ? operation.description : null;
 			const entry = { verb, path: routeKey, operationId, requestBody, responses, parameters, security, summary, tags, description };
 
-			const routeMatchKey = `${verb} ${normalizedRoute}`;
+			const routeMatchKey = `${verb} ${routeShape}`;
 			const existingRoute = byRoute.get(routeMatchKey);
 			if (existingRoute) existingRoute.push(entry); else byRoute.set(routeMatchKey, [entry]);
 
@@ -1475,7 +1501,7 @@ export function reconcileModule({ index, module, pathPrefix = null, includeDescr
 				stats.unresolved++;
 			} else {
 				const candidates = prefix.value === '' ? [ep.path] : [...new Set([prefix.value + ep.path, ep.path])];
-				const hits = candidates.flatMap((c) => index.byRoute.get(`${ep.verb} ${normalizeRoute(c)}`) ?? []);
+				const hits = candidates.flatMap((c) => index.byRoute.get(`${ep.verb} ${canonicalRouteShape(c)}`) ?? []);
 				if (hits.length === 0) {
 					result = { kind: 'unresolved', reason: 'no-candidate', scanVerb: ep.verb, scanPath: ep.path };
 					stats.unresolved++;

package/handles/_engine.mjs

@@ -5,11 +5,16 @@
 // D-handles-providers (G4) in DECISIONS.md. `handles/providers/java-spring/emit.mjs` is the
 // reference caller to compare against if this file's behavior is ever in question.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { sha256File, sha256String } from '../lib/fsutil.mjs';
 import { loadManifest, saveManifest, classifyFile, extractResolverOwnerFeatureId, BSKEL_GENERATED_MARKER } from '../lib/handles-manifest.mjs';
+// D-patch-transactions: unifiedDiff() moved to lib/diff.mjs (stack/config-apply.mjs needs the
+// identical mechanism for its own collateral-diff safety gate) -- re-exported here so every
+// existing caller in this file keeps working unchanged.
+import { unifiedDiff } from '../lib/diff.mjs';
+
+export { unifiedDiff };
 
 function readIfExists(target) {
 	return fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
@@ -20,33 +25,6 @@ function writeUnit(target, content) {
 	fs.writeFileSync(target, content);
 }
 
-// D4 (D-handles-dryrun): a real unified diff via `git diff --no-index`, not a hand-rolled diff
-// algorithm -- `git` is already a hard dependency (isDirtyOrUntracked below already shells out to
-// it on every emit), so this adds zero new dependencies. `cwd: tmpDir` + relative `a/<relPath>`/
-// `b/<relPath>` paths (rather than absolute temp paths) keep the diff header clean and
-// reproducible -- the random tmpdir name never leaks into the output. `git diff --no-index` exits
-// 1 when the two sides differ (the expected, common case here, not a failure) -- only a status
-// other than 0/1 is a genuine error worth throwing.
-export function unifiedDiff(relPath, before, after) {
-	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bskel-handles-diff-'));
-	try {
-		const beforeAbs = path.join(tmpDir, 'a', relPath);
-		const afterAbs = path.join(tmpDir, 'b', relPath);
-		fs.mkdirSync(path.dirname(beforeAbs), { recursive: true });
-		fs.mkdirSync(path.dirname(afterAbs), { recursive: true });
-		fs.writeFileSync(beforeAbs, before ?? '');
-		fs.writeFileSync(afterAbs, after ?? '');
-		try {
-			return execFileSync('git', ['diff', '--no-index', '--no-color', '--', `a/${relPath}`, `b/${relPath}`], { cwd: tmpDir, encoding: 'utf8' });
-		} catch (err) {
-			if (err.status === 1 && typeof err.stdout === 'string') return err.stdout;
-			throw err;
-		}
-	} finally {
-		fs.rmSync(tmpDir, { recursive: true, force: true });
-	}
-}
-
 const DIFFABLE_ACTIONS = new Set(['update', 'conflict', 'adopt-update']);
 
 // O2: refuses --force on a target that isn't safely recoverable from git history -- a --force
@@ -79,7 +57,17 @@ function isDirtyOrUntracked(repoRoot, absPath) {
 //   computeDiff:   D4 -- when true, attaches a real unified diff (git diff --no-index) to every
 //                  'update'/'conflict'/'adopt-update' action -- the only 3 where content actually
 //                  differs. Off by default since it shells out to git per diffable file.
-export function emitUnits({ repoRoot, featureId, provider, force = false, reason = '', infraUnits, resolverUnits, orphanScan, dryRun = false, computeDiff = false }) {
+//   postResolverUnit: D-patch-transactions (Continued) -- an OPTIONAL single unit, { id,
+//                  templatePath, targetAbs, render() => string }, whose correct content can only
+//                  be computed AFTER resolverUnits above have been written (e.g. typescript-
+//                  express's resolvers_index.ts barrel -- its import list must reflect the
+//                  resolvers directory's REAL final on-disk listing, including this run's own
+//                  just-written resolver files, not just this run's own resolverUnits -- a 4th
+//                  infraUnits entry can't do this, since infra is processed BEFORE resolvers).
+//                  Reuses the exact same classify/conflict/force/manifest logic the infra loop
+//                  above already implements, applied to exactly one repo-owned (kind: 'infra')
+//                  unit. null (the default) is a true no-op.
+export function emitUnits({ repoRoot, featureId, provider, force = false, reason = '', infraUnits, resolverUnits, orphanScan, dryRun = false, computeDiff = false, postResolverUnit = null }) {
 	const manifest = loadManifest(repoRoot);
 	const nowIso = new Date().toISOString();
 
@@ -245,6 +233,68 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 		recordAction({ relPath, kind: 'resolver', action, resourceType: u.resourceType, diskContent, rendered: u.rendered });
 	}
 
+	// ---- post-resolver unit: an OPTIONAL single unit whose correct content can only be computed
+	// AFTER the resolver loop above has finished writing (e.g. typescript-express's
+	// resolvers_index.ts barrel -- its import list must reflect the resolvers directory's REAL
+	// on-disk listing, including THIS run's own just-written resolver files, not just this run's
+	// own resolverUnits). Reuses the EXACT SAME classify/conflict/force/manifest logic the infra
+	// loop above already implements, applied to exactly one unit. `render()` is called HERE, not
+	// earlier, precisely so it observes this run's own writes. null (the default) is a true no-op
+	// -- java-spring/python-fastapi never pass this, so this block never executes for them. See
+	// D-patch-transactions (Continued) in DECISIONS.md for why this couldn't just be a 4th
+	// infraUnits entry. ----
+	if (postResolverUnit) {
+		const u = postResolverUnit;
+		const rendered = u.render();
+		const relPath = path.relative(repoRoot, u.targetAbs);
+		const diskContent = readIfExists(u.targetAbs);
+		const exists = diskContent !== null;
+		const diskHash = exists ? sha256String(diskContent) : null;
+		const freshRenderHash = sha256String(rendered);
+		const entry = manifest.files[relPath];
+		const matchesPristineRender = exists && diskContent === rendered;
+		const action = classifyFile({ exists, diskHash, manifestEntryHash: entry?.generated_hash ?? null, freshRenderHash, matchesPristineRender });
+
+		if (action === 'conflict' && !force) {
+			conflicts.push({ path: relPath, kind: 'infra', reason: 'diverged from the last content backend-skeleton generated -- see notes for remediation' });
+			recordAction({ relPath, kind: 'infra', action, diskContent, rendered });
+		} else if (action === 'conflict') {
+			if (isDirtyOrUntracked(repoRoot, u.targetAbs)) {
+				conflicts.push({ path: relPath, kind: 'infra', reason: 'refusing --force: this file has uncommitted/untracked changes -- commit or stash it first so the overwrite is recoverable' });
+				recordAction({ relPath, kind: 'infra', action, diskContent, rendered });
+			} else {
+				if (!dryRun) {
+					manifest.files[relPath] = {
+						kind: 'infra', ownership: 'repo', owner: '_repo', provider, template: u.id,
+						template_hash: sha256File(u.templatePath), generated_hash: freshRenderHash,
+						updated_at: nowIso, last_force: { reason, at: nowIso },
+					};
+					manifestChanged = true;
+					writeUnit(u.targetAbs, rendered);
+				}
+				written.push(relPath);
+				forced.push(relPath);
+				recordAction({ relPath, kind: 'infra', action, diskContent, rendered });
+			}
+		} else if (action === 'unchanged') {
+			recordAction({ relPath, kind: 'infra', action });
+		} else {
+			if (action !== 'adopt-unchanged') {
+				if (!dryRun) writeUnit(u.targetAbs, rendered);
+				written.push(relPath);
+			}
+			if (!dryRun) {
+				manifest.files[relPath] = {
+					kind: 'infra', ownership: 'repo', owner: '_repo', provider, template: u.id,
+					template_hash: sha256File(u.templatePath), generated_hash: freshRenderHash,
+					updated_at: nowIso,
+				};
+				manifestChanged = true;
+			}
+			recordAction({ relPath, kind: 'infra', action, diskContent, rendered });
+		}
+	}
+
 	// ---- orphan detection: a resolver this feature's CURRENT plan no longer generates, left
 	// untouched and never deleted -- same conservative bias as D-migration-scope/D-config-patch.
 	// Suppressed entirely under --resource (orphanScan === null), since every resource outside the

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

@@ -121,6 +121,7 @@ function planPatchable({ javaSrcRoot, module: moduleName, controllers, entityCla
 // below already consumes -- findRequiredAuthority()/extractPreAuthorize()/classBodyStart() are
 // completely unchanged, D-security-7's own region-carving logic untouched.
 const HAS_ROLE_RE = /@PreAuthorize\(\s*"hasRole\('([^']+)'\)"\s*\)/;
+const HAS_AUTHORITY_RE = /@PreAuthorize\(\s*"hasAuthority\('([^']+)'\)"\s*\)/;
 const PRE_AUTH_RE = /@PreAuthorize\(/;
 
 function methodMappingBoundaries(text) {
@@ -138,14 +139,26 @@ function classBodyStart(text) {
 }
 
 // Returns { authority, unsupported } for an @PreAuthorize search over one region of source text.
-// `unsupported: true` means an @PreAuthorize annotation IS present but isn't the simple
-// hasRole('X') shape this regex-based scanner understands (hasAnyRole, SpEL, etc.) -- the caller
-// must fail closed (TODO_ROLE) rather than silently treating it as "no authority found" and
-// falling back to a weaker/wrong source.
+// `unsupported: true` means an @PreAuthorize annotation IS present but isn't one of the two
+// simple shapes this regex-based scanner understands (hasAnyRole, hasAnyAuthority, SpEL, etc.) --
+// the caller must fail closed (TODO_ROLE) rather than silently treating it as "no authority
+// found" and falling back to a weaker/wrong source.
+//
+// O5 (D-resolver-authorization-action-aware, hasAuthority follow-up): hasRole('X') and
+// hasAuthority('X') are NOT interchangeable at the Spring Security level -- hasRole('X') checks
+// for the granted authority "ROLE_X" (an implicit prefix Spring itself applies), hasAuthority('X')
+// checks for "X" verbatim. The returned `authority` string is the LITERAL granted-authority value
+// the generated code must match, decided HERE (plan time), not left for the template to re-derive
+// -- HandleController.java.tmpl's requireAuthority() does one plain equality check regardless of
+// which shape produced the value. This is the real discriminant this item's own EXIT note named:
+// widening the regex alone, without this prefix decision, would generate an incorrect check.
 function extractPreAuthorize(region) {
 	if (!PRE_AUTH_RE.test(region)) return null;
 	const hasRoleMatch = region.match(HAS_ROLE_RE);
-	return hasRoleMatch ? { authority: hasRoleMatch[1], unsupported: false } : { authority: null, unsupported: true };
+	if (hasRoleMatch) return { authority: `ROLE_${hasRoleMatch[1]}`, unsupported: false };
+	const hasAuthorityMatch = region.match(HAS_AUTHORITY_RE);
+	if (hasAuthorityMatch) return { authority: hasAuthorityMatch[1], unsupported: false };
+	return { authority: null, unsupported: true };
 }
 
 // D-security-7: a controller with more than one method can require DIFFERENT roles per method --
@@ -253,14 +266,14 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 		if (!fetchOp) {
 			notes.push(`${entity.className}: no single-resource GET endpoint found on a controller whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
 		} else if (authorityResult.unsupported) {
-			notes.push(`${entity.className}: @PreAuthorize found on ${fetchOp.controllerClassName}.${fetchOp.method} (or its class) but not in the simple hasRole('X') shape this scanner understands (e.g. hasAnyRole/SpEL) -- requiredAuthority() defaults to "TODO_ROLE" (fails closed) until a human fixes it`);
+			notes.push(`${entity.className}: @PreAuthorize found on ${fetchOp.controllerClassName}.${fetchOp.method} (or its class) but not in the simple hasRole('X')/hasAuthority('X') shape this scanner understands (e.g. hasAnyRole/SpEL) -- requiredAuthority() defaults to "TODO_ROLE" (fails closed) until a human fixes it`);
 		} else if (!requiredAuthority) {
-			notes.push(`${entity.className}: no method-level or class-level @PreAuthorize(hasRole(...)) found for ${fetchOp.controllerClassName}.${fetchOp.method} -- requiredAuthority() defaults to "TODO_ROLE", fix before relying on it`);
+			notes.push(`${entity.className}: no method-level or class-level @PreAuthorize(hasRole(...)/hasAuthority(...)) found for ${fetchOp.controllerClassName}.${fetchOp.method} -- requiredAuthority() defaults to "TODO_ROLE", fix before relying on it`);
 		}
 		if (updateOpForAuthority && patchAuthorityResult.unsupported) {
-			notes.push(`${entity.className}: @PreAuthorize found on ${updateOpForAuthority.controllerClassName}.${updateOpForAuthority.method} (or its class) but not in the simple hasRole('X') shape this scanner understands -- requiredAuthorityForPatch() defaults to "TODO_ROLE" (fails closed) until a human fixes it`);
+			notes.push(`${entity.className}: @PreAuthorize found on ${updateOpForAuthority.controllerClassName}.${updateOpForAuthority.method} (or its class) but not in the simple hasRole('X')/hasAuthority('X') shape this scanner understands -- requiredAuthorityForPatch() defaults to "TODO_ROLE" (fails closed) until a human fixes it`);
 		} else if (updateOpForAuthority && !requiredAuthorityForPatch) {
-			notes.push(`${entity.className}: no method-level or class-level @PreAuthorize(hasRole(...)) found for ${updateOpForAuthority.controllerClassName}.${updateOpForAuthority.method} -- requiredAuthorityForPatch() defaults to "TODO_ROLE", fix before relying on it`);
+			notes.push(`${entity.className}: no method-level or class-level @PreAuthorize(hasRole(...)/hasAuthority(...)) found for ${updateOpForAuthority.controllerClassName}.${updateOpForAuthority.method} -- requiredAuthorityForPatch() defaults to "TODO_ROLE", fix before relying on it`);
 		}
 		if (!service) {
 			notes.push(`${entity.className}: no ${entity.className}Service found under domain/${targetModule.module}/application/ -- resolver NOT generated for this entity (would produce a broken import). Emit it by hand once the right service is identified.`);

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

@@ -200,12 +200,16 @@ public class HandleController {
 				.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "no active registration for this handle"));
 	}
 
-	private void requireAuthority(String requiredRole) {
+	// O5 (D-resolver-authorization-action-aware, hasAuthority follow-up): a plain equality check --
+	// the ROLE_ prefix Spring Security implicitly applies for hasRole('X') (but not hasAuthority('X'))
+	// is already baked into requiredAuthority by plan.mjs's extractPreAuthorize() at handles-plan
+	// time, so this method never needs to know which source annotation shape produced the value.
+	private void requireAuthority(String requiredAuthority) {
 		boolean granted = SecurityContextHolder.getContext().getAuthentication().getAuthorities().stream()
 				.map(GrantedAuthority::getAuthority)
-				.anyMatch(authority -> authority.equals("ROLE_" + requiredRole));
+				.anyMatch(authority -> authority.equals(requiredAuthority));
 		if (!granted) {
-			throw new ResponseStatusException(HttpStatus.FORBIDDEN, "requires role " + requiredRole);
+			throw new ResponseStatusException(HttpStatus.FORBIDDEN, "requires authority " + requiredAuthority);
 		}
 	}
 }

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

@@ -33,12 +33,18 @@ public interface ResourceResolver {
 	void patchField(UUID resourceUid, String pointer, Object value);
 
 	/**
-	 * Spring Security role name (no "ROLE_" prefix) required to {@code fetch}/{@code recover}
-	 * this resource type via a handle. O5 (D-resolver-authorization-action-aware): derived from
-	 * the entity's FETCH (GET) endpoint's own {@code @PreAuthorize} -- deliberately NOT reused
-	 * for {@link #patchField}, which has its own {@link #requiredAuthorityForPatch()} derived
-	 * from the entity's real UPDATE endpoint instead, since a real app's GET and PATCH endpoints
-	 * can (and often do) require genuinely different roles.
+	 * The literal Spring Security granted-authority string required to {@code fetch}/{@code
+	 * recover} this resource type via a handle -- e.g. {@code "ROLE_ADMIN"} when the source
+	 * {@code @PreAuthorize} was {@code hasRole('ADMIN')} (Spring implicitly applies the
+	 * {@code ROLE_} prefix), or a bare value like {@code "ADMIN"} when the source was
+	 * {@code hasAuthority('ADMIN')} (no prefix). This distinction is decided once, at
+	 * {@code bskel handles plan} time, by {@code extractPreAuthorize()} -- callers of this method
+	 * never need to know which source annotation shape produced the value; they compare it
+	 * verbatim against a granted authority. O5 (D-resolver-authorization-action-aware): derived
+	 * from the entity's FETCH (GET) endpoint's own {@code @PreAuthorize} -- deliberately NOT
+	 * reused for {@link #patchField}, which has its own {@link #requiredAuthorityForPatch()}
+	 * derived from the entity's real UPDATE endpoint instead, since a real app's GET and PATCH
+	 * endpoints can (and often do) require genuinely different roles.
 	 */
 	String requiredAuthority();
 

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

@@ -23,6 +23,16 @@ Requires nothing extra installed (unlike Java's spring-boot-starter-aop) -- Pyth
 no framework support -- but still requires a human to apply it to their own code; codegen never
 touches an existing business logic file.
 
+CRITICAL, python-specific correctness requirement (see DECISIONS.md D-runtime-conformance-receipts's
+own async-wrapper note, and observe_contract.py's identical dual-wrapper shape in this same
+directory): detects whether the wrapped function is a coroutine function
+(`inspect.iscoroutinefunction`) at DECORATION time and dispatches to a genuinely separate async
+wrapper (awaiting the wrapped call) vs. sync wrapper (calling it directly). A single wrapper naively
+calling an async function without awaiting it would return an unawaited coroutine object as the
+"result" -- the "response" snapshot would then record that coroutine object instead of the real
+result, and the "error" snapshot path would never fire even when the real async call later raises
+(calling an async function does not raise synchronously; only awaiting it does).
+
 Example:
     @record_snapshot(resource_type="Organization", operation_id="update_organization",
                       resource_uid_param="organization_id", session_param="session",
@@ -110,45 +120,97 @@ def record_snapshot(*, resource_type: str, operation_id: str, resource_uid_param
     def decorator(fn):
         signature = inspect.signature(fn)
 
-        @functools.wraps(fn)
-        def wrapper(*args, **kwargs):
-            bound = signature.bind(*args, **kwargs)
-            bound.apply_defaults()
-
-            resolver = resolver_for(resource_type)
-            if resolver is None:
-                logger.warning('record_snapshot: no resolver registered for resource_type "%s" on %s -- skipping snapshot recording, the wrapped call proceeds unaffected', resource_type, fn.__qualname__)
-                return fn(*args, **kwargs)
-
-            resource_uid = bound.arguments.get(resource_uid_param)
-            if not isinstance(resource_uid, uuid.UUID):
-                logger.warning('record_snapshot: resource_uid_param "%s" on %s does not resolve to a UUID argument -- skipping snapshot recording, the wrapped call proceeds unaffected', resource_uid_param, fn.__qualname__)
-                return fn(*args, **kwargs)
-
-            session = bound.arguments.get(session_param)
-            handle_uid = uuid.UUID(derive_handle_uid("r", resource_type, str(resource_uid), None))
-            contract_ref = resolver.contract_ref
-
-            def _register_and_record(envelope_dir, payload):
-                handle_service.register(session, "r", resource_type, resource_uid, None, resolver.feature_uid, operation_id, contract_ref)
-                handle_service.record_snapshot(session, handle_uid, envelope_dir, operation_id, contract_ref, payload)
-
-            def _record(envelope_dir, payload):
-                if isinstance(payload, (dict, list)):
-                    for pointer in redact:
-                        _redact(payload, pointer)
-                _safely(lambda: _register_and_record(envelope_dir, payload), handle_uid, envelope_dir)
-
-            request_payload = _request_payload(bound, resource_uid_param, session_param)
-            _record("request", request_payload)
-
-            try:
-                result = fn(*args, **kwargs)
-            except Exception as exc:
-                _record("error", {"message": str(exc)})
-                raise
-            _record("response", _to_jsonable(result))
-            return result
+        # CRITICAL, python-specific correctness requirement (see DECISIONS.md
+        # D-runtime-conformance-receipts's own async-wrapper note, ported here for the same reason):
+        # detects whether the wrapped function is a coroutine function (inspect.iscoroutinefunction)
+        # at DECORATION time and dispatches to a genuinely separate async wrapper (awaiting the
+        # wrapped call) vs. sync wrapper (calling it directly). A single wrapper naively calling an
+        # async function without awaiting it returns an unawaited coroutine object as "result" --
+        # the "response" snapshot then records that coroutine object instead of the real result, and
+        # the "error" snapshot path never fires even when the real async call later raises (calling
+        # an async function does not raise synchronously; only awaiting it does). This mirrors
+        # observe_contract.py's own dual-wrapper shape exactly, deliberately, so both decorators in
+        # this file handle async the same way.
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def wrapper(*args, **kwargs):
+                bound = signature.bind(*args, **kwargs)
+                bound.apply_defaults()
+
+                resolver = resolver_for(resource_type)
+                if resolver is None:
+                    logger.warning('record_snapshot: no resolver registered for resource_type "%s" on %s -- skipping snapshot recording, the wrapped call proceeds unaffected', resource_type, fn.__qualname__)
+                    return await fn(*args, **kwargs)
+
+                resource_uid = bound.arguments.get(resource_uid_param)
+                if not isinstance(resource_uid, uuid.UUID):
+                    logger.warning('record_snapshot: resource_uid_param "%s" on %s does not resolve to a UUID argument -- skipping snapshot recording, the wrapped call proceeds unaffected', resource_uid_param, fn.__qualname__)
+                    return await fn(*args, **kwargs)
+
+                session = bound.arguments.get(session_param)
+                handle_uid = uuid.UUID(derive_handle_uid("r", resource_type, str(resource_uid), None))
+                contract_ref = resolver.contract_ref
+
+                def _register_and_record(envelope_dir, payload):
+                    handle_service.register(session, "r", resource_type, resource_uid, None, resolver.feature_uid, operation_id, contract_ref)
+                    handle_service.record_snapshot(session, handle_uid, envelope_dir, operation_id, contract_ref, payload)
+
+                def _record(envelope_dir, payload):
+                    if isinstance(payload, (dict, list)):
+                        for pointer in redact:
+                            _redact(payload, pointer)
+                    _safely(lambda: _register_and_record(envelope_dir, payload), handle_uid, envelope_dir)
+
+                request_payload = _request_payload(bound, resource_uid_param, session_param)
+                _record("request", request_payload)
+
+                try:
+                    result = await fn(*args, **kwargs)
+                except Exception as exc:
+                    _record("error", {"message": str(exc)})
+                    raise
+                _record("response", _to_jsonable(result))
+                return result
+        else:
+            @functools.wraps(fn)
+            def wrapper(*args, **kwargs):
+                bound = signature.bind(*args, **kwargs)
+                bound.apply_defaults()
+
+                resolver = resolver_for(resource_type)
+                if resolver is None:
+                    logger.warning('record_snapshot: no resolver registered for resource_type "%s" on %s -- skipping snapshot recording, the wrapped call proceeds unaffected', resource_type, fn.__qualname__)
+                    return fn(*args, **kwargs)
+
+                resource_uid = bound.arguments.get(resource_uid_param)
+                if not isinstance(resource_uid, uuid.UUID):
+                    logger.warning('record_snapshot: resource_uid_param "%s" on %s does not resolve to a UUID argument -- skipping snapshot recording, the wrapped call proceeds unaffected', resource_uid_param, fn.__qualname__)
+                    return fn(*args, **kwargs)
+
+                session = bound.arguments.get(session_param)
+                handle_uid = uuid.UUID(derive_handle_uid("r", resource_type, str(resource_uid), None))
+                contract_ref = resolver.contract_ref
+
+                def _register_and_record(envelope_dir, payload):
+                    handle_service.register(session, "r", resource_type, resource_uid, None, resolver.feature_uid, operation_id, contract_ref)
+                    handle_service.record_snapshot(session, handle_uid, envelope_dir, operation_id, contract_ref, payload)
+
+                def _record(envelope_dir, payload):
+                    if isinstance(payload, (dict, list)):
+                        for pointer in redact:
+                            _redact(payload, pointer)
+                    _safely(lambda: _register_and_record(envelope_dir, payload), handle_uid, envelope_dir)
+
+                request_payload = _request_payload(bound, resource_uid_param, session_param)
+                _record("request", request_payload)
+
+                try:
+                    result = fn(*args, **kwargs)
+                except Exception as exc:
+                    _record("error", {"message": str(exc)})
+                    raise
+                _record("response", _to_jsonable(result))
+                return result
 
         return wrapper
 

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

@@ -95,29 +95,29 @@ export function emitTypeScriptExpress({ repoRoot, featureId, plan, resourceFilte
 		},
 	} : null;
 
-	const result = emitUnits({ repoRoot, featureId, provider: 'typescript-express', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff });
-
-	// The resolvers barrel's own import list is regenerated from the resolvers directory's REAL
-	// current contents (not just this run's own resolverUnits) -- an orphaned resolver from a
-	// different feature/module (O2's "never delete, only report" policy leaves it on disk) still
-	// needs its own `register(...)` call imported, or that resource type silently stops being
-	// servable. Unconditional, like migration.sql is for java-spring -- never manifest-tracked.
-	if (!dryRun) {
-		fs.mkdirSync(resolversDir, { recursive: true });
-	}
-	const currentResolverFiles = fs.existsSync(resolversDir)
-		? fs.readdirSync(resolversDir).filter((f) => f.endsWith('.ts') && f !== 'resolvers_index.ts').sort()
-		: [];
-	const imports = currentResolverFiles.map((f) => `import './${f.replace(/\.ts$/, '')}';`).join('\n');
-	const resolversIndexContent = render(RESOLVERS_INDEX_TEMPLATE, { IMPORTS: imports });
-	const resolversIndexRelPath = path.relative(repoRoot, resolversIndexPath);
-	const resolversIndexDiskContent = fs.existsSync(resolversIndexPath) ? fs.readFileSync(resolversIndexPath, 'utf8') : null;
-	const resolversIndexAction = resolversIndexDiskContent === null ? 'create' : (resolversIndexDiskContent === resolversIndexContent ? 'unchanged' : 'update');
-	if (!dryRun && resolversIndexAction !== 'unchanged') {
-		fs.writeFileSync(resolversIndexPath, resolversIndexContent);
-		result.written.push(resolversIndexRelPath);
-	}
-	result.actions.push({ path: resolversIndexRelPath, kind: 'spec', action: resolversIndexAction });
+	const result = emitUnits({
+		repoRoot, featureId, provider: 'typescript-express', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff,
+		// D-patch-transactions (Continued): the resolvers barrel's own import list is regenerated
+		// from the resolvers directory's REAL current contents (not just this run's own
+		// resolverUnits) -- an orphaned resolver from a different feature/module (O2's "never
+		// delete, only report" policy leaves it on disk) still needs its own `register(...)` call
+		// imported, or that resource type silently stops being servable. `render()` is called by
+		// emitUnits() itself AFTER its resolver loop writes this run's own files, so this always
+		// sees the final on-disk listing -- now conflict-safe/manifest-tracked like every other
+		// generated file, no longer unconditional (unlike migration.sql, which stays that way).
+		postResolverUnit: {
+			id: 'resolvers_index.ts.tmpl',
+			templatePath: RESOLVERS_INDEX_TEMPLATE,
+			targetAbs: resolversIndexPath,
+			render: () => {
+				const currentResolverFiles = fs.existsSync(resolversDir)
+					? fs.readdirSync(resolversDir).filter((f) => f.endsWith('.ts') && f !== 'resolvers_index.ts').sort()
+					: [];
+				const imports = currentResolverFiles.map((f) => `import './${f.replace(/\.ts$/, '')}';`).join('\n');
+				return render(RESOLVERS_INDEX_TEMPLATE, { IMPORTS: imports });
+			},
+		},
+	});
 
 	return {
 		...result,