svc-infra 0.1.615__tar.gz → 0.1.617__tar.gz

{svc_infra-0.1.615 → svc_infra-0.1.617}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.615
+Version: 0.1.617
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic

svc_infra-0.1.617/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-0.1.617/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-0.1.617/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-0.1.617/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-0.1.617/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-0.1.617/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

svc_infra-0.1.617/docs/adr/0006-ops-slos-and-metrics.md

@@ -0,0 +1,47 @@
+# ADR-0006: Ops SLOs, SLIs, and Metrics Naming
+
+Date: 2025-10-16
+
+## Status
+Accepted
+
+## Context
+We already expose Prometheus metrics via `svc_infra.obs.add.add_observability`, which mounts the `PrometheusMiddleware` and exports:
+- `http_server_requests_total{method,route,code}`
+- `http_server_request_duration_seconds_bucket{route,method}` + _sum/_count
+- `http_server_inflight_requests{route}`
+- `http_server_response_size_bytes_bucket` + _sum/_count (where available)
+- `http_server_exceptions_total{route,exception}` (where available)
+
+We also optionally expose SQLAlchemy pool metrics and instrument `requests`/`httpx`. Logging is configured via `svc_infra.app.logging.setup_logging`.
+
+## Decision
+1. Metric naming and labels
+   - Keep `http_server_*` naming aligned with Prometheus and OpenTelemetry conventions.
+   - Labels: `route` uses normalized FastAPI route pattern (e.g., `/users/{id}`); `method` is uppercase HTTP verb; `code` is the 3-digit status.
+   - Add DB pool metrics with `db_pool_*` prefix when bound (labels: `engine`/`pool_name`).
+2. SLIs
+   - Request Success Rate: 1 - error_ratio, where errors are 5xx by default; optionally include 429/499 as errors per service config.
+   - Request Latency: p50/p90/p99 on `http_server_request_duration_seconds` by `route` and overall.
+   - Availability (Probes): uptime of `/_ops/live` and `/_ops/ready` endpoints.
+3. SLOs
+   - Default SLOs per service class:
+     - Public API: 99.9% success, p99 < 500ms.
+     - Internal API/Jobs control plane: 99.5% success, p99 < 1000ms.
+   - Error Budget: monthly window; alert on burn rates of 2h (fast) and 24h (slow). Budgets computed from success SLI.
+4. Dashboards & Alerts
+   - Provide Grafana JSON dashboard templates referencing the above metrics and labels.
+   - Include alert rules for budget burn (fast/slow).
+
+## Consequences
+- Developers can rely on consistent metrics and labels for dashboards.
+- SLO targets are explicit and can be overridden per service.
+- Future work: Emit `http_server_exceptions_total` where missing; provide helper to register per-route classes (public/internal/admin) to pick default SLOs.
+
+## Alternatives Considered
+- OpenTelemetry SDK direct instrumentation was considered but deferred to keep dependency surface minimal; we keep the naming aligned for easy migration.
+
+## References
+- `src/svc_infra/obs/metrics/asgi.py`
+- `src/svc_infra/api/fastapi/ops/add.py`
+- Google SRE Workbook: SLOs and Error Budgets

svc_infra-0.1.617/docs/adr/0007-docs-and-sdks.md

@@ -0,0 +1,83 @@
+# ADR 0007: Docs & SDKs — Research and Design
+
+Status: Proposed
+
+Date: 2025-10-16
+
+## Context
+
+We want a production-ready documentation and SDK experience built on our existing FastAPI scaffolding.
+Current capabilities in the codebase:
+
+- Docs endpoints and export
+  - `add_docs(app, redoc_url, swagger_url, openapi_url, export_openapi_to)` mounts Swagger, ReDoc, and OpenAPI JSON; optional export on startup.
+  - `setup_service_api(...)` renders a landing page with per-version doc cards and local-only root docs.
+  - `add_prefixed_docs(...)` exposes scoped docs (e.g., for auth/payments) with per-scope OpenAPI, Swagger, ReDoc.
+- OpenAPI conventions and enrichment pipeline
+  - Mutators pipeline (`openapi/mutators.py`) with: conventions, normalized Problem schema, pagination params/components, header params, info mutator, and auth scheme installers.
+  - Conventions define `Problem` schema and normalize examples.
+- DX checks
+  - OpenAPI Problem+JSON lint in `dx/checks.py` and CLI to validate.
+- SDK stub
+  - `add_sdk_generation_stub(app, on_generate=...)` exposes a hook endpoint to trigger SDK generation (no hard deps).
+
+Gaps for a complete v1 experience:
+
+- Enriched OpenAPI with examples and tags is not yet standardized across routers.
+- No built-in SDK generator CLI; only a stub exists. No pinned toolchain or CI integration.
+- No Postman collection generator.
+- No dark-mode toggle/themes for Swagger/ReDoc (landing page supports light/dark).
+- No smoke tests for generated SDKs.
+
+## Decision
+
+We will standardize the Docs & SDKs approach around the following:
+
+1) OpenAPI enrichment
+- Use existing mutators pipeline and add small mutators to:
+  - Inject global tags and tag descriptions for major areas (auth, payments, webhooks, ops).
+  - Attach minimal `x-codeSamples` for common operations (curl/httpie).
+  - Ensure `Problem` schema and example responses are present across 4xx/5xx.
+  - Keep pagination and header parameter mutators enabled by default.
+
+2) Docs UI
+- Continue with Swagger UI and ReDoc via `add_docs` and `setup_service_api`.
+- Add an optional dark mode toggle for Swagger UI via custom CSS and a query param (design-only; implement later).
+- Keep local-only exposure of root docs; version-specific docs always exposed under their mount path.
+
+3) SDK generation pipeline (tools and layout)
+- TypeScript: `openapi-typescript` to generate types (no runtime client) to `clients/typescript/`.
+- Python: `openapi-python-client` to generate a client package to `clients/python/`.
+- Provide a new CLI group `svc-infra sdk` with subcommands:
+  - `svc-infra sdk ts --schema openapi.json --out clients/typescript --package @org/service`
+  - `svc-infra sdk py --schema openapi.json --out clients/python --package service_sdk`
+  - `svc-infra sdk postman --schema openapi.json --out clients/postman_collection.json` (via converter)
+- Pin generator versions in a minimal tool manifest (poetry extras and npm devDeps suggestions in docs) rather than hard deps in core library.
+- Add optional CI steps to generate SDKs on release tags; artifacts uploaded; publishing pipelines documented.
+
+4) Postman collection
+- Use the Postman converter (`openapi-to-postmanv2`) to produce `clients/postman_collection.json` from the exported OpenAPI.
+
+5) Testing & verification
+- Extend `dx` checks to include: schema export presence, generator dry-run, and minimal smoke tests:
+  - TS: typecheck the generated d.ts.
+  - Python: `pip install -e` and import a sample client in a quick script.
+- Keep these checks optional (opt-in via CI config) to avoid burdening minimal users.
+
+## Consequences
+
+- Pros: Clear, tool-agnostic pipeline; no heavy runtime dependencies; easy local and CI usage; versioned artifacts.
+- Cons: Adds extra tooling expectations (node and python generators) for teams that opt in.
+- Risk: Generator/tooling churn; mitigate by pinning versions and providing stubs/fallbacks.
+
+## Implementation Notes (planned)
+
+- Provide a small `svc_infra/cli/cmds/sdk` module with Typer commands that shell out to the generators if available, with helpful error messages if missing.
+- Document usage in `docs/docs-and-sdks.md` (to be added), including examples and troubleshooting.
+- Keep all new code behind DX/CLI; core library remains free of generator dependencies.
+
+## Out of Scope (v1)
+
+- Live “try it” consoles beyond Swagger UI.
+- Multi-language example snippets beyond curl/httpie.
+- Automatic publishing to npm/PyPI (documented manual workflows first).

svc_infra-0.1.617/docs/adr/0008-billing-primitives.md

@@ -0,0 +1,109 @@
+# ADR 0008: Billing Primitives (Usage, Quotas, Invoicing)
+
+## Status
+
+Proposed — Research and Design complete for v1 scope.
+
+## Context
+
+We need shared billing primitives to support both usage-based and subscription features across services. Goals:
+- Capture fine-grained usage events with idempotency and tenant isolation.
+- Aggregate usage into billable buckets (hour/day/month) with rollups.
+- Enforce entitlements/quotas at runtime (hard/soft limits).
+- Produce invoice data structures and events; enable later integration with external providers (Stripe, Paddle) without coupling core DX to any vendor.
+
+Non-goals for v1: taxes/VAT, complex proration rules, refunds/credits automation, dunning flows, provider-specific webhooks/end-to-end reconciliation.
+
+## Decisions
+
+1) Internal-first data model with optional provider adapters
+- Persist usage, aggregates, plans, subscriptions, invoices in our SQL layer.
+- Provide interfaces for provider adapters (Stripe later) to map internal invoices/lines and sync state when enabled.
+
+2) Usage ingestion API + idempotency
+- FastAPI router exposes POST /_billing/usage capturing events: {tenant_id, metric, amount, at, idempotency_key, metadata}.
+- Enforce request idempotency via existing middleware + usage-event unique index on (tenant_id, metric, idempotency_key).
+- Emit webhook event `billing.usage_recorded` (optional).
+
+3) Aggregation job (scheduler)
+- Background job reads new UsageEvent rows, aggregates into UsageAggregate by key (tenant, metric, period_start, period_granularity).
+- Granularities: hour, day, month (config). Maintains running totals; idempotent.
+- Emits `billing.usage_aggregated` webhook.
+
+4) Entitlements and quotas
+- Define Plan and PlanEntitlement models (feature flags, quotas per window).
+- Subscriptions bind tenant -> plan, effective_at/ended_at.
+- Runtime enforcement via dependency/decorator: `require_quota("metric", window="day", soft=True)` which raises/records when limit exceeded.
+
+5) Invoicing primitives
+- Invoice and InvoiceLine models created for each billing cycle (monthly default). Lines derived from aggregates and static prices.
+- Price model: unit amount, currency, metric reference (for metered), or fixed recurring.
+- Emit `billing.invoice_created` and `billing.invoice_finalized` webhooks; provider adapter can consume and sync out.
+
+6) Observability
+- Metrics: `billing_usage_ingest_total`, `billing_aggregate_duration_ms`, `billing_invoice_generated_total`.
+- Logs: aggregation windows processed, invoice cycles.
+
+7) Security & tenancy
+- All models include tenant_id; APIs require tenant context. RBAC: billing.read/billing.write for admin/operator roles.
+
+## Data Model (SQL)
+
+Tables (minimal v1):
+- usage_events(id, tenant_id, metric, amount, at_ts, idempotency_key, metadata_json, created_at)
+  - Unique (tenant_id, metric, idempotency_key)
+- usage_aggregates(id, tenant_id, metric, period_start, granularity, total, updated_at)
+  - Unique (tenant_id, metric, period_start, granularity)
+- plans(id, key, name, description, created_at)
+- plan_entitlements(id, plan_id, key, limit_per_window, window, created_at)
+- subscriptions(id, tenant_id, plan_id, effective_at, ended_at, created_at)
+- prices(id, key, currency, unit_amount, metric, recurring_interval, created_at)
+- invoices(id, tenant_id, period_start, period_end, status, total_amount, currency, created_at)
+- invoice_lines(id, invoice_id, price_id, metric, quantity, amount, created_at)
+
+All tables will be scaffolded with our SQL helpers and tenant mixin, with Alembic templates.
+
+## APIs
+
+- POST /_billing/usage: record usage events (body as above). Returns 202 with event id.
+- GET /_billing/usage: list usage by metric and window (aggregated).
+- GET /_billing/plans, GET /_billing/subscriptions, POST /_billing/subscriptions.
+- GET /_billing/invoices, GET /_billing/invoices/{id}.
+
+Routers mounted under a `/_billing` prefix and hidden behind auth + tenant guard. OpenAPI tags: Billing.
+
+## Jobs & Webhooks
+
+- Job: `aggregate_usage` runs on schedule; creates/updates UsageAggregate rows.
+- Job: `generate_invoices` runs monthly; emits invoice events and inserts Invoice/InvoiceLine rows.
+- Webhooks: `billing.usage_recorded`, `billing.usage_aggregated`, `billing.invoice_created`, `billing.invoice_finalized` (signed via existing module).
+
+## Implementation Plan (Phased)
+
+Phase 1 (MVP):
+- Models + migrations; CRUD for Plans/Subs/Prices; Usage ingestion + idempotency; Aggregator job (daily granularity); Basic invoice generator (monthly, fixed price + metered by day sum); Webhooks emitted; Tests for ingestion, aggregation, simple invoice.
+
+Phase 2:
+- Granularity options (hourly); soft/hard quota decorator; Read APIs; Observability metrics; Docs.
+
+Phase 3 (Provider adapter optional):
+- Stripe adapter skeleton: map internal invoices/lines -> Stripe, idempotent sync; basic webhook handler to update statuses.
+
+## Alternatives Considered
+
+- Provider-first approach (Stripe-only) rejected for v1 to keep core DX portable and support non-card use-cases.
+- Event-stream aggregation (Kafka) out-of-scope for framework baseline—can be integrated later.
+
+## Risks
+
+- Complexity creep around proration and taxes—explicitly out-of-scope for v1.
+- Performance on large tenants—mitigated by granular aggregation and indexes.
+
+## Testing
+
+- Unit tests for ingestion idempotency, aggregation correctness, invoice totals.
+- E2E-ish tests using in-memory queue + sqlite.
+
+## Documentation
+
+- `docs/billing.md`: usage API, quotas, invoice lifecycle, and Stripe adapter notes.

svc_infra-0.1.617/docs/adr/0009-acceptance-harness.md

@@ -0,0 +1,40 @@
+# ADR 0009: Acceptance Harness & Promotion Gate (A0)
+
+Date: 2025-10-17
+Status: Proposed
+Decision: Adopt a post-build acceptance harness that brings up an ephemeral stack (Docker Compose) and gates image promotion on acceptance results.
+
+## Context
+- We need a thin but strict pre-deploy acceptance layer that runs after building images, before promotion.
+- It should validate golden paths across domains and basic operational invariants.
+- It must be easy to run locally and in CI and support a backend matrix (in-memory vs Redis+Postgres).
+- Supply-chain checks (SBOM, image scan, provenance) should be part of the gate.
+
+## Decision
+- Introduce A0 Acceptance Harness:
+  - Compose stack (api + db + redis), Makefile helpers (accept/up/wait/seed/down).
+  - Seed CLI/script to create ADMIN/USER/TENANT fixtures and API key.
+  - Acceptance tests under `tests/acceptance` with `@pytest.mark.acceptance` and BASE_URL.
+  - CI job `build-and-accept` steps: build → compose up → seed → `pytest -m "acceptance or smoke"` → OpenAPI lint + API Doctor → teardown.
+  - Supply-chain: generate SBOM, image scan (Trivy/Grype) with severity threshold; upload SBOM.
+  - Provenance: sign/attest images via cosign/SLSA (best-effort for v1).
+  - Backend matrix: two jobs (in-memory vs Redis+Postgres).
+
+## Alternatives
+- Testcontainers-only approach (simpler per-test spin-up) — good DX but slower; we can adopt later for certain suites.
+- Kubernetes-in-Docker (kind) for near-prod parity — heavier; likely a v2 improvement.
+
+## Consequences
+- Slightly longer CI time due to matrix and scans.
+- Clearer promotion safety; early detection of config/env gaps.
+
+## Implementation Notes
+- Files to add:
+  - `docker-compose.test.yml`
+  - `Makefile` targets: `accept`, `compose_up`, `wait`, `seed`, `down`
+  - `tests/acceptance/` scaffolding: `conftest.py`, `_seed.py`, `_auth.py`, `_http.py`, first tests (headers/CORS)
+  - CI: `.github/workflows/ci.yml` job `build-and-accept`
+- Env contracts:
+  - `SQL_URL`, `REDIS_URL` for backend matrix; `APP_ENV=test-accept` for toggles.
+- Evidence:
+  - CI run URL, SBOM artifact link, scan report, acceptance summary.