svc-infra 0.1.506__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/db/sql/templates/setup/env_sync.py.tmpl

@@ -2,15 +2,13 @@ from __future__ import annotations
 
 import os
 import logging
-from typing import List
-import sys, pathlib, importlib.util
+from typing import List, Tuple
+import sys, pathlib, importlib, pkgutil, traceback
 
 from alembic import context
 from sqlalchemy.engine import make_url, URL
 
 from svc_infra.db.sql.utils import (
-    _coerce_sync_driver,
-    _ensure_ssl_default,
     get_database_url_from_env,
     build_engine,
 )
@@ -20,6 +18,7 @@ try:
 except Exception:
     _GUID = None
 
+
 def _render_item(type_, obj, autogen_context):
     if type_ == "type" and (
         (_GUID is not None and isinstance(obj, _GUID))
@@ -29,38 +28,49 @@ def _render_item(type_, obj, autogen_context):
         return "GUID()"
     return False
 
-# Logging
+
+# ---- Logging ----
 config = context.config
 if config.config_file_name is not None:
-    import logging.config
-    logging.config.fileConfig(config.config_file_name)
+    import logging.config as _lc
+    _lc.fileConfig(config.config_file_name)
+
 logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
 
-# --- sys.path bootstrap for src-layout projects ---
+# ---- sys.path bootstrap (append; do NOT shadow site-packages) ----
 prepend = config.get_main_option("prepend_sys_path") or ""
+script_loc = config.get_main_option("script_location") or os.path.dirname(__file__)
+migrations_dir = pathlib.Path(script_loc).resolve()
+project_root = migrations_dir.parent
+
+def _ensure_on_syspath_end(p: pathlib.Path) -> None:
+    s = str(p)
+    if s and s not in sys.path:
+        sys.path.append(s)  # append instead of insert(0) to avoid shadowing installed packages
+
 if prepend:
-    if prepend not in sys.path:
-        sys.path.insert(0, prepend)
+    _ensure_on_syspath_end(pathlib.Path(prepend))
     src_path = pathlib.Path(prepend) / "src"
     if src_path.exists():
-        s = str(src_path)
-        if s not in sys.path:
-            sys.path.insert(0, s)
+        _ensure_on_syspath_end(src_path)
+
+_ensure_on_syspath_end(project_root)
+if (project_root / "src").exists():
+    _ensure_on_syspath_end(project_root / "src")
+
 
-# --- robust x-arg parsing for all Alembic versions ---
+# ---- x-args ----
 def _x_args_dict() -> dict:
     try:
-        # Alembic >= 1.8 uses as_dictionary kw only
         return context.get_x_argument(as_dictionary=True)  # type: ignore[arg-type]
     except TypeError:
         try:
-            # Some versions just return a list even if you pass kw
             xs = context.get_x_argument()
         except TypeError:
-            # Very old signatures
             xs = []
-    # Parse ["k=v", "flag"] into dict
-    out = {}
+    out: dict = {}
     for item in xs:
         if "=" in item:
             k, v = item.split("=", 1)
@@ -69,7 +79,8 @@ def _x_args_dict() -> dict:
             out[item] = ""
     return out
 
-# --- Resolve effective DB URL (priority: -x -> env -> helper -> ini) ---
+
+# ---- DB URL resolution ----
 _x = _x_args_dict()
 cli_dburl = _x.get("dburl", "").strip()
 env_dburl = os.getenv("SQL_URL", "").strip()
@@ -90,103 +101,215 @@ if not effective_url:
 
 u = make_url(effective_url)
 u = _coerce_sync_driver(u)
-u = _ensure_ssl_default(u)
 config.set_main_option("sqlalchemy.url", u.render_as_string(hide_password=False))
 
-# --- metadata discovery (prefer ModelBase) ---
-DISCOVER_PACKAGES: List[str] = [__PACKAGES_LIST__]
+
+# ---- feature flags / constants ----
+WANT_PAYMENTS = os.getenv("APF_ENABLE_PAYMENTS", "").lower() in {"1", "true", "yes"}
+FORCE_PAYMENTS = os.getenv("ALEMBIC_FORCE_PAYMENTS", "").lower() in {"1", "true", "yes"}
+PAYMENT_TABLES = {"pay_customers", "pay_intents", "pay_events", "ledger_entries"}
+
+
+# ---- metadata discovery (prefer ModelBase; scan ALL attrs) ----
+# IMPORTANT: do NOT seed with payments package unless enabled/forced.
+DISCOVER_PACKAGES: List[str] = []  # seed empty; merged with FS + env
 ENV_DISCOVER = os.getenv("ALEMBIC_DISCOVER_PACKAGES")
 if ENV_DISCOVER:
-    DISCOVER_PACKAGES = [s.strip() for s in ENV_DISCOVER.split(',') if s.strip()]
+    DISCOVER_PACKAGES = [s.strip() for s in ENV_DISCOVER.split(",") if s.strip()]
 
 def _collect_metadata() -> list[object]:
-    try:
-        from svc_infra.db.sql.base import ModelBase  # type: ignore
-        md = getattr(ModelBase, "metadata", None)
-        if md is not None and hasattr(md, "tables") and md.tables:
-            return [md]
-    except Exception as e:
-        logger.debug("ModelBase not available or empty: %s", e)
-
-    import importlib, pkgutil, pathlib
+    """
+    Strategy:
+      1) (If WANT_PAYMENTS or FORCE_PAYMENTS) force-import payments module and log result.
+      2) Import packages + ALEMBIC_DISCOVER_PACKAGES (+ payments only when enabled).
+      3) ALSO import top-level packages under project root and src/.
+      4) Import common model-bearing submodules.
+      5) Prefer ModelBase.metadata after imports.
+      6) Collect ANY object whose `.metadata` has tables (scan ALL attrs).
+      7) De-dup and keep only those with at least one table.
+    """
+    tried: list[Tuple[str, str]] = []
+    errors: list[Tuple[str, str]] = []
     found: list[object] = []
 
+    def _note(name: str, ok: bool, err: str | None = None):
+        tried.append((name, "ok" if ok else "err"))
+        if not ok and err:
+            errors.append((name, err))
+
     def _maybe_add(obj: object) -> None:
         md = getattr(obj, "metadata", None) or obj
-        if hasattr(md, "tables") and hasattr(md, "schema"):
+        if hasattr(md, "tables") and getattr(md, "tables"):
             found.append(md)
 
-    pkgs = list(DISCOVER_PACKAGES) or []
-    if not pkgs:
-        roots = []
-        if prepend:
-            roots.append(pathlib.Path(prepend))
-            roots.append(pathlib.Path(prepend) / "src")
-        for root in roots:
-            if not root or not root.exists():
-                continue
-            for p in root.iterdir():
-                if p.is_dir() and (p / "__init__.py").exists():
-                    pkgs.append(p.name)
+    def _scan_module_objects(mod: object) -> None:
+        try:
+            for val in vars(mod).values():
+                md = getattr(val, "metadata", None) or None
+                if md is not None and hasattr(md, "tables") and getattr(md, "tables"):
+                    found.append(md)
+        except Exception:
+            pass
 
-    for pkg_name in pkgs:
+    # (1) Force-load payments when enabled/forced and log explicit outcome
+    if WANT_PAYMENTS or FORCE_PAYMENTS:
         try:
-            pkg = importlib.import_module(pkg_name)
-        except Exception as e:
-            logger.debug("Failed to import %s: %s", pkg_name, e)
-            continue
+            importlib.import_module("svc_infra.apf_payments.models")
+            context.config.print_stdout("[alembic env] payments module import: ok (svc_infra.apf_payments.models)")
+        except Exception:
+            context.config.print_stdout("[alembic env] payments module import: ERR (svc_infra.apf_payments.models)")
+            context.config.print_stdout(traceback.format_exc())
+
+    # (2) seed list
+    pkgs: list[str] = []
+    # add payments package ONLY when enabled/forced
+    if WANT_PAYMENTS or FORCE_PAYMENTS:
+        pkgs.append("svc_infra.apf_payments.models")
+
+    for p in list(DISCOVER_PACKAGES or []):
+        if p and p not in pkgs:
+            pkgs.append(p)
+
+    env_pkgs = os.getenv("ALEMBIC_DISCOVER_PACKAGES", "")
+    if env_pkgs:
+        for p in (x.strip() for x in env_pkgs.split(",") if x.strip()):
+            if p not in pkgs:
+                pkgs.append(p)
+
+    # (3) filesystem discovery (root + src) – appended, not shadowing site-packages
+    fs_roots: list[pathlib.Path] = []
+    for candidate in {project_root, project_root / "src"}:
+        if candidate.exists():
+            fs_roots.append(candidate)
+    for root in fs_roots:
+        for p in root.iterdir():
+            if p.is_dir() and (p / "__init__.py").exists():
+                name = p.name
+                if name not in pkgs:
+                    pkgs.append(name)
 
+    # Only attempt a bare 'models' import if discoverable to avoid noisy tracebacks
+    if "models" not in pkgs:
+        try:
+            spec = getattr(importlib, "util", None)
+            if spec is not None and getattr(spec, "find_spec", None) is not None:
+                if spec.find_spec("models") is not None:
+                    pkgs.append("models")
+        except Exception:
+            # If discovery fails, skip adding bare 'models'
+            pass
+
+    def _import_and_collect(modname: str):
+        try:
+            mod = importlib.import_module(modname)
+            _note(modname, True, None)
+        except Exception:
+            _note(modname, False, traceback.format_exc())
+            return None
         for attr in ("metadata", "MetaData", "Base", "base"):
-            obj = getattr(pkg, attr, None)
+            obj = getattr(mod, attr, None)
             if obj is not None:
                 _maybe_add(obj)
+        _scan_module_objects(mod)
+        return mod
+
+    for pkg_name in pkgs:
+        pkg = _import_and_collect(pkg_name)
+        if pkg is None:
+            continue
 
-        for subname in ("models",):
-            try:
-                sub = importlib.import_module(f"{pkg_name}.{subname}")
-                for attr in ("metadata", "MetaData", "Base", "base"):
-                    obj = getattr(sub, attr, None)
-                    if obj is not None:
-                        _maybe_add(obj)
-            except Exception:
-                pass
+        for subname in ("models", "db", "orm", "entities"):
+            _import_and_collect(f"{pkg_name}.{subname}")
 
         mod_path = getattr(pkg, "__path__", None)
         if not mod_path:
             continue
         for _, name, ispkg in pkgutil.walk_packages(mod_path, prefix=pkg_name + "."):
-            if ispkg or not any(x in name for x in (".models", ".db", ".orm", ".entities")):
+            if ispkg:
                 continue
-            try:
-                mod = importlib.import_module(name)
-            except Exception:
+            if not any(x in name for x in (".models", ".db", ".orm", ".entities")):
                 continue
-            for attr in ("metadata", "MetaData", "Base", "base"):
-                obj = getattr(mod, attr, None)
-                if obj is not None:
-                    _maybe_add(obj)
+            _import_and_collect(name)
 
-    # --- AUTOBIND API KEY MODEL (if a marked User model exists) ---
+    # Prefer ModelBase after all imports
+    try:
+        from svc_infra.db.sql.base import ModelBase  # type: ignore
+        mb_md = getattr(ModelBase, "metadata", None)
+        if mb_md is not None and getattr(mb_md, "tables", {}):
+            found.append(mb_md)
+            _note("ModelBase.metadata", True, None)
+        else:
+            _note("ModelBase.metadata(empty)", True, None)
+    except Exception:
+        _note("ModelBase import", False, traceback.format_exc())
+
+    # Optional: autobind API key model
     try:
         from svc_infra.db.sql.apikey import try_autobind_apikey_model
-        # If you prefer gating on env, pass require_env=True and set AUTH_ENABLE_API_KEYS=1
         try_autobind_apikey_model(require_env=False)
-    except Exception as e:
-        logger.debug("svc-infra apikey autobind skipped: %s", e)
+        _note("svc_infra.db.sql.apikey.try_autobind_apikey_model", True, None)
+    except Exception:
+        _note("svc_infra.db.sql.apikey.try_autobind_apikey_model", False, traceback.format_exc())
 
-    uniq, seen = [], set()
+    # De-dup MetaData objects
+    uniq: list[object] = []
+    seen: set[int] = set()
     for md in found:
+        try:
+            if not getattr(md, "tables", {}):
+                continue
+        except Exception:
+            continue
         if id(md) not in seen:
             seen.add(id(md))
             uniq.append(md)
+
+    total_tables = 0
+    try:
+        total_tables = sum(len(getattr(md, "tables", {})) for md in uniq)
+    except Exception:
+        pass
+
+    context.config.print_stdout(
+        f"[alembic env] discovered {len(uniq)} metadata objects with {total_tables} tables total"
+    )
+
+    if WANT_PAYMENTS and not FORCE_PAYMENTS:
+        saw_pay = any(any(tn in PAYMENT_TABLES for tn in md.tables.keys()) for md in uniq) if uniq else False
+        if not saw_pay:
+            context.config.print_stdout(
+                "[alembic env] WARNING: APF_ENABLE_PAYMENTS is set but no payments tables were discovered. "
+                "If you still see this, a local package named 'svc_infra' may be shadowing the installed one."
+            )
+
+    # If nothing, dump import attempts / first 10 tracebacks
+    if total_tables == 0:
+        context.config.print_stdout("[alembic env] import attempts (ok/err):")
+        for name, status in tried:
+            context.config.print_stdout(f"  - {status:3s}  {name}")
+        for name, tb in errors[:10]:
+            context.config.print_stdout(f"  --- import error: {name} ---")
+            context.config.print_stdout(tb)
+
     return uniq
 
+
 target_metadata = _collect_metadata()
 
+
 def _want_include_schemas() -> bool:
-    # allow override: alembic -x include_schemas=1
     val = _x.get("include_schemas", "") or os.getenv("ALEMBIC_INCLUDE_SCHEMAS", "")
-    return str(val).strip() in {"1", "true", "True", "yes"}
+    if str(val).strip() in {"1", "true", "True", "yes"}:
+        return True
+    try:
+        for md in (target_metadata or []):
+            for t in getattr(md, "tables", {}).values():
+                if getattr(t, "schema", None):
+                    return True
+    except Exception:
+        pass
+    return False
+
 
 def _system_schemas_for(url: str) -> set[str]:
     try:
@@ -203,21 +326,48 @@ def _system_schemas_for(url: str) -> set[str]:
         return {"INFORMATION_SCHEMA"}
     return set()
 
+
 def _include_object_factory(url: str):
     sys_schemas = _system_schemas_for(url)
+    skip_drops = os.getenv("ALEMBIC_SKIP_DROPS", "").lower() in {"1", "true", "yes"}
+    want_payments = WANT_PAYMENTS or FORCE_PAYMENTS
 
     def _include_object(obj, name, type_, reflected, compare_to):
-        # Skip system schemas
+        # filter system schemas
         schema = getattr(obj, "schema", None)
         if schema and str(schema) in sys_schemas:
             return False
-        # Always keep our version table
-        if type_ == "table" and name == (context.get_x_argument(as_dictionary=True).get("version_table") or "alembic_version"):
+
+        # Always keep Alembic version table
+        version_table = (
+            context.get_x_argument(as_dictionary=True).get("version_table")
+            if hasattr(context, "get_x_argument")
+            else None
+        ) or os.getenv("ALEMBIC_VERSION_TABLE", "alembic_version")
+        if type_ == "table" and name == version_table:
             return True
+
+        # Guard: don't drop tables that exist in DB but aren't in metadata
+        if skip_drops and type_ == "table" and reflected and compare_to is None:
+            return False
+
+        # Payments gating: when disabled, exclude payments tables and their indexes
+        if not want_payments:
+            if type_ == "table" and name in PAYMENT_TABLES:
+                return False
+            if type_ == "index":
+                try:
+                    parent = getattr(obj, "table", None)
+                    if parent is not None and getattr(parent, "name", None) in PAYMENT_TABLES:
+                        return False
+                except Exception:
+                    pass
+
         return True
 
     return _include_object
 
+
 def run_migrations_offline() -> None:
     url = config.get_main_option("sqlalchemy.url")
     context.configure(
@@ -236,6 +386,7 @@ def run_migrations_offline() -> None:
     with context.begin_transaction():
         context.run_migrations()
 
+
 def run_migrations_online() -> None:
     url = config.get_main_option("sqlalchemy.url")
     engine = build_engine(url, echo=False)
@@ -255,6 +406,7 @@ def run_migrations_online() -> None:
             context.run_migrations()
     engine.dispose()
 
+
 if context.is_offline_mode():
     run_migrations_offline()
 else:

svc_infra/db/sql/tenant.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .service import SqlService
+
+
+class TenantSqlService(SqlService):
+    """
+    SQL service wrapper that automatically scopes operations to a tenant.
+
+    - Adds a where filter (model.tenant_field == tenant_id) for list/get/update/delete/search/count.
+    - On create, if the model has the tenant field and it's not set in data, injects tenant_id.
+    """
+
+    def __init__(self, repo, *, tenant_id: str, tenant_field: str = "tenant_id"):
+        super().__init__(repo)
+        self.tenant_id = tenant_id
+        self.tenant_field = tenant_field
+
+    def _where(self) -> Sequence[Any]:
+        model = self.repo.model
+        col = getattr(model, self.tenant_field, None)
+        if col is None:
+            return []
+        return [col == self.tenant_id]
+
+    async def list(self, session: AsyncSession, *, limit: int, offset: int, order_by=None):
+        return await self.repo.list(
+            session, limit=limit, offset=offset, order_by=order_by, where=self._where()
+        )
+
+    async def count(self, session: AsyncSession) -> int:
+        return await self.repo.count(session, where=self._where())
+
+    async def get(self, session: AsyncSession, id_value: Any):
+        return await self.repo.get(session, id_value, where=self._where())
+
+    async def create(self, session: AsyncSession, data: dict[str, Any]):
+        data = await self.pre_create(data)
+        # inject tenant_id if model supports it and value missing
+        if self.tenant_field in self.repo._model_columns() and self.tenant_field not in data:
+            data[self.tenant_field] = self.tenant_id
+        return await self.repo.create(session, data)
+
+    async def update(self, session: AsyncSession, id_value: Any, data: dict[str, Any]):
+        data = await self.pre_update(data)
+        return await self.repo.update(session, id_value, data, where=self._where())
+
+    async def delete(self, session: AsyncSession, id_value: Any) -> bool:
+        return await self.repo.delete(session, id_value, where=self._where())
+
+    async def search(
+        self,
+        session: AsyncSession,
+        *,
+        q: str,
+        fields: Sequence[str],
+        limit: int,
+        offset: int,
+        order_by=None,
+    ):
+        return await self.repo.search(
+            session,
+            q=q,
+            fields=fields,
+            limit=limit,
+            offset=offset,
+            order_by=order_by,
+            where=self._where(),
+        )
+
+    async def count_filtered(self, session: AsyncSession, *, q: str, fields: Sequence[str]) -> int:
+        return await self.repo.count_filtered(session, q=q, fields=fields, where=self._where())
+
+
+__all__ = ["TenantSqlService"]

svc_infra/db/sql/utils.py

@@ -196,10 +196,17 @@ def _ensure_timeout_default(u: URL) -> URL:
     """
     Ensure a conservative connection timeout is present for libpq-based drivers.
     For psycopg/psycopg2, 'connect_timeout' is honored via the query string.
+    For asyncpg, timeout is set via connect_args (not query string).
     """
     backend = (u.get_backend_name() or "").lower()
     if backend not in ("postgresql", "postgres"):
         return u
+
+    # asyncpg doesn't support connect_timeout in query string - use connect_args instead
+    dn = (u.drivername or "").lower()
+    if "+asyncpg" in dn:
+        return u
+
     if "connect_timeout" in u.query:
         return u
     # Default 10s unless overridden
@@ -337,9 +344,8 @@ def _ensure_ssl_default(u: URL) -> URL:
     mode = (mode_env or "").strip()
 
     if "+asyncpg" in driver:
-        # asyncpg: use 'ssl=true' (SQLAlchemy forwards to asyncpg)
-        if "ssl" not in u.query:
-            return u.set(query={**u.query, "ssl": "true"})
+        # asyncpg: SSL is handled in connect_args in build_engine(), not in URL query
+        # Do not add ssl parameter to URL query for asyncpg
         return u
     else:
         # libpq-based drivers: use sslmode (default 'require' for hosted PG)
@@ -382,10 +388,18 @@ def build_engine(url: URL | str, echo: bool = False) -> Union[SyncEngine, AsyncE
                 "Async driver URL provided but SQLAlchemy async extras are not available."
             )
 
-        # asyncpg: honor connection timeout
+        # asyncpg: honor connection timeout only (NOT connect_timeout)
         if "+asyncpg" in (u.drivername or ""):
             connect_args["timeout"] = int(os.getenv("DB_CONNECT_TIMEOUT", "10"))
 
+            # asyncpg doesn't accept sslmode or ssl=true in query params
+            # Remove these and set ssl='require' in connect_args
+            if "ssl" in u.query or "sslmode" in u.query:
+                new_query = {k: v for k, v in u.query.items() if k not in ("ssl", "sslmode")}
+                u = u.set(query=new_query)
+            # Set ssl in connect_args - 'require' is safest for hosted databases
+            connect_args["ssl"] = "require"
+
         # NEW: aiomysql SSL default
         if "+aiomysql" in (u.drivername or "") and not any(
             k in u.query for k in ("ssl", "ssl_ca", "sslmode")

svc_infra/db/sql/versioning.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from sqlalchemy import Integer
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class Versioned:
+    """Mixin for optimistic locking with integer version.
+
+    - Initialize version=1 on insert (via default=1)
+    - Bump version in app code before commit to detect mismatches.
+    """
+
+    version: Mapped[int] = mapped_column(Integer, nullable=False, default=1)

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