@remnic/core 9.69.33 → 9.69.34

package/src/access-mcp.test.ts

@@ -263,6 +263,79 @@ test("MCP memory write tools reject malformed arguments before dispatch", async
   }
 });
 
+test("MCP memory write tools admit project-shaped category aliases (#2780)", async () => {
+  for (const toolName of ["engram.memory_store", "engram.suggestion_submit"]) {
+    let received: Record<string, unknown> | undefined;
+    const service = {
+      ...makeMockService(),
+      memoryStore: async (req: Record<string, unknown>) => {
+        received = req;
+        return {
+          schemaVersion: 1,
+          operation: "memory_store",
+          namespace: "default",
+          dryRun: true,
+          accepted: true,
+          queued: false,
+          status: "validated",
+        };
+      },
+      suggestionSubmit: async (req: Record<string, unknown>) => {
+        received = req;
+        return {
+          schemaVersion: 1,
+          operation: "suggestion_submit",
+          namespace: "default",
+          dryRun: true,
+          accepted: true,
+          queued: false,
+          status: "validated",
+        };
+      },
+    } as unknown as EngramAccessService;
+    const server = new EngramMcpServer(service);
+
+    const response = await server.handleRequest(
+      makeToolRequest(toolName, {
+        content: "valid durable content",
+        category: "project_state",
+        dryRun: true,
+      })
+    );
+    const result = (response as Record<string, unknown> & { result?: { isError?: boolean } }).result;
+
+    assert.equal(result?.isError, false, `${toolName} must admit project-shaped category aliases`);
+    assert.equal(
+      received?.category,
+      "project_state",
+      `${toolName} must forward the alias; the write surface coerces it to "fact"`
+    );
+  }
+});
+
+test("MCP memory_store invalid category error names valid categories and the fact hint (#2780)", async () => {
+  const server = new EngramMcpServer(makeMockService());
+
+  for (const bad of ["vibe", "projection", "project_typo"]) {
+    const response = await server.handleRequest(
+      makeToolRequest("engram.memory_store", {
+        content: "valid durable content",
+        category: bad,
+        dryRun: true,
+      })
+    );
+    const result = (response as Record<string, unknown> & {
+      result?: { isError?: boolean; content?: Array<{ text?: string }> };
+    }).result;
+
+    assert.equal(result?.isError, true, `${bad} must reject, not coerce`);
+    const text = (result?.content ?? []).map((part) => part.text ?? "").join("\n");
+    assert.match(text, /must be one of: /, "error must name the valid categories");
+    assert.match(text, /reasoning_trace/, "the full valid list must be present");
+    assert.match(text, /for project state\/facts use "fact"/, "error must carry the fact hint");
+  }
+});
+
 test("MCP write tools accept and forward client-injected cwd/projectTag (#1434)", async () => {
   for (const toolName of ["engram.memory_store", "engram.suggestion_submit"]) {
     let received: Record<string, unknown> | undefined;

package/src/access-mcp.ts

@@ -543,10 +543,7 @@ export class EngramMcpServer {
             topK: { type: "number" },
             mode: { type: "string", enum: ["auto", "no_recall", "minimal", "full", "graph_mode"] },
             includeDebug: { type: "boolean" },
-            // Recall disclosure depth (issue #677).  Default `chunk` when
-            // omitted.  Section/raw payload shaping ships in PR 2; this PR
-            // wires the field end-to-end so clients can already pass it
-            // without it being silently dropped.
+            // Disclosure depth (issue #677); default `chunk` when omitted.
             disclosure: { type: "string", enum: ["chunk", "section", "raw"] },
             cwd: { type: "string", description: "Working directory for auto git-context resolution." },
             projectTag: {
@@ -566,8 +563,11 @@ export class EngramMcpServer {
             tagMatch: {
               type: "string",
               enum: ["any", "all"],
-              description:
-                "Tag-filter match mode. 'any' (default) admits results with at least one filter tag; 'all' requires every filter tag.",
+              description: "Tag-filter match mode; 'any' (default) or 'all'.",
+            },
+            stateView: {
+              type: "boolean",
+              description: "Opt in to state-aware recall views (issue #1952); ORs with the recallStateViews config flag.",
             },
           },
           required: ["query"],

package/src/access-observe-write-surface.ts

@@ -30,6 +30,7 @@ import {
   NamespaceNotWritableError,
 } from "./access-service.js";
 import { extractionForceFlush } from "./access-extraction-force-flush.js";
+import { coerceProjectCategoryAlias, reapplyCategoryCoercion } from "./access-schema.js";
 import { ObserveTranscriptPersister, observeTranscriptSessionKey } from "./access-observe-transcript.js";
 import { FileCalendarSource, buildBriefing, parseBriefingFocus, parseBriefingWindow } from "./briefing.js";
 import {
@@ -482,9 +483,13 @@ export class AccessObserveWriteSurface {
   }
 
   async memoryStore(
-    request: EngramAccessMemoryStoreRequest,
+    rawRequest: EngramAccessMemoryStoreRequest,
     hooks?: { enforceWriteQuota?: () => void | Promise<void> }
   ): Promise<EngramAccessWriteResponse> {
+    // #2780: the boundary schema admits project-shaped category guesses;
+    // this funnel (MCP/HTTP/CLI all dispatch here) coerces them to the
+    // canonical "fact" once and reports the coercion on the response.
+    const { request, categoryCoercion } = coerceProjectCategoryAlias(rawRequest);
     let namespace: string;
     try {
       namespace = await this.deps.resolveCodingScopedWriteNamespace(request);
@@ -513,6 +518,7 @@ export class AccessObserveWriteSurface {
           queued: false,
           status: "validated",
           idempotencyKey: request.idempotencyKey?.trim() || undefined,
+          ...(categoryCoercion ? { categoryCoercion } : {}),
         };
       }
       const result = await persistExplicitCapture(this.deps.orchestrator, candidate, "memory_store");
@@ -539,13 +545,14 @@ export class AccessObserveWriteSurface {
         memoryId: result.id,
         duplicateOf: result.duplicateOf,
         idempotencyKey: request.idempotencyKey?.trim() || undefined,
+        ...(categoryCoercion ? { categoryCoercion } : {}),
       };
       log.info(
         `access-write op=memory_store namespace=${namespace} dryRun=false status=${response.status} memoryId=${response.memoryId ?? "-"} idempotency=${response.idempotencyKey ? "yes" : "no"}`
       );
       return response;
     };
-    return this.deps.handleIdempotentWrite({
+    const response = await this.deps.handleIdempotentWrite({
       operation: "memory_store",
       idempotencyKey: request.idempotencyKey,
       // Shared builder (issue #1989 PR3): byte-parity with the historical
@@ -566,12 +573,16 @@ export class AccessObserveWriteSurface {
       beforeExecute: hooks?.enforceWriteQuota,
       execute,
     });
+    // #2780 fix B: rewrite a replayed coercion note from THIS request's raw category.
+    return reapplyCategoryCoercion(response, categoryCoercion);
   }
 
   async suggestionSubmit(
-    request: EngramAccessSuggestionSubmitRequest,
+    rawRequest: EngramAccessSuggestionSubmitRequest,
     hooks?: { enforceWriteQuota?: () => void | Promise<void> }
   ): Promise<EngramAccessWriteResponse> {
+    // #2780: same alias funnel as memory_store — one shared coercion point.
+    const { request, categoryCoercion } = coerceProjectCategoryAlias(rawRequest);
     let namespace: string;
     try {
       namespace = await this.deps.resolveCodingScopedWriteNamespace(request);
@@ -599,6 +610,7 @@ export class AccessObserveWriteSurface {
           queued: true,
           status: "validated",
           idempotencyKey: request.idempotencyKey?.trim() || undefined,
+          ...(categoryCoercion ? { categoryCoercion } : {}),
         };
       }
       const result = await queueExplicitCaptureForReview(
@@ -622,13 +634,14 @@ export class AccessObserveWriteSurface {
         memoryId: result.id,
         duplicateOf: result.duplicateOf,
         idempotencyKey: request.idempotencyKey?.trim() || undefined,
+        ...(categoryCoercion ? { categoryCoercion } : {}),
       };
       log.info(
         `access-write op=suggestion_submit namespace=${namespace} dryRun=false status=${response.status} memoryId=${response.memoryId ?? "-"} idempotency=${response.idempotencyKey ? "yes" : "no"}`
       );
       return response;
     };
-    return this.deps.handleIdempotentWrite({
+    const replayed = await this.deps.handleIdempotentWrite({
       operation: "suggestion_submit",
       idempotencyKey: request.idempotencyKey,
       // Shared builder (issue #1989 PR3): byte-parity with the historical
@@ -649,6 +662,8 @@ export class AccessObserveWriteSurface {
       beforeExecute: hooks?.enforceWriteQuota,
       execute,
     });
+    // #2780 fix B: rewrite a replayed coercion note from THIS request's raw category.
+    return reapplyCategoryCoercion(replayed, categoryCoercion);
   }
 
   async runObserve(request: EngramAccessObserveRequest): Promise<EngramAccessObserveResponse> {

package/src/access-offline-manifest.ts

@@ -1,16 +1,22 @@
 import * as nodePath from "node:path";
-import type { Orchestrator } from "./orchestrator.js";
-import { iterateOfflineSyncSnapshotFileRecords } from "./offline-sync.js";
 import { offlineSyncStorageForSnapshot } from "./offline-sync-impression-drain.js";
+import { iterateOfflineSyncSnapshotFileRecords } from "./offline-sync.js";
+import type { Orchestrator } from "./orchestrator.js";
 import {
-  buildReconcileManifestFile,
+  CONTENT_HASH_NORMALIZER_VERSION,
+  IDENTITY_RESOLUTION_VERSION,
   RECONCILE_MANIFEST_FORMAT,
   RECONCILE_MANIFEST_SCHEMA_VERSION,
   type ReconcileManifest,
   type ReconcileManifestFile,
+  type ReconcileMemoryIdentity,
   type ReconcileMemoryParser,
+  buildReconcileManifestFile,
+  citationTemplateFingerprint,
+  isCachedIdentityReusable,
+  isReconcileMemoryIdentity,
 } from "./reconcile/manifest.js";
-import { isSupportPassportPrivateMemory } from "./support-passport/card-projection.js";
+import { createPersistedSupportPassportPrivateFileExclusion } from "./support-passport/card-projection.js";
 
 export interface OfflineSyncManifestRequest {
   includeTranscripts?: boolean;
@@ -22,14 +28,179 @@ export interface OfflineSyncManifestStreamResponse extends Omit<ReconcileManifes
   files: AsyncIterable<ReconcileManifestFile>;
 }
 
+export interface ServerIdentityCacheEntry {
+  path: string;
+  sha256: string;
+  memory?: ReconcileMemoryIdentity;
+  /** Stamped on sha-only entries so an upgrade re-parses them. */
+  normalizerVersion?: number;
+  identityResolutionVersion?: number;
+  /** Stat identity the exclusion classification was computed against. */
+  statIdentity?: string;
+  /** Persisted support-passport private-memory classification for statIdentity. */
+  excluded?: boolean;
+}
+
+/**
+ * Decide what the manifest stream should persist, and whether a write is
+ * needed at all.
+ *
+ * A write is required whenever the persisted set changed — an identity was
+ * rebuilt, or an entry was dropped because its file lost its identity — and
+ * also when a completed walk leaves entries for paths it never saw, which are
+ * files that have since been deleted. Skipping the write in that last case
+ * would strand those entries on disk forever.
+ *
+ * Pruning is gated on the walk completing: an aborted or partially consumed
+ * stream has simply not observed the remaining paths, so it may only add.
+ */
+export function planServerIdentityCacheWrite(input: {
+  persisted: ReadonlyMap<string, ServerIdentityCacheEntry>;
+  yieldedPaths: ReadonlySet<string>;
+  streamCompleted: boolean;
+  cacheDirty: boolean;
+}): { shouldWrite: boolean; entries: ServerIdentityCacheEntry[] } {
+  const entries = input.streamCompleted
+    ? [...input.persisted.values()].filter((entry) => input.yieldedPaths.has(entry.path))
+    : [...input.persisted.values()];
+  return { shouldWrite: input.cacheDirty || entries.length !== input.persisted.size, entries };
+}
+
+/**
+ * The cache lives under `.remnic/` rather than `state/`: snapshot enumeration
+ * excludes internal `.remnic/` paths structurally (`isInternalRemnicStatePath`),
+ * whereas `state/` is only filtered by an allowlist of known node-local
+ * artifacts. Under `state/` this node-local cache would be advertised as a peer
+ * file, so convergence would transfer the cache itself — and the stream rewrites
+ * it during finalization, so the advertised digest could go stale mid-transfer.
+ */
+function serverIdentityCachePath(storageDir: string): string {
+  return nodePath.join(storageDir, ".remnic", "state", "converge-identity-cache.json");
+}
+
+async function loadServerIdentityCache(
+  storageDir: string,
+  citationTemplate?: string
+): Promise<Map<string, ServerIdentityCacheEntry>> {
+  const cache = new Map<string, ServerIdentityCacheEntry>();
+  try {
+    const raw = JSON.parse(
+      await import("node:fs/promises").then((fs) => fs.readFile(serverIdentityCachePath(storageDir), "utf8"))
+    ) as {
+      citationTemplate?: string;
+      files?: unknown[];
+    };
+    // Identities are derived after stripping inline attribution for a specific
+    // citation template; entries written under a different one would produce
+    // wrong contentHash values for unchanged files.
+    if (raw.citationTemplate !== citationTemplateFingerprint(citationTemplate)) return cache;
+    for (const candidate of raw.files ?? []) {
+      const entry = candidate as Partial<ServerIdentityCacheEntry> | null;
+      if (typeof entry?.path !== "string" || typeof entry.sha256 !== "string") continue;
+      if (entry.memory !== undefined && !isReconcileMemoryIdentity(entry.memory)) continue;
+      if (entry.statIdentity !== undefined && typeof entry.statIdentity !== "string") continue;
+      if (entry.excluded !== undefined && typeof entry.excluded !== "boolean") continue;
+      if (entry.normalizerVersion !== undefined && typeof entry.normalizerVersion !== "number") continue;
+      if (entry.identityResolutionVersion !== undefined && typeof entry.identityResolutionVersion !== "number") {
+        continue;
+      }
+      cache.set(entry.path, {
+        path: entry.path,
+        sha256: entry.sha256,
+        ...(entry.memory ? { memory: entry.memory } : {}),
+        ...(entry.memory
+          ? {}
+          : {
+              ...(typeof entry.normalizerVersion === "number" ? { normalizerVersion: entry.normalizerVersion } : {}),
+              ...(typeof entry.identityResolutionVersion === "number"
+                ? { identityResolutionVersion: entry.identityResolutionVersion }
+                : {}),
+            }),
+        ...(entry.statIdentity !== undefined && entry.excluded !== undefined
+          ? { statIdentity: entry.statIdentity, excluded: entry.excluded }
+          : {}),
+      });
+    }
+  } catch {
+    // missing or corrupt cache: cold build
+  }
+  return cache;
+}
+
+const serverIdentityCacheWriteLocks = new Map<string, Promise<void>>();
+
+/** Serialize cache replacements per path: overlapping manifest streams for one
+ * namespace would otherwise each publish a whole-file snapshot, and the slower
+ * stream built from older filesystem state would overwrite the newer one. */
+async function withServerIdentityCacheWriteLock(cachePath: string, write: () => Promise<void>): Promise<void> {
+  const previous = serverIdentityCacheWriteLocks.get(cachePath) ?? Promise.resolve();
+  const next = previous.then(write, write);
+  serverIdentityCacheWriteLocks.set(cachePath, next);
+  try {
+    await next;
+  } finally {
+    if (serverIdentityCacheWriteLocks.get(cachePath) === next) {
+      serverIdentityCacheWriteLocks.delete(cachePath);
+    }
+  }
+}
+
+/** Union of the entries being written and the current on-disk set; on conflict
+ * the write wins (it reflects the newer run). Callers hold the write lock. */
+async function mergeServerIdentityCacheEntries(
+  fs: typeof import("node:fs/promises"),
+  cachePath: string,
+  entries: readonly ServerIdentityCacheEntry[],
+  citationTemplate: string | undefined,
+  dropped: ReadonlySet<string> = new Set()
+): Promise<ServerIdentityCacheEntry[]> {
+  const merged = new Map(entries.map((entry) => [entry.path, entry]));
+  try {
+    const raw = JSON.parse(await fs.readFile(cachePath, "utf8")) as {
+      citationTemplate?: string;
+      files?: unknown[];
+    };
+    if (raw.citationTemplate === citationTemplateFingerprint(citationTemplate)) {
+      for (const candidate of raw.files ?? []) {
+        const entry = candidate as Partial<ServerIdentityCacheEntry> | null;
+        if (typeof entry?.path !== "string" || typeof entry.sha256 !== "string") continue;
+        if (entry.memory !== undefined && !isReconcileMemoryIdentity(entry.memory)) continue;
+        if (dropped.has(entry.path) || merged.has(entry.path)) continue;
+        merged.set(entry.path, {
+          path: entry.path,
+          sha256: entry.sha256,
+          ...(entry.memory ? { memory: entry.memory } : {}),
+          ...(entry.memory
+            ? {}
+            : {
+                ...(typeof entry.normalizerVersion === "number" ? { normalizerVersion: entry.normalizerVersion } : {}),
+                ...(typeof entry.identityResolutionVersion === "number"
+                  ? { identityResolutionVersion: entry.identityResolutionVersion }
+                  : {}),
+              }),
+        });
+      }
+    }
+  } catch {
+    // missing or unreadable current cache: the write set stands alone
+  }
+  return [...merged.values()];
+}
+
 export async function createOfflineSyncManifestStream(
   orchestrator: Orchestrator,
   namespace: string,
   userExcludeRegexps: RegExp[],
   options: OfflineSyncManifestRequest,
-  parseMemory: ReconcileMemoryParser,
+  parseMemory: ReconcileMemoryParser
 ): Promise<OfflineSyncManifestStreamResponse> {
   const storage = await offlineSyncStorageForSnapshot(orchestrator, namespace);
+  const citationTemplate = orchestrator.config.inlineSourceAttributionFormat;
+  const identityCache = await loadServerIdentityCache(storage.dir, citationTemplate);
+  // The exclusion callback runs before every yield; without the persisted
+  // classification it would read and parse every candidate file, defeating the
+  // warm-cache skip entirely.
+  const classificationUpdates = new Map<string, { statIdentity: string; excluded: boolean }>();
   const snapshotFiles = iterateOfflineSyncSnapshotFileRecords({
     root: storage.dir,
     includeContent: false,
@@ -37,23 +208,133 @@ export async function createOfflineSyncManifestStream(
     readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
     signal: options.signal,
     userExcludeRegexps,
-    excludeFile: async ({ filePath }) => {
-      const memory = await storage.readMemoryByPath(filePath);
-      return memory ? isSupportPassportPrivateMemory(memory) : false;
-    },
+    excludeFile: createPersistedSupportPassportPrivateFileExclusion(storage, identityCache, classificationUpdates),
   });
   return {
     namespace,
     format: RECONCILE_MANIFEST_FORMAT,
     schemaVersion: RECONCILE_MANIFEST_SCHEMA_VERSION,
     files: (async function* () {
-      for await (const file of snapshotFiles) {
-        yield await buildReconcileManifestFile(
-          file,
-          async ({ path }) => storage.readOfflineSyncFile(nodePath.join(storage.dir, path)),
-          parseMemory,
-          orchestrator.config.inlineSourceAttributionFormat,
-        );
+      // Any change to the persisted set, not just a rebuilt identity: a file
+      // that lost its identity, or a completed walk that must prune vanished
+      // paths, also has to reach disk or the removal is lost forever.
+      let cacheDirty = false;
+      let streamCompleted = false;
+      // Seeded with every previously cached entry so a partially consumed
+      // stream (client disconnect, abort) can only add to the cache. Writing
+      // just this run's rebuilds would drop every cache hit, so one edit to a
+      // large corpus would shrink the cache to that single entry and force a
+      // near-cold rebuild on the next request.
+      const persistedEntries = new Map(identityCache);
+      const yieldedPaths = new Set<string>();
+      const flush = async (): Promise<void> => {
+        const { shouldWrite, entries } = planServerIdentityCacheWrite({
+          persisted: persistedEntries,
+          yieldedPaths,
+          streamCompleted,
+          cacheDirty,
+        });
+        if (!shouldWrite) return;
+        try {
+          const fs = await import("node:fs/promises");
+          const cachePath = serverIdentityCachePath(storage.dir);
+          await withServerIdentityCacheWriteLock(cachePath, async () => {
+            // Merge with whatever is on disk NOW: a concurrent stream for the
+            // same namespace may have published newer entries after this
+            // request loaded its snapshot, and a blind whole-file replace
+            // would discard them.
+            const written = new Set(entries.map((entry) => entry.path));
+            const dropped = streamCompleted
+              ? new Set([...identityCache.keys()].filter((pathName) => !written.has(pathName)))
+              : new Set<string>();
+            const merged = await mergeServerIdentityCacheEntries(
+              fs,
+              cachePath,
+              entries,
+              citationTemplate,
+              dropped
+            );
+            await fs.mkdir(nodePath.dirname(cachePath), { recursive: true });
+            const tmp = `${cachePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+            await fs.writeFile(
+              tmp,
+              JSON.stringify({ citationTemplate: citationTemplateFingerprint(citationTemplate), files: merged })
+            );
+            await fs.rename(tmp, cachePath);
+          });
+        } catch {
+          // cache persistence is best-effort
+        }
+      };
+      try {
+        const applyClassification = (path: string, sha256: string): void => {
+          const classification = classificationUpdates.get(path);
+          if (classification === undefined) return;
+          const entry = persistedEntries.get(path) ?? { path, sha256 };
+          if (entry.statIdentity === classification.statIdentity && entry.excluded === classification.excluded) {
+            return;
+          }
+          persistedEntries.set(path, {
+            ...entry,
+            ...(entry.memory ? { memory: entry.memory } : {}),
+            statIdentity: classification.statIdentity,
+            excluded: classification.excluded,
+          });
+          cacheDirty = true;
+        };
+        for await (const file of snapshotFiles) {
+          yieldedPaths.add(file.path);
+          const cached = identityCache.get(file.path);
+          if (
+            cached !== undefined &&
+            cached.sha256.toLowerCase() === file.sha256.toLowerCase() &&
+            isCachedIdentityReusable(cached)
+          ) {
+            applyClassification(file.path, file.sha256);
+            yield {
+              ...file,
+              ...(cached.memory
+                ? { memory: cached.memory }
+                : {
+                    normalizerVersion: cached.normalizerVersion,
+                    identityResolutionVersion: cached.identityResolutionVersion,
+                  }),
+            };
+            continue;
+          }
+          const built = await buildReconcileManifestFile(
+            file,
+            async ({ path }) => storage.readOfflineSyncFile(nodePath.join(storage.dir, path)),
+            parseMemory,
+            citationTemplate
+          );
+          // Negative results persist too: a memory-shaped file that parses
+          // without an identity would otherwise be re-read on every warm run.
+          const previous = persistedEntries.get(built.path);
+          if (previous?.sha256 !== built.sha256 || (built.memory !== undefined && previous?.memory !== built.memory)) {
+            cacheDirty = true;
+          }
+          if (built.memory === undefined && built.normalizerVersion === undefined) {
+            // Read failed: do not persist a negative identity for this SHA.
+            yield built;
+            continue;
+          }
+          persistedEntries.set(built.path, {
+            path: built.path,
+            sha256: built.sha256,
+            ...(built.memory !== undefined
+              ? { memory: built.memory }
+              : {
+                  normalizerVersion: built.normalizerVersion,
+                  identityResolutionVersion: built.identityResolutionVersion,
+                }),
+          });
+          applyClassification(built.path, built.sha256);
+          yield built;
+        }
+        streamCompleted = true;
+      } finally {
+        await flush();
       }
     })(),
   };

package/src/access-recall-surface.ts

@@ -833,11 +833,10 @@ export class AccessRecallSurface {
       this.deps.budget.gc();
     }
     const topK = Number.isFinite(request.topK) ? Math.max(0, Math.floor(request.topK ?? 0)) : undefined;
-    // Issue #680 — historical recall pin.  Validate at the input
-    // boundary so a malformed `asOf` is rejected with a structured
-    // 400 instead of silently flooring at NaN inside the orchestrator
-    // (CLAUDE.md rule 51, gotcha #51).  Empty / undefined is fine —
-    // means "no pin".
+    // Issue #680 — historical recall pin.  Validate at the input boundary so
+    // a malformed `asOf` is rejected with a structured 400 instead of
+    // silently flooring at NaN inside the orchestrator (rule 51, gotcha #51).
+    // Empty / undefined is fine — means "no pin".
     let asOf: string | undefined;
     if (request.asOf !== undefined && request.asOf !== null) {
       if (typeof request.asOf !== "string" || request.asOf.trim().length === 0) {
@@ -863,6 +862,7 @@ export class AccessRecallSurface {
       },
       ...(authenticatedPrincipal ? { principalOverride: authenticatedPrincipal } : {}),
       ...(request.sourceConnector ? { sourceConnector: request.sourceConnector } : {}),
+      ...(request.stateView !== undefined ? { stateView: request.stateView } : {}),
       ...(asOf !== undefined ? { asOf } : {}),
       ...(request.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
       ...(request.abortSignal ? { abortSignal: request.abortSignal } : {}),