svc-infra 0.1.621__py3-none-any.whl → 0.1.623__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
 
@@ -11,14 +10,10 @@ import click
 import typer
 from typer.core import TyperGroup
 
+from svc_infra.app.root import resolve_project_root
 
-def _norm(name: str) -> str:
-    """Normalize a topic name for stable CLI commands.
 
-    - Lowercase
-    - Replace spaces and underscores with hyphens
-    - Strip leading/trailing whitespace
-    """
+def _norm(name: str) -> str:
     return name.strip().lower().replace(" ", "-").replace("_", "-")
 
 
@@ -32,190 +27,95 @@ def _discover_fs_topics(docs_dir: Path) -> Dict[str, Path]:
 
 
 def _discover_pkg_topics() -> Dict[str, Path]:
-    """Discover docs packaged under 'docs/' in the installed distribution.
-
-    Works in external projects without a local docs/ by inspecting the wheel
-    metadata and, as a fallback, searching for a top-level docs/ next to the
-    installed package directory in site-packages.
+    """
+    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] = {}
-
-    # 1) Prefer distribution metadata (RECORD) for both hyphen/underscore names
-    dist = None
-    for name in ("svc-infra", "svc_infra"):
-        try:
-            dist = distribution(name)
-            break
-        except PackageNotFoundError:
-            dist = None
-
-    if dist is not None:
-        files = getattr(dist, "files", None) or []
-        for f in files:
-            s = str(f)
-            if not s.startswith("docs/") or not s.endswith(".md"):
-                continue
-            topic_name = _norm(Path(s).stem)
-            try:
-                abs_path = Path(dist.locate_file(f))
-                if abs_path.exists() and abs_path.is_file():
-                    topics[topic_name] = abs_path
-            except Exception:
-                # Best effort; continue to next
-                continue
-
-    # 2) Fallback: site-packages sibling 'docs/' directory (and repo-root docs in editable installs)
     try:
-        spec = importlib.util.find_spec("svc_infra")
-        if spec and spec.submodule_search_locations:
-            pkg_dir = Path(next(iter(spec.submodule_search_locations)))
-            candidates = [
-                pkg_dir.parent / "docs",  # site-packages/docs OR src/docs
-                pkg_dir / "docs",  # site-packages/svc_infra/docs OR src/svc_infra/docs
-                pkg_dir.parent.parent
-                / "docs",  # repo-root/docs when running editable from repo (src/svc_infra → ../../docs)
-            ]
-            for candidate in candidates:
-                if candidate.exists() and candidate.is_dir():
-                    for p in sorted(candidate.glob("*.md")):
-                        if p.is_file():
-                            topics.setdefault(_norm(p.stem), p)
-                    # If one candidate had docs, that's sufficient
-                    if any(k for k in topics):
-                        break
-    except Exception:
-        # Optional fallback only
-        pass
-
-    # 3) Last-resort: scan sys.path entries that look like site-/dist-packages for a top-level docs/
-    #    directory containing markdown files. This covers non-standard installs/editable modes.
-    try:
-        if not topics:
-            for entry in sys.path:
-                try:
-                    if not entry or ("site-packages" not in entry and "dist-packages" not in entry):
-                        continue
-                    docs_dir = Path(entry) / "docs"
-                    if docs_dir.exists() and docs_dir.is_dir():
-                        found = _discover_fs_topics(docs_dir)
-                        if found:
-                            # Merge but do not override anything already found
-                            for k, v in found.items():
-                                topics.setdefault(k, v)
-                            # If we found one valid docs dir, it's enough
-                            break
-                except Exception:
-                    continue
+        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
 
-    # 4) Parse dist-info/RECORD or egg-info/SOURCES.txt to enumerate docs if available
-    try:
-        if not topics:
-            spec = importlib.util.find_spec("svc_infra")
-            base_dir: Path | None = None
-            if spec and spec.submodule_search_locations:
-                base_dir = Path(next(iter(spec.submodule_search_locations))).parent
-            # Fallback to first site-packages on sys.path
-            if base_dir is None:
-                for entry in sys.path:
-                    if entry and "site-packages" in entry:
-                        base_dir = Path(entry)
-                        break
-            if base_dir and base_dir.exists():
-                # Check for both hyphen and underscore dist-info names
-                candidates = list(base_dir.glob("svc_infra-*.dist-info")) + list(
-                    base_dir.glob("svc-infra-*.dist-info")
-                )
-                for di in candidates:
-                    record = di / "RECORD"
-                    if record.exists():
-                        try:
-                            for line in record.read_text(
-                                encoding="utf-8", errors="ignore"
-                            ).splitlines():
-                                rel = line.split(",", 1)[0]
-                                if rel.startswith("docs/") and rel.endswith(".md"):
-                                    abs_p = base_dir / rel
-                                    if abs_p.exists() and abs_p.is_file():
-                                        topics.setdefault(_norm(Path(rel).stem), abs_p)
-                        except Exception:
-                            continue
-                # egg-info fallback
-                if not topics:
-                    egg_candidates = list(base_dir.glob("svc_infra-*.egg-info")) + list(
-                        base_dir.glob("svc-infra-*.egg-info")
-                    )
-                    for ei in egg_candidates:
-                        sources = ei / "SOURCES.txt"
-                        if sources.exists():
-                            try:
-                                for rel in sources.read_text(
-                                    encoding="utf-8", errors="ignore"
-                                ).splitlines():
-                                    rel = rel.strip()
-                                    if rel.startswith("docs/") and rel.endswith(".md"):
-                                        abs_p = base_dir / rel
-                                        if abs_p.exists() and abs_p.is_file():
-                                            topics.setdefault(_norm(Path(rel).stem), abs_p)
-                            except Exception:
-                                continue
-    except Exception:
-        pass
 
-    # 5) Deep fallback: recursively search site-packages/dist-packages for any 'docs' folder
-    #    containing markdown files (limited depth to keep overhead reasonable).
+def _resolve_docs_dir(ctx: click.Context) -> Path | None:
+    """
+    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
+    """
+    # 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:
+            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():
+            return p
+
+    # 3) In-repo convenience (so `svc-infra docs` works inside this repo)
     try:
-        if not topics:
-            for entry in sys.path:
-                if not entry or ("site-packages" not in entry and "dist-packages" not in entry):
-                    continue
-                base = Path(entry)
-                if not base.exists() or not base.is_dir():
-                    continue
-                base_parts = len(base.parts)
-                for root, dirs, files in os.walk(base):
-                    root_path = Path(root)
-                    # Limit search depth to avoid expensive scans
-                    if len(root_path.parts) - base_parts > 4:
-                        # prune
-                        dirs[:] = []
-                        continue
-                    if root_path.name == "docs":
-                        for p in sorted(root_path.glob("*.md")):
-                            if p.is_file():
-                                topics.setdefault(_norm(p.stem), p)
-                        # do not break; there might be multiple doc dirs
+        root = resolve_project_root()
+        proj_docs = root / "docs"
+        if proj_docs.exists():
+            return proj_docs
     except Exception:
         pass
 
-    return topics
-
-
-def _resolve_docs_dir(ctx: click.Context) -> Path | None:
-    # Deprecated: we no longer read docs from arbitrary paths or env.
-    # All docs are sourced from the packaged svc-infra distribution only.
     return None
 
 
 class DocsGroup(TyperGroup):
     def list_commands(self, ctx: click.Context) -> List[str]:
         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([k for k in pkg.keys()])
-        # Deduplicate and sort
-        return sorted({*names})
+        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:
-        # Built-ins first (e.g., list, show)
         cmd = super().get_command(ctx, name)
         if cmd is not None:
             return cmd
 
-        # Packaged topics only
+        key = _norm(name)
+
+        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_fs() -> None:
+                click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
+
+            return _show_fs
+
         pkg = _discover_pkg_topics()
-        if name in pkg:
-            file_path = pkg[name]
+        if key in pkg:
+            file_path = pkg[key]
 
             @click.command(name=name)
             def _show_pkg() -> None:
@@ -227,39 +127,62 @@ class DocsGroup(TyperGroup):
 
 
 def register(app: typer.Typer) -> None:
-    """Register the `docs` command group with dynamic topic subcommands."""
-
     docs_app = typer.Typer(no_args_is_help=True, add_completion=False, cls=DocsGroup)
 
     @docs_app.callback(invoke_without_command=True)
     def _docs_options(
+        docs_dir: Path | None = typer.Option(
+            None,
+            "--docs-dir",
+            help="Path to a docs directory to read from (overrides packaged docs)",
+        ),
         topic: str | None = typer.Option(None, "--topic", help="Topic to show directly"),
     ) -> None:
-        """Support --topic at group level (packaged docs only)."""
         if topic:
+            key = _norm(topic)
+            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 topic in pkg:
-                typer.echo(pkg[topic].read_text(encoding="utf-8", errors="replace"))
+            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()
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
         pkg = _discover_pkg_topics()
 
-        # Print packaged topics only
         def _print(name: str, path: Path) -> None:
-            typer.echo(f"{name}\t{path}")
+            try:
+                typer.echo(f"{name}\t{path}")
+            except Exception:
+                typer.echo(name)
 
-        for name, path in pkg.items():
+        for name, path in fs.items():
             _print(name, path)
+        for name, path in pkg.items():
+            if name not in fs:
+                _print(name, path)
 
-    # Also support a generic "show" command
     @docs_app.command("show", help="Show docs for a topic (alternative to dynamic subcommand)")
     def show(topic: str) -> None:
+        key = _norm(topic)
+        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 topic in pkg:
-            typer.echo(pkg[topic].read_text(encoding="utf-8", errors="replace"))
+        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