backend-skeleton 1.0.0-beta.9 → 1.1.0

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",
@@ -35,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
@@ -42,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
@@ -110,45 +140,105 @@ 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):
+                    # 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)):
+                        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):
+                    # 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)):
+                        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/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) {

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

@@ -2,11 +2,31 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { emitUnits } from '../../_engine.mjs';
+import { sha256File } from '../../../lib/fsutil.mjs';
+import { specPath } from '../../../lib/paths.mjs';
+import { loadFeatureFile } from '../../../lib/featurelifecycle.mjs';
 
 const PROVIDER_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(PROVIDER_ROOT, 'templates');
 const RESOLVER_TEMPLATE = path.join(TEMPLATES_DIR, 'resolver.ts.tmpl');
+const RESOLVER_POLICY_TEMPLATE = path.join(TEMPLATES_DIR, 'resolverPolicy.ts.tmpl');
 const RESOLVERS_INDEX_TEMPLATE = path.join(TEMPLATES_DIR, 'resolvers_index.ts.tmpl');
+const MIGRATION_TEMPLATE = path.join(TEMPLATES_DIR, 'migration.sql.tmpl');
+
+// D-typescript-express-registry-parity: a resource's fetch route file is the closest analog this
+// provider has to java-spring's/python-fastapi's own "service file" -- there is no separate
+// service layer this scanner extracts, so the static registration-gap check (mirrors Phase 1 item
+// 2 exactly) reads the same file `FETCH_ROUTE_FILE` already points at. Checks for an IMPORT of
+// recordSnapshotWrapper.ts, not the string "recordSnapshot(" alone -- that string is also the name
+// of handleService.ts's own lower-level persistence function (a real, deliberate naming overlap
+// recordSnapshotWrapper.ts.tmpl's own header explains), so a bare substring match would produce
+// false negatives on files that only import the OTHER recordSnapshot.
+const RECORD_SNAPSHOT_WRAPPER_IMPORT_RE = /from\s+['"][^'"]*recordSnapshotWrapper['"]/;
+
+function hasRecordSnapshotWrapper(filePath) {
+	if (!filePath || !fs.existsSync(filePath)) return false;
+	return RECORD_SNAPSHOT_WRAPPER_IMPORT_RE.test(fs.readFileSync(filePath, 'utf8'));
+}
 
 function render(templatePath, vars) {
 	let content = fs.readFileSync(templatePath, 'utf8');
@@ -34,53 +54,90 @@ function relativeImportPath(fromFile, toFile) {
 	return rel;
 }
 
-// G5 (D-typescript-express-provider): mirrors python-fastapi/emit.mjs's own 1st-slice shape
-// exactly (as it existed at 627c214, before that provider's own separate recover()/snapshot
-// follow-up) -- no migration, no recover(), see the EXCLUDED-equivalent reasoning in
-// D-typescript-express-provider. Unlike Python, router.ts is infra emitted UNCONDITIONALLY (no
-// SessionDep-shaped precondition exists for it -- TypeORM's DataSource is imported directly by
-// each resolver, never injected per-request the way FastAPI's Depends()/SQLAlchemy Session is).
-export function emitTypeScriptExpress({ repoRoot, featureId, plan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false }) {
+// G5 (D-typescript-express-provider), registry parity added in D-typescript-express-registry-parity:
+// migration.sql/recover()/enforcement now mirror java-spring's/python-fastapi's own shape --
+// see that DECISIONS.md entry for the full design (notably: no decorator-based interception
+// mechanism exists in TypeScript the way Java has AOP and Python has decorators, so
+// recordSnapshotWrapper.ts is a higher-order function instead). Unlike Python, router.ts is infra
+// emitted UNCONDITIONALLY (no SessionDep-shaped precondition exists for it -- TypeORM's
+// DataSource is imported directly by each resolver, never injected per-request the way FastAPI's
+// Depends()/SQLAlchemy Session is).
+export function emitTypeScriptExpress({ repoRoot, featureId, plan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false, enforceRegistry = false }) {
 	const handlesDir = path.join(plan.srcRoot, 'handles');
 	const resolversDir = path.join(handlesDir, 'resolvers');
 	const resolversIndexPath = path.join(resolversDir, 'resolvers_index.ts');
+	// D-typescript-express-registry-parity: repo-relative (specs/<id>/handles/migration.sql), not
+	// under plan.srcRoot -- mirrors java-spring's/python-fastapi's own migrationPath exactly.
+	const migrationPath = path.join(repoRoot, 'specs', featureId, 'handles', 'migration.sql');
 
 	const infraUnits = [
 		{ id: 'codec.ts.tmpl', templatePath: path.join(TEMPLATES_DIR, 'codec.ts.tmpl'), targetAbs: path.join(handlesDir, 'codec.ts'), rendered: render(path.join(TEMPLATES_DIR, 'codec.ts.tmpl'), {}) },
 		{ id: 'registry.ts.tmpl', templatePath: path.join(TEMPLATES_DIR, 'registry.ts.tmpl'), targetAbs: path.join(handlesDir, 'registry.ts'), rendered: render(path.join(TEMPLATES_DIR, 'registry.ts.tmpl'), {}) },
-		{ id: 'router.ts.tmpl', templatePath: path.join(TEMPLATES_DIR, 'router.ts.tmpl'), targetAbs: path.join(handlesDir, 'router.ts'), rendered: render(path.join(TEMPLATES_DIR, 'router.ts.tmpl'), {}) },
+		{ id: 'router.ts.tmpl', templatePath: path.join(TEMPLATES_DIR, 'router.ts.tmpl'), targetAbs: path.join(handlesDir, 'router.ts'), rendered: render(path.join(TEMPLATES_DIR, 'router.ts.tmpl'), { ENFORCE_REGISTRY: enforceRegistry ? 'true' : 'false' }) },
+		// D-typescript-express-registry-parity: repo-wide (one registry table, one service module,
+		// one wrapper), mirroring java-spring's global/handle/* infra exactly -- not per-resource.
+		{ id: 'handleEntities.ts.tmpl', templatePath: path.join(TEMPLATES_DIR, 'handleEntities.ts.tmpl'), targetAbs: path.join(handlesDir, 'handleEntities.ts'), rendered: render(path.join(TEMPLATES_DIR, 'handleEntities.ts.tmpl'), {}) },
+		{ id: 'handleService.ts.tmpl', templatePath: path.join(TEMPLATES_DIR, 'handleService.ts.tmpl'), targetAbs: path.join(handlesDir, 'handleService.ts'), rendered: render(path.join(TEMPLATES_DIR, 'handleService.ts.tmpl'), {}) },
+		{ id: 'recordSnapshotWrapper.ts.tmpl', templatePath: path.join(TEMPLATES_DIR, 'recordSnapshotWrapper.ts.tmpl'), targetAbs: path.join(handlesDir, 'recordSnapshotWrapper.ts'), rendered: render(path.join(TEMPLATES_DIR, 'recordSnapshotWrapper.ts.tmpl'), {}) },
 	];
 
-	const resolverUnits = plan.resources
-		.filter((r) => r.willGenerateResolver)
-		.map((resource) => {
-			const targetAbs = path.join(resolversDir, `${camelCase(resource.type)}.ts`);
-			const vars = {
-				FEATURE_ID: featureId,
-				RESOURCE_TYPE: resource.type,
-				MODEL: resource.type,
-				MODEL_IMPORT_PATH: relativeImportPath(targetAbs, path.join(plan.srcRoot, `${resource.modelImport}.ts`)),
-				DATA_SOURCE_NAME: resource.dataSource.name,
-				DATA_SOURCE_IMPORT_PATH: relativeImportPath(targetAbs, resource.dataSource.file),
-				ID_FIELD: resource.idField,
-				SELECT_PROJECTION: resource.selectFields.map((f) => `${f}: row.${f}`).join(', '),
-				FETCH_ROUTE_FILE: resource.fetchRoute ? path.relative(repoRoot, resource.fetchRoute.file) : '(unknown)',
-				FETCH_ROUTE_LINE: resource.fetchRoute ? resource.fetchRoute.line : '',
-			};
-			return {
+	// D-resolver-policy-split, ported here in D-typescript-express-registry-parity: mirrors
+	// java-spring's/python-fastapi's own contractRefFor/featureUidFor exactly, including the
+	// cross-feature adoption-safety fix -- see D-resolver-policy-split in DECISIONS.md.
+	const contractRefFor = (id) => sha256File(specPath(repoRoot, id, 'contracts', `${id}.schema.json`));
+	const featureUidFor = (id) => loadFeatureFile(repoRoot, id)?.feature_uid ?? '00000000-0000-0000-0000-000000000000';
+	const contractRef = contractRefFor(featureId);
+	const featureUid = featureUidFor(featureId);
+
+	const willGenerate = plan.resources.filter((r) => r.willGenerateResolver);
+	const resolverUnits = willGenerate.flatMap((resource) => {
+		const targetAbs = path.join(resolversDir, `${camelCase(resource.type)}.ts`);
+		const policyTargetAbs = path.join(resolversDir, `${camelCase(resource.type)}Policy.ts`);
+		const vars = {
+			FEATURE_ID: featureId,
+			RESOURCE_TYPE: resource.type,
+			RESOURCE_TYPE_CAMEL: camelCase(resource.type),
+			MODEL: resource.type,
+			MODEL_IMPORT_PATH: relativeImportPath(targetAbs, path.join(plan.srcRoot, `${resource.modelImport}.ts`)),
+			DATA_SOURCE_NAME: resource.dataSource.name,
+			DATA_SOURCE_IMPORT_PATH: relativeImportPath(targetAbs, resource.dataSource.file),
+			ID_FIELD: resource.idField,
+			SELECT_PROJECTION: resource.selectFields.map((f) => `${f}: row.${f}`).join(', '),
+			FETCH_ROUTE_FILE: resource.fetchRoute ? path.relative(repoRoot, resource.fetchRoute.file) : '(unknown)',
+			FETCH_ROUTE_LINE: resource.fetchRoute ? resource.fetchRoute.line : '',
+		};
+		// D-resolver-policy-split: CONTRACT_REF/FEATURE_UID live ONLY in the policy unit now, not
+		// the resolver unit -- FEATURE_ID is the only per-feature substitution the resolver itself
+		// still carries, so its own pristineRenderFor only ever needs to swap that one var.
+		const policyVars = { FEATURE_ID: featureId, RESOURCE_TYPE: resource.type, CONTRACT_REF: contractRef, FEATURE_UID: featureUid };
+		return [
+			{
 				id: 'resolver.ts.tmpl',
 				resourceType: resource.type,
 				module: plan.module,
 				templatePath: RESOLVER_TEMPLATE,
 				targetAbs,
 				rendered: render(RESOLVER_TEMPLATE, vars),
-				// FEATURE_ID is the only per-feature substitution (mirrors java-spring's/python-fastapi's
-				// own resolver templates -- no other var here changes between features for the SAME
-				// resource), so recovering the pristine render under a different owner is exactly the
-				// same render with FEATURE_ID swapped.
 				pristineRenderFor: (ownerId) => render(RESOLVER_TEMPLATE, { ...vars, FEATURE_ID: ownerId }),
-			};
-		});
+			},
+			{
+				id: 'resolverPolicy.ts.tmpl',
+				resourceType: resource.type,
+				module: plan.module,
+				templatePath: RESOLVER_POLICY_TEMPLATE,
+				targetAbs: policyTargetAbs,
+				rendered: render(RESOLVER_POLICY_TEMPLATE, policyVars),
+				// Only FEATURE_ID varies by owner for the resolver unit above; CONTRACT_REF/FEATURE_UID
+				// vary by owner HERE, exactly like java-spring's/python-fastapi's own policy unit.
+				pristineRenderFor: (ownerId) => render(RESOLVER_POLICY_TEMPLATE, {
+					...policyVars,
+					FEATURE_ID: ownerId,
+					CONTRACT_REF: ownerId === featureId ? contractRef : contractRefFor(ownerId),
+					FEATURE_UID: ownerId === featureId ? featureUid : featureUidFor(ownerId),
+				}),
+			},
+		];
+	});
 
 	const orphanScan = (!resourceFilter && plan.module) ? {
 		dir: resolversDir,
@@ -95,34 +152,66 @@ export function emitTypeScriptExpress({ repoRoot, featureId, plan, resourceFilte
 		},
 	} : null;
 
-	const result = emitUnits({ repoRoot, featureId, provider: 'typescript-express', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff });
+	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. D-typescript-express-registry-parity: excludes `*Policy.ts` files
+		// explicitly -- those have no `register(...)` side effect of their own (their sibling
+		// resolver file already imports them directly), importing them a second time here would
+		// be a spurious, pointless barrel entry.
+		// D-write-safety-phase0/D-typescript-express-registry-parity: migration.sql now shares
+		// this array with resolvers_index.ts (widened from a single optional unit to an array
+		// specifically so this provider could have both at once -- see D-typescript-express-registry-parity
+		// in DECISIONS.md for why migration.sql needed the SAME manifest-tracked treatment
+		// java-spring/python-fastapi already have, from day one).
+		postResolverUnits: [
+			{
+				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' && !f.endsWith('Policy.ts')).sort()
+						: [];
+					const imports = currentResolverFiles.map((f) => `import './${f.replace(/\.ts$/, '')}';`).join('\n');
+					return render(RESOLVERS_INDEX_TEMPLATE, { IMPORTS: imports });
+				},
+			},
+			{
+				id: 'migration.sql.tmpl', templatePath: MIGRATION_TEMPLATE, targetAbs: migrationPath,
+				render: () => render(MIGRATION_TEMPLATE, { FEATURE_ID: featureId }),
+				kind: 'migration', ownership: 'feature', owner: featureId,
+			},
+		],
+	});
 
-	// 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);
+	// D-write-safety-phase1 (item 2), ported here: per-resource, conditional on enforceRegistry
+	// actually being on -- mirrors java-spring's/python-fastapi's own registrationGaps exactly.
+	const registrationGaps = [];
+	const postEmitNotes = [
+		`NOT done automatically: wiring the generated router into your app -- add "import { router as handlesRouter } from './handles/router';" and mount it via your app's own router-composition file (e.g. app.use(handlesRouter)) by hand.`,
+		'NOT done automatically: wrapping an existing route handler with recordSnapshot(...) (see handles/recordSnapshotWrapper.ts) to have it register/snapshot automatically. Codegen never touches an existing business logic file.',
+	];
+	if (enforceRegistry) {
+		for (const resource of willGenerate) {
+			const fetchRouteFile = resource.fetchRoute?.file ?? null;
+			if (hasRecordSnapshotWrapper(fetchRouteFile)) continue;
+			const relFile = fetchRouteFile ? path.relative(repoRoot, fetchRouteFile) : '(unknown)';
+			const note = `${resource.type}: --enforce-registry is on, but no import of recordSnapshotWrapper.ts was found anywhere in ${relFile} -- this resource may never get its first HandleRegistry row, and every fetch()/patch() call against it will 404 until something registers it. Wrap ${resource.type}'s own create-flow route with recordSnapshot(...) (or call registerHandle() 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: relFile, note });
+		}
 	}
-	result.actions.push({ path: resolversIndexRelPath, kind: 'spec', action: resolversIndexAction });
 
 	return {
 		...result,
-		postEmitNotes: [
-			`NOT done automatically: wiring the generated router into your app -- add "import { router as handlesRouter } from './handles/router';" and mount it via your app's own router-composition file (e.g. app.use(handlesRouter)) by hand.`,
-		],
+		postEmitNotes,
+		registrationGaps,
 	};
 }

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

@@ -0,0 +1,102 @@
+// D-runtime-conformance-receipts: the emit-side half of opt-in runtime contract-conformance
+// checking for typescript-express. Mirrors handles/providers/python-fastapi/observe.mjs's own
+// shape -- observe and handles are orthogonal capabilities that happen to share the same repo-wide
+// "generated infra" pattern, not the same feature. See DECISIONS.md for the full WHY, including the
+// TS-specific response-body-capture note (res.json patch + res.on('finish', ...), never a wrapped
+// return value the way java's @Around/python's `await fn(...)` are) the generated
+// observeContract.ts itself implements.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { emitUnits, unifiedDiff } from '../../_engine.mjs';
+import { sha256File } from '../../../lib/fsutil.mjs';
+import { specPath } from '../../../lib/paths.mjs';
+import { projectOperation } from '../../observe-schema-projection.mjs';
+
+const PROVIDER_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(PROVIDER_ROOT, 'templates');
+
+// Repo-wide, shared across every feature that ever runs `bskel observe emit` -- observedSchema.ts
+// discovers every schemas/*.observed-schema.json file at MODULE LOAD time rather than being
+// regenerated per feature, so these three files are true infra (create-once-per-repo, all-or-nothing
+// conflict unit), same treatment INFRA_FILES gives handles' own handlesDir infra files (codec.ts/
+// registry.ts/router.ts). Three files, not python's four -- TS/Node has no __init__.py-equivalent
+// package marker a plain relative-import directory needs to be importable, so there is no
+// __init__.ts-shaped file to carry over. None of the three need any {{VAR}} substitution -- observe
+// stays decoupled from handles/, cross-imports between them are relative `from './contractCheck'`.
+const INFRA_FILES = [
+	{ template: 'contractCheck.ts.tmpl', target: 'contractCheck.ts' },
+	{ template: 'observedSchema.ts.tmpl', target: 'observedSchema.ts' },
+	{ template: 'observeContract.ts.tmpl', target: 'observeContract.ts' },
+];
+
+function render(templatePath, vars) {
+	let content = fs.readFileSync(templatePath, 'utf8');
+	for (const [key, value] of Object.entries(vars)) {
+		content = content.replaceAll(`{{${key}}}`, String(value));
+	}
+	return content;
+}
+
+function writeUnit(target, content) {
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.writeFileSync(target, content);
+}
+
+// See DECISIONS.md D-runtime-conformance-receipts. `contract` is the already-loaded, already
+// schema-validated feature contract (bin/bskel.mjs's loadContract) -- this function does not read
+// specs/ itself. `plan` is the already-computed typescript-express resource plan (bin/bskel.mjs
+// calls planTypeScriptExpress() before this, the same --module dependency python-fastapi's own
+// observe emit already established) -- only `plan.srcRoot` is used here, `plan.resources`/
+// `plan.notes` are computed and simply unused, same tolerance emitUnits() already extends to
+// java's/python's own `resolverUnits: []`. There is no per-resource generated file here (a human
+// inserts observeContract('...') directly into an existing route's own middleware array), so
+// emitUnits()'s resolver/orphan machinery has nothing to do.
+export function emitObserveTypeScriptExpress({ repoRoot, featureId, contract, plan, force = false, reason = '', dryRun = false, computeDiff = false }) {
+	const observeDir = path.join(plan.srcRoot, 'observe');
+
+	const infraUnits = INFRA_FILES.map((f) => ({
+		id: f.template,
+		templatePath: path.join(TEMPLATES_DIR, f.template),
+		targetAbs: path.join(observeDir, f.target),
+		rendered: render(path.join(TEMPLATES_DIR, f.template), {}),
+	}));
+
+	const result = emitUnits({ repoRoot, featureId, provider: 'typescript-express', force, reason, infraUnits, resolverUnits: [], orphanScan: null, dryRun, computeDiff });
+
+	// 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 both other providers' own observe schema resource, stay unconditional: nobody
+	// hand-finishes a generated data file, so O2-style conflict tracking buys nothing here).
+	// `kind: 'spec'` still means "always regenerated, not conflict-tracked" -- NOT the
+	// `kind: 'infra'` A13 gave resolvers_index.ts, which was a genuinely hand-editable barrel;
+	// this is a generated data file, a different class.
+	const operations = {};
+	for (const [opId, opContract] of Object.entries(contract.operations)) {
+		operations[opId] = projectOperation(opContract);
+	}
+	const contractRef = sha256File(specPath(repoRoot, featureId, 'contracts', `${featureId}.schema.json`));
+	const schemaContent = `${JSON.stringify({ sbf_observed_schema: '1', feature_id: featureId, feature_uid: contract.feature_uid, contract_ref: contractRef, operations }, null, '\t')}\n`;
+	const schemaPath = path.join(observeDir, 'schemas', `${featureId}.observed-schema.json`);
+	const schemaRelPath = path.relative(repoRoot, schemaPath);
+	const schemaDiskContent = fs.existsSync(schemaPath) ? fs.readFileSync(schemaPath, 'utf8') : null;
+	const schemaAction = schemaDiskContent === null ? 'create' : (schemaDiskContent === schemaContent ? 'unchanged' : 'update');
+	if (!dryRun) writeUnit(schemaPath, schemaContent);
+	result.written.push(schemaRelPath);
+	const schemaActionEntry = { path: schemaRelPath, kind: 'spec', action: schemaAction };
+	if (computeDiff && schemaAction === 'update') schemaActionEntry.diff = unifiedDiff(schemaRelPath, schemaDiskContent, schemaContent);
+	result.actions.push(schemaActionEntry);
+
+	return {
+		...result,
+		postEmitNotes: [
+			'NOT done automatically: route observeContract\'s own receipt sink (defaults to one JSON line per receipt via process.stdout.write) to wherever you want receipt lines collected -- bskel never edits your logging/process-supervisor config. Override it at app startup ("import { setReceiptSink } from \'./observe/observeContract\';") to point it at your own log pipeline, then point `bskel observe import --receipts <path>` at whatever that ends up as.',
+			'If your build compiles TypeScript to a separate output directory (`tsc --outDir dist`), make sure observe/schemas/*.json is copied alongside the compiled observedSchema.js -- tsc only compiles .ts files, it does not copy plain data files into the output tree, and observedSchema.ts discovers its schemas relative to its OWN compiled location at runtime (__dirname). A target app that only ever runs from src/ (ts-node, tsx) needs no extra step here.',
+			`Contract-conformance checking only covers path params always, plus a bounded slice of request/response/error body shape -- and only when this contract was emitted with --openapi-file. See the emitted ${path.relative(repoRoot, schemaPath)}'s own "unsupported" markers for exactly what is skipped for this feature.`,
+			'NOT done automatically: insert observeContract(\'<operationId>\') into whichever existing route\'s own middleware array/argument list you want observed (e.g. `router.get(path, [checkJwt, observeContract(\'op-id\')], handler)`) -- nothing is inserted for you (D-resolver-scope: never guess which route implements which operation).',
+			'error_class is never populated in this provider\'s receipts (always omitted) -- Express middleware runs BEFORE the route handler and is structurally unable to observe a thrown error the way java\'s @Around/python\'s except block can (by the time a handler throws or calls next(err), this middleware\'s own call frame has already returned). See DECISIONS.md D-runtime-conformance-receipts.',
+			'Response-body checking only covers a handler that calls res.json(...) or res.send(<object>) (Express\'s own res.send delegates to res.json for a plain-object body) -- a handler that calls res.send(<string>)/res.end(...) directly, or whose response is produced by Express\'s own default/generic error handler, has its response check silently skipped, never guessed.',
+			'OpenAPI reconciliation for this adapter matches scanned Express route strings EXACTLY against the OpenAPI document\'s own path keys (contracts/openapi.mjs has no ":id" <-> "{id}" translation) -- a real, standards-compliant OpenAPI document (which must use "{id}") will not match a scanned ":id"/":id([0-9]+)" route unless the document\'s own path key happens to already read that way. Unlike python-fastapi, this is not "for free."',
+		],
+	};
+}

package/handles/providers/typescript-express/templates/codec.ts.tmpl

@@ -55,10 +55,20 @@ export function encodeHandle(kind: string, type: string, uuid: string, pointer:
   return `sbf1_${base64url(Buffer.from(raw, 'utf8'))}`;
 }
 
+// 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. encodeHandle() is untouched -- it still only ever emits 'sbf1_' tokens.
+const HANDLE_DECODERS: Record<string, (token: string) => DecodedHandle> = { sbf1: decodeSbf1Handle };
+
 export function decodeHandle(token: string): DecodedHandle {
-  if (typeof token !== 'string' || !token.startsWith('sbf1_')) {
-    throw new Error('not an sbf1 handle (missing "sbf1_" prefix)');
-  }
+  const scheme = typeof token === 'string' && token.includes('_') ? token.slice(0, token.indexOf('_')) : token;
+  const decoder = typeof scheme === 'string' ? HANDLE_DECODERS[scheme] : undefined;
+  if (!decoder) throw new Error('not an sbf1 handle (missing "sbf1_" prefix)');
+  return decoder(token);
+}
+
+function decodeSbf1Handle(token: string): DecodedHandle {
   if (token.length > MAX_HANDLE_TOKEN_LENGTH) {
     throw new Error(`handle token exceeds the maximum length of ${MAX_HANDLE_TOKEN_LENGTH} characters`);
   }