backend-skeleton 1.0.0-beta.1

package/handles/providers/python-fastapi/templates/migration.sql.tmpl

@@ -0,0 +1,35 @@
+-- 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
+-- Alembic setup, wrapped in `op.execute(open("migration.sql").read())` 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 provider's own
+-- migration.sql.tmpl, so both 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/python-fastapi/templates/record_snapshot.py.tmpl

@@ -0,0 +1,155 @@
+"""Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+
+G4 follow-up (D-handles-providers): the opt-in AUTOMATIC half of the handle lifecycle -- apply
+`@record_snapshot(...)` to 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.
+
+Combines Java's separate `@RecordHandleSnapshot` annotation + `HandleAspect` interceptor into ONE
+file/decorator, deliberately -- Python decorators natively ARE this ecosystem's method-
+interception mechanism, so there is no separate "declare a marker" vs. "implement the
+interceptor" split to preserve; splitting this into two files would be cargo-culting Java's file
+count, not mirroring an invariant.
+
+`resource_uid_param`/`session_param` are explicit parameter NAMES (not positional indices --
+resolved via inspect.signature(fn).bind(...), so the SAME function can be called positionally or
+by keyword by different callers without silently misattributing a snapshot to the wrong resource,
+which a bare `args[index]` would do for any keyword call). `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) -- Python decorators need
+no framework support -- but still requires a human to apply it to their own code; codegen never
+touches an existing business logic file.
+
+Example:
+    @record_snapshot(resource_type="Organization", operation_id="update_organization",
+                      resource_uid_param="organization_id", session_param="session",
+                      redact=["/internal_note"])
+    def update_organization(session: Session, organization_id: uuid.UUID, request: UpdateOrganizationRequest) -> OrganizationResponse:
+        ...
+"""
+import functools
+import inspect
+import logging
+import uuid
+
+from {{PKG}}.handles import handle_service
+from {{PKG}}.handles.codec import derive_handle_uid
+from {{PKG}}.handles.registry import resolver_for
+
+logger = logging.getLogger(__name__)
+
+
+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
+    mutable (no read-only-.at()-style limitation to work around). Same ~1/~0 unescaping.
+    """
+    if not pointer or not pointer.startswith("/"):
+        return
+    parts = [p.replace("~1", "/").replace("~0", "~") for p in pointer[1:].split("/")]
+    current = obj
+    for part in parts[:-1]:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        elif isinstance(current, list) and part.lstrip("-").isdigit() and int(part) < len(current):
+            current = current[int(part)]
+        else:
+            return
+    leaf = parts[-1]
+    if isinstance(current, dict) and leaf in current:
+        current[leaf] = "***REDACTED***"
+    elif isinstance(current, list) and leaf.lstrip("-").isdigit() and int(leaf) < len(current):
+        current[int(leaf)] = "***REDACTED***"
+
+
+def _request_payload(bound: inspect.BoundArguments, resource_uid_param: str, session_param: str):
+    """The remaining arguments once the resource-uid/session ones are excluded -- the sole
+    survivor UNWRAPPED (the common case: one DTO), matching Java's own HandleAspect#requestPayload
+    exactly, so a `redact` pointer written against the DTO's own fields (e.g. "/internal_note")
+    resolves correctly. A real bug this design initially had and a real functional test caught:
+    an earlier draft always wrapped in `{param_name: value}`, so "/internal_note" silently never
+    matched anything (the real shape was `{"request": {"internal_note": ...}}`) -- redaction
+    looked like it worked (no error) but never actually redacted anything in the common
+    single-DTO case. Falls back to a dict keyed by parameter name (not Java's positional list --
+    Python's bound arguments already carry names) only when more than one non-uid/session
+    parameter remains.
+    """
+    rest = {k: _to_jsonable(v) for k, v in bound.arguments.items() if k not in (resource_uid_param, session_param)}
+    if len(rest) == 1:
+        return next(iter(rest.values()))
+    return rest
+
+
+def _to_jsonable(value):
+    """Best-effort plain-dict/list/scalar projection -- a Pydantic/SQLModel object's own
+    `.model_dump(mode="json")`, or the value as-is if it's already a plain JSON-shaped value
+    (matches the payload shapes this decorator actually receives: request DTOs, response models,
+    or a plain {"message": ...} error dict).
+    """
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    return value
+
+
+def _safely(action, handle_uid, envelope_dir: str) -> None:
+    """Best-effort: any failure here is logged, never propagated -- see this module's own
+    docstring for why.
+    """
+    try:
+        action()
+    except Exception:
+        logger.warning("record_snapshot: could not record %s snapshot for handle %s -- the wrapped call proceeds unaffected", envelope_dir, handle_uid, exc_info=True)
+
+
+def record_snapshot(*, resource_type: str, operation_id: str, resource_uid_param: str, session_param: str, redact: list[str] | None = None):
+    redact = redact or []
+
+    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
+
+        return wrapper
+
+    return decorator

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

@@ -0,0 +1,37 @@
+"""Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+
+In-process registry mapping a handle `type` string to its resolver instance -- deliberately NOT a
+database table. NOT the same concept as the `HandleRegistry` DB table in `tables.py` (G4
+follow-up, D-handles-providers) -- that table backs a real `GET /handles/{handle}/recover`;
+this dict is pure in-process dispatch, no persistence at all. The names collide only because
+Java's own naming does; treat them as unrelated.
+"""
+from typing import Protocol, runtime_checkable
+from uuid import UUID
+
+
+@runtime_checkable
+class ResourceResolver(Protocol):
+    type: str
+    # G4 follow-up: baked in at `bskel handles emit` time (regenerated every run, so a contract
+    # change is picked up automatically), never read from disk at runtime. handle_service.register
+    # stores contract_ref as a registry row's contract_ref; `recover`'s schema_drift check compares
+    # a snapshot's own recorded hash against the CURRENT value of this attribute, not a stale one.
+    contract_ref: str
+    feature_uid: UUID
+
+    def fetch(self, session, resource_uid): ...
+    def check_access(self, session, obj) -> None: ...
+    def patch_field(self, session, obj, pointer, value) -> None: ...
+    def to_public(self, obj): ...
+
+
+_RESOLVERS: dict[str, "ResourceResolver"] = {}
+
+
+def register(resolver: "ResourceResolver") -> None:
+    _RESOLVERS[resolver.type] = resolver
+
+
+def resolver_for(type_: str) -> "ResourceResolver | None":
+    return _RESOLVERS.get(type_)

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

@@ -0,0 +1,59 @@
+"""Generated by backend-skeleton (bskel handles emit) for feature {{FEATURE_ID}}.
+type = "{{RESOURCE_TYPE}}"
+
+`fetch`/`to_public` are wired to real, existing code: `fetch` uses SQLModel's `session.get(...)`,
+this stack's own canonical read path, and `to_public` projects through {{PUBLIC_MODEL}} -- required
+so a generic handle-fetch route can never accidentally serialize a column the app does not
+otherwise expose (a real example this provider was built against: a table model carrying a
+password hash column with no `response_model=`-shaped protection of its own). See the fetch route
+this was planned from: {{FETCH_ROUTE_FILE}}:{{FETCH_ROUTE_LINE}}.
+
+`check_access` is DELIBERATELY a fail-closed stub, not auto-generated business logic. FastAPI has
+no imperatively-readable global security context the way Spring's SecurityContextHolder is, and
+this stack's own real authorization logic lives inside route function bodies (per-row checks),
+which a static source scan cannot safely extract. Wire it to whatever this app's own current-
+user/permission pattern is before relying on it -- until then, every request is denied.
+
+`patch_field` is DELIBERATELY a stub for the same reason Java's ResourceResolverStub.java.tmpl's
+patchField() is: this stack's own update conventions must be checked by a human before writing to
+them (see D-resolver-scope in DECISIONS.md) -- do not write directly against the ORM, that
+bypasses this app's existing validation and business rules.
+"""
+import uuid
+
+from fastapi import HTTPException
+
+from {{MODEL_IMPORT}} import {{MODEL}}, {{PUBLIC_MODEL}}
+from {{PKG}}.handles.registry import register
+
+# G4 follow-up (D-handles-providers): baked in at `bskel handles emit` time, mirroring Java's
+# ResourceResolverStub.java.tmpl exactly -- see registry.py's own ResourceResolver.contract_ref/
+# feature_uid docstring for what these back.
+CONTRACT_REF = "{{CONTRACT_REF}}"
+FEATURE_UID = uuid.UUID("{{FEATURE_UID}}")
+
+
+class {{RESOURCE_TYPE}}Resolver:
+    type = "{{RESOURCE_TYPE}}"
+    contract_ref = CONTRACT_REF
+    feature_uid = FEATURE_UID
+
+    def fetch(self, session, resource_uid):
+        return session.get({{MODEL}}, resource_uid)
+
+    def check_access(self, session, obj) -> None:
+        # TODO: wire this app's own current-user/permission check before relying on this resolver.
+        # Fails closed until then -- every request is denied, not silently permitted.
+        raise HTTPException(status_code=403, detail="access check not yet implemented for {{RESOURCE_TYPE}}")
+
+    def patch_field(self, session, obj, pointer, value) -> None:
+        # TODO: route through this app's real update path for {{MODEL}}, matching whichever
+        # partial-update convention its own schemas actually use. Do not write directly to `obj`'s
+        # attributes and commit -- that bypasses this app's existing validation/business rules.
+        raise HTTPException(status_code=501, detail=f"patch_field not yet implemented for {{RESOURCE_TYPE}}{pointer}")
+
+    def to_public(self, obj):
+        return {{PUBLIC_MODEL}}.model_validate(obj)
+
+
+register({{RESOURCE_TYPE}}Resolver())

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

@@ -0,0 +1,13 @@
+"""Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+
+Auto-imports every sibling module in this package so each resolver's own `register(...)` call at
+import time runs exactly once. Keeps this file itself feature-independent (its content never
+depends on which resolvers exist), which is what lets `bskel handles emit` treat it as repo-owned
+infra rather than needing to regenerate it per feature.
+"""
+import importlib
+import pkgutil
+
+for _mod in pkgutil.iter_modules(__path__):
+    if not _mod.name.startswith("_"):
+        importlib.import_module(f"{__name__}.{_mod.name}")

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

@@ -0,0 +1,140 @@
+"""Generated by backend-skeleton.
+
+D-handles (DECISIONS.md): exposed in production. Per-resolver `check_access()` is the entire
+defense for this generic-object-accessor security surface -- see the docstring on each generated
+resolver for why it is ALWAYS a fail-closed stub in this provider (FastAPI has no imperatively
+readable global security context the way Spring's SecurityContextHolder is, and this app's own
+real authorization logic lives inside route function bodies, not decorators -- a static source
+scan cannot safely extract it).
+"""
+import uuid
+from datetime import datetime
+
+from fastapi import APIRouter, HTTPException, Query
+from sqlmodel import select
+
+from {{PKG}}.handles.codec import decode_handle, derive_handle_uid, resolve_json_pointer, MISSING
+from {{PKG}}.handles.registry import resolver_for
+from {{PKG}}.handles.tables import HandleRegistry, HandleSnapshot
+from {{SESSION_DEP_MODULE}} import {{SESSION_DEP_NAME}}
+
+router = APIRouter(prefix="/handles", tags=["handles"])
+
+
+@router.get("/{handle}")
+def fetch_handle(handle: str, session: {{SESSION_DEP_NAME}}):
+    try:
+        decoded = decode_handle(handle)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    resolver = resolver_for(decoded.type)
+    if resolver is None:
+        raise HTTPException(status_code=404, detail=f'no resolver registered for handle type "{decoded.type}"')
+
+    obj = resolver.fetch(session, decoded.uuid)
+    if obj is None:
+        raise HTTPException(status_code=404, detail="resource not found")
+    resolver.check_access(session, obj)
+    public = resolver.to_public(obj)
+    if decoded.pointer is None:
+        return public
+
+    # G4 follow-up (D-handles-providers): walks the PUBLIC projection, not the raw `fetch()`
+    # row -- a deliberate, security-preserving departure from Java's own literal code shape, not
+    # a weakening. Java's fetch() safely returns a walkable object because it already delegates
+    # to the resource's real response DTO; this provider's own fetch() returns the raw ORM row by
+    # original G4 design (to_public() is a SEPARATE, required projection specifically because a
+    # table can carry columns -- e.g. a password hash -- with no protection besides each route's
+    # own response_model=). Walking the raw row here would silently reopen exactly the column-leak
+    # vector to_public() exists to close (a crafted field handle with pointer "/hashed_password").
+    root = public.model_dump(mode="json") if hasattr(public, "model_dump") else public
+    target = resolve_json_pointer(root, decoded.pointer)
+    if target is MISSING:
+        raise HTTPException(status_code=404, detail=f'pointer "{decoded.pointer}" does not resolve on {decoded.type}')
+    return target
+
+
+@router.patch("/{handle}", status_code=204)
+def patch_handle(handle: str, session: {{SESSION_DEP_NAME}}, value: dict):
+    try:
+        decoded = decode_handle(handle)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    # D-security-10 parity: checks kind explicitly, not just pointer-presence -- mirrors
+    # HandleController.java.tmpl's identical check.
+    if decoded.kind != "f" or decoded.pointer is None:
+        raise HTTPException(status_code=400, detail="cannot PATCH a resource-level handle (kind=r) -- only field handles (kind=f) support PATCH")
+
+    resolver = resolver_for(decoded.type)
+    if resolver is None:
+        raise HTTPException(status_code=404, detail=f'no resolver registered for handle type "{decoded.type}"')
+
+    obj = resolver.fetch(session, decoded.uuid)
+    if obj is None:
+        raise HTTPException(status_code=404, detail="resource not found")
+    resolver.check_access(session, obj)
+    resolver.patch_field(session, obj, decoded.pointer, value)
+
+
+# G4 follow-up (D-handles-providers): mirrors HandleController.recover() including its full
+# D-security-9 cross-check -- never weakened. handle_uid alone does not prove WHAT is being
+# recovered (kind="r"'s derivation returns the resource UUID verbatim, no type binding baked into
+# the hash), so an attacker who controls `type` in the token (as long as it names a real,
+# registered resolver whose check_access() they can pass) could otherwise request the snapshot
+# history of a DIFFERENT, more sensitive resource type sharing the same UUID. Fix: cross-check the
+# decoded type/kind/pointer against the registry row this handle_uid was actually registered
+# under, and 404 on ANY disagreement -- without saying which field mismatched, so the error can't
+# be used to probe which part was wrong. A revoked handle is rejected the same way.
+#
+# Ecosystem-honest gap, not silently resolved: Java's role check is resource-existence-independent
+# (recovering history of a since-deleted resource is legitimate), so it never calls fetch() at
+# all before the registry check. This provider's own check_access(session, obj) is deliberately
+# ROW-level (every shipped resolver's check_access already denies unconditionally regardless of
+# obj, so calling fetch() first and passing obj=None through for a deleted resource is safe
+# today) -- but a human wiring a real check_access() must handle obj=None explicitly, or recover()
+# can never recall history for a resource that no longer exists.
+@router.get("/{handle}/recover")
+def recover_handle(handle: str, session: {{SESSION_DEP_NAME}}, at: datetime | None = Query(default=None)):
+    try:
+        decoded = decode_handle(handle)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    resolver = resolver_for(decoded.type)
+    if resolver is None:
+        raise HTTPException(status_code=404, detail=f'no resolver registered for handle type "{decoded.type}"')
+
+    obj = resolver.fetch(session, decoded.uuid)
+    resolver.check_access(session, obj)
+
+    handle_uid = uuid.UUID(derive_handle_uid(decoded.kind, decoded.type, decoded.uuid, decoded.pointer))
+    registry = session.get(HandleRegistry, handle_uid)
+    if (
+        registry is None
+        or registry.resource_type != decoded.type
+        or registry.kind != decoded.kind
+        or registry.pointer != decoded.pointer
+        or registry.is_revoked
+    ):
+        raise HTTPException(status_code=404, detail="no snapshot recorded for this handle")
+
+    query = select(HandleSnapshot).where(HandleSnapshot.handle_uid == handle_uid)
+    if at is not None:
+        query = query.where(HandleSnapshot.recorded_at <= at)
+    snapshot = session.exec(query.order_by(HandleSnapshot.recorded_at.desc())).first()
+    if snapshot is None:
+        detail = "no snapshot recorded for this handle" + (f" at or before {at}" if at is not None else "")
+        raise HTTPException(status_code=404, detail=detail)
+
+    return {
+        "handle": handle,
+        "recorded_at": snapshot.recorded_at,
+        "operation_id": snapshot.operation_id,
+        # snapshot.payload is already a native dict/list/scalar (a real JSONB column) -- no
+        # manual re-parse step exists here for the double-encoding bug Java once had to be
+        # possible in the first place. See tables.py's own docstring.
+        "payload": snapshot.payload,
+        "schema_drift": registry.contract_ref != snapshot.contract_hash,
+    }

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

@@ -0,0 +1,66 @@
+"""Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+
+G4 follow-up (D-handles-providers): mirrors Java's HandleRegistry.java.tmpl/HandleSnapshot.java.tmpl
+(sbf_handle/sbf_handle_snapshot) -- same table names, columns, and unique(resource_type,
+resource_uid, pointer) constraint, so both 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.py
+-- that file is an in-process type->resolver dispatch dict; HandleRegistry here is a real database
+table. The names collide only because Java's own naming does; treat them as unrelated.
+
+`HandleSnapshot.payload` is a native `JSONB` column holding a plain dict/list -- SQLAlchemy
+(de)serializes at the DB boundary automatically. There is no manual json.dumps/json.loads step
+anywhere in this provider for `payload` to round-trip through, unlike Java's own `payload` column
+(a manually (de)serialized String) -- the exact bug class that once caused Java's recover() to
+double-JSON-encode a caller's payload (forgetting to re-parse a raw string before re-embedding it)
+is structurally impossible here, not merely avoided by a matching fix.
+"""
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import Column, UniqueConstraint
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlmodel import Field, SQLModel
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class HandleRegistry(SQLModel, table=True):
+    __tablename__ = "sbf_handle"
+    __table_args__ = (UniqueConstraint("resource_type", "resource_uid", "pointer"),)
+
+    handle_uid: uuid.UUID = Field(primary_key=True)
+    # "r" (resource), "f" (field), or "o" (operation instance -- reserved, unused).
+    kind: str
+    resource_type: str
+    resource_uid: uuid.UUID
+    # RFC 6901 JSON Pointer, None for kind="r".
+    pointer: str | None = None
+    feature_uid: uuid.UUID
+    operation_id: str | None = None
+    contract_ref: str
+    created_at: datetime = Field(default_factory=_utcnow)
+    revoked_at: datetime | None = None
+    revoked_reason: str | None = None
+
+    @property
+    def is_revoked(self) -> bool:
+        return self.revoked_at is not None
+
+
+class HandleSnapshot(SQLModel, table=True):
+    __tablename__ = "sbf_handle_snapshot"
+
+    snapshot_id: int | None = Field(default=None, primary_key=True)
+    handle_uid: uuid.UUID = Field(foreign_key="sbf_handle.handle_uid")
+    # "request", "response", or "error" -- what kind of payload this envelope holds.
+    envelope_dir: str
+    operation_id: str
+    # 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 schema_drift marker) rather than silently returning a
+    # payload the current contract no longer describes.
+    contract_hash: str
+    payload: dict | list | str | int | float | bool | None = Field(sa_column=Column(JSONB, nullable=False))
+    recorded_at: datetime = Field(default_factory=_utcnow)

package/handles/providers/python-fastapi.mjs

@@ -0,0 +1,22 @@
+import { plan } from './python-fastapi/plan.mjs';
+import { emitPythonFastApi } from './python-fastapi/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). The real second codegen provider G1's own
+// D-adapter-registry EXIT held out for before the java-spring extraction (handles/providers/
+// java-spring.mjs) was worth doing at all.
+export const provider = {
+	contract: 'sbf.handles-provider/1',
+	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.
+	outputs: { spec: ['handles/migration.sql'] },
+	plan,
+	emit(args) {
+		return emitPythonFastApi(args);
+	},
+};

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

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { emitUnits } from '../../_engine.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 RESOLVERS_INDEX_TEMPLATE = path.join(TEMPLATES_DIR, 'resolvers_index.ts.tmpl');
+
+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 -> camelCase filename, good enough for the class names this scanner actually
+// extracts (ASCII identifiers only, same assumption every other provider's own naming makes).
+function camelCase(s) {
+	return s.length > 0 ? s[0].toLowerCase() + s.slice(1) : s;
+}
+
+// Relative TS import specifier from `fromFile`'s own directory to `toFile`, extension-stripped,
+// forward-slash-joined (Node import specifiers are never OS-path-separated), always explicitly
+// relative (`./x`, not bare `x`) so generated code never depends on a target's own tsconfig
+// `baseUrl` being set a particular way.
+function relativeImportPath(fromFile, toFile) {
+	const fromDir = path.dirname(fromFile);
+	let rel = path.relative(fromDir, toFile).replace(/\.ts$/, '');
+	rel = rel.split(path.sep).join('/');
+	if (!rel.startsWith('.')) rel = `./${rel}`;
+	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 }) {
+	const handlesDir = path.join(plan.srcRoot, 'handles');
+	const resolversDir = path.join(handlesDir, 'resolvers');
+	const resolversIndexPath = path.join(resolversDir, 'resolvers_index.ts');
+
+	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'), {}) },
+	];
+
+	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 {
+				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 }),
+			};
+		});
+
+	const orphanScan = (!resourceFilter && plan.module) ? {
+		dir: resolversDir,
+		module: plan.module,
+		matchesFile: (file) => file.endsWith('.ts') && file !== 'resolvers_index.ts',
+		// Filename can't reliably recover the exact class-name casing -- read the `type: 'X'` field
+		// the resolver template itself carries instead of guessing from the filename, same content-
+		// read approach python-fastapi's own orphan scan already uses.
+		resourceTypeOf: (_file, content) => {
+			const m = content.match(/^\s*type:\s*'([^']+)'/m);
+			return m ? m[1] : null;
+		},
+	} : null;
+
+	const result = emitUnits({ repoRoot, featureId, provider: 'typescript-express', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff });
+
+	// 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);
+	}
+	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.`,
+		],
+	};
+}