backend-skeleton 1.0.0-beta.9 → 1.1.0

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

@@ -77,9 +77,18 @@ function findRequestBodyTypeName(controllerFilePath, methodName) {
 // during this item's grounding). A DTO living somewhere else is a documented gap: patchable stays
 // empty for that resource, exactly like findServiceFile()'s own "resolver NOT generated" fallback
 // for a service that can't be found.
+// D-write-safety-phase1 (item 4b): a real, bounded fallback -- after the domain/<module>/
+// presentation/dto/ convention (Team-IZ-Backend's own shape) fails, also try the DTO directly
+// under <module>/ with no domain/presentation/dto middle segments, the natural flat-package
+// variant of the same convention (javaSrcRoot is already base-package-anchored -- see
+// detectBasePackage() -- so this is `<basePackage>/<module>/<Type>.java`, not a second guessed
+// base). Does not attempt any other shape: no second real oracle has ever validated one, and
+// guessing further risks W9-style overfitting to an imagined repo rather than a confirmed one.
 function findUpdateDtoFile(javaSrcRoot, module, dtoTypeName) {
-	const guessedPath = path.join(javaSrcRoot, 'domain', module, 'presentation', 'dto', `${dtoTypeName}.java`);
-	return fs.existsSync(guessedPath) ? guessedPath : null;
+	const conventional = path.join(javaSrcRoot, 'domain', module, 'presentation', 'dto', `${dtoTypeName}.java`);
+	if (fs.existsSync(conventional)) return conventional;
+	const flat = path.join(javaSrcRoot, module, `${dtoTypeName}.java`);
+	return fs.existsSync(flat) ? flat : null;
 }
 
 // The full patchable-field pipeline for one entity: find its update endpoint -> find the
@@ -121,6 +130,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 +148,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 --
@@ -181,10 +203,20 @@ function findRequiredAuthority(controllerFilePath, methodName) {
 // guaranteed for every entity): <Entity>Service under domain/<module>/application/. Only
 // trusted if the file actually exists -- see D-resolver-scope in DECISIONS.md for why a
 // resolver is only generated when this resolves to a real file, not a guessed import.
+// D-write-safety-phase1 (item 4b): falls back to <module>/<Entity>Service.java directly under
+// javaSrcRoot (no domain/application segments) when the conventional path doesn't exist -- the
+// flat-package variant of the same convention. Confirmed this does NOT close the real-world case
+// that motivated it (spring-projects/spring-petclinic): petclinic has no *Service.java at all
+// (controllers call a Spring Data repository directly), and its entities are Integer-keyed, not
+// UUID (see idFieldIsUuid's own gate in planHandles() below, which fires first regardless). This
+// is a real, independent improvement for a different, plausible shape -- a UUID-keyed entity with
+// a Service layer, just not nested under domain/ -- not a claim that it closes the petclinic gap.
 function findServiceFile(javaSrcRoot, module, entityClassName) {
 	const guessedType = `${entityClassName}Service`;
-	const guessedPath = path.join(javaSrcRoot, 'domain', module, 'application', `${guessedType}.java`);
-	return fs.existsSync(guessedPath) ? { serviceType: guessedType, file: guessedPath } : null;
+	const conventional = path.join(javaSrcRoot, 'domain', module, 'application', `${guessedType}.java`);
+	if (fs.existsSync(conventional)) return { serviceType: guessedType, file: conventional };
+	const flat = path.join(javaSrcRoot, module, `${guessedType}.java`);
+	return fs.existsSync(flat) ? { serviceType: guessedType, file: flat } : null;
 }
 
 // Counts top-level commas in a captured argument list, treating `<...>` (generics) as non-
@@ -233,10 +265,26 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 
 	for (const entity of targetModule.entities) {
 		if (resourceFilter && !resourceFilter.includes(entity.className)) continue;
+
+		// D-write-safety-phase1 (item 4a): a non-UUID primary key disqualifies resolver generation
+		// entirely, independent of whether a Service class can be found -- fetch(UUID resourceUid)
+		// and the sbf1_ handle token format both hard-assume a UUID identity. Checked BEFORE the
+		// service lookup so the note names the real, decisive reason instead of the generic "no
+		// XService found" note below, which would be true but misleading here (implies the fix is
+		// finding/writing a service, when no service could ever make this entity addressable).
+		// `=== false` (not just falsy) deliberately excludes `null` (idField itself was never
+		// found, e.g. inherited from an unindexed superclass) -- that stays the existing, separate
+		// "no XService found" path unchanged, since this scanner genuinely doesn't know the type
+		// there, not that it's confirmed non-UUID.
+		const pkIsNonUuid = entity.idFieldIsUuid === false;
+		if (pkIsNonUuid) {
+			notes.push(`${entity.className}: primary key is declared \`${entity.idFieldType}\`, not UUID -- the handles subsystem only generates UUID-addressable resolvers (fetch(UUID resourceUid); the sbf1_ handle token format encodes a UUID). Resolver NOT generated for this entity, and cannot be regardless of where its service file lives. See D-handle-uid-type-binding in DECISIONS.md.`);
+		}
+
 		const fetchOp = findFetchOperation(targetModule.controllers, entity.className);
 		const authorityResult = findRequiredAuthority(fetchOp?.controllerFile ?? null, fetchOp?.method ?? null);
 		const requiredAuthority = authorityResult.authority;
-		const service = findServiceFile(javaSrcRoot, targetModule.module, entity.className);
+		const service = pkIsNonUuid ? null : findServiceFile(javaSrcRoot, targetModule.module, entity.className);
 		const serviceParamCount = (service && fetchOp) ? countServiceMethodParams(service.file, fetchOp.method) : null;
 
 		// O5 (D-resolver-authorization-action-aware): the SAME extraction, run again against the
@@ -253,22 +301,26 @@ 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.`);
+			// pkIsNonUuid already explained the real reason above -- this note would be true but
+			// redundant (and misleading: it implies finding a service would fix it).
+			if (!pkIsNonUuid) {
+				notes.push(`${entity.className}: no ${entity.className}Service found under domain/${targetModule.module}/application/ or ${targetModule.module}/ -- resolver NOT generated for this entity (would produce a broken import). Emit it by hand once the right service is identified.`);
+			}
 		} else if (fetchOp && serviceParamCount !== 1) {
 			const reason = serviceParamCount === null
 				? `could not find a ${fetchOp.method}(...) method on ${service.serviceType} to confirm its argument count`
 				: `${service.serviceType}.${fetchOp.method} takes ${serviceParamCount} argument(s), not the single resource UUID the generated resolver always passes`;
-			notes.push(`${entity.className}: ${reason} -- resolver NOT generated (would either fail to compile or silently call the wrong overload and drop a required scoping argument, e.g. an organization/cohort id). Wire it by hand.`);
+			notes.push(`${entity.className}: ${reason} -- resolver NOT generated (would either fail to compile or silently call the wrong overload and drop a required scoping argument, e.g. an organization/cohort id). Wire it by hand -- ResourceResolver#fetch/#patchField receive the request's Authentication (D-resolver-authentication-context) for exactly this case, e.g. deriving a tenant/org id the same way the resource's own controller already does.`);
 		}
 
 		// A3 (D-patch-strategy): only worth computing once fetch()/the resolver itself is actually
@@ -306,6 +358,11 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 			type: entity.className,
 			table: entity.table,
 			idField: entity.idField,
+			// D-write-safety-phase1 (item 4a): surfaced in --json output too, not just the note --
+			// null/null when the type genuinely couldn't be determined (not the same as confirmed
+			// non-UUID; see pkIsNonUuid's own `=== false` check above).
+			idFieldType: entity.idFieldType,
+			idFieldIsUuid: entity.idFieldIsUuid,
 			fetchOperation: fetchOp,
 			updateOperation: patchResult.updateOperation,
 			patchable: patchResult.patchable,

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

@@ -64,10 +64,28 @@ public final class HandleCodec {
 		return "sbf1_" + Base64.getUrlEncoder().withoutPadding().encodeToString(raw.getBytes(StandardCharsets.UTF_8));
 	}
 
+	/**
+	 * D-handle-identity-contract-freeze (Phase 3): scheme-dispatch, not a hardcoded {@code sbf1_}
+	 * check -- reserves the discriminant for a future {@code sbf2_} scheme (Phase 6,
+	 * capability-scoped handles) to register itself here additively, without ever changing how an
+	 * existing {@code sbf1_} token decodes. {@link #encode} is untouched -- it still only ever
+	 * emits {@code sbf1_} tokens.
+	 */
 	public static Decoded decode(String token) {
-		if (token == null || !token.startsWith("sbf1_")) {
+		String scheme = scheme(token);
+		if (!"sbf1".equals(scheme)) {
 			throw new IllegalArgumentException("not an sbf1 handle (missing \"sbf1_\" prefix)");
 		}
+		return decodeSbf1(token);
+	}
+
+	private static String scheme(String token) {
+		if (token == null) return null;
+		int sep = token.indexOf('_');
+		return sep == -1 ? token : token.substring(0, sep);
+	}
+
+	private static Decoded decodeSbf1(String token) {
 		if (token.length() > MAX_HANDLE_TOKEN_LENGTH) {
 			throw new IllegalArgumentException("handle token exceeds the maximum length of " + MAX_HANDLE_TOKEN_LENGTH + " characters");
 		}

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

@@ -4,6 +4,7 @@ import {{JACKSON_PACKAGE}}.JsonNode;
 import {{JACKSON_PACKAGE}}.ObjectMapper;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.context.SecurityContextHolder;
 import org.springframework.http.HttpStatus;
@@ -58,12 +59,13 @@ public class HandleController {
 	public ResponseEntity<Object> fetch(@PathVariable String handle) {
 		HandleCodec.Decoded decoded = decodeOrThrow(handle);
 		ResourceResolver resolver = resolverFor(decoded.type());
-		requireAuthority(resolver.requiredAuthority());
+		Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+		requireAuthority(authentication, resolver.requiredAuthority());
 		if (ENFORCE_REGISTRY) {
 			requireRegisteredOrThrow(decoded);
 		}
 
-		Object resource = resolver.fetch(decoded.uuid());
+		Object resource = resolver.fetch(decoded.uuid(), authentication);
 		if (decoded.pointer() == null) {
 			return ResponseEntity.ok(resource);
 		}
@@ -95,15 +97,16 @@ public class HandleController {
 			throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "cannot PATCH a resource-level handle (kind=r) -- only field handles (kind=f) support PATCH");
 		}
 		ResourceResolver resolver = resolverFor(decoded.type());
+		Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
 		// O5 (D-resolver-authorization-action-aware): the PATCH-specific authority, independently
 		// derived from the entity's own UPDATE endpoint -- NOT resolver.requiredAuthority(), which
 		// is fetch()/recover()'s own value and may legitimately require a different role.
-		requireAuthority(resolver.requiredAuthorityForPatch());
+		requireAuthority(authentication, resolver.requiredAuthorityForPatch());
 		if (ENFORCE_REGISTRY) {
 			requireRegisteredOrThrow(decoded);
 		}
 
-		resolver.patchField(decoded.uuid(), decoded.pointer(), value);
+		resolver.patchField(decoded.uuid(), decoded.pointer(), value, authentication);
 		return ResponseEntity.noContent().build();
 	}
 
@@ -111,7 +114,7 @@ public class HandleController {
 	public ResponseEntity<?> recover(@PathVariable String handle, @RequestParam(required = false) Instant at) {
 		HandleCodec.Decoded decoded = decodeOrThrow(handle);
 		ResourceResolver resolver = resolverFor(decoded.type());
-		requireAuthority(resolver.requiredAuthority());
+		requireAuthority(SecurityContextHolder.getContext().getAuthentication(), resolver.requiredAuthority());
 
 		// D-security-9 / O3 (D-handle-registry-enforcement): recover() structurally REQUIRES a
 		// registry row to find a snapshot's own primary key -- there is no "unenforced" mode for
@@ -200,12 +203,19 @@ public class HandleController {
 				.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "no active registration for this handle"));
 	}
 
-	private void requireAuthority(String requiredRole) {
-		boolean granted = SecurityContextHolder.getContext().getAuthentication().getAuthorities().stream()
+	// 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.
+	// D-resolver-authentication-context: takes the already-fetched Authentication (callers now need
+	// it themselves, to thread into resolver.fetch()/patchField() too) rather than re-reading
+	// SecurityContextHolder a second time per request.
+	private void requireAuthority(Authentication authentication, String requiredAuthority) {
+		boolean granted = authentication.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/HandleService.java.tmpl

@@ -3,6 +3,7 @@ package {{BASE_PACKAGE}}.global.handle;
 import {{JACKSON_PACKAGE}}.ObjectMapper;
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
 import org.springframework.transaction.annotation.Transactional;
 
 import java.time.Instant;
@@ -38,8 +39,23 @@ public class HandleService {
 	 * unique-constraint check. Returns the encoded handle token ({@link HandleCodec#encode},
 	 * already implemented -- "minting" a token was never the missing piece, persisting the row
 	 * backing it was).
+	 *
+	 * <p>D-handles-pilot-cohort: {@code REQUIRES_NEW}, not the default {@code REQUIRED} --
+	 * {@link HandleAspect} calls this from WITHIN the wrapped business method's own transaction
+	 * (e.g. a {@code @Transactional(readOnly = true)} read path, a real, unremarkable shape found
+	 * live against {@code CohortService}). Under the default propagation this PARTICIPATES in that
+	 * transaction rather than starting a new one; if it fails (readOnly rejects the INSERT, or any
+	 * other real constraint), the whole shared transaction/connection is marked aborted by the
+	 * database, and {@link HandleAspect#safely}'s {@code catch (Exception e)} genuinely swallows
+	 * THIS method's own exception -- but the WRAPPED business call still fails when it next touches
+	 * that same aborted connection, directly contradicting {@code safely()}'s own documented
+	 * promise ("the wrapped call proceeds unaffected"). Confirmed live: a real disposable Postgres
+	 * reproduced exactly this with {@code CohortService.findCohort} (readOnly) before this fix.
+	 * {@code REQUIRES_NEW} makes this a genuinely separate transaction/connection, so a failure
+	 * here can never propagate into the caller's own transaction -- matching what "best-effort,
+	 * never propagated" already claimed to guarantee.
 	 */
-	@Transactional
+	@Transactional(propagation = Propagation.REQUIRES_NEW)
 	public String register(String kind, String type, UUID resourceUid, String pointer, UUID featureUid, String operationId, String contractRef) {
 		String token = HandleCodec.encode(kind, type, resourceUid, pointer);
 		UUID handleUid = HandleCodec.deriveHandleUid(kind, type, resourceUid, pointer);
@@ -58,8 +74,11 @@ public class HandleService {
 	 * object (a DTO, a request body, an error shape), never a pre-serialized string, so this is
 	 * the one place that decides how it becomes the JSON text {@code sbf_handle_snapshot.payload}
 	 * stores.
+	 *
+	 * <p>{@code REQUIRES_NEW} for the same reason {@link #register} now uses it -- see that
+	 * method's own javadoc.
 	 */
-	@Transactional
+	@Transactional(propagation = Propagation.REQUIRES_NEW)
 	public void recordSnapshot(UUID handleUid, String envelopeDir, String operationId, String contractHash, Object payload) {
 		// A generic `catch (Exception e)` (not the Jackson-2-specific checked
 		// JsonProcessingException, nor assuming Jackson 3's unchecked JacksonException) compiles

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

@@ -29,7 +29,7 @@ import java.lang.annotation.Target;
  * }</pre>
  *
  * <p>Generated by backend-skeleton ({@code bskel handles emit}). Requires {@code
- * spring-boot-starter-aop} on the target repo's own classpath -- NOT added automatically (see
+ * {{AOP_ARTIFACT_NAME}}} on the target repo's own classpath -- NOT added automatically (see
  * {@code handles emit}'s own post-emit notes), matching this project's established boundary of
  * never auto-editing a target's build file.
  */

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

@@ -1,5 +1,7 @@
 package {{BASE_PACKAGE}}.global.handle;
 
+import org.springframework.security.core.Authentication;
+
 import java.util.UUID;
 
 /**
@@ -19,8 +21,24 @@ public interface ResourceResolver {
 	/** Must match the {@code type} segment used when this resource's handles were minted (e.g. "Organization"). */
 	String type();
 
-	/** Fetches the whole resource, serialized the same shape its normal API response uses. */
-	Object fetch(UUID resourceUid);
+	/**
+	 * Fetches the whole resource, serialized the same shape its normal API response uses.
+	 *
+	 * <p>{@code authentication} is the SAME object {@link HandleController} already reads via
+	 * {@code SecurityContextHolder.getContext().getAuthentication()} for its own {@code
+	 * requireAuthority()} check, passed through verbatim -- for the common case (role-only
+	 * authorization, already fully covered by {@link #requiredAuthority()}) implementations
+	 * ignore this parameter entirely. It exists for resources whose real read path is scoped by
+	 * something {@code requiredAuthority()}'s single role string cannot express -- tenant/
+	 * organization/ownership scoping derived from the caller's own identity (e.g. an org id
+	 * carried in {@code authentication.getDetails()}), the same information the resource's real,
+	 * hand-written controller already reads from {@code Authentication} to enforce that scoping
+	 * itself. The framework interprets nothing here and never will -- same "never guess-modify
+	 * hand-written code" boundary {@link #patchField} already follows; a hand-written resolver
+	 * derives whatever it needs from this object using the target app's own existing helper (e.g.
+	 * mirroring the source controller's own extraction logic), never a guess this generator makes.
+	 */
+	Object fetch(UUID resourceUid, Authentication authentication);
 
 	/**
 	 * Applies a single field-level patch. Implementations route through the resource's EXISTING
@@ -29,16 +47,25 @@ public interface ResourceResolver {
 	 * this feature's target module for the specific pattern to follow (some DTOs use {@code
 	 * PatchField<T>} for null-has-meaning fields, most just treat null-vs-absent as "unchanged",
 	 * and some require re-submitting the whole object; check the target DTO before assuming).
+	 *
+	 * <p>{@code authentication}: see {@link #fetch}'s own javadoc -- same object, same purpose,
+	 * ignored by implementations that don't need it.
 	 */
-	void patchField(UUID resourceUid, String pointer, Object value);
+	void patchField(UUID resourceUid, String pointer, Object value, Authentication authentication);
 
 	/**
-	 * 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/java-spring/templates/ResourceResolverStub.java.tmpl

@@ -3,6 +3,7 @@ package {{BASE_PACKAGE}}.domain.{{MODULE}}.infrastructure;
 import {{BASE_PACKAGE}}.global.handle.ResourceResolver;
 import {{SERVICE_IMPORT}};
 {{PATCH_IMPORTS}}import lombok.RequiredArgsConstructor;
+import org.springframework.security.core.Authentication;
 import org.springframework.stereotype.Component;
 
 import java.util.UUID;
@@ -48,13 +49,18 @@ public class {{RESOURCE_TYPE}}Resolver implements ResourceResolver {
 		return {{RESOURCE_TYPE}}ResolverPolicy.type();
 	}
 
+	// D-resolver-authentication-context: `authentication` is unused here -- this stub is only ever
+	// generated for the single-resource-UUID-arg case (D-security-8), where the real service
+	// method needs nothing beyond resourceUid. It's still part of the signature (ResourceResolver
+	// requires it) so a hand-edit that later needs tenant/ownership scoping has it available
+	// without changing the interface again.
 	@Override
-	public Object fetch(UUID resourceUid) {
+	public Object fetch(UUID resourceUid, Authentication authentication) {
 		return {{SERVICE_FIELD}}.{{FETCH_METHOD}}(resourceUid);
 	}
 
 	@Override
-	public void patchField(UUID resourceUid, String pointer, Object value) {
+	public void patchField(UUID resourceUid, String pointer, Object value, Authentication authentication) {
 {{PATCH_FIELD_BODY}}
 	}
 

package/handles/providers/java-spring.mjs

@@ -13,6 +13,14 @@ export const provider = {
 	id: 'java-spring',
 	title: 'Java / Spring Boot',
 	requiresCapabilities: ['resource.fetch'],
+	// D-write-safety-phase0 (item 1): migration.sql is manifest-tracked now (classifyFile()-
+	// classified, conflict-blocked, --force --reason-audited), so it no longer needs
+	// handles/conformance.mjs's idempotence-check exclusion for correctness -- but this field is
+	// ALSO lib/verify.mjs's S6 safety net (a `handles ran` check that fires even with no manifest
+	// entry at all, e.g. a `gate force`d handles gate that never really emitted anything), which is
+	// still real and still needed. Left unchanged rather than emptied -- checkArtifacts() dedupes
+	// against the manifest-based check by path, so this doesn't produce a duplicate when a real
+	// manifest entry exists; it only fires as the fallback when one doesn't.
 	outputs: { spec: ['handles/migration.sql'] },
 	plan,
 	emit({ repoRoot, featureId, plan: handlesPlan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false, enforceRegistry = false }) {

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

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { emitUnits, unifiedDiff } from '../../_engine.mjs';
+import { emitUnits } from '../../_engine.mjs';
 import { sha256File } from '../../../lib/fsutil.mjs';
 import { specPath } from '../../../lib/paths.mjs';
 import { loadFeatureFile } from '../../../lib/featurelifecycle.mjs';
@@ -16,11 +16,6 @@ const RESOLVER_TEMPLATE = path.join(TEMPLATES_DIR, 'resolver.py.tmpl');
 const POLICY_TEMPLATE = path.join(TEMPLATES_DIR, 'resolver_policy.py.tmpl');
 const MIGRATION_TEMPLATE = path.join(TEMPLATES_DIR, 'migration.sql.tmpl');
 
-function writeUnit(target, content) {
-	fs.mkdirSync(path.dirname(target), { recursive: true });
-	fs.writeFileSync(target, content);
-}
-
 function render(templatePath, vars) {
 	let content = fs.readFileSync(templatePath, 'utf8');
 	for (const [key, value] of Object.entries(vars)) {
@@ -175,23 +170,20 @@ export function emitPythonFastApi({ repoRoot, featureId, plan, resourceFilter =
 		},
 	} : null;
 
-	const result = emitUnits({ repoRoot, featureId, provider: 'python-fastapi', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff });
-
-	// G4 follow-up (D-handles-providers): mirrors java-spring/emit.mjs's own migration.sql
-	// handling exactly -- regenerated fresh every run, unconditionally, never manifest-tracked
-	// (no conflict detection for it at all). `kind: 'spec'` tags it distinctly from the
-	// manifest-tracked infra/resolver kinds, same D4/outputs.spec category P4's conformance
-	// harness already special-cases.
-	const migrationContent = render(MIGRATION_TEMPLATE, { FEATURE_ID: featureId });
+	// D-write-safety-phase0 (item 1): mirrors java-spring/emit.mjs's own fix exactly -- migration.sql
+	// used to be regenerated fresh every run, unconditionally, never manifest-tracked. Reuses
+	// emitUnits()'s postResolverUnits slot (kind/ownership/owner overridden for feature ownership;
+	// widened to an array in D-typescript-express-registry-parity) instead of a separate,
+	// untracked write path.
 	const migrationPath = path.join(repoRoot, 'specs', featureId, 'handles', 'migration.sql');
-	const migrationRelPath = path.relative(repoRoot, migrationPath);
-	const migrationDiskContent = fs.existsSync(migrationPath) ? fs.readFileSync(migrationPath, 'utf8') : null;
-	const migrationAction = migrationDiskContent === null ? 'create' : (migrationDiskContent === migrationContent ? 'unchanged' : 'update');
-	if (!dryRun) writeUnit(migrationPath, migrationContent);
-	result.written.push(migrationRelPath);
-	const migrationActionEntry = { path: migrationRelPath, kind: 'spec', action: migrationAction };
-	if (computeDiff && migrationAction === 'update') migrationActionEntry.diff = unifiedDiff(migrationRelPath, migrationDiskContent, migrationContent);
-	result.actions.push(migrationActionEntry);
+	const result = emitUnits({
+		repoRoot, featureId, provider: 'python-fastapi', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff,
+		postResolverUnits: [{
+			id: 'migration.sql.tmpl', templatePath: MIGRATION_TEMPLATE, targetAbs: migrationPath,
+			render: () => render(MIGRATION_TEMPLATE, { FEATURE_ID: featureId }),
+			kind: 'migration', ownership: 'feature', owner: featureId,
+		}],
+	});
 
 	const postEmitNotes = [
 		'NOT done automatically: applying specs/<id>/handles/migration.sql to any database. Review it and apply yourself.',
@@ -209,16 +201,19 @@ export function emitPythonFastApi({ repoRoot, featureId, plan, resourceFilter =
 
 	// O3 follow-up (D-handle-registry-enforcement, "Continued"): per-resource, conditional on
 	// enforceRegistry.
+	// D-write-safety-phase1 (item 2): mirrors java-spring/emit.mjs's own registrationGaps exactly --
+	// see that file's comment for the full reasoning.
+	const registrationGaps = [];
 	if (enforceRegistry) {
 		for (const resource of plan.resources) {
 			if (!resource.willGenerateResolver) continue;
 			if (hasRecordSnapshot(resource.fetchRoute.file)) continue;
 			const relRouteFile = path.relative(repoRoot, resource.fetchRoute.file);
-			postEmitNotes.push(
-				`${resource.type}: --enforce-registry is on, but no @record_snapshot(...) was found anywhere in ${relRouteFile} -- this resource may never get its first registry row, and every fetch/patch call against it will 404 until something registers it. Apply @record_snapshot to its own create-flow route function (or call handle_service.register() by hand at least once per resource), then re-emit. See D-handle-registry-enforcement in DECISIONS.md for the full bootstrapping explanation.`,
-			);
+			const note = `${resource.type}: --enforce-registry is on, but no @record_snapshot(...) was found anywhere in ${relRouteFile} -- this resource may never get its first registry row, and every fetch/patch call against it will 404 until something registers it. Apply @record_snapshot to its own create-flow route function (or call handle_service.register() by hand at least once per resource), then re-emit. See D-handle-registry-enforcement in DECISIONS.md for the full bootstrapping explanation.`;
+			postEmitNotes.push(note);
+			registrationGaps.push({ resourceType: resource.type, file: relRouteFile, note });
 		}
 	}
 
-	return { ...result, postEmitNotes };
+	return { ...result, postEmitNotes, registrationGaps };
 }

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

@@ -62,11 +62,12 @@ export function emitObservePythonFastApi({ repoRoot, featureId, contract, plan,
 
 	const result = emitUnits({ repoRoot, featureId, provider: 'python-fastapi', force, reason, infraUnits, resolverUnits: [], orphanScan: null, dryRun, computeDiff });
 
-	// The projected observed-schema.json resource -- regenerated unconditionally every run, like
-	// handles' own migration.sql (and java observe's own schema resource), 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. Discovered at runtime via a plain glob under observe/schemas/
+	// The projected observed-schema.json resource -- regenerated unconditionally every run (unlike
+	// handles' own migration.sql, which moved to manifest tracking in D-write-safety-phase0; this
+	// file, and java observe's own schema resource, stay unconditional: 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'` still means "always regenerated, not conflict-tracked".
+	// Discovered at runtime via a plain glob under observe/schemas/
 	// (see observed_schema.py.tmpl's own docstring for why -- no importlib.resources needed since
 	// this ecosystem only ever runs from source).
 	const operations = {};

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

@@ -63,9 +63,7 @@ class DecodedHandle:
         self.pointer = pointer
 
 
-def decode_handle(token: str) -> DecodedHandle:
-    if not isinstance(token, str) or not token.startswith("sbf1_"):
-        raise ValueError('not an sbf1 handle (missing "sbf1_" prefix)')
+def _decode_sbf1(token: str) -> DecodedHandle:
     if len(token) > MAX_HANDLE_TOKEN_LENGTH:
         raise ValueError(f"handle token exceeds the maximum length of {MAX_HANDLE_TOKEN_LENGTH} characters")
     raw = _base64url_decode(token[len("sbf1_"):]).decode("utf-8")
@@ -76,6 +74,23 @@ def decode_handle(token: str) -> DecodedHandle:
     return DecodedHandle(kind.lower(), type_, resource_uuid.lower(), pointer)
 
 
+# D-handle-identity-contract-freeze (Phase 3): scheme-dispatch table, not a hardcoded "sbf1_"
+# check -- reserves the discriminant for a future "sbf2_" scheme (Phase 6, capability-scoped
+# handles) to register itself here additively, without ever changing how an existing "sbf1_"
+# token decodes. encode_handle() is untouched -- it still only ever emits "sbf1_" tokens.
+_HANDLE_DECODERS = {"sbf1": _decode_sbf1}
+
+
+def decode_handle(token: str) -> DecodedHandle:
+    if not isinstance(token, str):
+        raise ValueError('not an sbf1 handle (missing "sbf1_" prefix)')
+    scheme = token.split("_", 1)[0]
+    decoder = _HANDLE_DECODERS.get(scheme)
+    if decoder is None:
+        raise ValueError('not an sbf1 handle (missing "sbf1_" prefix)')
+    return decoder(token)
+
+
 # O3 (D-handle-uid-type-binding): ALL three kinds hash a "type:uuid[:...]" discriminant through
 # UUIDv5 -- kind="r" used to return resource_uuid verbatim (no type binding at all), so two
 # different resource TYPES sharing the same resourceUid derived the SAME handle_uid and collided