@voltro/cli 0.1.0

package/templates/agent-docs/multi-tenancy.md

@@ -0,0 +1,610 @@
+# Multi-tenancy
+
+> Multi-tenancy as a runtime primitive — the tenant() mixin, ctx.subject.tenantId, automatic read scoping, explicit write gates.
+
+
+
+---
+
+<!-- source: en/multi-tenancy/overview.md -->
+## Overview
+
+_Multi-tenancy as a runtime primitive — the tenant() mixin, ctx.subject.tenantId, automatic read scoping, explicit write gates._
+
+Multi-tenancy is one of those features every B2B SaaS re-derives badly. Voltro treats it as a runtime primitive: drop the `tenant()` mixin on a table, and the framework guarantees cross-tenant data leakage is structurally impossible for **reads**. Writes get a typed `TenantMismatch` error if you forget the explicit check.
+
+## The model
+
+```text
+       Subject (tenantId: 'acme')
+              │
+              ▼
+   ┌─────────────────────────┐
+   │  Queries (read)          │  ← runtime AND-merges
+   │   ctx.store.select(...) │     WHERE tenantId = subject.tenantId
+   └─────────────────────────┘
+   ┌─────────────────────────┐
+   │  Mutations (write)      │  ← you call
+   │   ctx.store.insert(...) │     assertOwnTenant(input.tenantId, subject)
+   └─────────────────────────┘
+```
+
+Reads are auto-scoped because the subject + table mixin contain enough information.
+Writes are NOT auto-scoped because the input gets to *propose* a tenant — your code decides whether to honour it (typical: never) or assert against the subject (typical: always).
+
+## What's in this section
+
+- [The tenant() mixin](/docs/multi-tenancy/mixin) — how it works under the hood, when scoping kicks in, when it doesn't
+- [Edge cases](/docs/multi-tenancy/edge-cases) — public queries, cross-tenant admins, anonymous subjects, x-tenant header resolution, vector + storage isolation
+
+## The shortest possible end-to-end
+
+Schema:
+
+```ts
+import { table, id, text } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+export const notes = table('notes', {
+  id:    id(),
+  title: text(),
+}).with(tenant())
+```
+
+Query (auto-scoped):
+
+```tsx
+export const listNotes = defineQuery({ name: 'notes.list', input: Schema.Struct({}) })
+export default async (_input, ctx) => ctx.store.select('notes').all()
+// SQL: SELECT * FROM notes WHERE tenantId = $1   (with subject.tenantId)
+```
+
+Mutation (explicit gate):
+
+```tsx
+import { assertOwnTenant, TenantMismatch } from '@voltro/plugin-multitenancy'
+
+export const createNote = defineMutation({
+  name:  'notes.create',
+  input: Schema.Struct({ tenantId: Schema.String, title: Schema.String }),
+  error: TenantMismatch,
+})
+export default async (input, ctx) => {
+  assertOwnTenant(input.tenantId, ctx.subject)
+  return ctx.store.insert('notes', input)
+}
+```
+
+If a client posts `{ tenantId: 'their-tenant', title: 'hack' }` while their cookie's subject says `tenantId: 'acme'`, the mutation throws `TenantMismatch`. The audit log records it; the client sees a typed error variant.
+
+## Why the asymmetry
+
+Reads always have a single answer: "what does this subject see?" → AND the tenant. Auto-scopable.
+
+Writes have an open question: "which tenant should this go in?" The input gets to claim — sometimes legitimately (impersonation by an admin, switching active tenant). Your code decides whether to honour the claim. The framework can't auto-enforce because legitimate exceptions exist.
+
+Defaulting to "auto-reject mismatching writes" would still work for 99% of mutations + would make the 1% impossible. We picked "assert explicitly" instead — slightly more code, full flexibility.
+
+## Tenant scoping covers more than just the database
+
+| Surface | Scoped by |
+|---|---|
+| `ctx.store` selects | `tenant()` mixin's subscription filter |
+| `*.query.ts` subscriptions | Same — mixin applies inside the query's read tracker |
+| Vector search (pgvector) | Same |
+| `@voltro/plugin-storage` keys | Prefix convention: `<tenantId>/<key>` |
+| `@voltro/plugin-search` indexes | Per-tenant index (or filter, depending on backend) |
+| Workflows + agents | Inherit calling subject |
+| AI audit log | `ctx.subject.tenantId` recorded on every call |
+
+The mixin is the lever — every adjacent plugin reads from the same subject + the same column.
+
+## Isolation model
+
+The framework ships **two** isolation topologies. The default is **shared-schema**: one DB, one schema, a `tenantId` column kept apart by the `tenant()` mixin's WHERE filter. Opt into **namespace** isolation for *physical* separation — a per-request namespace, resolved from the request's tenant, into which every table reference is qualified. The runtime API is **identical** across both: the `tenant()` mixin, handler code, and `ctx.store` calls don't change. Only store resolution differs.
+
+### Opting in
+
+```ts
+// app.config.ts
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  tenancy: { isolation: 'namespace' },   // default: 'shared-schema'
+}
+```
+
+Or via env — `VOLTRO_TENANT_ISOLATION=namespace` — which overrides the config field. The same flag is read by `voltro dev` and `voltro serve`, so the topology can't drift between dev and prod.
+
+### One mechanism, per-dialect mapping
+
+Namespace isolation is **one** mechanism — a per-request namespace `tenant_<sanitised-id>`, derived from `subject.tenantId` — mapped to each dialect's native physical container:
+
+| Dialect | Namespace is a… | Table reference |
+|---|---|---|
+| postgres / mssql | **schema** | `tenant_<id>.todos` |
+| mysql / mariadb | **database** (SCHEMA ≡ DATABASE — this *is* database-per-tenant) | `tenant_<id>.todos` |
+| sqlite | **attached database** (`ATTACH DATABASE '<id>.db' AS tenant_<id>`) | `tenant_<id>.todos` |
+
+Database-per-tenant falls out of the same seam for free — only the namespace id differs; the mapping to a physical container is a per-dialect detail. Isolation is **physical**: it no longer depends on a predicate being present, so a query that forgets the tenant filter — or a table that never carried the `tenant()` mixin at all — still cannot read another tenant's rows.
+
+### Postgres fast-path — `SET LOCAL search_path`
+
+On postgres each request runs inside a transaction whose first statement is `SET LOCAL search_path TO "tenant_<id>"`. Because it's `SET LOCAL` (transaction-scoped), the setting **resets at commit** — mandatory on a pooled connection, where a bare `SET search_path` would persist and leak into the next request that checks out the same connection. The other dialects qualify identifiers directly (`tenant_<id>.todos`).
+
+### Fail closed on a missing tenant
+
+A request with **no resolvable tenant** does NOT fall back to a shared or default namespace (which could read another tenant's data) — it **fails closed**: the store refuses the operation and throws `TenantNamespaceUnresolved`. The tenant id is sanitised into a safe identifier (`tenant_<id>`, `[a-z0-9_]` only); anything that could break out of an identifier position is rejected or escaped before it reaches SQL.
+
+### Provisioning a tenant's namespace
+
+When namespace isolation is on, the auto-migrate DDL fans out per tenant: it creates the container (`CREATE SCHEMA` / `CREATE DATABASE` / `ATTACH DATABASE`) and runs the table DDL inside it. Provision a new tenant's namespace eagerly at migrate time or lazily on first use via `provisionTenantNamespace(tables, namespace, sqlLayer, dialect)` from `@voltro/database/sql`.
+
+### CDC namespace tagging
+
+The postgres `LISTEN/NOTIFY` payload carries the writing schema (`TG_TABLE_SCHEMA`) so a write in tenant A's namespace doesn't spuriously wake tenant B's subscriptions on the same-named table. mariadb's binlog already carries the database name; mysql / mssql / sqlite emit through the framework's own path, which already knows the namespace. A spurious wake is **not** a leak — the re-query runs against the woken subscription's OWN namespace — so suppressing cross-namespace wakes is purely a wasted-work optimization.
+
+
+
+---
+
+<!-- source: en/multi-tenancy/mixin.md -->
+## The tenant() mixin
+
+_What tenant() adds — the tenantId reference, the auto-index, the read scoping — and how it composes with other mixins._
+
+The `tenant()` mixin is the lever that turns a normal table into a tenant-scoped one. This page covers exactly what it does.
+
+## What it adds
+
+```ts
+import { table, id, text } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+export const notes = table('notes', {
+  id:    id(),
+  title: text(),
+}).with(tenant())
+```
+
+`tenant()` takes **no arguments**. It returns a `MixinDefinition` you apply with `.with(...)` — never spread it into the field object. The mixin contributes:
+
+1. **A `tenantId` column** — `reference(requireTenants())`, an FK into your app's `tenants` table (not a bare text column).
+2. **An auto-index** on `tenantId` (`indexes: [{ fields: ['tenantId'] }]`). The name is auto-generated as `<tableName>_tenantId_idx`.
+3. **Read scoping** — the runtime AND-merges `WHERE tenantId = ctx.subject.tenantId` into every subscription against this table.
+4. **Insert auto-fill** — when an insert's row payload omits `tenantId`, the runtime stamps it from the request subject.
+
+The mixin's stable id is `voltro/tenant`. The execution lives in the runtime's `wrapStoreWithMixinBehaviour` (write side) and the CLI's `applyTenantScope` (read side) — both key off that id. The mixin source is `voltro/packages/plugin-multitenancy/src/mixin.ts`.
+
+## tenant() requires audit()
+
+`tenant()` transitively requires `audit()` — every tenant-scoped row is also a who/when-stamped artefact in the audit trail. The dependency resolver dedupes if you apply both explicitly, so `.with(tenant())` alone is enough.
+
+## Composing with other mixins
+
+```ts
+import { table, id, text } from '@voltro/database'
+import { tenant }     from '@voltro/plugin-multitenancy'
+import { audit }      from '@voltro/plugin-audit'
+import { softDelete } from '@voltro/plugin-soft-delete'
+
+export const notes = table('notes', {
+  id:    id(),
+  title: text(),
+}).with(softDelete(), tenant(), audit())   // tenant() pulls in audit() anyway
+```
+
+The behaviors compose. A read against `notes`:
+
+- Filters by `tenantId` (from `tenant()`)
+- ALSO filters out `deletedAt IS NOT NULL` (from `softDelete()`)
+- Returns the audit columns alongside
+
+Order in the `.with(...)` chain doesn't matter for these — mixin read predicates are AND-merged.
+
+## The auto-fill behaviour
+
+```ts
+// Mutation:
+ctx.store.insert('notes', { title: 'Hello' })
+```
+
+If you DON'T pass `tenantId`, the runtime auto-fills it from `ctx.subject.tenantId`. The row is created in the caller's tenant. This is the safe default — it's hard to accidentally create a cross-tenant row.
+
+When you DO pass an explicit `tenantId` (an admin writing into another tenant), the framework does NOT silently substitute the subject's value — silent substitution is a footgun. Guard the write with `assertOwnTenant` (see below); a genuine cross-tenant write runs as the `system` subject via `runAsSystem` (see [Edge cases](/docs/multi-tenancy/edge-cases)).
+
+## What it does NOT do
+
+- **Auto-guard writes.** Read scoping is automatic; mutations receive user-supplied input including `tenantId`. A client authenticated as tenant A can post `tenantId: 'B'` and the row lands in B without a guard. Call `assertOwnTenant` at the top of the executor:
+
+  ```ts
+  import { assertOwnTenant, TenantMismatch } from '@voltro/plugin-multitenancy'
+
+  export default async (input, ctx) => {
+    assertOwnTenant(input.tenantId, ctx.request.subject)   // throws TenantMismatch on spoof
+    return ctx.store.insert('notes', input)
+  }
+  ```
+
+  Declare `error: TenantMismatch` on the mutation descriptor so the rpc layer surfaces the rejection typed.
+
+- **Apply to raw SQL.** A hand-written `@effect/sql` query bypasses the mixin. Write the filter yourself.
+
+## Performance considerations
+
+The auto-injected `tenantId = $1` filter is fast — the mixin's single-column index covers it. For high-cardinality tables (events, logs, audits), add a composite index with `tenantId` as the leftmost column on the actual hot query:
+
+```ts
+table('messages', {
+  id:        id(),
+  channelId: text(),
+  body:      text(),
+  createdAt: timestamp().default('now'),
+})
+  .with(tenant())
+  .index('messages_tenant_channel_created',
+    ['tenantId', 'channelId', { col: 'createdAt', order: 'desc' }])
+```
+
+Now `WHERE tenantId = $1 AND channelId = $2 ORDER BY createdAt DESC LIMIT 50` is served from the index. Indexes are declared at the table level — there is no column-level `.index()` modifier.
+
+## When NOT to use the mixin
+
+- **Truly global tables** — feature flags, system config, audit retention policies. These don't belong to any single tenant. Leave them un-mixin'd.
+- **Cross-tenant aggregates** — usage reports, cross-tenant leaderboards, admin dashboards. Run the read as the `system` subject via `runAsSystem` (see [Edge cases](/docs/multi-tenancy/edge-cases)); a system subject has `tenantId: null` by construction and the AND-merge is skipped.
+
+The mixin is opt-in per table. You declare it for the tables that should be scoped + leave the rest free.
+
+## See also
+
+- [Overview](/docs/multi-tenancy/overview) — the read/write asymmetry model
+- [Edge cases](/docs/multi-tenancy/edge-cases) — cross-tenant reads, anonymous subjects, storage isolation
+
+
+
+---
+
+<!-- source: en/multi-tenancy/edge-cases.md -->
+## Edge cases
+
+_Cross-tenant admins, anonymous subjects, public queries, x-tenant header resolution, vector + storage isolation._
+
+The `tenant()` mixin handles the 95% case. The remaining 5% is here.
+
+## Cross-tenant reads — `.unscoped()`
+
+For staff that need to read across tenants (support, billing ops) the
+fluent `ctx.store.select(...)` builder exposes `.unscoped()`, which drops
+the automatic `tenantId` filter:
+
+```ts
+const all = await ctx.store.select('notes').unscoped().all()
+```
+
+`.unscoped()` is a raw capability — it is NOT role-gated by the
+framework. Whether the caller is *allowed* to read cross-tenant is YOUR
+decision: gate on a scope before you call it.
+
+```ts
+import { hasScope } from '@voltro/protocol'
+
+if (!hasScope(ctx.request.subject, 'admin:full')) {
+  throw new Error('cross-tenant read requires admin scope')
+}
+const all = await ctx.store.select('notes').unscoped().all()
+```
+
+The subject carries `scopes` (resolved by the auth strategy), never a
+`roles` field. Use `hasScope` / `requireScope` from `@voltro/protocol`;
+`admin:full` is the blanket bypass.
+
+The same `.unscoped()` modifier exists on the `update(...)` and
+`delete(...)` builders for cross-tenant writes — both equally ungated, so
+guard them the same way.
+
+## Anonymous subjects
+
+Anonymous requests have a `null` `id` and may carry a `tenantId` or
+`null`. The fluent `select` only AND-merges the tenant filter when the
+subject's `tenantId` is non-null, so an anonymous subject WITHOUT a
+tenant reads with no tenant filter — be deliberate about which tables
+you expose to it.
+
+For **truly public** tables that don't need scoping, drop the mixin:
+
+```ts
+const publicArticles = table('public_articles', {
+  id:    id(),
+  body:  text(),
+  // NO .with(tenant()) — anyone can read
+})
+```
+
+For tables that ARE tenant-scoped but should serve **anonymous** users
+with the tenant inferred from a request header, the anonymous fallback
+in `composeAuthStrategies` produces an `anonymousSubject(tenantId)` from
+the `x-tenant` header when no strategy matches:
+
+```ts
+import { anonymousSubject } from '@voltro/protocol'
+// the composer's default fallback reads `x-tenant` and yields
+//   { type: 'anonymous', id: null, tenantId: 'acme' }
+```
+
+A request with `x-tenant: acme` reads tenant-scoped tables under that
+tenant. Use this for per-tenant marketing pages, public listings filtered
+by tenant slug, status pages. Never expose any table that should require
+auth this way — the header is client-controlled and unauthenticated.
+
+## Subdomain-based tenant resolution
+
+For `tenant1.your-product.com` / `tenant2.your-product.com`, write a
+custom strategy and add it to the chain in `app.config.ts`:
+
+```ts
+// app.config.ts
+import { composeAuthStrategies } from '@voltro/protocol'
+import { anonymousSubject } from '@voltro/protocol'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  auth: {
+    strategies: [
+      {
+        id: 'subdomain',
+        resolve: async (input) => {
+          const host = input.headers.host ?? ''
+          const sub = host.split('.')[0]
+          const tenant = await lookupTenantBySubdomain(sub)
+          return tenant
+            ? { kind: 'matched', subject: anonymousSubject(tenant.id) }
+            : { kind: 'skip' }
+        },
+      },
+    ],
+  },
+}
+```
+
+The built-in signed-cookie password strategy always runs FIRST, so when
+the user signs in, the cookie subject (with their own `tenantId`)
+overrides the anonymous subdomain one.
+
+## Public queries that bypass the mixin
+
+For a `*.query.ts` that serves data from a tenant-scoped table to
+anonymous users (read public articles for tenant X):
+
+```tsx
+export default async (input, ctx) => {
+  // input.tenantId comes from the URL slug
+  return ctx.store.select('articles')
+    .unscoped()                                      // drop the auto-filter
+    .where('tenantId', input.tenantId)               // … and add ours explicitly
+    .where('published', true)
+    .all()
+}
+```
+
+The `unscoped()` + explicit `where('tenantId', …)` pattern makes intent
+obvious — the next reader sees exactly which tenant the query serves.
+
+## Anonymous vector search
+
+Same pattern for pgvector:
+
+```ts
+ctx.store.select('public_docs')
+  .unscoped()
+  .where('tenantId', publicTenantId)
+  .nearestNeighbours('embedding', query)
+  .limit(5)
+  .all()
+```
+
+For multi-tenant SaaS where each tenant has its own knowledge base plus
+an anonymous "marketing" tenant ID for public demos.
+
+## Object storage (R2 / S3) keys
+
+`@voltro/plugin-storage` keys are tenant-prefixed. The stored object key
+is composed as `<tenantPrefix>/<tenantId | 'global'>/<key>` — the
+`tenantId` comes from the request subject, and `tenantPrefix` is an
+optional static app/env namespace set in `storagePlugin({ tenantPrefix })`.
+Two tenants uploading the same `key` land at distinct paths, so one
+tenant can't read another's object through the service.
+
+## Backup + restore considerations
+
+Shared-schema multi-tenancy means **one backup covers all tenants**:
+
+- Restoring a snapshot brings every tenant back to that point —
+  including tenants that weren't asking for the restore.
+- Per-tenant point-in-time recovery is not possible with shared schema.
+  It IS possible with the namespace isolation topology (schema- /
+  database-per-tenant), see [Overview](/docs/multi-tenancy/overview).
+
+If a single tenant wants to "roll back" their data, you need a
+`tenant_snapshots` table you maintain explicitly, or a schema-per-tenant
+deployment topology.
+
+## Soft-delete + multi-tenancy
+
+```ts
+const notes = table('notes', {
+  id:    id(),
+  title: text(),
+}).with(softDelete(), tenant())
+```
+
+A scoped read filters both predicates:
+
+```sql
+WHERE tenantId = subject.tenantId
+  AND deletedAt IS NULL
+```
+
+A row soft-deleted in tenant A is gone for subjects in A and invisible to
+any other tenant (they couldn't see A's rows anyway). To bring a soft-
+deleted row back, use the `update` builder's `.restore()` (clears
+`deletedAt`); read soft-deleted rows with `.withDeleted()`:
+
+```ts
+await ctx.store.update('notes').where('id', noteId).restore()
+const trash = await ctx.store.select('notes').withDeleted().all()
+```
+
+## Workflows that need to cross tenants
+
+Some workflows legitimately cross — billing aggregation, cross-tenant
+analytics jobs. Run them as the `system` subject:
+
+```tsx
+// scheduled job
+import { runAsSystem } from '@voltro/runtime'
+
+await runAsSystem(async (ctx) => {
+  const usage = await ctx.store.select('events')
+    .unscoped()
+    .where('createdAt', '>', cutoff)
+    .all()
+  // aggregate, write, etc.
+}, { id: 'job:billing-aggregator' })
+```
+
+`runAsSystem` binds `ctx.subject` to a `system` subject
+(`{ type: 'system', id: 'job:billing-aggregator', tenantId: null }`). A
+system subject has `tenantId: null` by construction, so the tenant
+AND-merge is skipped; the `.unscoped()` above additionally drops the
+soft-delete filter when the table carries `softDelete()`. The system
+subject defaults to the `admin:full` scope; pass `{ scopes }` to narrow,
+and `{ id }` for a named job (default `'system'`).
+
+## Tests + multi-tenancy
+
+Test contexts can fake any subject:
+
+```ts
+import { makeTestContext } from '@voltro/testing'
+
+const ctx = makeTestContext({
+  subject: { type: 'user', id: 'usr_test', tenantId: 'tenant-a' },
+})
+
+// All ctx.store calls now scoped to tenant-a
+```
+
+For cross-tenant isolation tests:
+
+```ts
+const ctxA = makeTestContext({ subject: { type: 'user', id: 'a', tenantId: 'A' } })
+const ctxB = makeTestContext({ subject: { type: 'user', id: 'b', tenantId: 'B' } })
+
+await ctxA.store.insert('notes', { title: 'A note' })
+const fromB = await ctxB.store.select('notes').all()
+expect(fromB).toEqual([])   // B cannot see A's row
+```
+
+This is the kind of test you write ONCE per table with the `tenant()`
+mixin.
+
+## What can still go wrong
+
+- **A raw `@effect/sql` query that forgets the tenant filter** — the
+  mixin doesn't intercept hand-written SQL. Audit raw queries carefully.
+- **An `.unscoped()` call without a scope check in front of it** — the
+  modifier is ungated by design. A `requireScope` / `hasScope` guard
+  belongs immediately before every cross-tenant read or write.
+- **A subject leaked across requests** — the framework's request-scoped
+  subject resolution makes this hard, but a custom strategy can do it.
+  If you write one, return a fresh subject each call.
+- **Plugin code that bypasses `ctx.store`** — third-party plugins should
+  use `ctx.store` only. If they reach for `@effect/sql` directly, they
+  skip the mixin. Audit third-party plugins.
+
+For high-stakes deploys (compliance, healthcare), add a CI check that
+scans for `.unscoped()` calls and reviews each one. The framework can't
+catch the cases where you legitimately opt out — that's a code-review
+responsibility.
+
+
+
+---
+
+<!-- source: en/multi-tenancy/residency.md -->
+## Data residency
+
+_Pin each tenant's data to a HOME region and fail closed everywhere else — a deployment never serves or provisions a tenant homed in a region it doesn't hold, so a US deployment can never touch an EU-homed tenant's rows._
+
+Data residency pins each tenant's data to a **home region** and makes every other
+deployment **fail closed**. A deployment declares which regions it can serve (it
+holds their stores); a request for a tenant homed elsewhere is refused, not
+served from a fallback — the gateway is expected to route it to the home region's
+deployment. So a US deployment can **never** read, bind, or provision an EU-homed
+tenant's data.
+
+> Residency **never falls back to a default store.** No home mapped → typed
+> `TenantResidencyUnresolved`. Home region not served here → typed
+> `TenantRegionUnavailable`. Both fail closed; that's the whole point.
+
+## Configure it
+
+```ts
+import { setResidencyConfig } from '@voltro/database'
+
+setResidencyConfig({
+  // tenant → home region (+ optional named connection for the home DB).
+  homes: [
+    { tenantId: 'acme',  region: 'eu-west' },
+    { tenantId: 'globex', region: 'us-east' },
+  ],
+  // The regions THIS deployment can actually serve (it holds their stores).
+  servableRegions: ['us-east'],
+})
+```
+
+A tenant mapped to two different regions is rejected at config time (ambiguous
+routing), and `servableRegions` must be non-empty.
+
+## Resolve + bind per request
+
+`bindResidentStore` picks the store for the subject's home region from the
+per-region handles this deployment holds — failing closed if the home is
+unresolved or not served here:
+
+```ts
+import { bindResidentStore } from '@voltro/database'
+
+// stores: ReadonlyMap<region, StoreHandle> — what THIS deployment wired.
+const { store, placement } = bindResidentStore(subject, config, stores)
+// placement = { region, namespace, connectionKey? }
+// throws TenantRegionUnavailable for an EU-homed tenant on a US deployment.
+```
+
+`residentPlacement(subject, config)` gives the placement alone (region +
+the tenant's namespace within that region's store) without needing the handles.
+
+## Provision a new resident tenant
+
+`provisionResidentTenant` runs an injected provisioner against the tenant's HOME
+store + namespace, behind the SAME fail-closed guards as binding:
+
+```ts
+import { provisionResidentTenant } from '@voltro/database'
+
+await provisionResidentTenant(subject, config, stores, async (store, placement) => {
+  // e.g. provisionTenantNamespace(tables, placement.namespace, sqlLayer, dialect)
+})
+// A US deployment provisioning an EU-homed tenant → TenantRegionUnavailable.
+```
+
+## How it composes with the `tenant()` mixin
+
+Residency is the **physical** placement (which region's store); the
+[`tenant()` mixin](/docs/multi-tenancy/mixin) is the **logical** scope (the
+`WHERE tenantId = …` filter within a store). They stack: residency routes the
+request to the right region's store, then the mixin scopes the rows inside it.
+Namespace isolation within a region uses the same `resolveTenantNamespace` the
+mixin's physical-isolation mode uses.