doc: add per-tenant namespace isolation and teardown design

[somfornot]

This is a design proposal (docs only) — the accepted spec for upcoming per-tenant data-isolation work on the SDK-native direct data plane. Companion to the tenant rate-limit and traffic-observability designs.

Model (the three decisions this design is built on)

1. Boundary = the SDK-declared TenantID, as a trusted partition — not bucket/prefix, not a gateway principal. The direct plane is unauthenticated, so the tenant is trusted for partitioning and lifecycle, not proven identity.
2. Private per-tenant namespace — the same logical path denotes different data for different tenants, so tenant participates in origin addressing.
3. Per-tenant origin — each tenant has its own bucket and credentials, resolved from a coordinator-distributed registry.

Highlights

• Per-tenant cache shard + cache_root/<tenant>/ subtree, under one global eviction budget (shard the eviction policy, not the budget — per the v1 Design / DESIGN.md describes a monoio/io_uring Layer-1 runtime that does not exist — the codebase is entirely Tokio #273).
• Miss path resolves origin + per-tenant credentials from the registry and fails closed on unknown/disabled/unbound tenants (never a default fallback).
• DropTenant = in-memory shard drop + subtree rename + background unlink, fenced by binding generation. Near-constant, no full-cache scan.
• Isolation is structural (no accidental cross-tenant serving) but not a defense against a forged tenant id; native-plane authentication is a documented follow-on.

Scope

Design + mdBook SUMMARY wiring only. The object-store gateway access path is explicitly out of scope.

🤖 Generated with Claude Code