@pyxmate/memory 0.15.3 → 0.17.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, MemoryStats as MemoryStats$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, IngestEvent as IngestEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
+import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, PrincipalContext as PrincipalContext$1, MemoryStats as MemoryStats$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, IngestEvent as IngestEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
 
 /** Parameters for paginated entry listing. */
 interface MemoryListParams {
@@ -12,6 +12,13 @@ interface MemoryListParams {
     agentId?: string;
     /** Filter by tenant ID for multi-tenant isolation. */
     tenantId?: string;
+    /**
+     * Calling principal. When supplied, list applies the AuthzPlan
+     * visibility filter so entries in forbidden namespaces never reach
+     * the response. Single-tenant / library-direct callers may omit it
+     * and get the legacy tenant-only scope.
+     */
+    principal?: PrincipalContext$1;
 }
 /** Result of a paginated entry listing. */
 interface MemoryListResult {
@@ -30,6 +37,14 @@ interface TemporalQueryFilters {
 /** Options for scoping operations to a specific tenant. */
 interface TenantScopeOptions {
     tenantId?: string;
+    /**
+     * Calling principal. When supplied alongside or instead of tenantId,
+     * the operation applies the AuthzPlan visibility filter — get/delete
+     * will treat entries in forbidden namespaces as if they did not exist.
+     * Single-tenant / library-direct callers may omit it and get the
+     * legacy tenant-only scope.
+     */
+    principal?: PrincipalContext$1;
 }
 /** Abstract interface for memory systems (local or remote). */
 interface MemoryInterface {
@@ -337,6 +352,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 +389,31 @@ 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[];
+    /**
+     * AuthzPlan-derived list of strict-mode namespaces in the caller's
+     * tenant the principal CANNOT see (v0.17.0). Graph traversal MUST
+     * drop edges whose `namespace_id` matches the supplied set even when
+     * the surrounding KG node is otherwise reachable. Populated
+     * internally by `Memory.search` from `AuthzPlan.forbiddenStrict
+     * NamespaceIds` — callers should NOT set this directly.
+     */
+    forbiddenStrictNamespaceIds?: string[];
 }
 interface MemorySearchResult {
     entries: MemoryEntry[];
@@ -474,6 +523,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.
@@ -506,6 +557,13 @@ interface GraphRelationship {
     type: string;
     properties: Record<string, unknown>;
     memoryEntryId?: string;
+    /**
+     * Namespace_id provenance carried from the originating MemoryEntry.
+     * `null` (or absent) = legacy / tenant-root bucket. Foundation for the
+     * v0.17.0 strict traversal filter (the AuthzPlan compares this value
+     * edge-by-edge so KG dedupe at the node level can stay intact).
+     */
+    namespaceId?: string | null;
 }
 interface GraphTraversalResult {
     nodes: GraphNode[];
@@ -629,4 +687,156 @@ 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 };
+/**
+ * Namespace topology-isolation modes for v0.17.0.
+ *
+ * `shared` (default, pre-existing posture): a namespace's edges/nodes
+ * remain visible across the tenant whenever AuthzPlan grants access via
+ * any path. The KG layer dedupes nodes globally so edges from different
+ * namespaces can co-exist on the same node — `shared` lets that
+ * cross-namespace visibility through.
+ *
+ * `strict`: edges attributed to this namespace are invisible to any
+ * principal who does not hold an explicit grant on it, even when the
+ * underlying KG node is shared with other namespaces. The strictness is
+ * enforced at traversal time by AuthzPlan.forbiddenStrictNamespaceIds —
+ * the planning layer collects every strict namespace in the tenant the
+ * caller does NOT see, and the graph WHERE filter excludes edges whose
+ * `namespace_id` matches that set. KG dedupe at the node level stays
+ * intact (Codex round 3 architectural guarantee).
+ */
+declare const NamespaceIsolation: {
+    readonly SHARED: "shared";
+    readonly STRICT: "strict";
+};
+type NamespaceIsolation = (typeof NamespaceIsolation)[keyof typeof NamespaceIsolation];
+
+/**
+ * Move-related types for the entry-move admin API (v0.16.1).
+ *
+ * The admin API lets operators reassign existing entries to namespaces —
+ * needed for migrating legacy NULL-namespace data and for periodic
+ * reorganization. v0.16.1 is intra-tenant only; cross-tenant moves stay
+ * forbidden as a contract (see `MoveFailureReason.CROSS_TENANT_FORBIDDEN`).
+ */
+/**
+ * Destination of a move. Used by both single and batch endpoints.
+ *
+ * Wrapping a single field in an interface (rather than a bare
+ * `string | null` alias) leaves room to extend the destination spec
+ * later (e.g., cascade options) without breaking call sites.
+ */
+interface MoveTarget {
+    /**
+     * Target namespace ID. `null` = tenant-root (the legacy
+     * NULL-namespace bucket, visible to anyone with tenant access).
+     * A non-null string opts the entry into AuthzPlan filtering.
+     */
+    namespaceId: string | null;
+}
+/**
+ * Selection criteria for batch move. `fromNamespaceId` is required —
+ * forcing operators to narrow the source explicitly avoids the
+ * "move every entry I can see" footgun.
+ */
+interface MoveEntriesFilter {
+    /** Source namespace. `null` = tenant-root (legacy NULL-namespace bucket). */
+    fromNamespaceId: string | null;
+    /** Restrict to this explicit set of entry IDs (within `fromNamespaceId`). */
+    entryIds?: string[];
+    /** Narrow further within `fromNamespaceId`. */
+    agentId?: string;
+    teamId?: string;
+    userId?: string;
+    source?: string;
+    /** Cap rows per call. Server enforces a hard max. */
+    limit?: number;
+    /** Opaque cursor returned by a prior call. */
+    cursor?: string;
+}
+/**
+ * Why a single-entry move failed. Set on `MoveResult.failureReason`
+ * when `success === false`.
+ */
+declare const MoveFailureReason: {
+    /** Entry not found in the caller's tenant. */
+    readonly NOT_FOUND: "not_found";
+    /** Move would cross tenant boundary (always forbidden). */
+    readonly CROSS_TENANT_FORBIDDEN: "cross_tenant_forbidden";
+    /** Target namespace ID does not exist in the caller's tenant. */
+    readonly TARGET_NAMESPACE_NOT_FOUND: "target_namespace_not_found";
+    /** SQLite metadata update failed; no compensation needed. */
+    readonly SQLITE_UPDATE_FAILED: "sqlite_update_failed";
+    /** Vector store metadata update failed; SQLite reverted. */
+    readonly VECTOR_UPDATE_FAILED: "vector_update_failed";
+    /** Graph edge namespace update failed; SQLite + vector reverted. */
+    readonly GRAPH_UPDATE_FAILED: "graph_update_failed";
+    /** Compensation itself failed — manual intervention required. */
+    readonly COMPENSATION_FAILED: "compensation_failed";
+};
+type MoveFailureReason = (typeof MoveFailureReason)[keyof typeof MoveFailureReason];
+/**
+ * Per-entry result of a move. Batch endpoints return one per input
+ * entry; the single endpoint returns exactly one.
+ */
+interface MoveResult {
+    entryId: string;
+    success: boolean;
+    /** Source namespace before the move. `null` = tenant-root. */
+    fromNamespaceId?: string | null;
+    /** Destination namespace after the move. `null` = tenant-root. */
+    toNamespaceId?: string | null;
+    /** Present when `success === false`. */
+    failureReason?: MoveFailureReason;
+    /** Human-readable detail when `success === false`. */
+    error?: string;
+}
+
+/**
+ * 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 MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, SINGLE_TENANT_ID, SensitivityLevel, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, VectorProvider };

package/dist/index.mjs

@@ -10,6 +10,12 @@ var DEFAULTS = {
   MEMORY_SERVER_PORT: 7822
 };
 
+// ../shared/src/types/isolation.ts
+var NamespaceIsolation = {
+  SHARED: "shared",
+  STRICT: "strict"
+};
+
 // ../shared/src/types/memory.ts
 var MemoryType = {
   SHORT_TERM: "short-term",
@@ -45,13 +51,37 @@ var StoreTarget = {
   VECTOR: "vector",
   GRAPH: "graph"
 };
+
+// ../shared/src/types/move.ts
+var MoveFailureReason = {
+  /** Entry not found in the caller's tenant. */
+  NOT_FOUND: "not_found",
+  /** Move would cross tenant boundary (always forbidden). */
+  CROSS_TENANT_FORBIDDEN: "cross_tenant_forbidden",
+  /** Target namespace ID does not exist in the caller's tenant. */
+  TARGET_NAMESPACE_NOT_FOUND: "target_namespace_not_found",
+  /** SQLite metadata update failed; no compensation needed. */
+  SQLITE_UPDATE_FAILED: "sqlite_update_failed",
+  /** Vector store metadata update failed; SQLite reverted. */
+  VECTOR_UPDATE_FAILED: "vector_update_failed",
+  /** Graph edge namespace update failed; SQLite + vector reverted. */
+  GRAPH_UPDATE_FAILED: "graph_update_failed",
+  /** Compensation itself failed — manual intervention required. */
+  COMPENSATION_FAILED: "compensation_failed"
+};
+
+// ../shared/src/types/principal.ts
+var SINGLE_TENANT_ID = "_single";
 export {
   DEFAULTS,
   EmbeddingProviderName,
   MemoryClient,
   MemoryServerError,
   MemoryType,
+  MoveFailureReason,
+  NamespaceIsolation,
   RAGStrategy,
+  SINGLE_TENANT_ID,
   SensitivityLevel,
   StoreTarget,
   VectorProvider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.15.3",
+  "version": "0.17.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,234 @@ 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
+
+| 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
 
-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:
+```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... }'
 ```
-User/Agent Request
-      ↓
-[Your Application]
-      ↓
-[Access Policy Layer]  ← checks role + scope before forwarding
-      ↓
-[pyx-memory]           ← stores data, unaware of permissions
+
+### 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>"
+  }'
 ```
 
-### Why this is better than building ACL into the memory store
+Reversing later is the same — delete the tuple, visibility flips back the next request.
 
-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.
+### Search-time enforcement
 
-### Implementation approach
+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)
-    );
-  });
-}
+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
+  }'
 ```
 
-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.
+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.

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

@@ -60,6 +60,99 @@ 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.
+
+## Strict Topology Isolation (v0.17.0)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/admin/namespaces/:id/isolation` | Toggle isolation. Body: `{ isolation: 'shared' \| 'strict' }`. Returns `{ namespace, changed }` — `changed: false` means the no-op path (already in the requested mode); revision unchanged. |
+
+Effect of `strict`:
+
+- Graph traversal (`/api/memory/graph/query` and indirect uses inside `/api/memory/search`) drops edges whose `namespace_id` matches `AuthzPlan.forbiddenStrictNamespaceIds`.
+- `/api/memory/graph/nodes` and `/api/memory/graph/relationships` apply the AuthzPlan at the HTTP boundary. Node projection intersects `memoryEntryIds` with the visible set and strips provenance properties (`source`, `sourceUrl`, `sourceTitle`, `sourceUri`, `url`, `title`).
+- Effect propagates immediately — the toggle bumps the per-tenant AuthzPlan revision, so cached plans pick up `forbiddenStrictNamespaceIds` on the next request.
+
+## Idempotent Admin Mutations (v0.17.0)
+
+All `/api/admin/*` mutation routes (POST / DELETE / PUT) honor the `X-Idempotency-Key` request header. A replay with the same key — within the 24h TTL — returns the previously recorded response body + status without re-executing the handler. Set the header from the BFF / sweeper:
+
+```bash
+curl -X POST "$ENDPOINT/api/admin/namespaces" \
+  -H "Authorization: Bearer $ADMIN_API_KEY" \
+  -H "X-Tenant-Id: $TENANT" \
+  -H "X-Idempotency-Key: $(uuidgen)" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"engineering"}'
+```
+
+GET / OPTIONS / HEAD bypass the wrapper entirely (read-only methods are safe to retry). The header is OPTIONAL — callers that don't set it get the legacy fire-and-forget behavior.
+
+## Entry Move Admin (v0.16.1)
+
+Reassign existing entries to a target namespace — the migration path for legacy NULL-namespace data and any later reorganization. Both routes are gated by `ADMIN_API_KEY` and require `X-Tenant-Id`. See [`patterns/access-control.md`](../patterns/access-control.md) Pattern 15 § "Migrating legacy entries" for the workflow.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/admin/entries/:id/move` | Single move (JSON: `{ namespaceId: string \| null }`) |
+| POST | `/api/admin/entries/move-batch` | Batch move with cursor + dryRun (JSON: `{ filter, target, limit?, dryRun? }`) |
+
+**Single response** — `200 OK` with the standard `{ success: true, data: T }` envelope wrapping a `MoveResult`:
+
+```json
+{
+  "success": true,
+  "data": {
+    "entryId": "entry-abc",
+    "success": true,
+    "fromNamespaceId": null,
+    "toNamespaceId": "ns-engineering"
+  }
+}
+```
+
+The inner `success: false` flag carries `failureReason` ∈ `{ not_found, cross_tenant_forbidden, target_namespace_not_found, sqlite_update_failed, vector_update_failed, graph_update_failed, compensation_failed }`. The route never returns 2xx with a failed inner result — instead it maps the failureReason to HTTP status as: `not_found` → 404, `cross_tenant_forbidden` / `target_namespace_not_found` → 400, store failures (`sqlite_update_failed` / `vector_update_failed` / `graph_update_failed`) → 502, `compensation_failed` → 500. The error body uses the project's standard `{ success: false, error: string }` envelope.
+
+**Batch body shape**:
+
+```json
+{
+  "filter": {
+    "fromNamespaceId": "ns-old" | null,
+    "entryIds": ["..."],
+    "agentId": "...", "teamId": "...", "userId": "...", "source": "...",
+    "limit": 100,
+    "cursor": "<opaque>"
+  },
+  "target": { "namespaceId": "ns-new" | null },
+  "dryRun": true,
+  "limit": 100
+}
+```
+
+`filter.fromNamespaceId` is required (footgun guard — there is no "move every entry I can see" form). `target.namespaceId: null` reverts entries to tenant-root. `dryRun: true` returns the prospective `MoveResult[]` without touching any store; `dryRun: false` (default) executes. Response carries `nextCursor` when more rows match — feed it back via `filter.cursor` for the next page.
+
 ## 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.