backend-skeleton 1.0.0 → 1.1.0

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
@@ -204,8 +207,11 @@ public class HandleController {
 	// 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()
+	// 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(requiredAuthority));
 		if (!granted) {

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,8 +47,11 @@ 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);
 
 	/**
 	 * The literal Spring Security granted-authority string required to {@code fetch}/{@code

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

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

@@ -45,6 +45,8 @@ import inspect
 import logging
 import uuid
 
+from sqlmodel import Session
+
 from {{PKG}}.handles import handle_service
 from {{PKG}}.handles.codec import derive_handle_uid
 from {{PKG}}.handles.registry import resolver_for
@@ -52,6 +54,24 @@ from {{PKG}}.handles.registry import resolver_for
 logger = logging.getLogger(__name__)
 
 
+def _side_channel_session(caller_session: Session) -> Session:
+    """D-handles-pilot-cohort (python-fastapi follow-up to the java-spring transaction-isolation
+    finding, D-handle-aspect-transaction-isolation): `handle_service.register`/`record_snapshot`
+    each call `session.commit()` -- fine when a human calls them directly on their OWN session
+    (handle_service.py's own documented use case), genuinely dangerous when called from THIS
+    decorator on the WRAPPED function's session, whose transaction semantics this decorator
+    cannot know. Real, concrete risk: a wrapped function that does multiple related writes
+    without committing (expecting ITS OWN caller to commit-or-rollback atomically) raises
+    mid-transaction -- this decorator's own error-path snapshot recording would call
+    `session.commit()` on that SAME session, silently persisting the should-have-rolled-back
+    partial write instead of ever reaching a real rollback. A genuinely separate session --
+    sharing only the caller's engine/connection pool via `get_bind()`, never its in-flight
+    transaction -- makes handle registration/snapshot recording a real side channel, matching
+    what `Propagation.REQUIRES_NEW` achieves on the Java side for the identical reason.
+    """
+    return Session(caller_session.get_bind())
+
+
 def _redact(obj, pointer: str) -> None:
     """Walks to `pointer`'s parent container and blanks the leaf value in place -- genuinely
     simpler than Java's hand-rolled ObjectNode navigator, since Python containers are natively
@@ -152,8 +172,12 @@ def record_snapshot(*, resource_type: str, operation_id: str, resource_uid_param
                 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)
+                    # D-handles-pilot-cohort: a genuinely separate session -- see
+                    # _side_channel_session's own docstring for why this must never be the
+                    # wrapped function's own `session`.
+                    with _side_channel_session(session) as side_session:
+                        handle_service.register(side_session, "r", resource_type, resource_uid, None, resolver.feature_uid, operation_id, contract_ref)
+                        handle_service.record_snapshot(side_session, handle_uid, envelope_dir, operation_id, contract_ref, payload)
 
                 def _record(envelope_dir, payload):
                     if isinstance(payload, (dict, list)):
@@ -192,8 +216,12 @@ def record_snapshot(*, resource_type: str, operation_id: str, resource_uid_param
                 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)
+                    # D-handles-pilot-cohort: a genuinely separate session -- see
+                    # _side_channel_session's own docstring for why this must never be the
+                    # wrapped function's own `session`.
+                    with _side_channel_session(session) as side_session:
+                        handle_service.register(side_session, "r", resource_type, resource_uid, None, resolver.feature_uid, operation_id, contract_ref)
+                        handle_service.record_snapshot(side_session, handle_uid, envelope_dir, operation_id, contract_ref, payload)
 
                 def _record(envelope_dir, payload):
                     if isinstance(payload, (dict, list)):

package/handles/providers/python-fastapi.mjs

@@ -11,9 +11,9 @@ export const provider = {
 	id: 'python-fastapi',
 	title: 'Python / FastAPI / SQLModel',
 	requiresCapabilities: ['resource.fetch'],
-	// G4 follow-up (D-handles-providers): this provider now generates a real recover()
-	// lifecycle + sbf_handle/sbf_handle_snapshot migration, mirroring java-spring's own O4 work --
-	// the EXCLUDED reasoning that used to justify an empty outputs.spec here is stale.
+	// D-write-safety-phase0 (item 1): mirrors java-spring.mjs's own updated comment exactly -- kept
+	// unchanged rather than emptied. See that file for the full reasoning (checkArtifacts()'s S6
+	// safety net for a `handles ran` but manifest-less state still needs this declared).
 	outputs: { spec: ['handles/migration.sql'] },
 	plan,
 	emit(args) {