@pyxmate/memory 0.15.2 → 0.16.0

package/dist/index.d.ts

@@ -337,6 +337,15 @@ interface MemoryEntry {
     userId?: string;
     /** Team/group ID within the tenant. */
     teamId?: string;
+    /**
+     * Namespace ID — the primary protected resource for ReBAC authorization.
+     * `undefined` (NULL on the row) means the entry lives in the legacy
+     * "tenant-root" bucket and is visible to anyone with tenant access (the
+     * pre-ReBAC posture). Setting `namespaceId` opts the entry into AuthzPlan-
+     * based filtering, where visibility is computed from `authz_tuples` for
+     * the calling principal.
+     */
+    namespaceId?: string;
     /**
      * When true, consolidation leaves this entry alone — it is never archived by
      * decay and never merged (nor merged-into) by semantic deduplication. Use for
@@ -365,6 +374,22 @@ interface MemorySearchParams {
     userId?: string;
     /** Team/group ID within the tenant. */
     teamId?: string;
+    /**
+     * AuthzPlan-derived visibility list. Populated internally by `Memory.search`
+     * after computing the plan from the calling principal — callers should
+     * NOT set this directly. Empty array means "no granted namespaces" (only
+     * legacy NULL-namespace entries are visible). `undefined` skips the
+     * filter (single-tenant / pre-ReBAC compat).
+     *
+     * "Search within this specific folder" UX is intentionally NOT supported
+     * via a singular `namespaceId` field for v1 — adding it would force
+     * intersection logic with the visibility list (and confused-deputy risk
+     * if the singular value isn't validated against the plan). Callers that
+     * need it can compute the singleton intersection client-side and pass
+     * `namespaceIds: [chosenNamespace]` after verifying access via the
+     * admin API.
+     */
+    namespaceIds?: string[];
 }
 interface MemorySearchResult {
     entries: MemoryEntry[];
@@ -474,6 +499,8 @@ interface MemoryIngestRequest {
     userId?: string;
     /** Team/group ID within the tenant. */
     teamId?: string;
+    /** Namespace ID — see `MemoryEntry.namespaceId`. */
+    namespaceId?: string;
     /**
      * Exclude this entry from consolidation (decay-archive and semantic dedup).
      * See `MemoryEntry.pinned` for full semantics.
@@ -629,4 +656,51 @@ interface IngestErrorEvent {
 }
 type IngestEvent = IngestProgressEvent | IngestHeartbeatEvent | IngestResultEvent | IngestErrorEvent;
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type EnrichmentCallbacks, type ExtendedMemoryInterface, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, RAGStrategy, SensitivityLevel, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, VectorProvider };
+/**
+ * Caller identity for ReBAC authorization.
+ *
+ * The canonical "subject" in Zanzibar terms — passed alongside requests so the
+ * memory layer can compute an AuthzPlan (visible namespaces + entry overrides)
+ * before any retrieval source fans out.
+ *
+ * Identity comes from authenticated request context (X-Tenant-Id / auth token
+ * claims), never from request bodies or multipart form fields. The legacy
+ * `userId` / `teamId` / `agentId` columns on MemoryEntry remain for audit and
+ * legacy filters but MUST NOT drive authorization decisions — they are
+ * collision-prone aliases (a service principal sharing an ID with a human
+ * user has no protection against confused-deputy attacks).
+ *
+ * Sensitivity / clearance is intentionally NOT on this object. It is a
+ * MAC-style classification, orthogonal to RBAC, and continues to be carried
+ * via the `X-Caller-Access-Level` header → `MemorySearchParams.maxSensitivity`.
+ * Conflating the two couples future changes (e.g. per-namespace classification
+ * rules) to identity propagation.
+ */
+interface PrincipalContext {
+    /**
+     * Hard isolation boundary. Required even in single-tenant deployments —
+     * single-mode passes a stable sentinel (`SINGLE_TENANT_ID`) so authz code
+     * paths look identical regardless of mode.
+     */
+    tenantId: string;
+    /**
+     * Stable subject ID (within the tenant). For humans this is the userId;
+     * for AI runtimes it is the agentId; for system actors it is a service
+     * identifier. Combined with `kind`, forms the Zanzibar subject coordinate
+     * `<kind>:<principalId>`.
+     */
+    principalId: string;
+    /**
+     * Subject namespace. Distinguishes humans from AI agents from internal
+     * services so a userId/agentId/serviceId collision cannot grant
+     * unintended access.
+     *  - `user`: human end user
+     *  - `agent`: AI runtime acting on a user's behalf or autonomously
+     *  - `service`: non-AI internal system (cron, ETL, admin tooling)
+     */
+    kind: 'user' | 'agent' | 'service';
+}
+/** Sentinel tenant ID used in single-tenant deployments. */
+declare const SINGLE_TENANT_ID = "_single";
+
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type EnrichmentCallbacks, type ExtendedMemoryInterface, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type PrincipalContext, RAGStrategy, SINGLE_TENANT_ID, SensitivityLevel, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, VectorProvider };

package/dist/index.mjs

@@ -45,6 +45,9 @@ var StoreTarget = {
   VECTOR: "vector",
   GRAPH: "graph"
 };
+
+// ../shared/src/types/principal.ts
+var SINGLE_TENANT_ID = "_single";
 export {
   DEFAULTS,
   EmbeddingProviderName,
@@ -52,6 +55,7 @@ export {
   MemoryServerError,
   MemoryType,
   RAGStrategy,
+  SINGLE_TENANT_ID,
   SensitivityLevel,
   StoreTarget,
   VectorProvider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/skills/pyx-memory/SKILL.md

@@ -7,14 +7,17 @@ description: >
   files or images, or search for what was discussed before. Also use when
   integrating the pyx-memory SDK into code, working with MemoryClient, or using
   the HTTP API. Covers multi-tenant isolation (tenantId, TENANT_MODE),
+  fine-grained ReBAC (namespaces, principals, authz tuples, AuthzPlan),
   sensitivity classification, encryption at rest, and confidence/abstention.
   Triggers on: 'remember', 'recall', 'store memory', 'search memory',
   'ingest file', 'store this image', 'remember this document',
   'what did we decide', 'pyx-memory', 'memory', 'MemoryClient',
   'integrate memory', 'memory consolidation', 'multi-tenant',
   'tenant isolation', 'sensitivity', 'encryption', 'confidence',
-  'abstention', 'access control', 'RBAC', 'read-only', 'permissions',
-  'agent isolation', 'per-agent memory', 'role-based access'.
+  'abstention', 'access control', 'RBAC', 'ReBAC', 'Zanzibar',
+  'namespace', 'principal', 'authz tuple', 'permission', 'permissions',
+  'role', 'role-based access', 'read-only', 'agent isolation',
+  'per-agent memory'.
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(curl *)
 argument-hint: "[store|search|ingest] <content or query>"
 ---
@@ -126,7 +129,7 @@ For integrating pyx-memory into TypeScript/Bun projects, see the reference docs:
 |---|---|
 | Wire pyx-memory into a consumer project | [patterns/consumer.md](patterns/consumer.md) |
 | Set up embedded memory (full features) | [patterns/embedded.md](patterns/embedded.md) |
-| Multi-tenant, RBAC, sensitivity, encryption | [patterns/access-control.md](patterns/access-control.md) |
+| Multi-tenant, ReBAC (namespaces + tuples), sensitivity, encryption | [patterns/access-control.md](patterns/access-control.md) |
 | SDK quick start, package map, DO/DON'T | [reference/sdk-guide.md](reference/sdk-guide.md) |
 | HTTP API endpoints | [reference/http-api.md](reference/http-api.md) |
 | Type signatures and interfaces | [reference/types.md](reference/types.md) |

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

@@ -9,7 +9,7 @@ Production patterns for restricting who can read and write which memories.
 - [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)
-- [Architecture: Access Policy Layer](#architecture-access-policy-layer)
+- [Pattern 15: Built-in ReBAC](#pattern-15-built-in-rebac-namespaces--tuples--authzplan) ← **start here for fine-grained per-user / per-team access**
 
 ---
 
@@ -22,6 +22,9 @@ Need to isolate agents from each other?
 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)
 
@@ -29,7 +32,7 @@ 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 14 (full production stack) + Pattern 15 (ReBAC)
 ```
 
 ---
@@ -256,7 +259,7 @@ function memoryAccessMiddleware(req: Request, userRole: string): boolean {
 
 ## Pattern 14: Full Production Stack
 
-Combines all patterns for a production multi-tenant deployment with sensitivity, encryption, and role-based access.
+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
 
@@ -331,51 +334,136 @@ function createDashboardClient(tenantId: string, userId: string) {
 
 ---
 
-## Architecture: Access Policy Layer
+## 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
 
-For organizations that need true RBAC (role-based access control) with fine-grained per-entry permissions, the recommended architecture adds a policy layer between your application and pyx-memory:
+| 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
 ```
-User/Agent Request
-      ↓
-[Your Application]
-      ↓
-[Access Policy Layer]  ← checks role + scope before forwarding
-      ↓
-[pyx-memory]           ← stores data, unaware of permissions
+
+### 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... }'
 ```
 
-### Why this is better than building ACL into the memory store
+### Make something public to the whole tenant
 
-1. **Separation of concerns** — memory stays fast and simple (store/retrieve). Access logic lives in your application where business rules belong.
-2. **Flexibility** — you can change access rules without migrating data or changing the memory schema.
-3. **Auditability** — policy decisions are logged at the application layer, not buried in storage internals.
+```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"}'
 
-### Implementation approach
+# 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
-// Define scopes as metadata on memory entries
 await memory.store({
   content: 'Q4 revenue projections',
   type: 'long-term',
-  metadata: {
-    scope: 'finance:confidential',       // your custom scope tag
-    allowedTeams: ['finance', 'exec'],   // who can read
-    allowedRoles: ['analyst', 'admin'],  // which roles
-  },
+  metadata: {},
+  namespaceId: '<NS_ID>',
 });
-
-// In your API gateway, filter results based on caller identity
-function filterByAccess(entries: MemoryEntry[], caller: CallerIdentity): MemoryEntry[] {
-  return entries.filter(entry => {
-    const meta = entry.metadata;
-    if (!meta.allowedTeams) return true; // no restriction = public
-    return (
-      meta.allowedTeams.includes(caller.teamId) ||
-      meta.allowedRoles.includes(caller.role)
-    );
-  });
-}
 ```
 
-This approach is not built into pyx-memory because access policies are inherently application-specific. The memory store provides the building blocks (tenant isolation, sensitivity classification, metadata storage) — your application composes them into the access model that fits your organization.
+No bulk migration is required — legacy data keeps working unchanged.
+
+### 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.

package/skills/pyx-memory/reference/http-api.md

@@ -60,6 +60,28 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 | GET | `/api/memory/query-as-of?asOf=...` | Bi-temporal point-in-time query (asOf, type, agentId, source, limit) |
 | GET | `/api/memory/query-by-event-time?startTime=...&endTime=...` | Bi-temporal event time range query (startTime, endTime, type, agentId, source, limit) |
 
+## ReBAC Admin (11 endpoints)
+
+Fine-grained access control inside a tenant — namespaces, principals, group membership, and authz tuples. All routes require `ADMIN_API_KEY` and an `X-Tenant-Id` header. See [`patterns/access-control.md`](../patterns/access-control.md) Pattern 15 for the full guide.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/admin/namespaces` | Create namespace (JSON: `{ name, parentId?, metadata?, createdBy? }`) |
+| GET | `/api/admin/namespaces` | List namespaces in this tenant |
+| DELETE | `/api/admin/namespaces/:id` | Delete namespace + tuples referencing it (RESTRICT on children) |
+| POST | `/api/admin/principals` | Upsert principal (JSON: `{ kind, externalId?, displayName?, metadata? }`) |
+| GET | `/api/admin/principals` | List principals in this tenant |
+| DELETE | `/api/admin/principals/:id` | Delete principal + cascade memberships |
+| POST | `/api/admin/principal-members` | Add member to group (JSON: `{ groupId, memberId }`) — cycle-checked |
+| DELETE | `/api/admin/principal-members/:groupId/:memberId` | Remove membership |
+| POST | `/api/admin/authz-tuples` | Write tuple (JSON: `{ subjectKind, subjectId, subjectRelation?, relation, objectKind, objectId, createdBy? }`) |
+| GET | `/api/admin/authz-tuples?objectId=&subjectId=` | List tuples (filterable) |
+| DELETE | `/api/admin/authz-tuples` | Delete tuple (JSON: same body shape as POST) |
+
+`kind`: `'user' | 'team' | 'group' | 'agent' | 'service' | 'everyone'`. `objectKind` is `'namespace'` only in v1. `relation` is freeform (built-in rewrite: `owner ⊇ editor ⊇ viewer`).
+
+Cross-tenant safety: every route verifies the referenced resource belongs to the caller's tenant; mismatches return `404` (not `403`) to avoid existence disclosure.
+
 ## File Ingestion (Images + Documents)
 
 `POST /api/memory/ingest/file` accepts multipart/form-data with:

package/skills/pyx-memory/reference/types.md

@@ -185,9 +185,10 @@ interface MemoryEntry {
   source?: string;             // filename, URL, session ID
   eventTime?: string;          // when event happened (bi-temporal)
   ingestTime?: string;         // when stored (bi-temporal)
-  tenantId?: string;           // multi-tenant isolation
-  userId?: string;             // user within tenant
-  teamId?: string;             // team/group within tenant
+  tenantId?: string;           // multi-tenant isolation (hard boundary)
+  userId?: string;             // user within tenant (legacy soft-scope)
+  teamId?: string;             // team/group within tenant (legacy soft-scope)
+  namespaceId?: string;        // ReBAC resource coordinate; NULL = legacy tenant-root bucket
   sensitivity?: SensitivityLevel; // auto-classified: 'public' | 'internal' | 'secret'
   encrypted?: boolean;         // true when content is encrypted at rest
   pinned?: boolean;            // exempt from consolidation (decay-archive + dedup-merge); use for stable anchors referenced by external systems
@@ -209,6 +210,11 @@ interface MemorySearchParams {
   tenantId?: string;            // multi-tenant scoping
   userId?: string;              // user-level scoping
   teamId?: string;              // team-level scoping
+  /** Calling principal — drives ReBAC AuthzPlan. Search applies it as a
+   * native pre-filter on SQLite/FTS, vector, and graph layers; forbidden
+   * entries never enter RRF / reranker / abstention. Optional. */
+  principal?: PrincipalContext;
+  namespaceIds?: string[];      // populated internally from AuthzPlan — do not set directly
   maxSensitivity?: SensitivityLevel; // filter by max sensitivity level
   abstentionThreshold?: number; // 0-1, below this confidence → shouldAbstain=true (default: 0.3)
 }
@@ -223,6 +229,66 @@ interface SearchFilters {
 }
 ```
 
+## PrincipalContext + ReBAC Types (v0.16.0+)
+
+The calling identity used to compute search-time AuthzPlan. Comes from
+authenticated request context (`X-Tenant-Id` + `X-User-Id` / `X-Agent-Id`),
+NEVER from request bodies.
+
+```typescript
+interface PrincipalContext {
+  tenantId: string;            // hard boundary; SINGLE_TENANT_ID sentinel in single mode
+  principalId: string;         // userId | agentId | service identifier
+  kind: 'user' | 'agent' | 'service';
+}
+
+interface Namespace {
+  id: string;
+  tenantId: string;
+  name: string;
+  parentId?: string;           // adjacency tree, max-depth 8
+  createdAt: string;
+  createdBy?: string;
+  metadata: Record<string, unknown>;
+}
+
+interface Principal {
+  id: string;
+  tenantId: string;
+  kind: 'user' | 'team' | 'group' | 'agent' | 'service' | 'everyone';
+  externalId?: string;         // maps to userId / agentId / teamId on entries
+  displayName?: string;
+  createdAt: string;
+  metadata: Record<string, unknown>;
+}
+
+interface AuthzTuple {
+  tenantId: string;
+  subjectKind: PrincipalKind;
+  subjectId: string;
+  subjectRelation?: string;    // for usersets like "members of team-eng"
+  relation: 'viewer' | 'editor' | 'owner' | string;
+  objectKind: 'namespace';     // v1 only supports namespace-level grants
+  objectId: string;
+  createdAt: string;
+  createdBy?: string;
+}
+
+interface AuthzPlan {
+  tenantId: string;
+  visibleNamespaceIds: string[];   // resolved + transitively expanded
+  visibleEntryOverrides: string[]; // reserved for v1.1
+  revision: string;                // bumps on every tuple/principal/membership mutation
+}
+```
+
+Built-in relation rewrite: `owner ⊇ editor ⊇ viewer`. Adding new relations
+is a code change, not a schema migration.
+
+In-process API: `Memory.authz` exposes `AuthzStore` with `createNamespace`,
+`upsertPrincipal`, `addMember`, `writeTuple`, `deleteTuple`, `buildAuthzPlan`
+etc. Sidecar / HTTP API: see [`http-api.md`](./http-api.md) §ReBAC Admin.
+
 ## MemoryOptions Reference
 
 > **Embedding is internal** — pyx-memory uses `LocalEmbeddingProvider` with BGE-M3 (1024d) automatically. You do NOT pass an `embedder` option.