feat(tenancy): logical multi-tenancy — per-tenant config resolution (Step 6.1)

[officialCodeWork]

Summary

Step 6.1 — Logical multi-tenancy: make per-tenant rag.yaml config actually drive each request, and start Phase 6 (Governance & Tenancy). Built as a single PR.

Before this, TenantConfig was a passive registry — the gateway used one global config for every tenant, and only quotas (Step 4.5) were per-tenant. Now:

• TenantResolver (rag_config.tenancy) maps a tenant id → frozen TenantSettings (rag_core.types: tenant_id / namespace / pii_policy / acl_labels), merging the tenants: entry with safe defaults.
• Applied once at the gateway boundary (build_gateway_context): the resolved namespace + pii_policy land on the RequestContext, and the tenant's acl_labels are unioned into the principal's. The resolved view is also exposed on request.state.gateway.tenant_settings.
• Unknown tenants resolve to safe defaults (namespace = the id, default PII redact, no labels) — isolated, never privileged.
• New RequestContext.namespace defaults to tenant_id via a before-validator, so every pre-6.1 call site is unchanged. It's a backend-partition primitive — Pinecone now partitions on ctx.namespace — not a chunk field, so PolicyEngine.filter_pushdown is unchanged (chunks carry tenant_id).
• TenantConfig gains namespace + acl_labels; GET /v1/status/tenant surfaces the resolved view; ragctl tenant list / resolve <id> print it (the scaffold is promoted to a real command).
• Inert by default in build_app; build_app_from_config builds the resolver from cfg.tenants.

TenantSettings joins dist/schemas, RequestContext regenerated, TenantConfig fields → rag.schema, /v1/status/tenant → dist/openapi.

Scope & boundaries

This is the logical-tenancy foundation — resolution + threading of the per-tenant isolation/governance primitives. The enforcement that builds on them lands later in Phase 6: ACL push-down at retrieval is 6.3, PII egress enforcement is 6.5, physical tenancy (dedicated index) is 6.2.

Documentation

• ADR-0033 — the decision + boundaries
• docs/reference/tenancy.md — config table, resolver, endpoint, CLI
• docs/architecture/multi-tenancy.md — design + the 6.2/6.3/6.5 boundary
• docs/architecture/request-context.md — namespace field + resolver note
• docs/README.md — registered the new docs
• TRACKER.md — 6.1 ✅, Phase 6 1/10, overall 65/84, next action → 6.2, PR history

Test plan

• ruff check + ruff format --check clean
• mypy --strict clean (293 source files)
• RAG001 logging gate clean
• schema-drift + openapi-drift regenerated (committed); proto-compat + policy-coverage pass
• full suite 1152 passed (one transient config hot-reload-watcher flake, unrelated; reran clean)
• ~21 new tests: TenantResolver unit (tests/config/test_tenancy.py), gateway boundary + /v1/status/tenant (apps/gateway/tests/test_tenancy.py), cross-tenant red-team namespace/ACL/PII isolation (tests/redteam/test_cross_tenant_namespace.py), ragctl tenant (packages/ragctl/tests/test_tenant.py)
• ragctl tenant resolve acme -f rag.yaml ran end-to-end (known + unknown tenants)

🤖 Generated with Claude Code