@remnic/core 9.45.2 → 9.45.4

package/src/access-http.test.ts

@@ -1,12 +1,12 @@
 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";
 import { gzipSync } from "node:zlib";
 
 import { EngramAccessHttpServer, type RemnicAdminControls, type RemnicAdminDashboardStatus } from "./access-http.js";
-import { EngramAccessInputError, type EngramAccessService } from "./access-service.js";
+import { EngramAccessInputError, type EngramAccessRecallRequest, type EngramAccessService } from "./access-service.js";
 import { tokenCapabilityStore, type TokenCapabilities } from "./access-token-capabilities.js";
 import { parseConfig } from "./config.js";
 import { readPair, writePair } from "./contradiction/contradiction-review.js";
@@ -858,6 +858,7 @@ test("HTTP offline snapshot forwards namespace and transfer options", async () =
         createdAt: new Date("2026-05-21T00:00:00Z").toISOString(),
         sourceId: "remote:test",
         includeTranscripts: options.includeTranscripts !== false,
+        deletions: [{ path: "facts/deleted.md", mtimeMs: 1235 }],
         files: [],
       };
     },
@@ -876,12 +877,18 @@ test("HTTP offline snapshot forwards namespace and transfer options", async () =
       `http://127.0.0.1:${status.port}/remnic/v1/offline-sync/snapshot?namespace=team&include_transcripts=false&content=false`,
       { headers: { authorization: "Bearer test-token" } },
     );
-    const body = await response.json() as { namespace?: string; includeTranscripts?: boolean; files?: unknown[] };
+    const body = await response.json() as {
+      namespace?: string;
+      includeTranscripts?: boolean;
+      files?: unknown[];
+      deletions?: unknown[];
+    };
 
     assert.equal(response.status, 200);
     assert.equal(body.namespace, "team");
     assert.equal(body.includeTranscripts, false);
     assert.deepEqual(body.files, []);
+    assert.deepEqual(body.deletions, [{ path: "facts/deleted.md", mtimeMs: 1235 }]);
     assert.deepEqual(calls, [{
       namespace: "team",
       principal: "reader",
@@ -1016,6 +1023,7 @@ test("HTTP offline snapshot stream emits metadata records as NDJSON", async () =
         createdAt: new Date("2026-05-21T00:00:00Z").toISOString(),
         sourceId: "remote:test",
         includeTranscripts: options.includeTranscripts !== false,
+        deletions: [{ path: "facts/deleted.md", mtimeMs: 1235 }],
         files: (async function* () {
           yield {
             path: "facts/a.md",
@@ -1050,6 +1058,7 @@ test("HTTP offline snapshot stream emits metadata records as NDJSON", async () =
     assert.equal(response.headers.get("content-type"), "application/x-ndjson; charset=utf-8");
     assert.equal(lines[0]?.type, "snapshot");
     assert.equal(lines[0]?.namespace, "team");
+    assert.deepEqual(lines[0]?.deletions, [{ path: "facts/deleted.md", mtimeMs: 1235 }]);
     assert.equal(lines[1]?.type, "file");
     assert.deepEqual((lines[1]?.file as { path?: string }).path, "facts/a.md");
     assert.deepEqual(calls, [{
@@ -1062,6 +1071,120 @@ test("HTTP offline snapshot stream emits metadata records as NDJSON", async () =
     await server.stop();
   }
 });
+test("HTTP offline manifest stream preserves snapshot-stream auth and emits body-free rows", async () => {
+  const calls: Array<Record<string, unknown>> = [];
+  const service = {
+    offlineSyncManifestStream: async (options: Record<string, unknown>) => {
+      calls.push(options);
+      return {
+        namespace: options.namespace ?? "default",
+        format: "remnic-reconcile-manifest",
+        schemaVersion: 1,
+        files: (async function* () {
+          yield {
+            path: "facts/a.md",
+            sha256: "a".repeat(64),
+            bytes: 12,
+            mtimeMs: 1234,
+            memory: {
+              id: "fact-a",
+              status: "active",
+              category: "fact",
+              contentHash: "b".repeat(64),
+            },
+          };
+        })(),
+      };
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    principal: "reader",
+    authTokenEntriesGetter: () => [
+      { token: "wrong-op", capabilities: { version: 1, ops: ["offline_sync_snapshot"] } },
+      {
+        token: "wrong-namespace",
+        capabilities: { version: 1, ops: ["offline_sync_snapshot_stream"], namespaces: ["other"] },
+      },
+      {
+        token: "reader",
+        capabilities: { version: 1, ops: ["offline_sync_snapshot_stream"], namespaces: ["team"] },
+      },
+    ],
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  const request = (token: string, query = "namespace=team&include_transcripts=false") =>
+    fetch(`http://127.0.0.1:${status.port}/remnic/v1/offline-sync/manifest-stream?${query}`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+  try {
+    assert.equal((await request("wrong-op")).status, 403);
+    assert.equal((await request("wrong-namespace")).status, 403);
+    assert.equal(calls.length, 0);
+    assert.equal((await request("reader", "namespace=team&include_transcripts=invalid")).status, 400);
+    assert.equal((await request("reader", "namespace=team&content=true")).status, 400);
+    assert.equal(calls.length, 0);
+
+    const response = await request("reader");
+    const text = await response.text();
+    const lines = text.trim().split("\n").map((line) => JSON.parse(line) as Record<string, unknown>);
+    assert.equal(response.status, 200);
+    assert.equal(response.headers.get("content-type"), "application/x-ndjson; charset=utf-8");
+    assert.equal(lines[0]?.type, "manifest");
+    assert.equal(lines[1]?.type, "file");
+    assert.deepEqual(lines[1]?.file, {
+      path: "facts/a.md",
+      sha256: "a".repeat(64),
+      bytes: 12,
+      mtimeMs: 1234,
+      memory: {
+        id: "fact-a",
+        status: "active",
+        category: "fact",
+        contentHash: "b".repeat(64),
+      },
+    });
+    assert.doesNotMatch(text, /contentBase64|rawContent|memory body/);
+    assert.deepEqual({
+      namespace: calls[0]?.namespace,
+      principal: calls[0]?.principal,
+      includeTranscripts: calls[0]?.includeTranscripts,
+    }, {
+      namespace: "team",
+      principal: "reader",
+      includeTranscripts: false,
+    });
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP offline sync capabilities advertise manifest streaming", async () => {
+  const server = new EngramAccessHttpServer({
+    service: {} as EngramAccessService,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${status.port}/engram/v1/offline-sync/capabilities`,
+      { headers: { authorization: "Bearer test-token" } },
+    );
+    assert.equal(response.status, 200);
+    assert.deepEqual(await response.json(), {
+      version: 1,
+      convergenceFinalization: true,
+      manifestStream: true,
+    });
+  } finally {
+    await server.stop();
+  }
+});
+
 
 test("HTTP offline files forwards namespace and requested paths", async () => {
   const calls: Array<{
@@ -2960,6 +3083,42 @@ test("HTTP chat/message gates the NEW session's namespace — scoped token canno
   }
 });
 
+test("HTTP recall forwards the connector from the authorized token entry", async () => {
+  let captured: EngramAccessRecallRequest | undefined;
+  const service = {
+    recall: (request: EngramAccessRecallRequest) => {
+      captured = request;
+      return Promise.resolve({ context: "", count: 0, memoryIds: [], results: [] });
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authTokenEntriesGetter: () => [
+      { token: "connector-token", connector: "chatgpt" },
+    ],
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${status.port}/engram/v1/recall`,
+      {
+        method: "POST",
+        headers: {
+          authorization: "Bearer connector-token",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ query: "shared namespace query" }),
+      },
+    );
+    assert.equal(response.status, 200);
+    assert.equal(captured?.sourceConnector, "chatgpt");
+  } finally {
+    await server.stop();
+  }
+});
+
 // ---------------------------------------------------------------------------
 // PR #1852: token-rotation race — authorized entry must be reused for provenance
 // ---------------------------------------------------------------------------
@@ -3649,6 +3808,34 @@ test("HTTP authorization probe verifies requested operation grants without invok
   }
 });
 
+test("HTTP capabilities explicitly advertise receiver convergence finalization", async () => {
+  const service = {} as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    const route = `http://127.0.0.1:${status.port}/engram/v1/capabilities`;
+    const denied = await fetch(route);
+    assert.equal(denied.status, 401);
+
+    const response = await fetch(route, {
+      headers: { authorization: "Bearer test-token" },
+    });
+    assert.equal(response.status, 200);
+    assert.deepEqual(await response.json(), {
+      lcmCompactionFlushBatch: true,
+      offlineSyncConvergenceComplete: true,
+    });
+  } finally {
+    await server.stop();
+  }
+});
+
 test("HTTP convergence completion forwards one authenticated namespace batch refresh", async () => {
   const calls: Array<{ namespaces: string[]; principal?: string; sourceId: string }> = [];
   const service = {
@@ -3701,6 +3888,50 @@ test("HTTP convergence completion forwards one authenticated namespace batch ref
   }
 });
 
+test("HTTP convergence completion accepts either receiver mutation grant", async () => {
+  let completions = 0;
+  const service = {
+    offlineSyncFinalizeConvergence: async () => {
+      completions += 1;
+      return { namespaces: ["team"], refreshed: true as const };
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authTokenEntriesGetter: () => [
+      { token: "file-token", capabilities: { version: 1, ops: ["offline_sync_apply_file_content"] } },
+      { token: "delete-token", capabilities: { version: 1, ops: ["offline_sync_apply"] } },
+      { token: "read-token", capabilities: { version: 1, ops: ["offline_sync_snapshot"] } },
+    ],
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  const route = `http://127.0.0.1:${status.port}/remnic/v1/offline-sync/convergence-complete?namespace=team`;
+  const complete = (token: string) => fetch(route, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "x-remnic-source-id": encodeURIComponent("remnic-converge"),
+    },
+  });
+
+  try {
+    const fileResponse = await complete("file-token");
+    assert.equal(fileResponse.status, 200);
+    await fileResponse.text();
+    const deleteResponse = await complete("delete-token");
+    assert.equal(deleteResponse.status, 200);
+    await deleteResponse.text();
+    const deniedResponse = await complete("read-token");
+    assert.equal(deniedResponse.status, 403);
+    await deniedResponse.text();
+    assert.equal(completions, 2);
+  } finally {
+    await server.stop();
+  }
+});
+
 test("HTTP convergence completion enforces the per-principal write rate limit", async () => {
   let completions = 0;
   const service = {
@@ -3784,3 +4015,79 @@ test("HTTP convergence completion denies scoped tokens that omit the namespace",
     await server.stop();
   }
 });
+
+test("HTTP external wiki search aliases return the same cited result", async () => {
+  const rootDir = await mkdtemp(path.join(os.tmpdir(), "remnic-http-external-wiki-"));
+  await mkdir(path.join(rootDir, "wiki"), { recursive: true });
+  await writeFile(
+    path.join(rootDir, "INDEX.md"),
+    "- [[wiki/planning|Planning Systems]] - deterministic planner fan-out\n",
+    "utf8",
+  );
+  await writeFile(
+    path.join(rootDir, "wiki", "planning.md"),
+    "# Planning Systems\n\nDeterministic planner fan-out keeps cited evidence.\n",
+    "utf8",
+  );
+  const service = {
+    configRef: {
+      externalWikis: [{
+        id: "planning",
+        rootDir,
+        enabled: true,
+        pagesDir: "wiki",
+        indexFile: "INDEX.md",
+        indexInQmd: false,
+        includeInDefaultRecall: false,
+      }],
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    let canonicalBody: unknown;
+    for (const prefix of ["remnic", "engram"]) {
+      const response = await fetch(`http://127.0.0.1:${status.port}/${prefix}/v1/external-wikis/search`, {
+        method: "POST",
+        headers: {
+          authorization: "Bearer test-token",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          query: "deterministic planner",
+          wikiId: "planning",
+          limit: 2,
+          maxCharsPerHit: 200,
+        }),
+      });
+      assert.equal(response.status, 200);
+      const body: unknown = await response.json();
+      if (canonicalBody === undefined) canonicalBody = body;
+      else assert.deepEqual(body, canonicalBody);
+    }
+    assert.ok(canonicalBody && typeof canonicalBody === "object" && "hits" in canonicalBody);
+    assert.ok(Array.isArray(canonicalBody.hits));
+    const firstHit = canonicalBody.hits[0];
+    assert.ok(firstHit && typeof firstHit === "object" && "path" in firstHit);
+    assert.equal(firstHit.path, "wiki/planning.md");
+
+    const invalid = await fetch(`http://127.0.0.1:${status.port}/remnic/v1/external-wikis/search`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ query: "  " }),
+    });
+    assert.equal(invalid.status, 400);
+  } finally {
+    await server.stop();
+    await rm(rootDir, { recursive: true, force: true });
+  }
+});

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")
@@ -3417,6 +3471,7 @@ export class EngramAccessHttpServer {
       createdAt: snapshot.createdAt,
       sourceId: snapshot.sourceId,
       includeTranscripts: snapshot.includeTranscripts,
+      deletions: snapshot.deletions,
     })) return;
     for await (const file of snapshot.files) {
       if (!await writeLine({ type: "file", file })) return;
@@ -3856,6 +3911,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 }),