@remnic/core 9.7.15 → 9.8.0

package/src/access-service.ts

@@ -1,11 +1,17 @@
 import { stat } from "node:fs/promises";
+import { buildAccessWriteRequestFingerprint, buildObserveRequestFingerprint } from "./write-envelope.js";
 import * as nodeFs from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import { readdirSync, unlinkSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { ZodError } from "zod";
 import { AccessIdempotencyStore, hashAccessIdempotencyPayload } from "./access-idempotency.js";
-import { throwIfAborted } from "./abort-error.js";
+import {
+  recordCitationUsage as recordCitationUsageForAccess,
+  type CitationUsageRequest,
+  type CitationUsageResult,
+} from "./access-citation.js";
+import { coordinateRecall, type RecallCoordinatorHost, type RecallExecResult } from "./access-recall-concurrency.js";
 import { resolveNamespaceCapabilities,
   resolveMemoryLifecycleCapabilities,
   resolveQmdCapabilities,
@@ -78,8 +84,14 @@ import {
   type ExplicitCaptureInput,
   type ValidExplicitCapture,
 } from "./explicit-capture.js";
-import { CrossNamespaceBudget, type BudgetDecision } from "./cross-namespace-budget.js";
+import { CrossNamespaceBudget, type BudgetWarning } from "./cross-namespace-budget.js";
 import { log } from "./logger.js";
+import {
+  defaultNamespaceAtFlatRoot,
+  mergeMemorySearchDefaultFallback,
+  resolveMemorySearchDefaultFallback,
+  runMemorySearchFanout,
+} from "./access-memory-search-fanout.js";
 import {
   buildQualityScore,
   buildProposedActions,
@@ -106,7 +118,7 @@ import {
   toMemoryPathRel,
 } from "./memory-lifecycle-ledger-utils.js";
 import { getMemoryProjectionPath } from "./memory-projection-store.js";
-import { canReadNamespace, canWriteNamespace, defaultNamespaceForPrincipal, recallNamespacesForPrincipal, resolvePrincipal } from "./namespaces/principal.js";
+import { canReadNamespace, canWriteNamespace, citationAuthorizedNamespaces, defaultNamespaceForPrincipal, recallNamespacesForPrincipal, resolvePrincipal } from "./namespaces/principal.js";
 import {
   expandScopeProfileReadNamespaces,
   resolveScopeProfilePlan,
@@ -153,6 +165,7 @@ import {
   type GraphSnapshotNodeMetadata,
 } from "./graph-snapshot.js";
 import * as nodePath from "node:path";
+import { ALL_CATEGORY_DIRS } from "./utils/category-dir.js";
 import {
   buildBriefing,
   FileCalendarSource,
@@ -243,6 +256,7 @@ import {
   type OfflineSyncFileState,
   type OfflineSyncSnapshot,
 } from "./offline-sync.js";
+import { offlineSyncStorageForSnapshot } from "./offline-sync-impression-drain.js";
 import {
   evaluateActionConfidence,
   type ActionConfidenceInput,
@@ -258,7 +272,10 @@ import { AccessRecallSurface } from "./access-recall-surface.js";
 import { AccessIdentityContinuitySurface } from "./access-identity-continuity-surface.js";
 import { selfDeps } from "./orchestration/self-deps.js";
 
-export class EngramAccessInputError extends Error {}
+import { EngramAccessInputError, NamespaceNotWritableError } from "./access-errors.js";
+// Re-exported so existing `import { … } from "./access-service.js"` callers keep
+// working after these classes moved to ./access-errors (issue #1888).
+export { EngramAccessInputError, NamespaceNotWritableError } from "./access-errors.js";
 
 function qmdCollectionPathParts(resultPath: string): {
   collection: string;
@@ -391,6 +408,10 @@ export interface EngramAccessQmdHealthResponse {
   upgradeAvailable: boolean | null;
   doctorAvailable: boolean | null;
   debugStatus: string;
+  pendingEmbeddings: number | null;
+  oldestPendingAgeMs: number | null;
+  embeddingBacklogThreshold: number;
+  degradedReason?: string;
 }
 
 export interface EngramAccessRecallRequest {
@@ -403,6 +424,14 @@ export interface EngramAccessRecallRequest {
   mode?: RecallPlanMode | "auto";
   includeDebug?: boolean;
   abortSignal?: AbortSignal;
+  /**
+   * Internal, server-set field (issue #1906): wall-clock ms the caller
+   * waited for a per-principal recall slot / single-flight leader before
+   * execution. Set by `recall()`, forwarded into `RecallInvocationOptions`,
+   * and folded additively into recall-timings. Not part of the zod schema
+   * (same pattern as `abortSignal`).
+   */
+  queueWaitMs?: number;
   /**
    * Recall disclosure depth. Omitting it preserves the `"chunk"` default.
    * Other accepted values are `"section"` and `"raw"`.
@@ -507,7 +536,7 @@ export interface EngramAccessRecallResponse {
   disclosure: RecallDisclosure;
   budgetsApplied?: LastRecallSnapshot["budgetsApplied"];
   auditAnomalies?: AnomalyDetectorResult;
-  budgetWarning?: BudgetDecision;
+  budgetWarning?: BudgetWarning;
   latencyMs?: number;
   debug?: {
     snapshot?: LastRecallSnapshot;
@@ -1305,7 +1334,8 @@ export function shapeMemorySummary(
 export class EngramAccessService {
   private readonly idempotency: AccessIdempotencyStore;
   private readonly idempotencyLocks = new Map<string, Promise<void>>();
-  private readonly budgetLocks = new Map<string, Promise<void>>();
+  private readonly recallSemaphores = new Map<string, unknown>();
+  private readonly recallInFlight = new Map<string, unknown>();
   private readonly budget: CrossNamespaceBudget;
   private readonly auditAdapter: AccessAuditAdapter | null;
 
@@ -1459,10 +1489,12 @@ export class EngramAccessService {
       this.orchestrator.config,
     );
     if (!result.ok) {
-      throw new EngramAccessInputError(
-        result.reason === "unsupported"
-          ? `unsupported namespace: ${result.namespace}`
-          : `namespace is not writable: ${result.namespace}`,
+      if (result.reason === "unsupported") {
+        throw new EngramAccessInputError(`unsupported namespace: ${result.namespace}`);
+      }
+      throw new NamespaceNotWritableError(
+        result.namespace,
+        this.resolveRequestPrincipal(sessionKey, authenticatedPrincipal),
       );
     }
     return result.namespace;
@@ -1588,9 +1620,8 @@ export class EngramAccessService {
         profilePlan.writeNamespace.length > 0 &&
         profilePlan.readNamespaces.includes(profilePlan.writeNamespace);
       if (!selectedLayer?.writable || !writeNamespaceReadable) {
-        throw new EngramAccessInputError(
-          `scope profile ${profilePlan.profileId} has no writable layer inside the profile read stack for principal ${principal ?? "anonymous"}`,
-        );
+        throw new NamespaceNotWritableError(profilePlan.writeNamespace, principal,
+          `scope profile ${profilePlan.profileId} has no writable layer for principal ${principal ?? "anonymous"}`);
       }
       return profilePlan.writeNamespace;
     }
@@ -1609,7 +1640,7 @@ export class EngramAccessService {
     // no separate write policy.
     const base = defaultNamespaceForPrincipal(principal, this.orchestrator.config);
     if (!canWriteNamespace(principal, base, this.orchestrator.config)) {
-      throw new EngramAccessInputError(`namespace is not writable: ${base}`);
+      throw new NamespaceNotWritableError(base, principal);
     }
     return combineNamespaces(base, overlay.namespace);
   }
@@ -1820,9 +1851,8 @@ export class EngramAccessService {
         profilePlan.readNamespaces.includes(profilePlan.writeNamespace);
       if (!selectedLayer?.writable || !writeNamespaceReadable) {
         clearSeededContext();
-        throw new EngramAccessInputError(
-          `scope profile ${profilePlan.profileId} has no writable layer inside the profile read stack for principal ${principal ?? "anonymous"}`,
-        );
+        throw new NamespaceNotWritableError(profilePlan.writeNamespace, principal,
+          `scope profile ${profilePlan.profileId} has no writable layer for principal ${principal ?? "anonymous"}`);
       }
       const legacyRecallNamespaces = Array.isArray(this.orchestrator.config.defaultRecallNamespaces)
         ? recallNamespacesForPrincipal(principal, this.orchestrator.config)
@@ -1896,9 +1926,7 @@ export class EngramAccessService {
         !canWriteNamespace(principal, baseNamespace, this.orchestrator.config)
       ) {
         clearSeededContext();
-        throw new EngramAccessInputError(
-          `namespace is not writable: ${baseNamespace}`,
-        );
+        throw new NamespaceNotWritableError(baseNamespace, principal);
       }
       return {
         principal,
@@ -1925,9 +1953,7 @@ export class EngramAccessService {
     // it, so it needs no separate write policy — rule 42 / 47 / 48).
     if (!canWriteNamespace(principal, baseNamespace, this.orchestrator.config)) {
       clearSeededContext();
-      throw new EngramAccessInputError(
-        `namespace is not writable: ${baseNamespace}`,
-      );
+      throw new NamespaceNotWritableError(baseNamespace, principal);
     }
     const writeNamespace = overlaidBase;
     const readNamespaces = [writeNamespace];
@@ -2010,7 +2036,10 @@ export class EngramAccessService {
     return resolved;
   }
 
-  private resolveReadableNamespacesForSearch(namespace: string | undefined, principal?: string): string[] {
+  private async resolveReadableNamespacesForSearch(
+    namespace: string | undefined,
+    principal?: string,
+  ): Promise<string[]> {
     const requested = namespace?.trim();
     if (requested) {
       return [this.resolveReadableNamespace(requested, principal)];
@@ -2036,18 +2065,32 @@ export class EngramAccessService {
       codingContext: null,
       codingOverlay: null,
     });
-    const namespaces = profilePlan
-      ? expandScopeProfileReadNamespaces({
-          profilePlan,
-          principalSelfNamespace: profilePlan.baseNamespace,
-          config: this.orchestrator.config,
-          principal,
-          codingOverlay: null,
-          legacyRecallNamespaces,
-        })
-      : legacyRecallNamespaces;
-    if (profilePlan) return namespaces;
-    return namespaces.filter((ns) =>
+    if (profilePlan) {
+      // Issue #2018: memory_search has no sessionKey, so unlike recall it
+      // cannot resolve a coding overlay. Reach the base collection (default
+      // namespace) only when the profile intends a global layer and the
+      // principal is authorized — see access-memory-search-fanout.ts. The
+      // flat-root storage probe runs lazily HERE (after auth, no explicit
+      // namespace, profile active) so explicit-namespace queries and auth
+      // rejections never touch the default store (#2056 r5).
+      const profileNamespaces = expandScopeProfileReadNamespaces({
+        profilePlan,
+        principalSelfNamespace: profilePlan.baseNamespace,
+        config: this.orchestrator.config,
+        principal,
+        codingOverlay: null,
+        legacyRecallNamespaces,
+      });
+      const fallback = await resolveMemorySearchDefaultFallback({
+        profilePlan,
+        config: this.orchestrator.config,
+        principal,
+        defaultAtFlatRootProvider: () =>
+          defaultNamespaceAtFlatRoot((n) => this.orchestrator.getStorage(n), this.orchestrator.config),
+      });
+      return mergeMemorySearchDefaultFallback(profileNamespaces, fallback);
+    }
+    return legacyRecallNamespaces.filter((ns) =>
       canReadNamespace(principal, ns, this.orchestrator.config),
     );
   }
@@ -2215,7 +2258,7 @@ export class EngramAccessService {
     memoryPath: string,
     primaryNamespace: string,
     recallNamespaces: readonly string[] = [],
-  ): Promise<{ storage: StorageManager; dir: string } | null> {
+  ): Promise<{ storage: StorageManager; dir: string; namespace: string } | null> {
     const resolvedPath = nodePath.resolve(memoryPath);
     const memoryRoot = nodePath.resolve(this.orchestrator.config.memoryDir);
     const namespacesRoot = nodePath.join(memoryRoot, "namespaces");
@@ -2226,20 +2269,15 @@ export class EngramAccessService {
     }
     configuredNamespaces.add(this.orchestrator.config.defaultNamespace);
     configuredNamespaces.add(this.orchestrator.config.sharedNamespace);
+    // Legacy snapshots persist an absolute resultPath with no per-result namespace;
+    // derive the on-disk owner (decoded) so those paths still resolve (#2020).
     if (isPathInsideStorageRoot(namespacesRoot, resolvedPath)) {
-      const relativeToNamespaces = nodePath.relative(namespacesRoot, resolvedPath);
-      const [namespaceSegment] = relativeToNamespaces.split(/[\\/]/);
-      if (namespaceSegment) {
-        configuredNamespaces.add(
-          namespaceIdentityFromToken(namespaceSegment) ?? namespaceSegment,
-        );
-      }
-    }
-    for (const policy of this.orchestrator.config.namespacePolicies ?? []) {
-      configuredNamespaces.add(policy.name);
+      const [seg] = nodePath.relative(namespacesRoot, resolvedPath).split(/[\\/]/);
+      if (seg) configuredNamespaces.add(namespaceIdentityFromToken(seg) ?? seg);
     }
+    for (const policy of this.orchestrator.config.namespacePolicies ?? []) configuredNamespaces.add(policy.name);
 
-    const matches: Array<{ storage: StorageManager; dir: string }> = [];
+    const matches: Array<{ storage: StorageManager; dir: string; namespace: string }> = [];
     for (const ns of configuredNamespaces) {
       if (!ns) continue;
       let candidateStorage: StorageManager;
@@ -2256,7 +2294,7 @@ export class EngramAccessService {
       ) {
         continue;
       }
-      matches.push({ storage: candidateStorage, dir: candidateRoot });
+      matches.push({ storage: candidateStorage, dir: candidateRoot, namespace: ns });
     }
 
     matches.sort((a, b) => b.dir.length - a.dir.length);
@@ -2420,27 +2458,6 @@ export class EngramAccessService {
     }
   }
 
-  private async withBudgetLock<T>(principal: string, abortSignal: AbortSignal | undefined, fn: () => Promise<T>): Promise<T> {
-    const key = principal || "__anonymous__";
-    const previous = this.budgetLocks.get(key) ?? Promise.resolve();
-    let release!: () => void;
-    const current = new Promise<void>((resolve) => {
-      release = resolve;
-    });
-    const queued = previous.then(() => current, () => current);
-    this.budgetLocks.set(key, queued);
-    await previous.catch(() => {});
-    try {
-      throwIfAborted(abortSignal);
-      return await fn();
-    } finally {
-      release();
-      if (this.budgetLocks.get(key) === queued) {
-        this.budgetLocks.delete(key);
-      }
-    }
-  }
-
   async health(namespace?: string): Promise<EngramAccessHealthResponse> {
     const resolvedNamespace = this.resolveNamespace(namespace);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
@@ -2743,38 +2760,23 @@ export class EngramAccessService {
         "authentication required: namespaces are enabled and no principal was supplied",
       );
     }
-    return this.withBudgetLock(principal ?? "default", request.abortSignal, async () => {
-      let budgetRecordPrincipal: string | null = null;
-      const response = await this.handleIdempotentRead({
-        operation: "recall",
-        idempotencyKey: request.idempotencyKey,
-        requestFingerprint,
-        execute: async () => {
-          const result = await this.executeRecall(normalizedRequest);
-          throwIfAborted(request.abortSignal);
-          budgetRecordPrincipal = result.budgetRecordPrincipal;
-          return result.response;
-        },
-        afterStore: () => {
-          if (!budgetRecordPrincipal) return;
-          const recordedBudgetDecision = this.budget.record(budgetRecordPrincipal);
-          if (!recordedBudgetDecision.allowed) {
-            throw new EngramAccessInputError(
-              `recall denied: cross-namespace budget exceeded (${recordedBudgetDecision.count}/${recordedBudgetDecision.limit.hardLimit} in ${recordedBudgetDecision.limit.windowMs}ms window)`,
-            );
-          }
-        },
-      });
-      return response;
-    });
+    const principalKey = principal ?? "default";
+    // Single-flight gate resolved through the shared access-setup capability
+    // projection so the config flag is read only in capabilities.ts (#1523).
+    const singleFlight = resolveAccessSetupCapabilities(this.orchestrator.config).recallSingleFlight;
+    return coordinateRecall(
+      this as unknown as RecallCoordinatorHost,
+      request,
+      normalizedRequest,
+      requestFingerprint,
+      principalKey,
+      singleFlight,
+    );
   }
 
   private async executeRecall(
     request: EngramAccessRecallRequest,
-  ): Promise<{
-    response: EngramAccessRecallResponse;
-    budgetRecordPrincipal: string | null;
-  }> {
+  ): Promise<RecallExecResult> {
     return this.accessRecallSurface.executeRecall(
       request,
     );
@@ -2947,18 +2949,20 @@ export class EngramAccessService {
     return this.peekIdempotentWrite({
       operation: "memory_store",
       idempotencyKey: request.idempotencyKey,
-      requestFingerprint: {
+      // Shared builder (issue #1989 PR3): byte-parity with the historical
+      // inline literal is asserted by access-fingerprint-parity.test.ts.
+      requestFingerprint: buildAccessWriteRequestFingerprint({
         schemaVersion,
+        namespace,
         content: request.content,
         category: request.category,
         confidence: request.confidence,
-        namespace,
         tags: request.tags,
         entityRef: request.entityRef,
         ttl: request.ttl,
         sourceReason: request.sourceReason,
         sourceConnector: request.sourceConnector,
-      },
+      }),
       skip: request.dryRun === true,
     });
   }
@@ -2984,18 +2988,20 @@ export class EngramAccessService {
     return this.peekIdempotentWrite({
       operation: "suggestion_submit",
       idempotencyKey: request.idempotencyKey,
-      requestFingerprint: {
+      // Shared builder (issue #1989 PR3): byte-parity with the historical
+      // inline literal is asserted by access-fingerprint-parity.test.ts.
+      requestFingerprint: buildAccessWriteRequestFingerprint({
         schemaVersion,
+        namespace,
         content: request.content,
         category: request.category,
         confidence: request.confidence,
-        namespace,
         tags: request.tags,
         entityRef: request.entityRef,
         ttl: request.ttl,
         sourceReason: request.sourceReason,
         sourceConnector: request.sourceConnector,
-      },
+      }),
       skip: request.dryRun === true,
     });
   }
@@ -3287,7 +3293,6 @@ export class EngramAccessService {
     return isCorrectionFeatureEnabled(this.orchestrator.config);
   }
 
-
   private _correctionService: CorrectionService | null = null;
 
   /** Lazily construct + cache the CorrectionService with deps wired from the orchestrator. */
@@ -4050,7 +4055,9 @@ export class EngramAccessService {
     return this.handleIdempotentWrite<EngramAccessObserveResponse>({
       operation: "observe",
       idempotencyKey: request.idempotencyKey,
-      requestFingerprint: {
+      // Shared builder (issue #1989 PR3): byte-parity with the historical
+      // inline literal is asserted by access-fingerprint-parity.test.ts.
+      requestFingerprint: buildObserveRequestFingerprint({
         sessionKey: request.sessionKey,
         messages: request.messages,
         namespace: request.namespace,
@@ -4060,7 +4067,7 @@ export class EngramAccessService {
         projectTag: request.projectTag,
         effectiveCodingContext: effectiveCodingContext ?? null,
         sourceConnector: request.sourceConnector,
-      },
+      }),
       beforeExecute: hooks?.enforceWriteQuota,
       execute: () => this.runObserve(request),
     });
@@ -4736,8 +4743,6 @@ export class EngramAccessService {
       expectedGuidelineVersion: request.expectedGuidelineVersion,
     });
   }
-
-
   // ── Memory search & debug ─────────────────────────────────────────────
 
   async memorySearch(request: {
@@ -4760,20 +4765,21 @@ export class EngramAccessService {
         ? await this.orchestrator.qmd.searchGlobal(query, maxResults)
         : await this.orchestrator.qmd.search(query, collection, maxResults);
     } else {
-      const readableNamespaces = this.resolveReadableNamespacesForSearch(namespace, principal);
+      const readableNamespaces = await this.resolveReadableNamespacesForSearch(namespace, principal);
       const namespaces = this.resolveMemorySearchNamespacesForCollection(
         collection,
         readableNamespaces,
         namespace?.trim() ? undefined : principal,
       );
-      results = namespaces.length === 0
-        ? []
-        : await this.orchestrator.searchAcrossNamespaces({
-            query,
-            namespaces,
-            maxResults,
-            mode: "search",
-          });
+      results = await runMemorySearchFanout({
+        query,
+        namespaces,
+        maxResults,
+        principal,
+        requestedNamespace: namespace,
+        collection,
+        search: (params) => this.orchestrator.searchAcrossNamespaces(params),
+      });
     }
 
     return {
@@ -4994,61 +5000,62 @@ export class EngramAccessService {
     };
   }
 
-  /**
-   * Record citation usage from an observed oai-mem-citation block.
-   * For each citation entry, extract the memory ID from the path and
-   * increment its access tracking via the orchestrator. Returns the
-   * count of submitted IDs and the count of IDs that matched real memories.
-   */
-  async recordCitationUsage(request: {
-    sessionId?: string;
-    namespace?: string;
-    authenticatedPrincipal?: string;
-    entries: Array<{ path: string; lineStart: number; lineEnd: number; note: string }>;
-    rolloutIds: string[];
-  }): Promise<{ submitted: number; matched: number }> {
-    if (request.entries.length === 0) return { submitted: 0, matched: 0 };
-
-    // Enforce namespace ACLs — citation tracking is a write-like operation.
-    // Pass authenticatedPrincipal so the principal resolution matches other
-    // write endpoints (gotcha #42: read and write paths must resolve through
-    // the same namespace layer).
-    const resolvedNamespace = this.writableNamespaceFor(
-      request.namespace,
-      request.sessionId,
-      request.authenticatedPrincipal,
+  async recordCitationUsage(
+    request: CitationUsageRequest,
+  ): Promise<CitationUsageResult> {
+    return recordCitationUsageForAccess(
+      {
+        resolveNamespace: (namespace, sessionId, authenticatedPrincipal) =>
+          this.writableNamespaceFor(namespace, sessionId, authenticatedPrincipal),
+        resolveNamespaceForPath: async (
+          memoryPath,
+          fallbackNamespace,
+          sessionId,
+          authenticatedPrincipal,
+        ) => {
+          const principal = this.resolveRequestPrincipal(sessionId, authenticatedPrincipal);
+          const namespacesEnabled = resolveNamespaceCapabilities(this.orchestrator.config).namespaces;
+          if (
+            namespacesEnabled &&
+            !canReadNamespace(principal, fallbackNamespace, this.orchestrator.config)
+          ) {
+            throw new EngramAccessInputError(
+              `namespace is not readable: ${fallbackNamespace}`,
+            );
+          }
+          const authorizedNamespaces = namespacesEnabled
+            ? Array.from(
+                new Set([...citationAuthorizedNamespaces(principal, this.orchestrator.config), fallbackNamespace]),
+              )
+            : [fallbackNamespace];
+          const resolved = await this.storageForAbsoluteRecallPath(
+            memoryPath,
+            fallbackNamespace,
+            authorizedNamespaces,
+          );
+          if (!resolved) {
+            if (nodePath.isAbsolute(memoryPath)) {
+              throw new EngramAccessInputError("cited path is outside the caller's readable namespaces");
+            }
+            // Attribute to the longest authorized namespace that prefixes the cited
+            // path (namespace names may contain "/"); a bare category lead like a
+            // default `facts/a.md` is not a namespace (#2020).
+            let nsMatch = "";
+            for (const ns of authorizedNamespaces) {
+              if (!ns || ALL_CATEGORY_DIRS.includes(ns)) continue;
+              if ((memoryPath === ns || memoryPath.startsWith(`${ns}/`)) && ns.length > nsMatch.length) nsMatch = ns;
+            }
+            if (nsMatch) return nsMatch;
+            return fallbackNamespace;
+          }
+          return resolved.namespace;
+        },
+        getStorage: (namespace) => this.orchestrator.getStorage(namespace),
+        trackMemoryAccess: (memoryIds, memoryPaths, memoryNamespaces) =>
+          this.orchestrator.trackMemoryAccess(memoryIds, memoryPaths, memoryNamespaces),
+      },
+      request,
     );
-
-    // Extract memory IDs from citation paths. The path in citations
-    // follows the pattern `facts/<id>.md` or just `<id>.md`.
-    const memoryIds: string[] = [];
-    for (const entry of request.entries) {
-      // Strip directory prefix and .md extension to derive the memory ID.
-      const basename = entry.path.split("/").pop() ?? entry.path;
-      const id = basename.endsWith(".md") ? basename.slice(0, -3) : basename;
-      if (id.length > 0) {
-        memoryIds.push(id);
-      }
-    }
-
-    if (memoryIds.length === 0) return { submitted: 0, matched: 0 };
-
-    // Determine which IDs correspond to real memories in storage using a
-    // targeted file-existence scan instead of loading all memories (Finding #2).
-    const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const existingIds = await storage.filterExistingMemoryIds(memoryIds);
-    const matchedIds = memoryIds.filter((id) => existingIds.has(id));
-
-    if (matchedIds.length > 0) {
-      try {
-        this.orchestrator.trackMemoryAccess(matchedIds);
-      } catch {
-        // Fail gracefully — citation usage tracking is best-effort.
-        log.debug("citation usage tracking: failed to record access for cited memories");
-      }
-    }
-
-    return { submitted: memoryIds.length, matched: matchedIds.length };
   }
 
   // ── Operator Console state (issue #688 PR 2/3) ────────────────────────────
@@ -5502,7 +5509,7 @@ export class EngramAccessService {
     options: EngramAccessOfflineSyncSnapshotRequest & { signal?: AbortSignal } = {},
   ): Promise<EngramAccessOfflineSyncSnapshotResponse> {
     const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
-    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const storage = await offlineSyncStorageForSnapshot(this.orchestrator, resolvedNamespace);
     const storageHash = createHash("sha256").update(storage.dir).digest("hex").slice(0, 16);
     const snapshotBuilder = options.includeContent === false && options.baseFiles && options.baseFiles.length > 0
       ? buildOfflineSyncSnapshotFromBase
@@ -5528,7 +5535,7 @@ export class EngramAccessService {
     options: Omit<EngramAccessOfflineSyncSnapshotRequest, "baseCapturedAt" | "baseFiles"> & { signal?: AbortSignal } = {},
   ): Promise<EngramAccessOfflineSyncSnapshotStreamResponse> {
     const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
-    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const storage = await offlineSyncStorageForSnapshot(this.orchestrator, resolvedNamespace);
     const storageHash = createHash("sha256").update(storage.dir).digest("hex").slice(0, 16);
     return {
       namespace: resolvedNamespace,
@@ -5553,7 +5560,7 @@ export class EngramAccessService {
     options: EngramAccessOfflineSyncFilesRequest,
   ): Promise<EngramAccessOfflineSyncFilesResponse> {
     const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
-    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const storage = await offlineSyncStorageForSnapshot(this.orchestrator, resolvedNamespace);
     const storageHash = createHash("sha256").update(storage.dir).digest("hex").slice(0, 16);
     try {
       const snapshot = await buildOfflineSyncSnapshotForPaths({

package/src/access-surface-catalog.ts

@@ -183,6 +183,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/action-confidence", operation: "action_confidence" },
   { method: "GET", pathname: "/engram/v1/recall/tier-explain", operation: "recall_tier_explain" },
   { method: "GET", pathname: "/engram/v1/recall/xray", operation: "recall_xray" },
+  { method: "GET", pathname: "/engram/v1/namespace/writable", operation: "namespace_writable" },
   { method: "GET", pathname: "/engram/v1/wearables/status", operation: "wearables_status" },
   { method: "POST", pathname: "/engram/v1/wearables/sync", operation: "wearables_sync" },
   { method: "GET", pathname: "/engram/v1/wearables/transcript", operation: "transcript_day" },

package/src/access-token-capabilities.ts

@@ -327,20 +327,27 @@ export function resolveEffectiveNamespace(
  * behavior is unchanged. Both the HTTP transport (`resolveNamespace`) and the
  * MCP dispatch route through this ONE function so no surface is missed.
  */
+export function isNamespaceAllowed(
+  caps: TokenCapabilities | undefined | null,
+  namespace: string | undefined,
+  defaultNamespace: string | undefined,
+): boolean {
+  if (caps?.namespaces === undefined) return true; // unrestricted token
+  const effective = resolveEffectiveNamespace(namespace, defaultNamespace);
+  return effective !== undefined && caps.namespaces.includes(effective);
+}
+
 export function enforceNamespaceAllowList(
   caps: TokenCapabilities | undefined | null,
   namespace: string | undefined,
   defaultNamespace: string | undefined,
 ): void {
-  if (caps?.namespaces === undefined) return; // unrestricted token — unchanged
-  const effective = resolveEffectiveNamespace(namespace, defaultNamespace);
-  if (effective === undefined || !caps.namespaces.includes(effective)) {
-    throw new EngramAccessForbiddenError(
-      namespace === undefined
-        ? "token is scoped to specific namespaces; the server default namespace is not permitted — supply an allowed namespace"
-        : `token is not permitted to access namespace: ${namespace}`,
-    );
-  }
+  if (isNamespaceAllowed(caps, namespace, defaultNamespace)) return;
+  throw new EngramAccessForbiddenError(
+    namespace === undefined
+      ? "token is scoped to specific namespaces; the server default namespace is not permitted — supply an allowed namespace"
+      : `token is not permitted to access namespace: ${namespace}`,
+  );
 }
 
 /**