svc-infra 0.1.622__py3-none-any.whl → 0.1.624__py3-none-any.whl

svc_infra/cli/cmds/docs/docs_cmds.py

@@ -1,9 +1,8 @@
 from __future__ import annotations
 
-import importlib.util
 import os
-import sys
-from importlib.metadata import PackageNotFoundError, distribution
+from importlib.resources import as_file
+from importlib.resources import files as pkg_files
 from pathlib import Path
 from typing import Dict, List
 
@@ -13,153 +12,88 @@ from typer.core import TyperGroup
 
 from svc_infra.app.root import resolve_project_root
 
-# ---------- small helpers ----------
-
 
 def _norm(name: str) -> str:
     return name.strip().lower().replace(" ", "-").replace("_", "-")
 
 
-def _md_topics_in(dirpath: Path) -> Dict[str, Path]:
+def _discover_fs_topics(docs_dir: Path) -> Dict[str, Path]:
     topics: Dict[str, Path] = {}
-    if dirpath.exists() and dirpath.is_dir():
-        for p in sorted(dirpath.glob("*.md")):
+    if docs_dir.exists() and docs_dir.is_dir():
+        for p in sorted(docs_dir.glob("*.md")):
             if p.is_file():
                 topics[_norm(p.stem)] = p
     return topics
 
 
-# ---------- where could docs live after install? ----------
+def _discover_pkg_topics() -> Dict[str, Path]:
+    """
+    Discover docs shipped inside the installed package at svc_infra/docs/*,
+    using importlib.resources so this works for wheels, sdists, and zipped wheels.
+    """
+    topics: Dict[str, Path] = {}
+    try:
+        docs_root = pkg_files("svc_infra").joinpath("docs")
+        # docs_root is a Traversable; it may be inside a zip. Iterate safely.
+        for entry in docs_root.iterdir():
+            if entry.name.endswith(".md"):
+                # materialize to a real tempfile path if needed
+                with as_file(entry) as concrete:
+                    p = Path(concrete)
+                    if p.exists() and p.is_file():
+                        topics[_norm(p.stem)] = p
+    except Exception:
+        # If the package has no docs directory, just return empty.
+        pass
+    return topics
 
 
-def _candidate_docs_dirs(ctx: click.Context) -> List[Path]:
+def _resolve_docs_dir(ctx: click.Context) -> Path | None:
     """
-    Return likely directories that contain the shipped docs (*.md), ordered by priority.
-    Covers:
-      1) explicit --docs-dir / env var
-      2) in-repo (editable install):   <repo>/docs  relative to src/svc_infra
-      3) wheel installs:               <site-packages>/docs
-      4) wheel .data area:             <site-packages>/{name}-{ver}.data/**/docs
+    Optional override precedence:
+      1) --docs-dir CLI option
+      2) SVC_INFRA_DOCS_DIR env var
+      3) *Only when working inside the svc-infra repo itself*: repo-root /docs
     """
-    out: List[Path] = []
-
-    # 1) explicit override (--docs-dir or env)
-    #    Walk up parent contexts to see Typer's group option.
-    cur: click.Context | None = ctx
-    while cur is not None:
-        docs_dir_opt = (cur.params or {}).get("docs_dir")
+    # 1) CLI option on this or parent contexts
+    current: click.Context | None = ctx
+    while current is not None:
+        docs_dir_opt = (current.params or {}).get("docs_dir")
         if docs_dir_opt:
-            p = docs_dir_opt if isinstance(docs_dir_opt, Path) else Path(docs_dir_opt)
-            p = p.expanduser()
-            if p.exists():
-                out.append(p)
-                return out  # explicit override wins
-        cur = cur.parent
+            path = docs_dir_opt if isinstance(docs_dir_opt, Path) else Path(docs_dir_opt)
+            path = path.expanduser()
+            if path.exists():
+                return path
+        current = current.parent
 
+    # 2) Env var
     env_dir = os.getenv("SVC_INFRA_DOCS_DIR")
     if env_dir:
         p = Path(env_dir).expanduser()
         if p.exists():
-            out.append(p)
-            return out  # explicit override wins
-
-    # locate installed package dir: .../site-packages/svc_infra
-    pkg_dir: Path | None = None
-    spec = importlib.util.find_spec("svc_infra")
-    if spec and spec.submodule_search_locations:
-        pkg_dir = Path(next(iter(spec.submodule_search_locations)))
-
-    # 2) in-repo editable install: src/svc_infra -> ../../docs
-    if pkg_dir:
-        repo_root_docs = pkg_dir.parent.parent / "docs"
-        if repo_root_docs.exists():
-            out.append(repo_root_docs)
-
-        # 3) wheel installs often end up with a top-level site-packages/docs
-        top_level_docs = pkg_dir.parent / "docs"
-        if top_level_docs.exists():
-            out.append(top_level_docs)
-
-    # 4) wheel .data layout: <site-packages>/{dist-name}-{version}.data/**/docs
-    #    This catches Poetry's include=docs/**/* paths installed by pip.
-    #    We compute sibling candidates off site-packages base.
-    site_pkgs: Path | None = pkg_dir.parent if pkg_dir else None
-    dist = None
-    for name in ("svc-infra", "svc_infra"):
-        try:
-            dist = distribution(name)
-            break
-        except PackageNotFoundError:
-            dist = None
-
-    if site_pkgs and dist is not None:
-        # normalized dist name (hyphen/underscore forms both happen in practice)
-        dist_name = dist.metadata.get("Name", "svc-infra")
-        dist_ver = dist.version
-        data_candidates = [
-            site_pkgs / f"{dist_name}-{dist_ver}.data",
-            site_pkgs / f"{dist_name.replace('-', '_')}-{dist_ver}.data",
-            site_pkgs / f"{dist_name.replace('_', '-')}-{dist_ver}.data",
-        ]
-        for data_dir in data_candidates:
-            if not data_dir.exists():
-                continue
-            # common wheel data subfolders
-            for sub in ("purelib", "platlib", "data"):
-                d = data_dir / sub / "docs"
-                if d.exists():
-                    out.append(d)
-            # fallback: search shallowly for any docs/ folder inside .data
-            for root, dirs, _files in os.walk(data_dir):
-                root_path = Path(root)
-                # limit depth (cheap)
-                if len(root_path.parts) - len(data_dir.parts) > 3:
-                    dirs[:] = []
-                    continue
-                if root_path.name == "docs":
-                    out.append(root_path)
-
-    # 5) extremely defensive: scan sys.path entries that look like site-/dist-packages for top-level docs/
-    for entry in sys.path:
-        if not entry or ("site-packages" not in entry and "dist-packages" not in entry):
-            continue
-        p = Path(entry) / "docs"
-        if p.exists():
-            out.append(p)
-
-    # de-dup while preserving order
-    seen = set()
-    uniq: List[Path] = []
-    for p in out:
-        if p.exists():
-            key = str(p.resolve())
-            if key not in seen:
-                seen.add(key)
-                uniq.append(p)
-    return uniq
-
-
-def _discover_topics(ctx: click.Context) -> Dict[str, Path]:
-    topics: Dict[str, Path] = {}
-    for d in _candidate_docs_dirs(ctx):
-        found = _md_topics_in(d)
-        # do not override earlier (higher-priority) sources
-        for k, v in found.items():
-            topics.setdefault(k, v)
-        if topics:
-            # one dir with content is enough for most setups
-            # (comment out this break if you *want* deep merging)
-            break
-    return topics
+            return p
 
+    # 3) In-repo convenience (so `svc-infra docs` works inside this repo)
+    try:
+        root = resolve_project_root()
+        proj_docs = root / "docs"
+        if proj_docs.exists():
+            return proj_docs
+    except Exception:
+        pass
 
-# ---------- Typer group ----------
+    return None
 
 
 class DocsGroup(TyperGroup):
     def list_commands(self, ctx: click.Context) -> List[str]:
-        topics = _discover_topics(ctx)
-        return sorted(topics.keys())
+        names: List[str] = list(super().list_commands(ctx) or [])
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        pkg = _discover_pkg_topics()
+        names.extend(fs.keys())
+        names.extend([k for k in pkg.keys() if k not in fs])
+        return sorted(set(names))
 
     def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
         cmd = super().get_command(ctx, name)
@@ -167,15 +101,27 @@ class DocsGroup(TyperGroup):
             return cmd
 
         key = _norm(name)
-        topics = _discover_topics(ctx)
-        if key in topics:
-            file_path = topics[key]
+
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        if key in fs:
+            file_path = fs[key]
 
             @click.command(name=name)
-            def _show() -> None:
+            def _show_fs() -> None:
                 click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
 
-            return _show
+            return _show_fs
+
+        pkg = _discover_pkg_topics()
+        if key in pkg:
+            file_path = pkg[key]
+
+            @click.command(name=name)
+            def _show_pkg() -> None:
+                click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
+
+            return _show_pkg
 
         return None
 
@@ -194,31 +140,49 @@ def register(app: typer.Typer) -> None:
     ) -> None:
         if topic:
             key = _norm(topic)
-            topics = _discover_topics(click.get_current_context())
-            if key in topics:
-                typer.echo(topics[key].read_text(encoding="utf-8", errors="replace"))
+            ctx = click.get_current_context()
+            dir_to_use = _resolve_docs_dir(ctx)
+            fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+            if key in fs:
+                typer.echo(fs[key].read_text(encoding="utf-8", errors="replace"))
+                raise typer.Exit(code=0)
+            pkg = _discover_pkg_topics()
+            if key in pkg:
+                typer.echo(pkg[key].read_text(encoding="utf-8", errors="replace"))
                 raise typer.Exit(code=0)
             raise typer.BadParameter(f"Unknown topic: {topic}")
 
     @docs_app.command("list", help="List available documentation topics")
     def list_topics() -> None:
         ctx = click.get_current_context()
-        root = resolve_project_root()
-        topics = _discover_topics(ctx)
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        pkg = _discover_pkg_topics()
 
-        for name, path in topics.items():
+        def _print(name: str, path: Path) -> None:
             try:
-                rel = path.relative_to(root)
-                typer.echo(f"{name}\t{rel}")
-            except Exception:
                 typer.echo(f"{name}\t{path}")
+            except Exception:
+                typer.echo(name)
+
+        for name, path in fs.items():
+            _print(name, path)
+        for name, path in pkg.items():
+            if name not in fs:
+                _print(name, path)
 
     @docs_app.command("show", help="Show docs for a topic (alternative to dynamic subcommand)")
     def show(topic: str) -> None:
         key = _norm(topic)
-        topics = _discover_topics(click.get_current_context())
-        if key in topics:
-            typer.echo(topics[key].read_text(encoding="utf-8", errors="replace"))
+        ctx = click.get_current_context()
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        if key in fs:
+            typer.echo(fs[key].read_text(encoding="utf-8", errors="replace"))
+            return
+        pkg = _discover_pkg_topics()
+        if key in pkg:
+            typer.echo(pkg[key].read_text(encoding="utf-8", errors="replace"))
             return
         raise typer.BadParameter(f"Unknown topic: {topic}")
 

svc_infra/docs/acceptance-matrix.md

@@ -0,0 +1,71 @@
+# Acceptance Matrix (A-IDs)
+
+This document maps Acceptance scenarios (A-IDs) to endpoints, CLIs, fixtures, and seed data. Use it to drive the CI promotion gate and local `make accept` runs.
+
+## A0. Harness
+- Stack: docker-compose.test.yml (api, db, redis)
+- Makefile targets: accept, compose_up, wait, seed, down
+- Tests bootstrap: tests/acceptance/conftest.py (BASE_URL), _auth.py, _seed.py, _http.py
+
+## A1. Security & Auth
+- A1-01 Register → Verify → Login → /auth/me
+  - Endpoints: POST /auth/register, POST /auth/verify, POST /auth/login, GET /auth/me
+  - Fixtures: admin, user
+- A1-02 Password policy & breach check
+  - Endpoints: POST /auth/register
+- A1-03 Lockout escalation and cooldown
+  - Endpoints: POST /auth/login
+- A1-04 RBAC/ABAC enforced
+  - Endpoints: GET /admin/*, resource GET with owner guard
+- A1-05 Session list & revoke
+  - Endpoints: GET/DELETE /auth/sessions
+- A1-06 API keys lifecycle
+  - Endpoints: POST/GET/DELETE /auth/api-keys, usage via Authorization header
+- A1-07 MFA lifecycle
+  - Endpoints: /auth/mfa/*
+
+## A2. Rate Limiting
+- A2-01 Global limit → 429 with Retry-After
+- A2-02 Per-route & tenant override honored
+- A2-03 Window reset
+
+## A3. Idempotency & Concurrency
+- A3-01 Same Idempotency-Key → identical 2xx
+- A3-02 Conflicting payload + same key → 409
+- A3-03 Optimistic lock mismatch → 409; success increments version
+
+## A4. Jobs & Scheduling
+- A4-01 Custom job consumed
+- A4-02 Backoff & DLQ
+- A4-03 Cron tick observed
+
+## A5. Webhooks
+- A5-01 Producer → delivery (HMAC verified)
+- A5-02 Retry stops on success
+- A5-03 Secret rotation window accepts old+new
+
+## A6. Tenancy
+- A6-01 tenant_id injected on create; list scoped
+- A6-02 Cross-tenant → 404/403
+- A6-03 Per-tenant quotas enforced
+
+## A7. Data Lifecycle
+- A7-01 Soft delete hides; undelete restores
+- A7-02 GDPR erasure steps with audit
+- A7-03 Retention purge soft→hard
+- A7-04 Backup verification healthy
+
+## A8. SLOs & Ops
+- A8-01 Metrics http_server_* and db_pool_* present
+- A8-02 Maintenance mode 503; circuit breaker trips/recover
+- A8-03 Liveness/readiness under DB up/down
+
+## A9. OpenAPI & Error Contracts
+- A9-01 /openapi.json valid; examples present
+- A9-02 Problem+JSON conforms
+- A9-03 Spectral + API Doctor pass
+
+## A10. CLI & DX
+- A10-01 DB migrate/rollback/seed
+- A10-02 Jobs runner consumes a sample job
+- A10-03 SDK smoke-import and /ping

svc_infra/docs/acceptance.md

@@ -0,0 +1,44 @@
+# Pre-Deploy Acceptance (Promotion Gate)
+
+This guide describes the acceptance harness that runs post-build against an ephemeral stack. Artifacts are promoted only if acceptance checks pass.
+
+## Stack
+- docker-compose.test.yml: api (uvicorn serving tests.acceptance.app), optional db/redis (via profiles), and a tester container to run pytest inside
+- Makefile targets: accept, compose_up, wait, seed, down
+- Health probes: /healthz (liveness), /readyz (readiness), /startupz (startup)
+
+## Workflow
+1. Build image
+2. docker compose up -d (test stack)
+3. CLI DB checks & seed: run `sql setup-and-migrate`, `sql current`, `sql downgrade -1`, `sql upgrade head` against an ephemeral SQLite DB, then call `sql seed tests.acceptance._seed:acceptance_seed` (no-op by default)
+4. Run pytest inside tester: docker compose run --rm tester (Makefile wires this)
+5. OpenAPI lint & API Doctor
+6. Teardown
+
+## Supply-chain & Matrix (v1 scope)
+- SBOM: generate and upload as artifact; image scan (Trivy/Grype) with severity gate.
+- Provenance: sign/attest images (cosign/SLSA) on best-effort basis.
+- Backend matrix: run acceptance against two stacks via COMPOSE_PROFILES:
+	1) in-memory stores (default), 2) Redis + Postgres (COMPOSE_PROFILES=pg-redis).
+
+## Additional Acceptance Checks (fast wins)
+- Headers/CORS: assert HSTS, X-Content-Type-Options, Referrer-Policy, X-Frame-Options/SameSite; OPTIONS preflight behavior.
+- Resilience: restart DB/Redis during request; expect breaker trip and recovery.
+- DR drill: restore a tiny SQL dump then run smoke.
+- OpenAPI invariants: no orphan routes; servers block correctness for versions; 100% examples for public JSON; stable operationIds; reject /auth/{id} path via lint rule.
+- CLI contracts: `svc-infra --help` and key subcommands exit 0 and print expected flags.
+
+## Local usage
+- make accept (runs the full flow locally)
+- make down (tears down the stack)
+- To run tests manually: docker compose run --rm tester
+- To target a different backend: COMPOSE_PROFILES=pg-redis make accept
+
+## Files
+- tests/acceptance/conftest.py: BASE_URL, httpx client, fixtures
+- tests/acceptance/_auth.py: login/register helpers
+- tests/acceptance/_seed.py: seed users/tenants/api keys
+- tests/acceptance/_http.py: HTTP helpers
+
+## Scenarios
+See docs/acceptance-matrix.md for A-IDs and mapping to endpoints.

svc_infra/docs/adr/0002-background-jobs-and-scheduling.md

@@ -0,0 +1,40 @@
+# ADR 0002: Background Jobs & Scheduling
+
+Date: 2025-10-15
+
+Status: Accepted
+
+## Context
+We need production-grade background job processing and simple scheduling with a one-call setup. The library already includes in-memory queue/scheduler for tests/local. We need a production backend and a minimal runner.
+
+## Decision
+- JobQueue protocol defines enqueue/reserve/ack/fail with retry and exponential backoff (base seconds * attempts). Jobs have: id, name, payload, available_at, attempts, max_attempts, backoff_seconds, last_error.
+- Backends:
+  - InMemoryJobQueue for tests/local.
+  - RedisJobQueue for production using Redis primitives with visibility timeout and atomic operations.
+- Scheduler:
+  - InMemoryScheduler providing interval-based scheduling via next_run_at. Cron parsing is out of scope initially; a simple YAML loader can be added later.
+- Runner:
+  - A CLI loop `svc-infra jobs run` will tick the scheduler and process jobs in a loop with small sleep/backoff.
+- Configuration:
+  - One-call `easy_jobs()` returns (queue, scheduler). Picks backend via `JOBS_DRIVER` env (memory|redis). Redis URL via `REDIS_URL`.
+
+## Alternatives Considered
+- Using RQ/Huey/Celery: heavier dependency and less control over API ergonomic goals; we prefer thin primitives aligned with svc-infra patterns.
+- SQL-backed queue first: we will consider later; Redis is sufficient for v1.
+
+## Consequences
+- Enables outbox/webhook processors on a reliable queue.
+- Minimal cognitive load: consistent APIs, ENV-driven.
+- Future work: SQL queue, cron YAML loader, metrics, concurrency controls.
+
+## Redis Data Model (initial)
+- List `jobs:ready` holds ready job IDs; a ZSET `jobs:delayed` with score=available_at keeps delayed jobs; a HASH per job `job:{id}` stores fields.
+- Reserve uses RPOPLPUSH from `jobs:ready` to `jobs:processing` or BRPOPLPUSH with timeout; sets `visible_at` on job as now+vt and increments `attempts`.
+- Ack removes job from `jobs:processing` and deletes `job:{id}`.
+- Fail increments attempts and computes next available_at = now + backoff_seconds * attempts; moves job to delayed ZSET.
+- A housekeeping step periodically moves due jobs from delayed ZSET to ready list. Reserve also checks ZSET for due jobs opportunistically.
+
+## Testing Strategy
+- Unit tests cover enqueue/reserve/ack/fail, visibility timeout behavior, and DLQ after max_attempts.
+- Runner tests cover one iteration loop processing.

svc_infra/docs/adr/0003-webhooks-framework.md

@@ -0,0 +1,24 @@
+# ADR 0003: Webhooks Framework
+
+Date: 2025-10-15
+
+Status: Accepted
+
+## Context
+Services need a consistent way to publish domain events to external consumers via webhooks, verify inbound signatures, and handle retries with backoff. We already have an outbox pattern, a job queue, and a webhook delivery worker.
+
+## Decision
+- Event Schema: minimal fields {topic, payload, version, created_at}. Versioning included to evolve payloads.
+- Signing: HMAC-SHA256 over canonical JSON payload; header `X-Signature` carries hex digest. Future: include timestamp and v1 signature header variant.
+- Outbox → Job Queue: Producer writes events to Outbox; outbox tick enqueues delivery jobs; worker performs HTTP POST with signature.
+- Subscriptions: In-memory subscription store maps topic → {url, secret}. Persistence deferred.
+- Verification: Provide helper for verifying incoming webhook requests by recomputing the HMAC.
+- Retry: Already handled by JobQueue backoff; DLQ after max attempts.
+
+## Consequences
+- Clear boundary: producers don't call HTTP directly; they publish to Outbox.
+- Deterministic signing & verification across producer/consumer.
+- Extensibility: timestamped signed headers, secret rotation, persisted subscriptions are future extensions.
+
+## Testing
+- Unit tests for verification helper and end-to-end publish→outbox→queue→delivery using in-memory components and a fake HTTP client.

svc_infra/docs/adr/0004-tenancy-model.md

@@ -0,0 +1,42 @@
+# ADR-0004: Tenancy Model and Enforcement
+
+Date: 2025-10-15
+
+Status: Proposed
+
+## Context
+
+The framework needs a consistent, ergonomic multi-tenant story across modules (API scaffolding, SQL/Mongo persistence, auth/security, payments, jobs, webhooks). Existing patterns already reference `tenant_id` in many places (payments models and service, audit/session models, SQL/Mongo scaffolds). However, enforcement and app ergonomics were not unified.
+
+## Decision
+
+Adopt a default "soft-tenant" isolation model via a `tenant_id` column and centralized enforcement primitives:
+
+- Resolution: `resolve_tenant_id` and `require_tenant_id` FastAPI dependencies in `api.fastapi.tenancy.context`. Resolution order: override hook → identity (user/api_key) → `X-Tenant-Id` header → `request.state.tenant_id`.
+- Enforcement in SQL: `TenantSqlService(SqlService)` that scopes list/get/update/delete/search/count with a `where` clause and injects `tenant_id` on create when the model supports it. Repository methods accept optional `where` filters.
+- Router ergonomics: `make_tenant_crud_router_plus_sql` which requires `TenantId` and uses `TenantSqlService` under the hood. This keeps route code simple while enforcing scoping.
+- Extensibility: `set_tenant_resolver` hook to override resolution logic per app; `tenant_field` parameter to support custom column names. Future: schema-per-tenant or db-per-tenant via alternate repository/service implementations.
+
+## Alternatives considered
+
+1) Enforce tenancy at the ORM layer (SQLAlchemy events/session) – rejected for clarity and testability; we prefer explicit service/dep composition.
+2) Global middleware that rewrites queries – rejected due to SQLAlchemy complexity and opacity.
+3) Only rely on developers to remember filters – rejected due to footguns.
+
+## Consequences
+
+- Clear default behavior with escape hatches. Minimal changes for consumers using CRUD builders and SqlService.
+- Requires models to include an optional or required `tenant_id` column for scoping.
+- Non-SQL stores should add equivalent wrappers; Mongo scaffolds already include `tenant_id` fields and can mirror these patterns later.
+
+## Implementation Notes
+
+- New modules: `api.fastapi.tenancy.context`, `db.sql.tenant`. Repository updated to accept `where` filters.
+- CRUD router extended with `make_tenant_crud_router_plus_sql` to require `TenantId`.
+- Tests added: `tests/tenancy/*` for resolution and service scoping.
+
+## Open Items
+
+- Per-tenant quotas & rate limit overrides (tie into rate limit dependency/middleware via a resolver that returns per-tenant config).
+- Export tenant CLI (dump/import data for a specific tenant).
+- Docs: isolation guidance (column vs schema vs db), migration guidance.

svc_infra/docs/adr/0005-data-lifecycle.md

@@ -0,0 +1,86 @@
+# ADR 0005: Data Lifecycle — Soft Delete, Retention, Erasure, Backups
+
+Date: 2025-10-16
+Status: Accepted
+
+## Context
+We need a coherent Data Lifecycle story in svc-infra that covers:
+- Migrations & fixtures: simple way to run DB setup/migrations and load reference data.
+- Soft delete conventions: consistent filtering and model scaffolding support.
+- Retention policies: periodic purging of expired records per model/table.
+- GDPR/PII erasure: queued workflow to scrub user-related data while preserving legal audit.
+- Backups/PITR verification: a job that exercises restore checks or at least validates backup health signals.
+
+Existing building blocks:
+- Migrations CLI with end-to-end "setup-and-migrate" and new `sql seed` command for executing a user-specified seed callable.
+  - Code: `src/svc_infra/cli/cmds/db/sql/alembic_cmds.py` (cmd_setup_and_migrate, cmd_seed)
+- Soft delete support in repository and scaffold:
+  - Repo filtering: `src/svc_infra/db/sql/repository.py` (soft_delete flags, `deleted_at` timestamp, optional active flag)
+  - Model scaffolding: `src/svc_infra/db/sql/scaffold.py` (optional `deleted_at` field)
+- Easy-setup helper to coordinate lifecycle bits:
+  - `src/svc_infra/data/add.py` provides a startup hook to auto-migrate and optional callbacks for fixtures, retention jobs, and an erasure job.
+
+Gaps:
+- No standardized fixture loader contract beyond the callback surface.
+- No built-in retention policy registry or purge execution job.
+- No opinionated GDPR erasure workflow and audit trail.
+- No backup/PITR verification job implementation.
+
+## Decision
+Introduce minimal, composable primitives that keep svc-infra flexible while providing a clear path to production-grade lifecycle.
+
+1) Fixture Loader Contract
+- Provide a simple callable signature for deterministic, idempotent fixture loading: `Callable[[], None | Awaitable[None]]`.
+- Document best practices: UPSERT by natural keys, avoid random IDs, guard on existing rows.
+- Expose via `add_data_lifecycle(on_load_fixtures=...)` (already available); add docs and tests.
+
+2) Retention Policy Registry
+- Define a registry API that allows services to register per-resource retention rules.
+- Basic shape:
+  - `RetentionPolicy(name: str, model: type, where: list[Any] | None, older_than_days: int, soft_delete_field: str = "deleted_at")`
+  - A purge function computes a cutoff timestamp and issues DELETE or marks soft-delete fields.
+- Execution model: a periodic job (via jobs scheduler) calls `run_retention_purge(registry)`.
+- Keep SQL-only first; room for NoSQL extensions later.
+
+3) GDPR Erasure Workflow
+- Provide a single callable entrypoint `erase_principal(principal_id: str) -> None | Awaitable[None]`.
+- Default strategy: enqueue a job that runs a configurable erasure plan composed of steps (delete/soft-delete/overwrite) across tables.
+- Add an audit log entry per erasure request with outcome and timestamp (reuse `security.audit` helpers if feasible).
+- Keep the plan provider pluggable so apps specify which tables/columns participate.
+
+4) Backup/PITR Verification Job
+- Define an interface `verify_backups() -> HealthReport` with a minimal default implementation that:
+  - Queries the backup system or driver for last successful backup timestamp and retention window.
+  - Emits metrics/logs and returns a structured status.
+- Defer full "restore drill" capability; provide extension hook only.
+
+## Interfaces
+- Registry
+  - `register_retention(policy: RetentionPolicy) -> None`
+  - `run_retention_purge(session_factory, policies: list[RetentionPolicy]) -> PurgeReport`
+- Erasure
+  - `erase_principal(principal_id: str, plan: ErasurePlan, session_factory) -> ErasureReport`
+- Fixtures
+  - `load_fixtures()` as provided by caller via `add_data_lifecycle`.
+- Backup
+  - `verify_backups() -> BackupHealthReport`
+
+## Alternatives Considered
+- Heavy-weight DSL for retention and erasure: rejected for now; keep APIs Pythonic and pluggable.
+- Trigger-level soft delete enforcement: skipped to avoid provider lock-in; enforced at repository and query layer.
+- Full restore drill automation: out of scope for v1; introduce later behind provider integrations.
+
+## Consequences
+- Minimal surface that doesn't over-constrain adopters; provides default patterns and contracts.
+- Requires additional test scaffolds and example docs to demonstrate usage.
+- SQL-focused initial implementation; other backends can plug via similar interfaces.
+
+## Rollout & Testing
+- Add unit/integration tests for fixture loader, retention purge logic, and erasure workflow skeleton.
+- Provide docs in `docs/database.md` with examples and operational guidance.
+
+## References
+- `src/svc_infra/db/sql/repository.py` soft-delete handling
+- `src/svc_infra/db/sql/scaffold.py` deleted_at field scaffolding
+- `src/svc_infra/data/add.py` data lifecycle helper
+- `src/svc_infra/cli/cmds/db/sql/alembic_cmds.py` migrations & seed