@pyxmate/memory 0.16.0 → 0.17.1

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 {
@@ -390,6 +405,15 @@ interface MemorySearchParams {
      * 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[];
@@ -533,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[];
@@ -656,6 +687,111 @@ interface IngestErrorEvent {
 }
 type IngestEvent = IngestProgressEvent | IngestHeartbeatEvent | IngestResultEvent | IngestErrorEvent;
 
+/**
+ * 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.
  *
@@ -703,4 +839,4 @@ interface PrincipalContext {
 /** 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 };
+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",
@@ -46,6 +52,24 @@ var StoreTarget = {
   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 {
@@ -54,6 +78,8 @@ export {
   MemoryClient,
   MemoryServerError,
   MemoryType,
+  MoveFailureReason,
+  NamespaceIsolation,
   RAGStrategy,
   SINGLE_TENANT_ID,
   SensitivityLevel,

package/package.json

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

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

@@ -452,8 +452,125 @@ await memory.store({
 });
 ```
 
+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:

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

@@ -24,8 +24,8 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 |--------|----------|-------------|
 | GET | `/health` | Public health check (status only — no internals exposed) |
 | GET | `/admin/health` | Admin health check (version, uptime, embedding provider, memory stats) |
-| POST | `/api/memory/ingest` | Store a memory (JSON: `{ content, type, metadata, agentId?, sessionId?, targets?, entities?, relationships?, importance?, source?, eventTime?, id?, parentId?, ingestTime?, pinned? }`) |
-| POST | `/api/memory/ingest/file` | Upload file (multipart, 100MB limit). For PDFs with images, returns an `enrichment` block with HMAC token and image metadata for two-phase enrichment. |
+| POST | `/api/memory/ingest` | Store a memory (JSON: `{ content, type, metadata, namespaceId?, agentId?, sessionId?, targets?, entities?, relationships?, importance?, source?, eventTime?, id?, parentId?, ingestTime?, pinned? }`) |
+| POST | `/api/memory/ingest/file` | Upload file (multipart, 100MB limit; optional `namespaceId` field or `X-Namespace-Id` header). For PDFs with images, returns an `enrichment` block with HMAC token and image metadata for two-phase enrichment. |
 | GET | `/api/memory/files/download/:filename` | Download uploaded file binary by filename. Returns the original file with proper Content-Type. Images served inline, documents as attachment. |
 | GET | `/api/memory/files/:fileId/images/:imageId?token=...` | Fetch an extracted PDF image (binary). Requires HMAC token from ingest response. |
 | POST | `/api/memory/files/:fileId/enrich` | Submit image descriptions + entities after LLM vision processing. Requires `X-Enrichment-Token` header. |
@@ -82,6 +82,92 @@ Fine-grained access control inside a tenant — namespaces, principals, group me
 
 Cross-tenant safety: every route verifies the referenced resource belongs to the caller's tenant; mismatches return `404` (not `403`) to avoid existence disclosure.
 
+## Namespaced Ingest (v0.17.1)
+
+`POST /api/memory/ingest` accepts `namespaceId` either in the JSON body or the `X-Namespace-Id` header. `POST /api/memory/ingest/file` accepts the same header or a multipart `namespaceId` field. The header is canonical; sending both channels with different values returns `400 namespace_id_conflict`. Sending JSON `namespaceId: null` is invalid; omit the field to keep the legacy NULL namespace bucket.
+
+When a namespace is supplied, the server resolves it once against the caller tenant before storing. Missing or cross-tenant namespaces return `404 namespace_not_found` so callers cannot distinguish "does not exist" from "exists in another tenant".
+
+```bash
+curl -X POST {{ENDPOINT}}/api/memory/ingest \
+  -H "Authorization: Bearer {{API_KEY}}" \
+  -H "X-Tenant-Id: tenant-acme" \
+  -H "X-Namespace-Id: ns-engineering" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"Q4 revenue projections","type":"long-term"}'
+```
+
+## 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:
@@ -90,6 +176,7 @@ Cross-tenant safety: every route verifies the referenced resource belongs to the
 |-------|------|----------|-------------|
 | `file` | File | Yes | The file to ingest (max 100MB) |
 | `description` | string | No | Agent-provided description (e.g., from LLM vision). Used instead of parser output for images. |
+| `namespaceId` | string | No | ReBAC namespace to stamp on every chunk. `X-Namespace-Id` header is preferred when both are present. |
 
 **Supported formats**: `.txt`, `.md`, `.csv`, `.tsv`, `.log`, `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.json`, `.jsonl`, `.html`, `.htm`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`, `.svg`