@pyxmate/memory 0.20.5 → 0.21.1

package/skills/pyx-memory/patterns/access-control.md

@@ -1,586 +0,0 @@
-# Access Control Patterns
-
-Production patterns for restricting who can read and write which memories.
-
-## Contents
-- [Quick Decision Tree](#quick-decision-tree)
-- [Pattern 10: Per-Agent Isolation](#pattern-10-per-agent-isolation)
-- [Pattern 11: Multi-Tenant with Team Scoping](#pattern-11-multi-tenant-with-team-scoping)
-- [Pattern 12: Sensitivity-Based Read Restriction](#pattern-12-sensitivity-based-read-restriction)
-- [Pattern 13: Read-Only vs Read-Write Access](#pattern-13-read-only-vs-read-write-access)
-- [Pattern 14: Full Production Stack](#pattern-14-full-production-stack)
-- [Pattern 15: Built-in ReBAC](#pattern-15-built-in-rebac-namespaces--tuples--authzplan) ← **start here for fine-grained per-user / per-team access**
-
----
-
-## Quick Decision Tree
-
-```
-Need to isolate agents from each other?
-  → Use agentId scoping (Pattern 10)
-
-Need to isolate organizations/customers?
-  → Use TENANT_MODE=multi + X-Tenant-Id (Pattern 11)
-
-Need fine-grained per-user / per-team / per-folder access INSIDE a tenant?
-  → Use built-in ReBAC: namespaces + principals + authz_tuples (Pattern 15)
-
-Need to hide sensitive data from some users?
-  → Use sensitivity classification + X-Caller-Access-Level (Pattern 12)
-
-Need read-only vs read-write roles?
-  → Use API_KEY + ADMIN_API_KEY + an API gateway (Pattern 13)
-
-Need all of the above?
-  → Pattern 14 (full production stack) + Pattern 15 (ReBAC)
-```
-
----
-
-## Pattern 10: Per-Agent Isolation
-
-Each agent sees only its own memories. Other agents' memories are invisible — not redacted, just absent from results.
-
-```typescript
-// Agent A — can only see its own memories
-const agentAMemory = new Memory({
-  dataDir: './data',
-  agentId: 'agent-researcher',
-});
-await agentAMemory.initialize();
-
-// Anything agent A stores is tagged with agentId: 'agent-researcher'
-await agentAMemory.store({
-  content: 'Found a bug in the auth module',
-  type: 'long-term',
-  metadata: {},
-});
-
-// Agent A's searches only return agent A's memories
-const results = await agentAMemory.search({ query: 'auth bug' });
-// ✓ Returns the entry above
-
-// Agent B — completely isolated
-const agentBMemory = new Memory({
-  dataDir: './data',
-  agentId: 'agent-writer',
-});
-await agentBMemory.initialize();
-
-const bResults = await agentBMemory.search({ query: 'auth bug' });
-// ✗ Returns nothing — agent A's memories are invisible to agent B
-```
-
-**Sidecar mode**: Pass `agentId` in the request body or query params — the server filters by it.
-
-```bash
-# Store as agent-researcher
-curl -X POST http://localhost:7822/api/memory/ingest \
-  -H "Content-Type: application/json" \
-  -d '{"content":"Agent-scoped fact","type":"long-term","metadata":{},"agentId":"agent-researcher"}'
-
-# Search as agent-researcher — only sees agent-researcher's memories
-curl 'http://localhost:7822/api/memory/search?query=fact&agentId=agent-researcher'
-```
-
-**When to use**: Multiple AI agents sharing one memory instance, each needing their own knowledge base. Agents that should collaborate can omit `agentId` to share a global pool.
-
----
-
-## Pattern 11: Multi-Tenant with Team Scoping
-
-For SaaS / multi-organization deployments where each customer's data must be completely isolated.
-
-### Server config
-
-```bash
-# docker-compose.yaml
-environment:
-  - TENANT_MODE=multi    # enforce X-Tenant-Id on ALL operations
-  - API_KEY=your-key     # always set API_KEY with multi-tenant
-```
-
-### Per-client setup
-
-```typescript
-import { MemoryClient } from '@pyx-memory/client';
-
-// Organization A — engineering team
-const orgAEng = new MemoryClient('http://memory:7822', {
-  apiKey: process.env.MEMORY_API_KEY,
-  defaultHeaders: {
-    'X-Tenant-Id': 'org-acme',
-    'X-User-Id': 'alice',
-    'X-Team-Id': 'team-engineering',
-  },
-});
-
-// Organization A — marketing team (same tenant, different team)
-const orgAMkt = new MemoryClient('http://memory:7822', {
-  apiKey: process.env.MEMORY_API_KEY,
-  defaultHeaders: {
-    'X-Tenant-Id': 'org-acme',
-    'X-User-Id': 'bob',
-    'X-Team-Id': 'team-marketing',
-  },
-});
-
-// Organization B — completely isolated tenant
-const orgB = new MemoryClient('http://memory:7822', {
-  apiKey: process.env.MEMORY_API_KEY,
-  defaultHeaders: {
-    'X-Tenant-Id': 'org-globex',
-    'X-User-Id': 'charlie',
-  },
-});
-```
-
-### What's enforced
-
-| Scope level | How it works |
-|-------------|-------------|
-| `tenantId` | **Hard isolation.** Tenant A never sees tenant B's data. Enforced server-side when `TENANT_MODE=multi`. |
-| `teamId` | **Soft scoping.** Stored on entries but not enforced by the server. Use application-layer filtering. |
-| `userId` | **Soft scoping.** Stored on entries but not enforced by the server. Use application-layer filtering. |
-| `agentId` | **Hard filtering.** When set in MemoryOptions or query params, only that agent's entries are returned. |
-
-**Key rule**: `TENANT_MODE=multi` enforces tenantId. userId and teamId are for your application to filter — pyx-memory stores them but does not enforce boundaries between users/teams within a tenant.
-
----
-
-## Pattern 12: Sensitivity-Based Read Restriction
-
-Control which memories are visible based on the caller's access level. Entries classified above the caller's level are automatically redacted in search results.
-
-### How sensitivity classification works
-
-Every `store()` automatically scans content and classifies it:
-
-| Level | Auto-detected when | Example |
-|-------|-------------------|---------|
-| `public` | No credentials or PII detected | "Prefer tabs over spaces" |
-| `internal` | PII found (email, phone, SSN, etc.) | "Alice's email is alice@acme.com" |
-| `secret` | Credentials found (API keys, tokens, passwords) | "The API key is sk-ant-..." |
-
-### Restricting search results
-
-```typescript
-// Embedded: use maxSensitivity search param
-const results = await memory.search({
-  query: 'config',
-  maxSensitivity: 'internal', // only public + internal; secret entries are redacted
-});
-
-// Sidecar: use X-Caller-Access-Level header
-const restricted = new MemoryClient('http://memory:7822', {
-  apiKey: process.env.MEMORY_API_KEY,
-  defaultHeaders: {
-    'X-Caller-Access-Level': 'internal', // this client never sees secret entries
-  },
-});
-```
-
-### What "redacted" means
-
-When a search returns entries above the caller's access level, the content is replaced with `[REDACTED: sensitive content]`. The entry metadata (id, type, createdAt) is still visible so the caller knows something exists — they just can't read it.
-
-### Sensitivity policy options
-
-| `SENSITIVITY_POLICY` | Behavior |
-|----------------------|----------|
-| `flag` (default) | Classify and store sensitivity level. No content modification. |
-| `redact` | Replace detected credentials with `[REDACTED]` before storage. |
-| `block` | Reject any ingest containing credentials (HTTP 400). |
-| `encrypt` | Encrypt `secret` entries at rest with AES-256-GCM. Transparent decrypt on read when key is available. |
-
-```bash
-# Production config with encryption
-environment:
-  - SENSITIVITY_POLICY=encrypt
-  - ENCRYPTION_KEY=your-64-hex-char-key  # 32 bytes as hex
-```
-
----
-
-## Pattern 13: Read-Only vs Read-Write Access
-
-pyx-memory has two auth tiers: `API_KEY` (read + write) and `ADMIN_API_KEY` (destructive ops). For finer read-only vs read-write control, use an API gateway or proxy layer in front.
-
-### Built-in auth tiers
-
-| Key | Allowed operations |
-|-----|-------------------|
-| `API_KEY` | All read operations (search, get, list, stats) + write operations (store, ingestFileEvents) |
-| `ADMIN_API_KEY` | Destructive operations: DELETE, forget, decay, consolidate, reindex, deleteBySource |
-
-```bash
-# Give agents API_KEY (read + write), give admin tools ADMIN_API_KEY
-environment:
-  - API_KEY=agent-key-for-read-write
-  - ADMIN_API_KEY=admin-key-for-destructive-ops
-```
-
-### Adding read-only access via a proxy
-
-pyx-memory doesn't have a native "read-only API key." To implement read-only roles, put a reverse proxy (nginx, Caddy, API gateway) in front:
-
-```nginx
-# nginx example: read-only role blocks POST/PUT/DELETE
-location /api/memory/ {
-    # Read-only key can only GET
-    if ($http_authorization = "Bearer readonly-key") {
-        limit_except GET {
-            deny all;
-        }
-    }
-    proxy_pass http://memory:7822;
-}
-```
-
-Or implement it in your application layer:
-
-```typescript
-// Application-level access control middleware
-function memoryAccessMiddleware(req: Request, userRole: string): boolean {
-  const method = req.method;
-  const isWrite = method === 'POST' || method === 'PUT' || method === 'DELETE';
-
-  if (userRole === 'viewer' && isWrite) {
-    throw new ForbiddenError('Read-only access — cannot modify memory');
-  }
-  if (userRole === 'editor' && req.url.includes('/consolidate')) {
-    throw new ForbiddenError('Editors cannot run consolidation');
-  }
-  return true;
-}
-```
-
----
-
-## Pattern 14: Full Production Stack
-
-Combines all patterns for a production multi-tenant deployment with sensitivity, encryption, and the built-in two-tier API key model (`API_KEY` for read+write, `ADMIN_API_KEY` for destructive ops). For fine-grained per-user/per-namespace access inside a tenant, layer Pattern 15 (ReBAC) on top of this base.
-
-### Server config
-
-```yaml
-# docker-compose.yaml
-services:
-  memory:
-    image: ghcr.io/pyx-corp/pyx-memory-v1:latest
-    environment:
-      - DATA_DIR=/data
-      - API_KEY=${MEMORY_API_KEY}
-      - ADMIN_API_KEY=${MEMORY_ADMIN_KEY}
-      - TENANT_MODE=multi
-      - SENSITIVITY_POLICY=encrypt
-      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
-      - PII_POLICY=flag
-      - RATE_LIMIT_RPM=120
-      - CORS_ORIGIN=https://app.example.com
-      - NODE_ENV=production
-```
-
-### Client setup per role
-
-```typescript
-import { MemoryClient } from '@pyx-memory/client';
-
-const MEMORY_URL = 'http://memory:7822';
-
-// Admin client — full access, destructive ops allowed
-function createAdminClient(tenantId: string) {
-  return new MemoryClient(MEMORY_URL, {
-    apiKey: process.env.MEMORY_ADMIN_KEY,
-    defaultHeaders: {
-      'X-Tenant-Id': tenantId,
-      'X-Caller-Access-Level': 'secret',
-    },
-  });
-}
-
-// Agent client — read + write, scoped to agent + tenant
-function createAgentClient(tenantId: string, agentId: string) {
-  return new MemoryClient(MEMORY_URL, {
-    apiKey: process.env.MEMORY_API_KEY,
-    defaultHeaders: {
-      'X-Tenant-Id': tenantId,
-      'X-Caller-Access-Level': 'internal', // can't see secret entries
-    },
-  });
-  // Note: agentId is passed per-request, not via headers
-}
-
-// Dashboard client — read-only (enforce at application layer)
-function createDashboardClient(tenantId: string, userId: string) {
-  return new MemoryClient(MEMORY_URL, {
-    apiKey: process.env.MEMORY_API_KEY,
-    defaultHeaders: {
-      'X-Tenant-Id': tenantId,
-      'X-User-Id': userId,
-      'X-Caller-Access-Level': 'public', // most restricted view
-    },
-  });
-}
-```
-
-### What each role sees
-
-| Role | tenantId | agentId | maxSensitivity | Write | Delete/Admin |
-|------|----------|---------|----------------|-------|-------------|
-| Admin | scoped | all | secret | yes | yes (ADMIN_API_KEY) |
-| Agent | scoped | scoped | internal | yes | no |
-| Dashboard | scoped | all | public | no (app-enforced) | no |
-
----
-
-## Pattern 15: Built-in ReBAC (namespaces + tuples + AuthzPlan)
-
-For fine-grained access control inside a tenant — "alice can read project-X but not project-Y", "team-eng has editor on engineering/*", "revoke without entry rewrite" — pyx-memory ships first-class ReBAC primitives. No external policy service required for v1; the model is Zanzibar-aligned so you can later export to OpenFGA / SpiceDB without changing application code.
-
-### The four primitives
-
-| Resource | Role |
-|----------|------|
-| `namespace` | The unit you grant access to (folders, projects, channels). Hierarchical via `parentId`. Granting on a parent transitively covers descendants. |
-| `principal` | A subject — `user`, `team`, `group`, `agent`, `service`, or per-tenant `everyone`. Identified by `(tenantId, kind, externalId)`. |
-| `principal_member` | Membership edge `member ∈ group`. Group-of-groups supported (cycles rejected, max-depth-8 namespaces). |
-| `authz_tuple` | The grant: `(subject, relation, object)` — e.g. `(user:alice, viewer, namespace:proj-acme)`. Built-in rewrite: `owner ⊇ editor ⊇ viewer`. |
-
-### Server config
-
-```yaml
-# docker-compose.yaml
-environment:
-  - TENANT_MODE=multi
-  - API_KEY=${MEMORY_API_KEY}
-  - ADMIN_API_KEY=${MEMORY_ADMIN_KEY}   # required to manage namespaces / tuples
-```
-
-### Manage namespaces, principals, and tuples (admin API)
-
-All `/api/admin/*` routes require `ADMIN_API_KEY` and `X-Tenant-Id`.
-
-```bash
-# 1. Create a namespace (the resource you'll grant access to)
-curl -X POST http://memory:7822/api/admin/namespaces \
-  -H "Authorization: Bearer $ADMIN_KEY" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"engineering"}'
-# → {"id":"<NS_ID>", ...}
-
-# 2. Register a principal (idempotent on tenant + kind + externalId)
-curl -X POST http://memory:7822/api/admin/principals \
-  -H "Authorization: Bearer $ADMIN_KEY" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "Content-Type: application/json" \
-  -d '{"kind":"user","externalId":"alice","displayName":"Alice"}'
-# → {"id":"<ALICE_ID>", ...}
-
-# 3. Grant alice viewer on engineering
-curl -X POST http://memory:7822/api/admin/authz-tuples \
-  -H "Authorization: Bearer $ADMIN_KEY" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "subjectKind":"user","subjectId":"<ALICE_ID>",
-    "relation":"viewer",
-    "objectKind":"namespace","objectId":"<NS_ID>"
-  }'
-
-# 4. Revoke (one row delete — no entry rewrite, takes effect immediately)
-curl -X DELETE http://memory:7822/api/admin/authz-tuples \
-  -H "Authorization: Bearer $ADMIN_KEY" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "Content-Type: application/json" \
-  -d '{ ...same body as the grant... }'
-```
-
-### Make something public to the whole tenant
-
-```bash
-# Resolve the per-tenant `everyone` principal (auto-created)
-curl -X POST http://memory:7822/api/admin/principals \
-  -H "Authorization: Bearer $ADMIN_KEY" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "Content-Type: application/json" \
-  -d '{"kind":"everyone","externalId":"_everyone"}'
-
-# Grant `everyone` viewer on the announcements namespace
-curl -X POST http://memory:7822/api/admin/authz-tuples \
-  -H "Authorization: Bearer $ADMIN_KEY" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "subjectKind":"everyone","subjectId":"<EVERYONE_ID>",
-    "relation":"viewer",
-    "objectKind":"namespace","objectId":"<NS_ID>"
-  }'
-```
-
-Reversing later is the same — delete the tuple, visibility flips back the next request.
-
-### Search-time enforcement
-
-Pass the calling principal on `Memory.search()`. The server computes an `AuthzPlan` (visible namespaces + cached revision) BEFORE any retrieval source fans out. SQLite/FTS, LanceDB vector search, and the graph engine all apply the plan as a native pre-filter — forbidden entries never enter RRF fusion or reranker scoring (which would skew normalization for everyone).
-
-```typescript
-const result = await memory.search({
-  query: 'Q4 revenue',
-  strategy: 'hybrid',
-  principal: {
-    tenantId: 'tenant-acme',
-    principalId: 'alice',
-    kind: 'user',
-  },
-});
-// result.entries contains only namespaces alice can `view`,
-// plus legacy NULL-namespace entries (tenant-root bucket).
-```
-
-### Legacy compatibility
-
-Entries with `namespace_id IS NULL` (the default before ReBAC) remain visible to anyone with tenant access. You opt entries into ReBAC by setting `namespaceId` at ingest:
-
-```typescript
-await memory.store({
-  content: 'Q4 revenue projections',
-  type: 'long-term',
-  metadata: {},
-  namespaceId: '<NS_ID>',
-});
-```
-
-HTTP ingest accepts the same resource coordinate on JSON and file uploads:
-
-```bash
-curl -X POST "$MEMORY_URL/api/memory/ingest" \
-  -H "Authorization: Bearer $API_KEY" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "X-Namespace-Id: <NS_ID>" \
-  -H "Content-Type: application/json" \
-  -d '{"content":"Q4 revenue projections","type":"long-term"}'
-
-curl -N -X POST "$MEMORY_URL/api/memory/ingest/file" \
-  -H "Authorization: Bearer $API_KEY" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "X-Namespace-Id: <NS_ID>" \
-  -F "file=@report.pdf"
-```
-
-`X-Namespace-Id` is canonical when both header and body/form field are sent; conflicting values return `400 namespace_id_conflict`. A missing or cross-tenant namespace returns `404 namespace_not_found`.
-
-No bulk migration is required — legacy data keeps working unchanged.
-
-### Migrating legacy entries (v0.16.1)
-
-When you _do_ want to move pre-ReBAC entries (or reorganize an existing namespace tree), the admin entry-move API coordinates SQLite + vector + graph for you:
-
-```bash
-# Single entry: move one row to a target namespace.
-curl -X POST "$ENDPOINT/api/admin/entries/$ENTRY_ID/move" \
-  -H "Authorization: Bearer $ADMIN_API_KEY" \
-  -H "X-Tenant-Id: $TENANT" \
-  -H "Content-Type: application/json" \
-  -d '{"namespaceId": "<NS_ID>"}'
-# null reverts to tenant-root (the legacy / pre-ReBAC bucket).
-```
-
-Batch moves accept a filter and return cursor-paginated `MoveResult` rows. Always preview with `dryRun: true` first — the same filter + cursor drives both the dryRun preview and the execute pass, so what you see in dryRun is exactly what executes:
-
-```bash
-# Dry-run: see which rows would move, without touching any store.
-curl -X POST "$ENDPOINT/api/admin/entries/move-batch" \
-  -H "Authorization: Bearer $ADMIN_API_KEY" \
-  -H "X-Tenant-Id: $TENANT" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "filter": { "fromNamespaceId": null, "source": "legacy-import.csv" },
-    "target": { "namespaceId": "<NS_ID>" },
-    "dryRun": true,
-    "limit": 100
-  }'
-# Response includes results[] + nextCursor for paging.
-
-# Execute: same body without dryRun (or dryRun: false).
-curl -X POST "$ENDPOINT/api/admin/entries/move-batch" \
-  -H "Authorization: Bearer $ADMIN_API_KEY" \
-  -H "X-Tenant-Id: $TENANT" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "filter": { "fromNamespaceId": null, "source": "legacy-import.csv" },
-    "target": { "namespaceId": "<NS_ID>" },
-    "limit": 100
-  }'
-```
-
-What the move guarantees:
-
-- **3-store coordination.** SQLite + vector + graph (when registered) all see the new `namespace_id`. On per-store failure the earlier writes are reverted in reverse order so partial states do not survive — the `MoveResult.failureReason` tells you which store rejected the move (`vector_update_failed`, `graph_update_failed`, etc.).
-- **Cross-tenant safety.** A move whose source entry belongs to a different tenant is rejected with `cross_tenant_forbidden`. A move whose target namespace belongs to a different tenant is rejected with `target_namespace_not_found` — same code as a missing namespace, deliberately, to avoid telling the caller "this namespace exists but somewhere else" (existence-disclosure guard).
-- **Authz revision bump.** Every successful move bumps the per-tenant AuthzPlan revision, so any cached plan keyed on `(principal, revision)` invalidates immediately.
-- **Footgun guard on batch.** `filter.fromNamespaceId` is required — there is no "move everything I can see" shorthand by design.
-
-`MoveFailureReason.compensation_failed` is the only deterministic-manual-recovery case: the forward write succeeded but the rollback failed. The response includes both error messages so an operator has enough detail to inspect each store directly.
-
-### Strict topology isolation (v0.17.0)
-
-By default a namespace is `shared` — its edges remain visible across the tenant whenever AuthzPlan grants access via any path. The KG layer dedupes nodes globally so edges from different namespaces co-exist on the same node, and `shared` lets that cross-namespace visibility through.
-
-Set a namespace to `strict` and its edges become invisible to any principal who does not hold an explicit grant on it, even when the underlying KG node is reachable through a shared neighbor. KG dedupe at the node stays intact — the strictness is enforced edge-by-edge in the AuthzPlan + graph traversal WHERE, not by splitting nodes.
-
-```bash
-# Flip a namespace to strict.
-curl -X POST "$ENDPOINT/api/admin/namespaces/$NS_ID/isolation" \
-  -H "Authorization: Bearer $ADMIN_API_KEY" \
-  -H "X-Tenant-Id: $TENANT" \
-  -H "Content-Type: application/json" \
-  -d '{"isolation":"strict"}'
-# {"namespace": {... "isolation": "strict"}, "changed": true}
-
-# Flip back to shared.
-curl -X POST "$ENDPOINT/api/admin/namespaces/$NS_ID/isolation" \
-  -H "Authorization: Bearer $ADMIN_API_KEY" \
-  -H "X-Tenant-Id: $TENANT" \
-  -H "Content-Type: application/json" \
-  -d '{"isolation":"shared"}'
-```
-
-Both flips bump the per-tenant AuthzPlan revision so cached plans invalidate on the next request — no manual cache invalidation step. A no-op flip (already in the requested mode) returns `changed: false` and leaves the revision untouched.
-
-What strict guarantees:
-
-- **Edge-level scoping.** SQLiteGraph WHERE clause + Neo4j post-filter drop edges whose `namespace_id` is in `AuthzPlan.forbiddenStrictNamespaceIds`. Legacy NULL-namespace edges (pre-v0.16.1 ingest) keep tenant-root visibility regardless.
-- **Bulk endpoint visibility.** `/api/memory/graph/relationships` filters at the HTTP boundary too. `/api/memory/graph/nodes` keeps only nodes that have at least one visible memoryEntryId, intersects the projection's memoryEntryIds with the visible set, and strips provenance properties (`source`, `sourceUrl`, `sourceTitle`, etc.) so a cross-namespace node cannot leak originating-namespace metadata via property bag.
-- **Hybrid RAG fail-loud.** Graph + community retrieval no longer swallow backend errors. A graph-store outage propagates as `MemorySearchError` so the operator sees it at the request boundary instead of as drifting RRF gaps.
-
-### Idempotent admin mutations (v0.17.0)
-
-The audit-outbox sweeper retries 5xx mutations until each lands. Set `X-Idempotency-Key` on every admin mutation request so a retry on the same key returns the recorded response without re-executing the handler:
-
-```bash
-KEY=$(uuidgen)
-curl -X POST "$ENDPOINT/api/admin/namespaces" \
-  -H "Authorization: Bearer $ADMIN_API_KEY" \
-  -H "X-Tenant-Id: $TENANT" \
-  -H "X-Idempotency-Key: $KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"engineering"}'
-```
-
-24h TTL. GET / OPTIONS bypass the wrapper entirely (read-only methods are already safe to retry). Pre-existing entries are dedupe-keyed by `key` (not by request body), so a sweeper retry with the original payload + key replays the original response even if the underlying state has since changed.
-
-### Why not metadata + post-filter?
-
-The pre-PR-D pattern was "tag entries with `metadata.allowedTeams`, filter results in your gateway". That breaks RAG retrieval:
-
-1. **Ranking pollution** — RRF fusion and reranker interpolation normalize against the candidate set. If forbidden entries enter retrieval, they shift the scoring for the entries the caller IS allowed to see.
-2. **Confidence corruption** — abstention scores depend on score variance over the candidate set. Hidden entries change the variance.
-3. **Write amplification** — changing a role means rewriting metadata on every affected chunk.
-
-ReBAC tuples solve all three: pre-filter at the SQL/vector layer, single-row mutations, no entry rewrites.
-
-### Next-scale: external PDP
-
-When you outgrow the in-process tuple store (~10M tuples, or you need cross-tenant sharing, or distributed enforcement), the tuple format is Zanzibar-compatible — export to OpenFGA or SpiceDB and swap the `AuthzPlan` compute path to call their `ListObjects` API. The retrieval-engine code does not change.