@remnic/core 9.45.3 → 9.45.5

package/src/access-http.ts

@@ -18,6 +18,10 @@ import {
   type EngramAccessWriteResponse,
 } from "./access-service.js";
 import { maybeHandleLifecycleFlush, type LifecycleFlushHttpDeps } from "./access-http-lifecycle-flush.js";
+import {
+  respondOfflineManifestStream,
+  respondOfflineSnapshotStream,
+} from "./access-http-offline-stream.js";
 import { nonEmptyQueryParam, optionalQueryString, positiveIntQueryParam } from "./access-http-query.js";
 import { CorrectionContractError } from "./correction/correction-contract.js";
 import { WearablesInputError } from "./wearables/errors.js"; import { respondMeetingsList, respondMeetingsGet, respondMeetingsBuild } from "./meetings/http-glue.js";
@@ -42,7 +46,7 @@ import { projectTagProjectId } from "./coding/coding-namespace.js";
 import { getOperation, type OperationName } from "./access-boundary.js";
 import { authorizationProbeNamespaces, probeOperationAuthorization } from "./access-authorization-probe.js";
 import { resolveQueryNamespaceWritablePreflight } from "./access-namespace-preflight.js";
-import { respondLcmCompactionCapabilitiesHttp } from "./access-http-lcm-compaction.js";
+import { respondAccessCapabilitiesHttp } from "./access-http-lcm-compaction.js";
 import {
   assertOperationAllowed,
   capabilityAllowsOp,
@@ -898,7 +902,7 @@ export class EngramAccessHttpServer {
       });
       return;
     }
-    if (req.method === "GET" && pathname === "/engram/v1/capabilities") return respondLcmCompactionCapabilitiesHttp(res);
+    if (req.method === "GET" && pathname === "/engram/v1/capabilities") return respondAccessCapabilitiesHttp(res);
     if (req.method === "GET" && pathname === "/engram/v1/authorization") {
       res.setHeader("cache-control", "no-store");
       const probe = probeOperationAuthorization(tokenCapabilityStore.getStore(), parsed.searchParams.getAll("op"));
@@ -910,11 +914,6 @@ export class EngramAccessHttpServer {
     }
 
     if (req.method === "GET" && pathname === "/engram/v1/adapters") {
-      // Issue #1850 round 5 (finding 1): adapter metadata is served after
-      // auth but was NOT op-gated, so a deny-all or narrow-ops token reached
-      // it. enforceTokenOp fail-closes it under the per-token ops allow-list;
-      // no-op for unrestricted/legacy tokens. There is no namespace axis —
-      // adapter metadata is not tenant-scoped.
       this.enforceTokenOp("adapters_status"); // boundary dispatch (issue #1850)
       const identity = this.resolveAdapterIdentity(req);
       this.respondJson(res, 200, {
@@ -958,6 +957,21 @@ export class EngramAccessHttpServer {
       }
       return;
     }
+    if (
+      req.method === "POST" &&
+      (pathname === "/engram/v1/external-wikis/search" ||
+        pathname === "/remnic/v1/external-wikis/search")
+    ) {
+      this.enforceTokenOp("external_wiki_search");
+      const operation = getOperation("external_wiki_search");
+      if (!operation) throw new EngramAccessInputError("external_wiki_search operation is not registered");
+      const output = await operation.run(await this.readJsonBody(req), { service: this.service });
+      if (!output || typeof output !== "object" || !("result" in output)) {
+        throw new Error("external_wiki_search returned an invalid operation result");
+      }
+      this.respondJson(res, 200, output.result);
+      return;
+    }
 
     if (req.method === "POST" && pathname === "/engram/v1/recall") {
       this.enforceTokenOp("recall"); // boundary dispatch (issue #1525)
@@ -1055,6 +1069,7 @@ export class EngramAccessHttpServer {
         query: body.query ?? "",
         sessionKey: body.sessionKey,
         authenticatedPrincipal: this.resolveRequestPrincipal(req),
+        sourceConnector: this.resolveConnector(req),
         idempotencyKey: body.idempotencyKey,
         namespace: this.resolveNamespace(req, body.namespace),
         topK: body.topK,
@@ -1078,10 +1093,6 @@ export class EngramAccessHttpServer {
       return;
     }
 
-    // Attach / clear coding-agent context for a session (issue #569 PR 5).
-    // Mirrors `setCodingContext` on the access service. Connectors call this
-    // at session start after resolving a git context for the cwd; `remnic
-    // doctor` (PR 8) surfaces the attached context.
     if (req.method === "POST" && pathname === "/engram/v1/coding-context") {
       this.enforceTokenOp("set_coding_context"); // boundary dispatch (issue #1525)
       const body = await this.readValidatedBody(req, "setCodingContext");
@@ -1142,6 +1153,20 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (
+      req.method === "GET" &&
+      (pathname === "/engram/v1/offline-sync/capabilities" ||
+        pathname === "/remnic/v1/offline-sync/capabilities")
+    ) {
+      this.enforceTokenOp("offline_sync_snapshot");
+      this.respondJson(res, 200, {
+        version: 1,
+        convergenceFinalization: true,
+        manifestStream: true,
+      });
+      return;
+    }
+
     if (
       req.method === "GET" &&
       (pathname === "/engram/v1/offline-sync/snapshot" || pathname === "/remnic/v1/offline-sync/snapshot")
@@ -1215,10 +1240,44 @@ export class EngramAccessHttpServer {
         includeContent: false,
         signal: this.createRequestAbortSignal(req, res),
       });
-      await this.respondOfflineSnapshotStream(res, result);
+      await respondOfflineSnapshotStream(res, result, correlationIdStore.getStore());
+      return;
+    }
+    if (
+      req.method === "GET" &&
+      (pathname === "/engram/v1/offline-sync/manifest-stream" ||
+        pathname === "/remnic/v1/offline-sync/manifest-stream")
+    ) {
+      this.enforceTokenOp("offline_sync_snapshot_stream");
+      const includeTranscriptsRaw = parsed.searchParams.get("include_transcripts");
+      const includeContentRaw = parsed.searchParams.get("content");
+      if (
+        includeTranscriptsRaw !== null &&
+        includeTranscriptsRaw !== "true" &&
+        includeTranscriptsRaw !== "false"
+      ) {
+        throw new EngramAccessInputError(
+          `include_transcripts must be one of: true, false (got: ${includeTranscriptsRaw})`,
+        );
+      }
+      if (includeContentRaw !== null && includeContentRaw !== "false") {
+        throw new EngramAccessInputError("manifest-stream content must be false");
+      }
+      const namespaceParam = parsed.searchParams.get("namespace");
+      const result = await this.service.offlineSyncManifestStream({
+        namespace: this.resolveNamespace(
+          req,
+          namespaceParam && namespaceParam.length > 0 ? namespaceParam : undefined,
+        ),
+        principal: this.resolveRequestPrincipal(req),
+        includeTranscripts: includeTranscriptsRaw !== "false",
+        signal: this.createRequestAbortSignal(req, res),
+      });
+      await respondOfflineManifestStream(res, result, correlationIdStore.getStore());
       return;
     }
 
+
     if (
       req.method === "POST" &&
       (pathname === "/engram/v1/offline-sync/snapshot" || pathname === "/remnic/v1/offline-sync/snapshot")
@@ -1323,6 +1382,7 @@ export class EngramAccessHttpServer {
       return;
     }
 
+
     if (
       req.method === "POST" &&
       (
@@ -1330,7 +1390,8 @@ export class EngramAccessHttpServer {
         pathname === "/remnic/v1/offline-sync/convergence-complete"
       )
     ) {
-      this.enforceTokenOp("offline_sync_apply_file_content");
+      void getOperation("offline_sync_apply_file_content");
+      this.enforceTokenAnyOf(["offline_sync_apply_file_content", "offline_sync_apply"]);
       const namespaceParams = parsed.searchParams.getAll("namespace").filter(Boolean);
       const requestedNamespaces: Array<string | undefined> =
         namespaceParams.length > 0 ? namespaceParams : [undefined];
@@ -1386,9 +1447,6 @@ export class EngramAccessHttpServer {
       return;
     }
 
-    // Tier-explain (issue #518): structured per-result annotation from
-    // the direct-answer retrieval tier.  Orthogonal to /recall/explain
-    // above, which returns a graph-path explanation document.
     if (req.method === "GET" && pathname === "/engram/v1/recall/tier-explain") {
       this.enforceTokenOp("recall_tier_explain"); // boundary dispatch (issue #1525)
       const sessionParam = parsed.searchParams.get("session");
@@ -1486,6 +1544,7 @@ export class EngramAccessHttpServer {
           namespace,
           budget,
           authenticatedPrincipal: this.resolveRequestPrincipal(req),
+          sourceConnector: this.resolveConnector(req),
           ...(disclosure !== undefined ? { disclosure } : {}),
         });
       } catch (err) {
@@ -1526,11 +1585,6 @@ export class EngramAccessHttpServer {
       return;
     }
 
-    // -- Wearables (Limitless / Bee / Omi transcript ingestion). All
-    //    behavior + validation lives in WearablesService; these routes
-    //    translate transport shape only. Service validation errors map
-    //    to 400 via respondWearablesError; backend faults bubble to the
-    //    global 500 handler.
     if (
       req.method === "GET" &&
       (pathname === "/engram/v1/wearables/status" || pathname === "/remnic/v1/wearables/status")
@@ -3370,62 +3424,6 @@ export class EngramAccessHttpServer {
     res.end(body);
   }
 
-  private async respondOfflineSnapshotStream(
-    res: ServerResponse,
-    snapshot: Awaited<ReturnType<EngramAccessService["offlineSyncSnapshotStream"]>>,
-  ): Promise<void> {
-    res.statusCode = 200;
-    res.setHeader("content-type", "application/x-ndjson; charset=utf-8");
-    res.setHeader("cache-control", "no-store");
-    const cid = correlationIdStore.getStore();
-    if (cid) {
-      res.setHeader("x-request-id", cid);
-    }
-    const waitForDrainOrClose = async (): Promise<boolean> => new Promise((resolve, reject) => {
-      const cleanup = () => {
-        res.off("drain", onDrain);
-        res.off("close", onClose);
-        res.off("error", onError);
-      };
-      const onDrain = () => {
-        cleanup();
-        resolve(true);
-      };
-      const onClose = () => {
-        cleanup();
-        resolve(false);
-      };
-      const onError = (error: Error) => {
-        cleanup();
-        reject(error);
-      };
-      res.once("drain", onDrain);
-      res.once("close", onClose);
-      res.once("error", onError);
-    });
-    const writeLine = async (payload: unknown): Promise<boolean> => {
-      if (res.destroyed || res.writableEnded) return false;
-      if (res.write(`${JSON.stringify(payload)}\n`)) return true;
-      if (res.destroyed || res.writableEnded) return false;
-      return waitForDrainOrClose();
-    };
-    if (!await writeLine({
-      type: "snapshot",
-      namespace: snapshot.namespace,
-      format: snapshot.format,
-      schemaVersion: snapshot.schemaVersion,
-      createdAt: snapshot.createdAt,
-      sourceId: snapshot.sourceId,
-      includeTranscripts: snapshot.includeTranscripts,
-    })) return;
-    for await (const file of snapshot.files) {
-      if (!await writeLine({ type: "file", file })) return;
-    }
-    if (!res.destroyed && !res.writableEnded) {
-      res.end();
-    }
-  }
-
   private respondBinary(
     res: ServerResponse,
     status: number,
@@ -3856,6 +3854,15 @@ export class EngramAccessHttpServer {
     void getOperation(op); // preserve the registration side-effect assertion
     assertOperationAllowed(tokenCapabilityStore.getStore(), op);
   }
+
+  private enforceTokenAnyOf(ops: readonly OperationName[]): void {
+    for (const op of ops) void getOperation(op);
+    const capabilities = tokenCapabilityStore.getStore();
+    if (ops.some((op) => capabilityAllowsOp(capabilities, op))) return;
+    throw new EngramAccessForbiddenError(
+      `token is not permitted to call any required operation: ${ops.join(", ")}`,
+    );
+  }
  
   /**
    * Operator/admin routes are unrestricted-only surfaces: a scoped

package/src/access-mcp-output-schemas.ts

@@ -260,6 +260,42 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
     guidelineVersion: { type: ["number", "null"] } as const,
   }),
   memory_search: objectSchema({ query: T_STRING, results: T_ARRAY, count: T_NUMBER }),
+  external_wiki_search: objectSchema({
+    query: T_STRING,
+    hits: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          wikiId: T_STRING,
+          title: T_STRING,
+          path: T_STRING,
+          snippet: T_STRING,
+          score: T_NUMBER,
+          rank: T_NUMBER,
+          citations: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                path: T_STRING,
+                lineStart: T_NUMBER,
+                lineEnd: T_NUMBER,
+                note: T_STRING,
+              },
+              required: ["path", "lineStart", "lineEnd", "note"],
+              additionalProperties: false,
+            },
+          },
+          indexBlurb: T_STRING,
+        },
+        required: ["wikiId", "title", "path", "snippet", "score", "rank", "citations"],
+        additionalProperties: false,
+      },
+    },
+    count: T_NUMBER,
+    degradedWikiIds: T_ARRAY,
+  }, ["query", "hits", "count", "degradedWikiIds"]),
   memory_profile: objectSchema({ profile: T_STRING }),
   memory_entities_list: objectSchema({ entities: T_ARRAY, count: T_NUMBER }),
   memory_questions: objectSchema({ questions: T_ARRAY, count: T_NUMBER }),

package/src/access-mcp.test.ts

@@ -7,7 +7,7 @@
  */
 
 import assert from "node:assert/strict";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -1283,3 +1283,97 @@ test("MCP graph_edge_decay_run: unrestricted and legacy tokens reach the handler
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+function readMcpResult(response: unknown): Record<string, unknown> {
+  assert.ok(response && typeof response === "object" && "result" in response);
+  const result = response.result;
+  assert.ok(result && typeof result === "object");
+  return Object.fromEntries(Object.entries(result));
+}
+
+test("MCP external_wiki_search exposes aliases and dispatches the stable result", async () => {
+  const rootDir = await mkdtemp(path.join(os.tmpdir(), "remnic-mcp-external-wiki-"));
+  await mkdir(path.join(rootDir, "wiki"), { recursive: true });
+  await writeFile(
+    path.join(rootDir, "INDEX.md"),
+    "- [[wiki/retrieval|Retrieval Architecture]] - cited hybrid retrieval\n",
+    "utf8",
+  );
+  await writeFile(
+    path.join(rootDir, "wiki", "retrieval.md"),
+    "# Retrieval Architecture\n\nHybrid retrieval keeps cited sources.\n",
+    "utf8",
+  );
+  try {
+    const service = {
+      ...makeMockService(),
+      configRef: {
+        externalWikis: [{
+          id: "reading",
+          rootDir,
+          enabled: true,
+          pagesDir: "wiki",
+          indexFile: "INDEX.md",
+          indexInQmd: false,
+          includeInDefaultRecall: false,
+        }],
+      },
+    } as unknown as EngramAccessService;
+    const server = new EngramMcpServer(service);
+
+    const listed = await server.handleRequest({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/list",
+      params: {},
+    });
+    const listedResult = readMcpResult(listed);
+    assert.ok(Array.isArray(listedResult.tools));
+    const toolNames = listedResult.tools.flatMap((tool) =>
+      tool && typeof tool === "object" && "name" in tool && typeof tool.name === "string"
+        ? [tool.name]
+        : []
+    );
+    assert.ok(toolNames.includes("remnic.external_wiki_search"));
+    assert.ok(toolNames.includes("engram.external_wiki_search"));
+
+    let canonicalResult: unknown;
+    for (const name of ["remnic.external_wiki_search", "engram.external_wiki_search"]) {
+      const response = await server.handleRequest(makeToolRequest(name, {
+        query: "hybrid retrieval",
+        limit: 3,
+        wikiId: "reading",
+        maxCharsPerHit: 400,
+      }));
+      const result = readMcpResult(response);
+      assert.equal(result.isError, false);
+      assert.ok(result.structuredContent && typeof result.structuredContent === "object");
+      if (canonicalResult === undefined) canonicalResult = result.structuredContent;
+      else assert.deepEqual(result.structuredContent, canonicalResult);
+    }
+    assert.ok(canonicalResult && typeof canonicalResult === "object" && "hits" in canonicalResult);
+    assert.ok(Array.isArray(canonicalResult.hits));
+    assert.equal(canonicalResult.hits.length, 1);
+    const firstHit = canonicalResult.hits[0];
+    assert.ok(firstHit && typeof firstHit === "object" && "path" in firstHit);
+    assert.equal(firstHit.path, "wiki/retrieval.md");
+  } finally {
+    await rm(rootDir, { recursive: true, force: true });
+  }
+});
+
+test("MCP external_wiki_search rejects an empty query before service dispatch", async () => {
+  let configRead = false;
+  const service = {
+    ...makeMockService(),
+    get configRef() {
+      configRead = true;
+      return parseConfig({ memoryDir: os.tmpdir(), externalWikis: [] });
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramMcpServer(service);
+
+  const response = await server.handleRequest(makeToolRequest("remnic.external_wiki_search", { query: "  " }));
+  assert.equal(readMcpResult(response).isError, true);
+  assert.equal(configRead, false);
+});

package/src/access-mcp.ts

@@ -43,7 +43,10 @@ import type { RecallDisclosure, RecallPlanMode } from "./types.js";
 import { expandTildePath } from "./utils/path.js";
 
 import { applyToolOutputSchemas } from "./access-mcp-output-schemas.js";
-import { MCP_READ_ONLY_TOOL_SUFFIXES } from "./mcp-read-only-tools.js";import { MEETINGS_MCP_TOOLS } from "./meetings/mcp-tools.js";import { WEARABLES_MCP_TOOLS } from "./wearables/mcp-tools.js";
+import { MCP_READ_ONLY_TOOL_SUFFIXES } from "./mcp-read-only-tools.js";
+import { MEETINGS_MCP_TOOLS } from "./meetings/mcp-tools.js";
+import { WEARABLES_MCP_TOOLS } from "./wearables/mcp-tools.js";
+import { EXTERNAL_WIKI_MCP_TOOLS } from "./external-wiki-mcp-tools.js";
 import { abortError, isAbortError } from "./abort-error.js";
 type JsonRpcId = string | number | null;
 
@@ -152,16 +155,10 @@ function withToolAliases(tool: McpTool, emitLegacyTools = true): McpTool[] {
   return emitLegacyTools ? [canonicalTool, tool] : [canonicalTool];
 }
 
-/**
- * MCP tool name (legacy `engram.*` form, since {@link toLegacyToolName}
- * canonicalizes incoming calls) → boundary operation it dispatches through.
- * A tool appears here once its `access-operations.ts` registration lands and
- * its surface-local validation is deleted. The fitness test
- * (`access-surface-catalog.test.ts`) asserts this map and the catalog agree.
- */
 const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.memory_get": "memory_get",
   "engram.memory_search": "memory_search",
+  "engram.external_wiki_search": "external_wiki_search",
   "engram.memory_store": "memory_store",
   "engram.coding_decision": "coding_decision",
   "engram.coding_architecture": "coding_architecture",
@@ -1427,7 +1424,7 @@ export class EngramMcpServer {
           additionalProperties: false,
         },
       },
-      // ── Memory search & debug tools ────────────────────────────────────
+      ...EXTERNAL_WIKI_MCP_TOOLS,
       {
         name: "engram.memory_search",
         description:
@@ -2740,6 +2737,7 @@ export class EngramMcpServer {
       const result = (await op.run(envelope, {
         service: this.service,
         authenticatedPrincipal: effectivePrincipal,
+        ...(sourceConnector ? { sourceConnector } : {}),
         ...(abortSignal ? { abortSignal } : {}),
       })) as { result: unknown };
       throwMcpAbort(abortSignal, "MCP recall aborted before postprocessing");

package/src/access-observe-helpers.ts

@@ -3,10 +3,31 @@ type PendingObservePreparation = {
   scopeHint?: string;
   principal?: string;
   namespace?: string;
+  scopeResolved: boolean;
+  resolvedScopeFences: Array<{ principal?: string; namespace?: string }>;
   released: Promise<void>;
   release: () => void;
 };
 
+function resolvedScopesMatch(
+  left: { principal?: string; namespace?: string },
+  right: { principal?: string; namespace?: string },
+): boolean {
+  return left.principal === right.principal && left.namespace === right.namespace;
+}
+
+function preparationMatchesScope(
+  reservation: PendingObservePreparation,
+  principal: string | undefined,
+  namespace: string | undefined,
+  scopeHint: string | undefined,
+): boolean {
+  if (reservation.scopeResolved) {
+    return resolvedScopesMatch(reservation, { principal, namespace });
+  }
+  return reservation.scopeHint === undefined || scopeHint === undefined || reservation.scopeHint === scopeHint;
+}
+
 export type PendingObservePreparationHandle = {
   isCancelled(): boolean;
   setScope(principal?: string, namespace?: string): void;
@@ -40,6 +61,8 @@ export class PendingObserveExtractionTracker {
     let resolveReleased: () => void = () => {};
     const reservation: PendingObservePreparation = {
       cancelled: false,
+      scopeResolved: false,
+      resolvedScopeFences: [],
       scopeHint,
       released: new Promise<void>((resolve) => {
         resolveReleased = resolve;
@@ -61,15 +84,38 @@ export class PendingObserveExtractionTracker {
       setScope: (principal, namespace) => {
         reservation.principal = principal;
         reservation.namespace = namespace;
+        reservation.scopeResolved = true;
+        if (reservation.resolvedScopeFences.some((fence) => resolvedScopesMatch(reservation, fence))) {
+          reservation.cancelled = true;
+        }
       },
       release: reservation.release,
     };
   }
 
-  private async waitForPreparations(sessionKey: string): Promise<void> {
+  private async waitForPreparations(
+    sessionKey: string,
+    principal: string | undefined,
+    namespace: string | undefined,
+    scopeHint: string | undefined,
+  ): Promise<void> {
     while (true) {
-      const pending = [...(this.preparations.get(sessionKey) ?? [])].filter(
-        (reservation) => !reservation.cancelled,
+      const reservations = [...(this.preparations.get(sessionKey) ?? [])];
+      for (const reservation of reservations) {
+        if (
+          !reservation.cancelled &&
+          !reservation.scopeResolved &&
+          !preparationMatchesScope(reservation, principal, namespace, scopeHint) &&
+          !reservation.resolvedScopeFences.some((fence) =>
+            resolvedScopesMatch(fence, { principal, namespace }),
+          )
+        ) {
+          reservation.resolvedScopeFences.push({ principal, namespace });
+        }
+      }
+      const pending = reservations.filter(
+        (reservation) =>
+          !reservation.cancelled && preparationMatchesScope(reservation, principal, namespace, scopeHint),
       );
       if (pending.length === 0) return;
       await Promise.all(pending.map((reservation) => reservation.released));
@@ -103,6 +149,19 @@ export class PendingObserveExtractionTracker {
       });
   }
 
+  cancelPreparations(sessionKey: string, scopeHint?: string): void {
+    for (const reservation of this.preparations.get(sessionKey) ?? []) {
+      if (
+        scopeHint !== undefined &&
+        reservation.scopeHint !== undefined &&
+        reservation.scopeHint !== scopeHint
+      ) {
+        continue;
+      }
+      reservation.cancelled = true;
+    }
+  }
+
   cancel(
     sessionKey: string,
     principal?: string,
@@ -110,24 +169,7 @@ export class PendingObserveExtractionTracker {
     scopeHint?: string,
   ): void {
     for (const reservation of this.preparations.get(sessionKey) ?? []) {
-      const principalMatches =
-        principal === undefined ||
-        reservation.principal === undefined ||
-        reservation.principal === principal;
-      const namespaceMatches =
-        namespace === undefined ||
-        reservation.namespace === undefined ||
-        reservation.namespace === namespace;
-      const resolvedScopeMatches =
-        namespace !== undefined &&
-        reservation.namespace === namespace &&
-        principalMatches;
-      const scopeHintMismatch =
-        (reservation.scopeHint !== undefined && reservation.scopeHint !== scopeHint) ||
-        (reservation.scopeHint === undefined && scopeHint !== undefined);
-      if ((!resolvedScopeMatches && scopeHintMismatch) || !principalMatches || !namespaceMatches) {
-        continue;
-      }
+      if (!preparationMatchesScope(reservation, principal, namespace, scopeHint)) continue;
       reservation.cancelled = true;
     }
 
@@ -158,7 +200,7 @@ export class PendingObserveExtractionTracker {
     registerCancellation?.(abortTracked);
     abortSignal?.addEventListener("abort", abortTracked, { once: true });
     try {
-      await this.waitForPreparations(sessionKey);
+      await this.waitForPreparations(sessionKey, principal, namespace, scopeHint);
       while (true) {
         const entry = this.entries.get(key);
         if (!entry) return;

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

@@ -110,6 +110,10 @@ export interface AccessObserveWriteSurfaceDeps {
       authenticatedPrincipal?: string;
     }
   ): Promise<MemoryScopePlan>;
+  cancelPendingObservePreparations?(
+    sessionKey: string,
+    scopeHint?: string,
+  ): void;
   cancelPendingObserveExtractions?(
     sessionKey: string,
     principal?: string,
@@ -132,6 +136,10 @@ export class AccessObserveWriteSurface {
   private quarantineStoreInstance?: WriteQuarantineStore;
   private readonly pendingObserveExtractions = new PendingObserveExtractionTracker();
 
+  public cancelPendingObservePreparations(sessionKey: string, scopeHint?: string): void {
+    this.pendingObserveExtractions.cancelPreparations(sessionKey, scopeHint);
+  }
+
   public cancelPendingObserveExtractions(
     sessionKey: string,
     principal?: string,

package/src/access-offline-manifest.ts

@@ -0,0 +1,54 @@
+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 {
+  buildReconcileManifestFile,
+  RECONCILE_MANIFEST_FORMAT,
+  RECONCILE_MANIFEST_SCHEMA_VERSION,
+  type ReconcileManifest,
+  type ReconcileManifestFile,
+  type ReconcileMemoryParser,
+} from "./reconcile/manifest.js";
+
+export interface OfflineSyncManifestRequest {
+  includeTranscripts?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface OfflineSyncManifestStreamResponse extends Omit<ReconcileManifest, "files"> {
+  namespace: string;
+  files: AsyncIterable<ReconcileManifestFile>;
+}
+
+export async function createOfflineSyncManifestStream(
+  orchestrator: Orchestrator,
+  namespace: string,
+  userExcludeRegexps: RegExp[],
+  options: OfflineSyncManifestRequest,
+  parseMemory: ReconcileMemoryParser,
+): Promise<OfflineSyncManifestStreamResponse> {
+  const storage = await offlineSyncStorageForSnapshot(orchestrator, namespace);
+  const snapshotFiles = iterateOfflineSyncSnapshotFileRecords({
+    root: storage.dir,
+    includeContent: false,
+    includeTranscripts: options.includeTranscripts !== false,
+    readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
+    signal: options.signal,
+    userExcludeRegexps,
+  });
+  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,
+        );
+      }
+    })(),
+  };
+}