backend-skeleton 1.0.0-beta.1

package/handles/providers/java-spring/templates/migration.sql.tmpl

@@ -0,0 +1,34 @@
+-- Generated by backend-skeleton (bskel handles emit) for feature {{FEATURE_ID}}.
+-- NOT applied automatically -- this repo has no Flyway/Liquibase (confirmed by `bskel scan`'s
+-- Plane A/B during Phase 2), so apply this yourself against Supabase (e.g. via the SQL editor
+-- or `psql`) once you've reviewed it. See D-config-patch / D-migration-scope in DECISIONS.md
+-- for why backend-skeleton never applies schema changes on its own.
+
+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/java-spring.mjs

@@ -0,0 +1,21 @@
+import { plan } from './java-spring/plan.mjs';
+import { emitJavaSpring } from './java-spring/emit.mjs';
+
+// D-handles-providers (G4). Zero-registration descriptor loaded by handles/registry.mjs -- see
+// schemas/handles-provider.schema.json for the contract this object's JSON-shaped fields must
+// match (plan/emit are functions, checked separately). This is the ORIGINAL handles codegen
+// (pre-G4: handles/plan.mjs + handles/emit.mjs, un-abstracted) extracted behind the same
+// interface handles/providers/python-fastapi.mjs implements -- see D-handles-providers for why
+// this extraction only happened once a real second provider existed to factor a boundary
+// against.
+export const provider = {
+	contract: 'sbf.handles-provider/1',
+	id: 'java-spring',
+	title: 'Java / Spring Boot',
+	requiresCapabilities: ['resource.fetch'],
+	outputs: { spec: ['handles/migration.sql'] },
+	plan,
+	emit({ repoRoot, featureId, plan: handlesPlan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false }) {
+		return emitJavaSpring({ repoRoot, featureId, plan: handlesPlan, basePackage: handlesPlan.basePackage, resourceFilter, force, reason, dryRun, computeDiff });
+	},
+};

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

@@ -0,0 +1,171 @@
+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 { 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.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)) {
+		content = content.replaceAll(`{{${key}}}`, String(value));
+	}
+	return content;
+}
+
+// PascalCase -> snake_case, good enough for the class names this scanner actually extracts
+// (ASCII identifiers only, same assumption java-spring's own naming makes).
+function snakeCase(s) {
+	return s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+}
+
+function dottedModulePath(file, importRoot) {
+	const rel = path.relative(importRoot, file).replace(/\.py$/, '');
+	return rel.split(path.sep).join('.');
+}
+
+// See DECISIONS.md D-handles-providers. G4 follow-up: migration.sql + a real recover() lifecycle
+// (tables.py/handle_service.py/record_snapshot.py) are now generated, mirroring java-spring's own
+// O4 work -- the EXCLUDED section's original "even Java hasn't got O4" reasoning is stale, see
+// that entry's own follow-up paragraph. `router.py` is only emitted when a SessionDep-shaped alias
+// was actually found (plan()'s willGenerateResolver gate already implies this for every resolver,
+// but the router itself is infra -- generated once, independent of which resolvers exist -- so it
+// needs its own guard for the "found zero resolvers, and specifically because no SessionDep
+// exists" case).
+export function emitPythonFastApi({ repoRoot, featureId, plan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false }) {
+	const handlesDir = path.join(plan.importRoot, plan.topPackage, 'handles');
+	const resolversDir = path.join(handlesDir, 'resolvers');
+
+	const infraUnits = [
+		{ id: '__init__.py.tmpl', templatePath: path.join(TEMPLATES_DIR, '__init__.py.tmpl'), targetAbs: path.join(handlesDir, '__init__.py'), rendered: render(path.join(TEMPLATES_DIR, '__init__.py.tmpl'), {}) },
+		{ id: 'codec.py.tmpl', templatePath: path.join(TEMPLATES_DIR, 'codec.py.tmpl'), targetAbs: path.join(handlesDir, 'codec.py'), rendered: render(path.join(TEMPLATES_DIR, 'codec.py.tmpl'), {}) },
+		{ id: 'registry.py.tmpl', templatePath: path.join(TEMPLATES_DIR, 'registry.py.tmpl'), targetAbs: path.join(handlesDir, 'registry.py'), rendered: render(path.join(TEMPLATES_DIR, 'registry.py.tmpl'), {}) },
+		{ id: 'resolvers_init.py.tmpl', templatePath: path.join(TEMPLATES_DIR, 'resolvers_init.py.tmpl'), targetAbs: path.join(resolversDir, '__init__.py'), rendered: render(path.join(TEMPLATES_DIR, 'resolvers_init.py.tmpl'), {}) },
+		// G4 follow-up (D-handles-providers): tables.py has zero {{VAR}} substitutions (same class
+		// as codec.py.tmpl above -- fixed schema, not per-feature), handle_service.py/
+		// record_snapshot.py each need only {{PKG}} to resolve their own sibling-module imports.
+		{ id: 'tables.py.tmpl', templatePath: path.join(TEMPLATES_DIR, 'tables.py.tmpl'), targetAbs: path.join(handlesDir, 'tables.py'), rendered: render(path.join(TEMPLATES_DIR, 'tables.py.tmpl'), {}) },
+		{ id: 'handle_service.py.tmpl', templatePath: path.join(TEMPLATES_DIR, 'handle_service.py.tmpl'), targetAbs: path.join(handlesDir, 'handle_service.py'), rendered: render(path.join(TEMPLATES_DIR, 'handle_service.py.tmpl'), { PKG: plan.topPackage }) },
+		{ id: 'record_snapshot.py.tmpl', templatePath: path.join(TEMPLATES_DIR, 'record_snapshot.py.tmpl'), targetAbs: path.join(handlesDir, 'record_snapshot.py'), rendered: render(path.join(TEMPLATES_DIR, 'record_snapshot.py.tmpl'), { PKG: plan.topPackage }) },
+	];
+
+	const sessionDep = plan.resources.find((r) => r.sessionDep)?.sessionDep ?? null;
+	if (sessionDep) {
+		infraUnits.push({
+			id: 'router.py.tmpl',
+			templatePath: path.join(TEMPLATES_DIR, 'router.py.tmpl'),
+			targetAbs: path.join(handlesDir, 'router.py'),
+			rendered: render(path.join(TEMPLATES_DIR, 'router.py.tmpl'), {
+				PKG: plan.topPackage,
+				SESSION_DEP_MODULE: dottedModulePath(sessionDep.file, plan.importRoot),
+				SESSION_DEP_NAME: sessionDep.name,
+			}),
+		});
+	}
+
+	// G4 follow-up (D-handles-providers): mirrors java-spring/emit.mjs's own contractRefFor/
+	// featureUidFor exactly, including the cross-feature adoption-safety fix that item's own Java
+	// work found the hard way -- proactively included here rather than rediscovered in Python
+	// later. requireNamedGate(root, 'contract', ...) already ran before emitPythonFastApi() is
+	// ever reached (cmdHandlesEmit's own precondition), so this feature's own contract file is
+	// guaranteed to exist here.
+	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 resolverUnits = plan.resources
+		.filter((r) => r.willGenerateResolver)
+		.map((resource) => {
+			const vars = {
+				FEATURE_ID: featureId,
+				RESOURCE_TYPE: resource.type,
+				MODEL: resource.type,
+				PUBLIC_MODEL: resource.publicModel,
+				MODEL_IMPORT: resource.modelImport,
+				PKG: plan.topPackage,
+				FETCH_ROUTE_FILE: resource.fetchRoute ? path.relative(repoRoot, resource.fetchRoute.file) : '(unknown)',
+				FETCH_ROUTE_LINE: resource.fetchRoute ? resource.fetchRoute.line : '',
+				CONTRACT_REF: contractRef,
+				FEATURE_UID: featureUid,
+			};
+			return {
+				id: 'resolver.py.tmpl',
+				resourceType: resource.type,
+				module: plan.module,
+				templatePath: RESOLVER_TEMPLATE,
+				targetAbs: path.join(resolversDir, `${snakeCase(resource.type)}.py`),
+				rendered: render(RESOLVER_TEMPLATE, vars),
+				// FEATURE_ID/CONTRACT_REF/FEATURE_UID all change between features -- deliberately NOT
+				// reused verbatim for a DIFFERENT owner (see java-spring/emit.mjs's own identical
+				// comment): O2's cross-feature adoption check re-renders using the ORIGINAL owner's
+				// feature_id specifically, so baking in the CURRENT run's own contract_ref/feature_uid
+				// there would compare disk content against the wrong feature's values and manufacture a
+				// false conflict for an untouched file.
+				pristineRenderFor: (ownerId) => render(RESOLVER_TEMPLATE, {
+					...vars,
+					FEATURE_ID: ownerId,
+					CONTRACT_REF: ownerId === featureId ? contractRef : contractRefFor(ownerId),
+					FEATURE_UID: ownerId === featureId ? featureUid : featureUidFor(ownerId),
+				}),
+			};
+		});
+
+	const orphanScan = (!resourceFilter && plan.module) ? {
+		dir: resolversDir,
+		module: plan.module,
+		matchesFile: (file) => file.endsWith('.py') && file !== '__init__.py',
+		// Filename can't reliably recover the type (organization_policy.py could be OrganizationPolicy
+		// or Organizationpolicy) -- read the `type = "X"` class attribute the resolver template
+		// itself carries instead of guessing from the filename, unlike java-spring's orphan scan.
+		resourceTypeOf: (_file, content) => {
+			const m = content.match(/^\s*type\s*=\s*"([^"]+)"/m);
+			return m ? m[1] : null;
+		},
+	} : 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 });
+	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 postEmitNotes = [
+		'NOT done automatically: applying specs/<id>/handles/migration.sql to any database. Review it and apply yourself.',
+	];
+	if (!sessionDep) {
+		postEmitNotes.push('router.py was NOT generated -- no SessionDep-shaped dependency alias was found under the detected package, see plan notes.');
+	} else {
+		postEmitNotes.push(`NOT done automatically: wiring the generated router into your app -- add "from ${plan.topPackage}.handles.router import router as handles_router" and include it via your app's own router-composition file (e.g. api_router.include_router(handles_router)) by hand.`);
+	}
+	// G4 follow-up (D-handles-providers): record_snapshot.py's decorator needs nothing extra
+	// installed (unlike Java's spring-boot-starter-aop requirement) -- Python decorators need no
+	// framework support -- but still requires a human to apply it to their own code, same "review
+	// and apply yourself" boundary as the migration note above.
+	postEmitNotes.push('NOT done automatically: applying @record_snapshot (handles/record_snapshot.py) to any of your own service functions. Codegen never touches existing business logic files.');
+
+	return { ...result, postEmitNotes };
+}

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

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Walks up from a file's own directory while `__init__.py` exists, returning the topmost such
+// directory (the "top package" dir), or null if the file's own directory has none at all. Not
+// named-conditioned on any particular directory name -- a standard PyPA src-layout
+// (`src/<package>/__init__.py`, a real `__init__.py`, just under a `src/` dir) walks up correctly
+// like any other layout (see D-typescript-express-provider's slice-4 correction in DECISIONS.md,
+// and the positive regression test in test/python-fastapi-handles.test.mjs). Only PEP 420
+// *implicit namespace packages* (omitting `__init__.py` entirely) hit the null case below --
+// unsupported, see COST in DECISIONS.md, exit 2.
+function packageRootFor(file) {
+	let dir = path.dirname(file);
+	if (!fs.existsSync(path.join(dir, '__init__.py'))) return null;
+	let top = dir;
+	for (;;) {
+		const parent = path.dirname(top);
+		if (parent === top || !fs.existsSync(path.join(parent, '__init__.py'))) break;
+		top = parent;
+	}
+	return top;
+}
+
+// O6-style ambiguity rejection (see java-spring's detectBasePackage): more than one DIFFERENT
+// package root among this module's own files is refused with named candidates rather than
+// silently picking one.
+function detectImportRoot(moduleFiles, repoRoot) {
+	const roots = new Set();
+	for (const file of moduleFiles) {
+		const r = packageRootFor(file);
+		if (r) roots.add(r);
+	}
+	if (roots.size === 0) {
+		throw new Error('could not detect a Python package root (no __init__.py found above any scanned file for this module) -- this provider does not support PEP 420 implicit namespace packages (omitting __init__.py entirely) yet. A standard src-layout WITH real __init__.py files works fine.');
+	}
+	if (roots.size > 1) {
+		throw new Error(`ambiguous Python package root -- found ${roots.size} different candidates among this module's own files: ${[...roots].map((r) => path.relative(repoRoot, r)).join(', ')}. This provider doesn't support multi-package-root repos yet.`);
+	}
+	const topPackageDir = [...roots][0];
+	return { importRoot: path.dirname(topPackageDir), topPackage: path.basename(topPackageDir) };
+}
+
+function listPythonFilesUnder(dir) {
+	const out = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith('.') || entry.name === '__pycache__') continue;
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...listPythonFilesUnder(full));
+		else if (entry.name.endsWith('.py')) out.push(full);
+	}
+	return out.sort();
+}
+
+// Same "canonical fetch" concept as java-spring's findFetchOperation, keyed on `ep.method` (the
+// Python function name) instead of `ep.operationId` -- python-fastapi's scan output always sets
+// operationId: null (see D-fastapi-adapter), so that logic cannot be shared as-is. A GET endpoint
+// whose path is exactly `${controller.basePath}/{param}` (one trailing path segment) on a
+// controller whose class-name affinity-matches the entity, mirroring java-spring's own check.
+function findFetchRoute(controllers, entityClassName) {
+	const needle = entityClassName.toLowerCase();
+	for (const controller of controllers) {
+		if (!controller.className.toLowerCase().includes(needle)) continue;
+		for (const ep of controller.endpoints) {
+			if (ep.verb !== 'GET') continue;
+			const suffix = ep.path.slice(controller.basePath.length);
+			if (/^\/\{[^/]+\}$/.test(suffix)) {
+				return { method: ep.method, path: ep.path, file: controller.file, line: ep.line, controllerClassName: controller.className };
+			}
+		}
+	}
+	return null;
+}
+
+// `class <Entity>Public(...)` -- scoped to the entity's own file. Required, not decorative: the
+// real oracle's User table carries hashed_password with no protection besides each individual
+// route's own `response_model=UserPublic` declaration -- a generic handle-fetch route serving
+// multiple types can't rely on that, so a resolver is refused entirely when this class is absent
+// rather than risk leaking a raw table row.
+function findPublicModel(entityFile, entityClassName) {
+	if (!entityFile || !fs.existsSync(entityFile)) return null;
+	const text = fs.readFileSync(entityFile, 'utf8');
+	const re = new RegExp(`^class\\s+${entityClassName}Public\\s*\\(`, 'm');
+	return re.test(text) ? `${entityClassName}Public` : null;
+}
+
+// `SessionDep = Annotated[Session, Depends(get_db)]` -- or whatever this app names its own
+// session-dependency alias. Searches the whole detected package (not just this module's files,
+// since the alias is typically declared once in a shared deps module), deterministic
+// shallowest-then-name tie-break if more than one file declares one -- same convention
+// scanners/adapters/python-fastapi.mjs's own byShallowestThenName helper uses.
+const SESSION_DEP_RE = /^(\w+)\s*=\s*Annotated\[\s*Session\s*,\s*Depends\(/m;
+
+function findSessionDep(files) {
+	const candidates = [];
+	for (const file of files) {
+		const text = fs.readFileSync(file, 'utf8');
+		const m = text.match(SESSION_DEP_RE);
+		if (m) candidates.push({ file, name: m[1] });
+	}
+	if (candidates.length === 0) return null;
+	candidates.sort((a, b) => {
+		const depthA = a.file.split(path.sep).length;
+		const depthB = b.file.split(path.sep).length;
+		return depthA !== depthB ? depthA - depthB : a.file.localeCompare(b.file);
+	});
+	return candidates[0];
+}
+
+function dottedModulePath(file, importRoot) {
+	const rel = path.relative(importRoot, file).replace(/\.py$/, '');
+	return rel.split(path.sep).join('.');
+}
+
+// The descriptor-facing entry point (handles/providers/python-fastapi.mjs's provider.plan). See
+// schemas/handles-plan.schema.json for the sbf.handles-plan/1 envelope this returns.
+export function plan({ repoRoot, scanReport, module: moduleName, resourceFilter }) {
+	const targetModule = moduleName
+		? scanReport.related_modules.find((m) => m.module === moduleName)
+		: scanReport.related_modules[0];
+
+	if (!targetModule) {
+		return {
+			schema: 'sbf.handles-plan/1', provider: 'python-fastapi', module: null, resources: [],
+			notes: ['no related module in the scan report -- run `bskel scan` first, or pass --module explicitly'],
+		};
+	}
+
+	const moduleFiles = [...targetModule.controllers.map((c) => c.file), ...targetModule.entities.map((e) => e.file)].filter(Boolean);
+	const { importRoot, topPackage } = detectImportRoot(moduleFiles, repoRoot);
+	const allProjectFiles = listPythonFilesUnder(path.join(importRoot, topPackage));
+	const sessionDep = findSessionDep(allProjectFiles);
+
+	const resources = [];
+	const notes = [];
+
+	for (const entity of targetModule.entities) {
+		if (resourceFilter && !resourceFilter.includes(entity.className)) continue;
+		const fetchRoute = findFetchRoute(targetModule.controllers, entity.className);
+		const publicModel = fetchRoute ? findPublicModel(entity.file, entity.className) : null;
+
+		if (!fetchRoute) {
+			notes.push(`${entity.className}: no single-resource GET route found on a router whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
+		} else if (!publicModel) {
+			notes.push(`${entity.className}: no ${entity.className}Public class found in ${path.relative(repoRoot, entity.file)} -- resolver NOT generated (a generic handle-fetch route serializing the raw table model could leak a column the app never otherwise exposes, e.g. a password hash). Add a Public projection class and re-run.`);
+		}
+		if (fetchRoute && !entity.idField) {
+			notes.push(`${entity.className}: no primary-key field detected on the table model -- resolver NOT generated.`);
+		}
+		if (fetchRoute && publicModel && entity.idField && !sessionDep) {
+			notes.push(`${entity.className}: fetch route and Public model found, but no SessionDep-shaped dependency alias (Annotated[Session, Depends(...)]) was found anywhere under ${topPackage}/ -- resolver NOT generated.`);
+		}
+		if (fetchRoute) {
+			notes.push(`${entity.className}: static scanning cannot safely determine this route's real authorization logic (see ${path.relative(repoRoot, fetchRoute.file)}:${fetchRoute.line}) -- the generated resolver's check_access() always denies until hand-wired.`);
+		}
+
+		const willGenerateResolver = Boolean(fetchRoute && publicModel && entity.idField && sessionDep);
+
+		resources.push({
+			type: entity.className,
+			table: entity.table,
+			idField: entity.idField,
+			readPath: fetchRoute ? `session.get(${entity.className}, ${entity.idField})` : null,
+			requiredAuthority: 'TODO_ACCESS_CHECK',
+			willGenerateResolver,
+			// provider-specific extras (additionalProperties: true in schemas/handles-plan.schema.json)
+			fetchRoute,
+			publicModel,
+			modelImport: dottedModulePath(entity.file, importRoot),
+			sessionDep,
+		});
+	}
+
+	if (resources.length === 0) {
+		notes.push(`no entities found for module "${targetModule.module}" ${resourceFilter ? `matching --resource filter [${resourceFilter.join(', ')}]` : ''} -- nothing to plan.`);
+	}
+
+	return {
+		schema: 'sbf.handles-plan/1',
+		provider: 'python-fastapi',
+		importRoot,
+		topPackage,
+		module: targetModule.module,
+		resources,
+		notes,
+	};
+}

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

@@ -0,0 +1 @@
+# Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.

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

@@ -0,0 +1,122 @@
+"""Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate,
+or the JS/Java/Python implementations will silently diverge.
+
+Encodes/decodes backend-skeleton "handles" (kind:type:uuid[:pointer], base64url with an "sbf1_"
+prefix). Must stay behavior-identical to handles/codec.mjs (the JS reference implementation) --
+verified by an executed round-trip test (test/handles-python-codec.test.mjs), not just by
+inspection. See D-handles-providers in DECISIONS.md.
+"""
+import base64
+import re
+import uuid
+
+NS_SBF_FIELD = uuid.UUID("a3f1c2e0-8b4d-4f1a-9c3e-1d2b3a4c5d6e")
+
+_UUID_PATTERN = r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
+_HANDLE_RE = re.compile(rf"^([rfo]):([^:]+):({_UUID_PATTERN})(?::(.*))?$", re.IGNORECASE)
+_BASE64URL_CHARSET_RE = re.compile(r"^[A-Za-z0-9_-]*$")
+
+MAX_HANDLE_TOKEN_LENGTH = 2048
+
+
+def _base64url_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+# D-security-10 parity, confirmed against this Python runtime directly: `base64.urlsafe_b64decode`
+# silently discards characters outside the base64 alphabet instead of rejecting them -- the exact
+# same defect handles/codec.mjs fixed for Node's `Buffer.from(str, 'base64')`. Without this
+# explicit charset check first, a corrupted/tampered handle token could decode to a DIFFERENT
+# valid-looking payload instead of raising.
+def _base64url_decode(s: str) -> bytes:
+    if not _BASE64URL_CHARSET_RE.match(s):
+        raise ValueError("not valid base64url after the sbf1_ prefix")
+    # Padding restoration must match handles/codec.mjs's own formula exactly:
+    # `(4 - (str.length % 4)) % 4` -- arithmetically identical to `-len(s) % 4` in Python.
+    padded = s + "=" * (-len(s) % 4)
+    try:
+        return base64.urlsafe_b64decode(padded)
+    except Exception as exc:  # binascii.Error (a ValueError subclass) on malformed input
+        raise ValueError("not valid base64url after the sbf1_ prefix") from exc
+
+
+def encode_handle(kind: str, type_: str, resource_uuid: str, pointer: str | None = None) -> str:
+    if kind not in ("r", "f", "o"):
+        raise ValueError(f'invalid handle kind "{kind}" (expected r, f, or o)')
+    if not type_ or not resource_uuid:
+        raise ValueError("encode_handle requires both type_ and resource_uuid")
+    if kind == "f" and not pointer:
+        raise ValueError("field handles (kind=f) require a JSON Pointer")
+    if kind != "f" and pointer:
+        raise ValueError(f'handle kind "{kind}" must not carry a JSON Pointer (only kind=f field handles do)')
+    raw = f"{kind}:{type_}:{resource_uuid}" + (f":{pointer}" if pointer else "")
+    return "sbf1_" + _base64url_encode(raw.encode("utf-8"))
+
+
+class DecodedHandle:
+    __slots__ = ("kind", "type", "uuid", "pointer")
+
+    def __init__(self, kind: str, type_: str, resource_uuid: str, pointer: str | None):
+        self.kind = kind
+        self.type = type_
+        self.uuid = resource_uuid
+        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)')
+    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")
+    match = _HANDLE_RE.match(raw)
+    if not match:
+        raise ValueError(f'malformed handle payload after decoding: "{raw}"')
+    kind, type_, resource_uuid, pointer = match.groups()
+    return DecodedHandle(kind.lower(), type_, resource_uuid.lower(), pointer)
+
+
+def derive_handle_uid(kind: str, type_: str, resource_uuid: str, pointer: str | None) -> str:
+    if kind == "r":
+        return resource_uuid
+    if kind == "f":
+        if not pointer:
+            raise ValueError("field handles require a pointer to derive handle_uid")
+        return str(uuid.uuid5(NS_SBF_FIELD, f"{type_}:{resource_uuid}:{pointer}"))
+    if kind == "o":
+        return str(uuid.uuid5(NS_SBF_FIELD, f"{type_}:{resource_uuid}:o"))
+    raise ValueError(f'invalid handle kind "{kind}"')
+
+
+# G4 follow-up (D-handles-providers): a sentinel, not `None`, for "path does not resolve" -- a
+# literal port of handles/codec.mjs's resolveJsonPointer (which relies on JS's `undefined` being
+# distinct from `null` at every step) would conflate "field is genuinely JSON null" with "field
+# doesn't exist" under Python's plain `dict.get()`/`None`, turning a present-but-null field into a
+# 404 instead of a 200 with `null` -- a real correctness regression, not a stylistic difference.
+MISSING = object()
+
+
+def resolve_json_pointer(obj, pointer: str | None):
+    if pointer is None or pointer == "":
+        return obj
+    if not pointer.startswith("/"):
+        raise ValueError(f'invalid JSON Pointer "{pointer}" -- must start with "/"')
+    parts = [p.replace("~1", "/").replace("~0", "~") for p in pointer.split("/")[1:]]
+    current = obj
+    for part in parts:
+        if current is None:
+            return MISSING
+        if isinstance(current, list):
+            if not re.fullmatch(r"-?\d+", part):
+                return MISSING
+            idx = int(part)
+            if idx < 0 or idx >= len(current):
+                return MISSING
+            current = current[idx]
+        elif isinstance(current, dict):
+            if part not in current:
+                return MISSING
+            current = current[part]
+        else:
+            return MISSING
+    return current

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

@@ -0,0 +1,96 @@
+"""Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+
+G4 follow-up (D-handles-providers): mirrors Java's HandleService.java.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 apply @record_snapshot (see record_snapshot.py) to an existing service
+function to have it called for you.
+
+Plain module-level functions taking `session` explicitly, not a class with injected dependencies
+-- matches this provider's own established convention (every resolver method already takes
+`session` as an explicit call-time argument; there is no DI container here the way Spring's
+@Service beans have).
+"""
+import uuid
+from datetime import datetime, timezone
+
+from sqlmodel import Session, select
+
+from {{PKG}}.handles.codec import encode_handle, derive_handle_uid
+from {{PKG}}.handles.tables import HandleRegistry, HandleSnapshot
+
+
+def register(
+    session: Session,
+    kind: str,
+    type_: str,
+    resource_uid: uuid.UUID,
+    pointer: str | None,
+    feature_uid: uuid.UUID,
+    operation_id: str | None,
+    contract_ref: str,
+) -> str:
+    """Derives handle_uid and UPSERTS the registry row -- the schema's own
+    unique(resource_type, resource_uid, pointer) constraint means the SAME (kind, type,
+    resource_uid, pointer) triple always derives the SAME handle_uid, so re-registering it is
+    expected, not an error: an existing row has its feature_uid/operation_id/contract_ref
+    refreshed, but revoked_at/revoked_reason are NEVER touched here -- re-registering a revoked
+    handle must never silently un-revoke it. Returns the encoded handle token.
+    """
+    token = encode_handle(kind, type_, str(resource_uid), pointer)
+    handle_uid = uuid.UUID(derive_handle_uid(kind, type_, str(resource_uid), pointer))
+    existing = session.get(HandleRegistry, handle_uid)
+    if existing is None:
+        session.add(HandleRegistry(
+            handle_uid=handle_uid, kind=kind, resource_type=type_, resource_uid=resource_uid,
+            pointer=pointer, feature_uid=feature_uid, operation_id=operation_id, contract_ref=contract_ref,
+        ))
+    else:
+        existing.feature_uid = feature_uid
+        existing.operation_id = operation_id
+        existing.contract_ref = contract_ref
+        session.add(existing)
+    session.commit()
+    return token
+
+
+def record_snapshot(
+    session: Session,
+    handle_uid: uuid.UUID,
+    envelope_dir: str,
+    operation_id: str,
+    contract_hash: str,
+    payload,
+) -> None:
+    """Records one envelope for an already-registered handle. `payload` is a plain
+    dict/list/scalar (already JSON-serializable), stored directly into the native JSONB column --
+    no manual json.dumps/json.loads round-trip exists here for `recover` to get wrong later.
+    """
+    session.add(HandleSnapshot(
+        handle_uid=handle_uid, envelope_dir=envelope_dir, operation_id=operation_id,
+        contract_hash=contract_hash, payload=payload,
+    ))
+    session.commit()
+
+
+def revoke(session: Session, handle_uid: uuid.UUID, reason: str) -> None:
+    registry = session.get(HandleRegistry, handle_uid)
+    if registry is not None:
+        registry.revoked_at = datetime.now(timezone.utc)
+        registry.revoked_reason = reason
+        session.add(registry)
+        session.commit()
+
+
+def prune_snapshots_older_than(session: Session, cutoff: datetime) -> int:
+    """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.
+    """
+    rows = session.exec(select(HandleSnapshot).where(HandleSnapshot.recorded_at < cutoff)).all()
+    for row in rows:
+        session.delete(row)
+    session.commit()
+    return len(rows)