backend-skeleton 1.0.0 → 1.1.0

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,
@@ -104,25 +161,57 @@ export function emitTypeScriptExpress({ repoRoot, featureId, plan, resourceFilte
 		// imported, or that resource type silently stops being servable. `render()` is called by
 		// emitUnits() itself AFTER its resolver loop writes this run's own files, so this always
 		// sees the final on-disk listing -- now conflict-safe/manifest-tracked like every other
-		// generated file, no longer unconditional (unlike migration.sql, which stays that way).
-		postResolverUnit: {
-			id: 'resolvers_index.ts.tmpl',
-			templatePath: RESOLVERS_INDEX_TEMPLATE,
-			targetAbs: resolversIndexPath,
-			render: () => {
-				const currentResolverFiles = fs.existsSync(resolversDir)
-					? fs.readdirSync(resolversDir).filter((f) => f.endsWith('.ts') && f !== 'resolvers_index.ts').sort()
-					: [];
-				const imports = currentResolverFiles.map((f) => `import './${f.replace(/\.ts$/, '')}';`).join('\n');
-				return render(RESOLVERS_INDEX_TEMPLATE, { IMPORTS: imports });
+		// 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,
+			},
+		],
 	});
 
+	// 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 });
+		}
+	}
+
 	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

@@ -64,12 +64,13 @@ export function emitObserveTypeScriptExpress({ repoRoot, featureId, contract, pl
 
 	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, like
-	// handles' own migration.sql (and both other providers' own observe schema resource), for the
-	// identical reason: nobody hand-finishes a generated data file, so O2-style conflict tracking
-	// buys nothing here. `kind: 'spec'` matches migration.sql's own action-reporting convention --
-	// NOT the `kind: 'infra'` A13 gave resolvers_index.ts, which was a genuinely hand-editable
-	// barrel; this is a generated data file, same class as migration.sql, not that one.
+	// 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);

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`);
   }

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

@@ -0,0 +1,89 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+//
+// G5 follow-up (D-typescript-express-registry-parity): mirrors java-spring's HandleRegistry.java.tmpl/
+// HandleSnapshot.java.tmpl and python-fastapi's tables.py.tmpl -- same table names, columns, and
+// unique(resource_type, resource_uid, pointer) constraint, so all three providers' generated
+// schemas agree byte-for-byte at the DDL level (see the emitted migration.sql). NOT the same
+// concept as this package's own registry.ts -- that file is an in-process type->resolver
+// dispatch map; HandleRegistry here is a real database table. The names collide only because
+// Java's own naming does; treat them as unrelated.
+//
+// `payload` is a native `jsonb` column -- TypeORM (de)serializes at the DB boundary automatically,
+// the same no-manual-round-trip safety python-fastapi's own tables.py already has (Java's original
+// `payload` column was a manually (de)serialized String, the exact bug class this structurally
+// cannot reproduce).
+//
+// Requires `experimentalDecorators`/`emitDecoratorMetadata` in the target app's own tsconfig --
+// already required by this provider's own real oracle (any TypeORM app already needs both for its
+// OWN `@Entity()` classes; this is not a new requirement this file introduces). Unlike codec.ts
+// (deliberately decorator-free so it can run standalone via `node --experimental-strip-types`),
+// this file is inherently coupled to a real TypeORM build the way every entity in this ecosystem
+// already is.
+import { Entity, PrimaryColumn, Column, CreateDateColumn, PrimaryGeneratedColumn } from 'typeorm';
+
+@Entity({ name: 'sbf_handle' })
+export class HandleRegistry {
+  @PrimaryColumn('uuid')
+  handleUid!: string;
+
+  // 'r' (resource), 'f' (field), or 'o' (operation instance -- reserved, unused).
+  @Column('text')
+  kind!: string;
+
+  @Column('text')
+  resourceType!: string;
+
+  @Column('uuid')
+  resourceUid!: string;
+
+  // RFC 6901 JSON Pointer, null for kind='r'.
+  @Column('text', { nullable: true })
+  pointer!: string | null;
+
+  @Column('uuid')
+  featureUid!: string;
+
+  @Column('text', { nullable: true })
+  operationId!: string | null;
+
+  @Column('text')
+  contractRef!: string;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  createdAt!: Date;
+
+  @Column('timestamptz', { nullable: true })
+  revokedAt!: Date | null;
+
+  @Column('text', { nullable: true })
+  revokedReason!: string | null;
+}
+
+@Entity({ name: 'sbf_handle_snapshot' })
+export class HandleSnapshot {
+  @PrimaryGeneratedColumn({ type: 'bigint' })
+  snapshotId!: string;
+
+  @Column('uuid')
+  handleUid!: string;
+
+  // 'request', 'response', or 'error' -- what kind of payload this envelope holds.
+  @Column('text')
+  envelopeDir!: string;
+
+  @Column('text')
+  operationId!: string;
+
+  // Hash of the feature contract this snapshot was recorded against. `recover` compares this to
+  // the CURRENT contract's hash -- a mismatch means the contract has since changed shape, and
+  // `recover` must say so explicitly (a schemaDrift marker) rather than silently returning a
+  // payload the current contract no longer describes.
+  @Column('text')
+  contractHash!: string;
+
+  @Column('jsonb')
+  payload!: unknown;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  recordedAt!: Date;
+}

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

@@ -0,0 +1,81 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+//
+// G5 follow-up (D-typescript-express-registry-parity): mirrors Java's HandleService.java.tmpl /
+// python-fastapi's handle_service.py.tmpl -- the explicit API that makes a real GET
+// /handles/:handle/recover reachable. Deliberately never auto-invoked by anything generated
+// elsewhere and never wired into any EXISTING business logic file -- call these functions
+// explicitly from your own service code at the point a resource is actually created/updated, or
+// wrap an existing service function with `recordSnapshot(...)` (see recordSnapshotWrapper.ts) to
+// have it called for you.
+//
+// Named `registerHandle`/`revokeHandle` (not `register`/`revoke`) -- `registry.ts`'s own
+// `register()` is a completely unrelated function (in-process resolver-type dispatch, not a
+// database write); the names collide only because both files use the word "register" for
+// different things. Plain exported functions taking `dataSource` explicitly, not a class with
+// injected dependencies -- matches this provider's own established convention (every resolver
+// already imports its own app-wide DataSource singleton directly; there is no DI container here
+// the way Spring's @Service beans have, or even FastAPI's own Depends()).
+import type { DataSource } from 'typeorm';
+import { HandleRegistry, HandleSnapshot } from './handleEntities';
+import { deriveHandleUid, encodeHandle } from './codec';
+
+export interface RegisterHandleArgs {
+  kind: string;
+  type: string;
+  resourceUid: string;
+  pointer: string | null;
+  featureUid: string;
+  operationId: string | null;
+  contractRef: string;
+}
+
+// Derives handleUid and UPSERTS the registry row -- the schema's own
+// unique(resource_type, resource_uid, pointer) constraint means the SAME (kind, type,
+// resource_uid, pointer) tuple always derives the SAME handleUid, so re-registering it is
+// expected, not an error: an existing row has its featureUid/operationId/contractRef refreshed,
+// but revokedAt/revokedReason are NEVER touched here -- re-registering a revoked handle must
+// never silently un-revoke it. Returns the encoded handle token.
+export async function registerHandle(dataSource: DataSource, args: RegisterHandleArgs): Promise<string> {
+  const { kind, type, resourceUid, pointer, featureUid, operationId, contractRef } = args;
+  const token = encodeHandle(kind, type, resourceUid, pointer);
+  const handleUid = deriveHandleUid(kind, type, resourceUid, pointer);
+  const repo = dataSource.getRepository(HandleRegistry);
+  const existing = await repo.findOne({ where: { handleUid } });
+  if (existing == null) {
+    await repo.save(repo.create({ handleUid, kind, resourceType: type, resourceUid, pointer, featureUid, operationId, contractRef, revokedAt: null, revokedReason: null }));
+  } else {
+    existing.featureUid = featureUid;
+    existing.operationId = operationId;
+    existing.contractRef = contractRef;
+    await repo.save(existing);
+  }
+  return token;
+}
+
+// Records one envelope for an already-registered handle. `payload` is a plain
+// object/array/scalar (already JSON-shaped), stored directly into the native jsonb column -- no
+// manual JSON.stringify/JSON.parse round-trip exists here for `recover` to get wrong later.
+export async function recordSnapshot(dataSource: DataSource, handleUid: string, envelopeDir: string, operationId: string, contractHash: string, payload: unknown): Promise<void> {
+  const repo = dataSource.getRepository(HandleSnapshot);
+  await repo.save(repo.create({ handleUid, envelopeDir, operationId, contractHash, payload }));
+}
+
+export async function revokeHandle(dataSource: DataSource, handleUid: string, reason: string): Promise<void> {
+  const repo = dataSource.getRepository(HandleRegistry);
+  const existing = await repo.findOne({ where: { handleUid } });
+  if (existing != null) {
+    existing.revokedAt = new Date();
+    existing.revokedReason = reason;
+    await repo.save(existing);
+  }
+}
+
+// Retention is EXPOSED, not auto-scheduled -- nothing generated here calls this automatically.
+// Deciding how long snapshots should live, and whether a background job is even appropriate for
+// this application, is left to a human -- the same boundary this provider's own migration.sql
+// already draws around never applying itself.
+export async function pruneSnapshotsOlderThan(dataSource: DataSource, cutoff: Date): Promise<number> {
+  const repo = dataSource.getRepository(HandleSnapshot);
+  const result = await repo.createQueryBuilder().delete().where('recorded_at < :cutoff', { cutoff }).execute();
+  return result.affected ?? 0;
+}

package/handles/providers/typescript-express/templates/migration.sql.tmpl

@@ -0,0 +1,36 @@
+-- Generated by backend-skeleton (bskel handles emit) for feature {{FEATURE_ID}}.
+-- NOT applied automatically -- review it and apply yourself (e.g. via `psql` or your own
+-- TypeORM migration, wrapped in a `queryRunner.query(...)` migration file if you use one). See
+-- D-config-patch / D-migration-scope in DECISIONS.md for why backend-skeleton never applies
+-- schema changes on its own. Same table names/columns as the java-spring/python-fastapi
+-- providers' own migration.sql.tmpl, so all three providers' generated schemas agree at the DDL
+-- level.
+
+create table if not exists sbf_handle (
+	handle_uid uuid primary key,
+	kind text not null check (kind in ('r', 'f', 'o')),
+	resource_type text not null,
+	resource_uid uuid not null,
+	pointer text,
+	feature_uid uuid not null,
+	operation_id text,
+	contract_ref text not null,
+	created_at timestamptz not null default now(),
+	revoked_at timestamptz,
+	revoked_reason text,
+	unique (resource_type, resource_uid, pointer)
+);
+
+create index if not exists ix_sbf_handle_resource on sbf_handle (resource_type, resource_uid);
+
+create table if not exists sbf_handle_snapshot (
+	snapshot_id bigserial primary key,
+	handle_uid uuid not null references sbf_handle (handle_uid),
+	envelope_dir text not null check (envelope_dir in ('request', 'response', 'error')),
+	operation_id text not null,
+	contract_hash text not null,
+	payload jsonb not null,
+	recorded_at timestamptz not null default now()
+);
+
+create index if not exists ix_sbf_handle_snapshot_handle_uid on sbf_handle_snapshot (handle_uid, recorded_at desc);

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

@@ -0,0 +1,123 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+//
+// D-typescript-express-registry-parity: the opt-in AUTOMATIC half of the handle lifecycle --
+// apply `recordSnapshot(...)` to wrap an EXISTING service function (never generated onto one --
+// a human decides which functions are worth handle-tracking) to have it automatically register
+// the resource-level handle and record the request/response/error envelope around every call.
+//
+// Java splits this into a marker annotation (@RecordHandleSnapshot) + a Spring AOP interceptor
+// (HandleAspect) because Java has no other way to intercept a method call. Python collapses both
+// into one decorator, because Python decorators natively ARE that ecosystem's interception
+// mechanism. TypeScript has NEITHER available here: TS decorators are an experimental,
+// `experimentalDecorators`-gated feature that targets class methods, not the standalone async
+// functions this provider's own resolvers/routes are written as -- and this provider's own
+// codec.ts already establishes "zero non-erasable TypeScript syntax (no decorators...)" as a
+// real, load-bearing constraint. The equivalent here is a HIGHER-ORDER FUNCTION: one mechanism,
+// same "no marker/interceptor split" property Python's decorator has, without decorator syntax.
+//
+// Only an async wrapper exists (no sync variant) -- unlike Python, where a decorator can wrap
+// either a sync or async function and must detect which at decoration time, every Express
+// handler and TypeORM repository call in this ecosystem is already async by convention, so
+// there's no second code path to maintain.
+//
+// `resourceUidArg` is an argument INDEX (not a parameter NAME) -- TypeScript/JavaScript has no
+// runtime reflection equivalent to Python's `inspect.signature(fn).bind(...)`, so this cannot
+// resolve a named parameter the way the Python port does; pass the zero-based position of the
+// resource-uid argument in the wrapped function's own parameter list. `redact` is an explicit
+// array of JSON Pointers, never a guessed heuristic. A failure recording a snapshot is ALWAYS
+// logged and swallowed, never allowed to fail the real business call it wraps -- snapshot
+// recording is best-effort observability, not a new way for an unrelated call to start failing.
+//
+// Requires nothing extra installed (unlike Java's spring-boot-starter-aop) -- a plain function
+// needs no framework support -- but still requires a human to apply it to their own code;
+// codegen never touches an existing business logic file.
+//
+// Example:
+//   export const updateOrganization = recordSnapshot(
+//     { resourceType: 'Organization', operationId: 'updateOrganization', resourceUidArg: 0, redact: ['/internalNote'] },
+//     async (organizationId: string, req: UpdateOrganizationRequest): Promise<OrganizationResponse> => { ... },
+//   );
+import type { DataSource } from 'typeorm';
+import { registerHandle, recordSnapshot as persistSnapshot } from './handleService';
+import { deriveHandleUid } from './codec';
+import { resolverFor } from './registry';
+
+export interface RecordSnapshotOptions {
+  resourceType: string;
+  operationId: string;
+  resourceUidArg: number;
+  redact?: string[];
+}
+
+function redactInPlace(obj: unknown, pointer: string): void {
+  if (!pointer.startsWith('/')) return;
+  const parts = pointer.slice(1).split('/').map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let current: unknown = obj;
+  for (const part of parts.slice(0, -1)) {
+    if (current == null) return;
+    current = Array.isArray(current) ? current[Number(part)] : (current as Record<string, unknown>)[part];
+  }
+  const leaf = parts[parts.length - 1];
+  if (Array.isArray(current)) {
+    const idx = Number(leaf);
+    if (!Number.isNaN(idx) && idx < current.length) current[idx] = '***REDACTED***';
+  } else if (current != null && typeof current === 'object') {
+    if (leaf in (current as Record<string, unknown>)) (current as Record<string, unknown>)[leaf] = '***REDACTED***';
+  }
+}
+
+function safely(action: () => Promise<void>, handleUid: string, envelopeDir: string): void {
+  action().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.warn(`recordSnapshot: could not record ${envelopeDir} snapshot for handle ${handleUid} -- the wrapped call proceeds unaffected`, err);
+  });
+}
+
+export function recordSnapshot<Args extends unknown[], R>(
+  options: RecordSnapshotOptions,
+  dataSource: DataSource,
+  fn: (...args: Args) => Promise<R>,
+): (...args: Args) => Promise<R> {
+  const { resourceType, operationId, resourceUidArg, redact = [] } = options;
+  return async (...args: Args): Promise<R> => {
+    const resolver = resolverFor(resourceType);
+    if (resolver == null) {
+      // eslint-disable-next-line no-console
+      console.warn(`recordSnapshot: no resolver registered for resourceType "${resourceType}" -- skipping snapshot recording, the wrapped call proceeds unaffected`);
+      return fn(...args);
+    }
+    const resourceUid = args[resourceUidArg];
+    if (typeof resourceUid !== 'string') {
+      // eslint-disable-next-line no-console
+      console.warn(`recordSnapshot: resourceUidArg ${resourceUidArg} on a call to a wrapped "${resourceType}" function did not resolve to a string argument -- skipping snapshot recording, the wrapped call proceeds unaffected`);
+      return fn(...args);
+    }
+    const handleUid = deriveHandleUid('r', resourceType, resourceUid, null);
+
+    const record = (envelopeDir: string, payload: unknown) => {
+      if (payload != null && typeof payload === 'object') {
+        for (const pointer of redact) redactInPlace(payload, pointer);
+      }
+      safely(async () => {
+        await registerHandle(dataSource, { kind: 'r', type: resourceType, resourceUid, pointer: null, featureUid: resolver.featureUid, operationId, contractRef: resolver.contractRef });
+        await persistSnapshot(dataSource, handleUid, envelopeDir, operationId, resolver.contractRef, payload);
+      }, handleUid, envelopeDir);
+    };
+
+    // The remaining arguments once resourceUidArg is excluded -- the sole survivor UNWRAPPED (the
+    // common case: one DTO), matching Java's/Python's own request-payload projection exactly, so
+    // a `redact` pointer written against the DTO's own fields resolves correctly.
+    const rest = args.filter((_, i) => i !== resourceUidArg);
+    record('request', rest.length === 1 ? rest[0] : rest);
+
+    let result: R;
+    try {
+      result = await fn(...args);
+    } catch (err) {
+      record('error', { message: err instanceof Error ? err.message : String(err) });
+      throw err;
+    }
+    record('response', result);
+    return result;
+  };
+}