@remnic/core 9.45.2 → 9.45.4

package/src/correction/correction-planner.test.ts

@@ -17,6 +17,7 @@ import path from "node:path";
 import { test } from "node:test";
 
 import { withTempDir as managedWithTempDir } from "../testing/tmp-dir.js";
+import { writeFileAtomically } from "../maintenance/atomic-file.js";
 import {
   CorrectionContractError,
   MEMORY_CATEGORIES,
@@ -301,6 +302,41 @@ test("plan persists atomically to state/corrections/pending/<planId>.json and ro
   });
 });
 
+test("#2206 cancellation after atomic plan commit returns the persisted plan without temp files", async () => {
+  await withTempDir(async (dir) => {
+    const state: StubState = {
+      candidatesById: new Map([["mem-x", makeCandidate({ memoryId: "mem-x", content: "old fact" })]]),
+      llmResult: {
+        classification: "outdated",
+        confidence: 0.9,
+        actions: [{ kind: "edit", memoryId: "mem-x", patch: "new fact" }],
+        relevance: [{ memoryId: "mem-x", why: "outdated" }],
+        warnings: [],
+      },
+      writeReplacementCalls: 0,
+      propagateCalls: 0,
+      retireCalls: 0,
+    };
+    const abortController = new AbortController();
+    const deps = makeDeps(dir, state);
+    deps.writePlanFile = async (outputPath, content) => {
+      await writeFileAtomically(outputPath, content);
+      abortController.abort(new Error("correction deadline exceeded"));
+    };
+    const planner = new CorrectionPlanner(deps);
+
+    const plan = await planner.plan(
+      { text: "old fact", targetIds: ["mem-x"] },
+      ["default"],
+      { abortSignal: abortController.signal },
+    );
+    const pendingDir = path.join(dir, "state", "corrections", "pending");
+    assert.equal(abortController.signal.aborted, true);
+    assert.equal((await planner.loadPlan("default", plan.planId))?.planId, plan.planId);
+    assert.equal((await readdir(pendingDir)).some((name) => name.endsWith(".tmp")), false);
+  });
+});
+
 test("plan expires after TTL — apply-time rejection is tested in executor; here we verify the timestamp", async () => {
   await withTempDir(async (dir) => {
     const state: StubState = {

package/src/correction/correction-planner.ts

@@ -20,9 +20,10 @@
  * only thing it persists is the plan document itself.
  */
 
-import { throwIfAborted } from "../abort-error.js";
-import { mkdir, readFile, rename, unlink, readdir, writeFile } from "node:fs/promises";
+import { readFile, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
+import { throwIfAborted } from "../abort-error.js";
+import { writeFileAtomically } from "../maintenance/atomic-file.js";
 import { serializeMutations } from "../utils/serialize-mutations.js";
 import {
   CORRECTION_TEXT_MAX,
@@ -109,6 +110,8 @@ export interface PlannerDeps {
   }): Promise<string>;
   /** Per-namespace storage dir root (so the plan lands in the right state/). */
   storageDir(namespace: string): Promise<string>;
+  /** Atomic persistence seam used by focused lifecycle tests. */
+  writePlanFile?: (outputPath: string, content: string) => Promise<unknown>;
   /** Max affected memories per plan (issue config: default 10). */
   readonly maxAffected: number;
   /** Plan TTL in hours (issue config: default 24). */
@@ -431,13 +434,8 @@ export class CorrectionPlanner {
       : plan;
     await serializeMutations(`correction-plan:${target}`, async () => {
       throwIfAborted(abortSignal, "correction planning aborted");
-      await mkdir(dir, { recursive: true });
-      const tmp = `${target}.${process.pid}.${Date.now().toString(36)}.tmp`;
-      throwIfAborted(abortSignal, "correction planning aborted");
-      await writeFile(tmp, `${JSON.stringify(persistedPlan)}\n`, "utf-8");
-      throwIfAborted(abortSignal, "correction planning aborted");
-      // rename() is atomic on POSIX for same-filesystem renames (rule 54).
-      await rename(tmp, target);
+      const writePlanFile = this.deps.writePlanFile ?? writeFileAtomically;
+      await writePlanFile(target, `${JSON.stringify(persistedPlan)}\n`);
     });
     return plan;
   }
@@ -520,9 +518,7 @@ export class CorrectionPlanner {
             : a,
         );
       }
-      const tmp = `${file}.${process.pid}.${Date.now().toString(36)}.tmp`;
-      await writeFile(tmp, `${JSON.stringify(plan)}\n`, "utf-8");
-      await rename(tmp, file);
+      await writeFileAtomically(file, `${JSON.stringify(plan)}\n`);
     });
   }
   /**
@@ -545,9 +541,7 @@ export class CorrectionPlanner {
       if (!plan || plan.status !== "applying") return;
       plan.status = "pending";
       delete plan.applyingAt;
-      const tmp = `${file}.${process.pid}.${Date.now().toString(36)}.tmp`;
-      await writeFile(tmp, `${JSON.stringify(plan)}\n`, "utf-8");
-      await rename(tmp, file);
+      await writeFileAtomically(file, `${JSON.stringify(plan)}\n`);
     });
   }
 

package/src/correction/correction-service.ts

@@ -52,6 +52,7 @@ export interface CorrectionNamespacePolicy {
     namespace: string;
     sessionKey?: string;
     principal?: string;
+    abortSignal?: AbortSignal;
   }): Promise<boolean>;
   /** Namespaces the caller may read — scopes the planner's search. */
   readableNamespaces(request: {
@@ -144,11 +145,12 @@ export class CorrectionService {
       abortSignal: opts.abortSignal,
       // Authorize rescope destinations through the namespace policy bound to
       // THIS caller's principal (review thread: authorize-rescope-destination).
-      canWriteDestination: (dest) =>
+      canWriteDestination: (dest, abortSignal) =>
         this.deps.policy.canWriteNamespace({
           namespace: dest,
           ...(opts.sessionKey ? { sessionKey: opts.sessionKey } : {}),
           ...(opts.principal ? { principal: opts.principal } : {}),
+          ...(abortSignal ? { abortSignal } : {}),
         }),
     });
   }

package/src/correction/correction-storage-integration.test.ts

@@ -16,12 +16,17 @@ import type { MemoryFile } from "../types.js";
 
 import { StorageManager, ContentHashIndex } from "../storage.js";
 import { sanitizeMemoryContent } from "../sanitize.js";
+import { loadRedactionRules } from "../extraction-redaction-rules.js";
+import { writeFileAtomically } from "../maintenance/atomic-file.js";
 import {
+  type CorrectionAccessWiring,
   isEligibleCorrectionCandidate,
   applyEditMemory,
   appendTombstoneFn,
+  appendAuditRecordFn,
   retireMemoryFn,
   rescopeMemoryFn,
+  registerRedactionRuleFn,
   writeReplacementMemory,
 } from "./correction-access-wiring.js";
 
@@ -292,6 +297,78 @@ test("#2128 tombstone append returns its committed id after cancellation", async
   }
 });
 
+test("#2206 redaction adapter returns after a committed rule write despite cancellation", async () => {
+  const { storage, cleanup } = await makeStorage("remnic-corr-redaction-abort-");
+  try {
+    const abortController = new AbortController();
+    let commitCompleted = false;
+    const wiring = {
+      orchestrator: { getStorage: async () => storage },
+    } as unknown as CorrectionAccessWiring;
+
+    await registerRedactionRuleFn(
+      wiring,
+      "default",
+      "do-not-store-this",
+      abortController.signal,
+      async (outputPath, content) => {
+        await writeFileAtomically(outputPath, content);
+        commitCompleted = true;
+        abortController.abort(new Error("correction deadline exceeded"));
+      },
+    );
+
+    assert.equal(commitCompleted, true);
+    assert.deepEqual(
+      (await loadRedactionRules(storage.dir)).map((rule) => rule.pattern),
+      ["do-not-store-this"],
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+test("#2206 audit adapter returns its committed id despite cancellation", async () => {
+  const { storage, cleanup } = await makeStorage("remnic-corr-audit-abort-");
+  try {
+    const originalWriteSealedMemory = storage.writeSealedMemory.bind(storage);
+    const abortController = new AbortController();
+    let committed = false;
+    storage.writeSealedMemory = async (...args: Parameters<typeof storage.writeSealedMemory>) => {
+      const result = await originalWriteSealedMemory(...args);
+      committed = true;
+      abortController.abort(new Error("correction deadline exceeded"));
+      return result;
+    };
+    const wiring = {
+      orchestrator: { getStorage: async () => storage },
+    } as unknown as CorrectionAccessWiring;
+
+    const auditId = await appendAuditRecordFn(
+      wiring,
+      "default",
+      {
+        planId: "plan-2206",
+        classification: "outdated",
+        outcome: {
+          planId: "plan-2206",
+          status: "partial",
+          results: [],
+          auditMemoryId: "",
+          appliedAt: "2026-07-30T00:00:00.000Z",
+        },
+        requestText: "update the stored fact",
+      },
+      abortController.signal,
+    );
+
+    assert.equal(committed, true);
+    assert.equal((await storage.getMemoryById(auditId))?.frontmatter.category, "correction");
+  } finally {
+    await cleanup();
+  }
+});
+
 // ---------------------------------------------------------------------------
 // item 4: per-key tombstone emission
 // ---------------------------------------------------------------------------

package/src/correction/correction-surfaces.test.ts

@@ -39,8 +39,8 @@ function extractToolNames(response: unknown): Set<string> {
 }
 
 interface MockCalls {
-  planRequests: Array<{ text: string; targetIds?: string[]; principal?: string }>;
-  applyRequests: Array<{ planId: string; confirm: boolean; principal?: string }>;
+  planRequests: Array<{ text: string; targetIds?: string[]; principal?: string; abortSignal?: AbortSignal }>;
+  applyRequests: Array<{ planId: string; confirm: boolean; principal?: string; abortSignal?: AbortSignal }>;
 }
 
 function makeMockService(
@@ -50,22 +50,26 @@ function makeMockService(
   const calls: MockCalls = { planRequests: [], applyRequests: [] };
   const service = {
     briefingEnabled: true,
-    correctionPlan(req: {
-      text: string;
-      targetIds?: string[];
-      principal?: string;
-    }): Promise<CorrectionPlan> {
-      calls.planRequests.push(req);
+    correctionPlan(
+      req: {
+        text: string;
+        targetIds?: string[];
+        principal?: string;
+      },
+      opts?: { abortSignal?: AbortSignal },
+    ): Promise<CorrectionPlan> {
+      calls.planRequests.push({ ...req, ...(opts?.abortSignal ? { abortSignal: opts.abortSignal } : {}) });
       return Promise.resolve(planResponse);
     },
     correctionApply(
       planId: string,
-      opts: { confirm?: boolean; principal?: string },
+      opts: { confirm?: boolean; principal?: string; abortSignal?: AbortSignal },
     ): Promise<CorrectionOutcome> {
       calls.applyRequests.push({
         planId,
         confirm: opts.confirm === true,
         ...(opts.principal ? { principal: opts.principal } : {}),
+        ...(opts.abortSignal ? { abortSignal: opts.abortSignal } : {}),
       });
       return Promise.resolve(applyResponse);
     },
@@ -130,22 +134,26 @@ test("tools/list gate: correction tools present when correctionVisible on (defau
 // MCP dispatch: tools/call → boundary operation → service method
 // ---------------------------------------------------------------------------
 
-test("MCP surface: memory_correct_plan dispatches to service.correctionPlan", async () => {
+test("MCP surface: memory_correct_plan forwards the request abort signal", async () => {
   const { service, calls } = makeMockService(STUB_PLAN, STUB_OUTCOME);
   const server = new EngramMcpServer(service, { emitLegacyTools: true, correctionVisible: true });
-  const response = await server.handleRequest({
-    jsonrpc: "2.0",
-    id: 1,
-    method: "tools/call",
-    params: {
-      name: "engram.memory_correct_plan",
-      arguments: { text: "we migrated to MySQL in March", targetIds: ["mem-1"] },
+  const abortController = new AbortController();
+  const response = await server.handleRequest(
+    {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: {
+        name: "engram.memory_correct_plan",
+        arguments: { text: "we migrated to MySQL in March", targetIds: ["mem-1"] },
+      },
     },
-  });
+    { abortSignal: abortController.signal },
+  );
   assert.equal(calls.planRequests.length, 1, "service.correctionPlan called exactly once");
   assert.equal(calls.planRequests[0]?.text, "we migrated to MySQL in March");
   assert.deepEqual(calls.planRequests[0]?.targetIds, ["mem-1"]);
-  // The response result is the plan returned by the service.
+  assert.equal(calls.planRequests[0]?.abortSignal, abortController.signal);
   assert.equal(
     typeof response === "object" && response !== null && "result" in response,
     true,
@@ -153,21 +161,26 @@ test("MCP surface: memory_correct_plan dispatches to service.correctionPlan", as
   );
 });
 
-test("MCP surface: memory_correct_apply dispatches to service.correctionApply with confirm", async () => {
+test("MCP surface: memory_correct_apply forwards confirmation and the request abort signal", async () => {
   const { service, calls } = makeMockService(STUB_PLAN, STUB_OUTCOME);
   const server = new EngramMcpServer(service, { emitLegacyTools: true, correctionVisible: true });
-  await server.handleRequest({
-    jsonrpc: "2.0",
-    id: 2,
-    method: "tools/call",
-    params: {
-      name: "engram.memory_correct_apply",
-      arguments: { planId: "corr-test-1", confirm: true },
+  const abortController = new AbortController();
+  await server.handleRequest(
+    {
+      jsonrpc: "2.0",
+      id: 2,
+      method: "tools/call",
+      params: {
+        name: "engram.memory_correct_apply",
+        arguments: { planId: "corr-test-1", confirm: true },
+      },
     },
-  });
+    { abortSignal: abortController.signal },
+  );
   assert.equal(calls.applyRequests.length, 1, "service.correctionApply called exactly once");
   assert.equal(calls.applyRequests[0]?.planId, "corr-test-1");
   assert.equal(calls.applyRequests[0]?.confirm, true);
+  assert.equal(calls.applyRequests[0]?.abortSignal, abortController.signal);
 });
 
 test("MCP surface: remnic.memory_correct_plan alias dispatches identically", async () => {

package/src/correction/passive-capture.test.ts

@@ -165,6 +165,65 @@ test("dedup: different bufferKey → both processed", async () => {
   assert.strictEqual(dedup.size, 2);
 });
 
+test("#2206 dedup records a plan that commits as cancellation arrives", async () => {
+  const plan = makePlan();
+  const abortController = new AbortController();
+  let planningCalls = 0;
+  const deps = mockDeps(plan);
+  deps.planCorrection = async () => {
+    planningCalls += 1;
+    abortController.abort(new Error("extraction deadline exceeded"));
+    return plan;
+  };
+  const dedup = new Set<string>();
+  const correction = makeCorrection();
+
+  const first = await capturePassiveCorrections(
+    [correction],
+    { ...LIVE_CTX, abortSignal: abortController.signal },
+    QUEUE_CONFIG,
+    deps,
+    dedup,
+  );
+  const second = await capturePassiveCorrections(
+    [correction],
+    LIVE_CTX,
+    QUEUE_CONFIG,
+    deps,
+    dedup,
+  );
+
+  assert.deepEqual(first.plans.map((candidate) => candidate.planId), [plan.planId]);
+  assert.equal(first.telemetry.queued, 1, "the committed pending plan must count as queued");
+  assert.equal(dedup.size, 1);
+  assert.equal(second.telemetry.queued, 0);
+  assert.equal(planningCalls, 1);
+});
+
+test("#2206 auto mode counts a plan left pending when cancellation lands at commit", async () => {
+  const plan = makePlan({ confidence: 0.9, classification: "outdated" });
+  const abortController = new AbortController();
+  const appliedPlans: string[] = [];
+  const deps = mockDeps(plan, { appliedPlans });
+  deps.planCorrection = async () => {
+    abortController.abort(new Error("extraction deadline exceeded"));
+    return plan;
+  };
+
+  const result = await capturePassiveCorrections(
+    [makeCorrection()],
+    { ...LIVE_CTX, abortSignal: abortController.signal },
+    AUTO_CONFIG,
+    deps,
+    new Set<string>(),
+  );
+
+  assert.equal(abortController.signal.aborted, true, "cancellation must land as planning commits");
+  assert.deepEqual(result.plans.map((candidate) => candidate.planId), [plan.planId]);
+  assert.equal(result.telemetry.queued, 1);
+  assert.deepEqual(appliedPlans, []);
+});
+
 // ---------------------------------------------------------------------------
 // Auto mode + guards
 // ---------------------------------------------------------------------------

package/src/correction/passive-capture.ts

@@ -262,10 +262,13 @@ export async function capturePassiveCorrections(
       );
       continue;
     }
-    if (ctx.abortSignal?.aborted) return { telemetry, plans };
     plans.push(plan);
     // Record the fingerprint only after a successful plan.
     dedupState.add(fp);
+    if (ctx.abortSignal?.aborted) {
+      telemetry.queued += 1;
+      return { telemetry, plans };
+    }
 
     // 3. Dispatch by mode
     if (config.mode === "queue") {

package/src/entity-retrieval-boundaries.ts

@@ -64,6 +64,19 @@ function isIntlWordBoundary(source: string, index: number): boolean {
   return UNICODE_WORD_SEGMENTER?.segment(source).containing(index)?.index === index;
 }
 
+function isStandaloneJapaneseLeadingParticle(
+  particle: string,
+  source: string,
+  boundaryIndex: number,
+): boolean {
+  if (!JAPANESE_WORD_SEGMENTER || boundaryIndex <= 0 || !JAPANESE_PARTICLE_RE.test(particle)) {
+    return false;
+  }
+  const particleStart = boundaryIndex - particle.length;
+  const segment = JAPANESE_WORD_SEGMENTER.segment(source).containing(particleStart);
+  return segment?.index === particleStart
+    && segment.index + segment.segment.length === boundaryIndex;
+}
 function isKoreanUnspacedQuestionBoundary(suffix: string): boolean {
   return KOREAN_UNSPACED_QUESTION_PARTICLES.some((particle) =>
     suffix.startsWith(particle) &&
@@ -91,18 +104,15 @@ function isUnicodePhraseBoundary(
   source: string = "",
   boundaryIndex: number = -1,
   strictUnicode = false,
-  allowLeadingParticle = false,
 ): boolean {
   return (
     character.length === 0
     || !UNICODE_WORD_OR_NUMBER_RE.test(character)
-    || (allowLeadingParticle && isJapaneseParticleBoundary(character))
     || isJapaneseParticleBoundary(suffix)
     || (!strictUnicode &&
       boundaryIndex >= 0 &&
       !JAPANESE_KANA_RE.test(suffix) &&
       isIntlWordBoundary(source, boundaryIndex))
-    || (allowLeadingParticle && isKoreanParticleBoundary(character))
     || isKoreanParticleBoundary(suffix)
   );
 }
@@ -117,7 +127,10 @@ export function containsPhrase(haystack: string, needle: string): boolean {
     const before = lastUnicodeCharacter(searchHaystack.slice(0, offset));
     const after = searchHaystack.slice(offset + searchNeedle.length);
     if (
-      isUnicodePhraseBoundary(before, "", searchHaystack, offset, caseInsensitive, true)
+      (
+        isUnicodePhraseBoundary(before, "", searchHaystack, offset, caseInsensitive)
+        || isStandaloneJapaneseLeadingParticle(before, searchHaystack, offset)
+      )
       && isUnicodePhraseBoundary(
         firstUnicodeCharacter(after),
         after,

package/src/entity-retrieval.ts

@@ -403,23 +403,37 @@ async function readCurrentPersistedEntityIndex(
 const namespaceEntityIndexCache = new Map<string, EntityMentionIndex>();
 const MAX_NAMESPACE_ENTITY_INDEX_CACHE_ENTRIES = 32;
 
+function nativeEntityIndexRevision(chunks: NativeKnowledgeChunk[]): string {
+  const projection = chunks.map((chunk) => [
+    chunk.chunkId,
+    chunk.sourcePath,
+    chunk.title,
+    chunk.sourceKind,
+    uniqueStrings(chunk.aliases ?? []),
+    compactLine(chunk.content, 180),
+    chunk.derivedDate ?? null,
+  ]);
+  return createHash("sha256").update(JSON.stringify(projection)).digest("hex");
+}
+
 function namespaceEntityIndexCacheKey(
   storages: StorageManager[],
   recallNamespaces: string[],
+  nativeRevision: string,
 ): string {
-  const namespaceKey = uniqueStrings(recallNamespaces).sort().join("\u001f");
+  const namespaceKey = uniqueStrings(recallNamespaces).join("\u001f");
   const storageKey = storages
     .map((scopedStorage) => {
       const aliases = Object.entries(scopedStorage.entityAliases)
         .sort(([left], [right]) => left.localeCompare(right));
       return (
         `${path.resolve(scopedStorage.dir)}@${scopedStorage.getMemoryStatusVersion()}` +
-        `:${scopedStorage.getMemoryCorpusVersion()}:${scopedStorage.hotCacheKeyId()}:${JSON.stringify(aliases)}`
+        `:${scopedStorage.getMemoryCorpusVersion()}:${scopedStorage.getEntityMutationVersion()}` +
+        `:${scopedStorage.hotCacheKeyId()}:${JSON.stringify(aliases)}`
       );
     })
-    .sort()
     .join("\u001f");
-  return `${namespaceKey}\u001e${storageKey}`;
+  return `${namespaceKey}\u001e${storageKey}\u001e${nativeRevision}`;
 }
 
 function rememberNamespaceEntityIndex(key: string, index: EntityMentionIndex): void {
@@ -1030,6 +1044,9 @@ export async function buildEntityRecallSection(options: BuildEntityRecallSection
     resolveNamespaceCapabilities(options.config).namespaces &&
     options.namespaceStorage !== undefined &&
     (options.recallNamespaces?.length ?? 0) > 0;
+  if (namespaceScoped) {
+    nativeChunks = await readNativeChunks(options.config, options.recallNamespaces);
+  }
   const resolvedStorages = namespaceScoped
     ? await resolveEntityIndexStorages(
       options.storage,
@@ -1039,8 +1056,12 @@ export async function buildEntityRecallSection(options: BuildEntityRecallSection
     )
     : undefined;
   const namespaceCacheKey =
-    resolvedStorages && options.recallNamespaces
-      ? namespaceEntityIndexCacheKey(resolvedStorages, options.recallNamespaces)
+    resolvedStorages && options.recallNamespaces && nativeChunks
+      ? namespaceEntityIndexCacheKey(
+        resolvedStorages,
+        options.recallNamespaces,
+        nativeEntityIndexRevision(nativeChunks),
+      )
       : undefined;
   let index: EntityMentionIndex | undefined = namespaceCacheKey
     ? namespaceEntityIndexCache.get(namespaceCacheKey)

package/src/external-wiki-access.test.ts

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+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 type { EngramAccessService } from "./access-service.js";
+import { externalWikiSearchOperation } from "./external-wiki-access.js";
+import type { ExternalWikiRoot } from "./external-wiki.js";
+
+async function fixtureRoot(): Promise<ExternalWikiRoot> {
+  const rootDir = await mkdtemp(path.join(os.tmpdir(), "remnic-external-wiki-access-"));
+  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"
+  );
+  return {
+    id: "planning",
+    rootDir,
+    enabled: true,
+    pagesDir: "wiki",
+    indexFile: "INDEX.md",
+    indexInQmd: false,
+    includeInDefaultRecall: false,
+  };
+}
+
+test("external wiki operation searches roots from the service config", async () => {
+  const root = await fixtureRoot();
+  try {
+    const service = { configRef: { externalWikis: [root] } } as EngramAccessService;
+    const output = await externalWikiSearchOperation.run(
+      { query: "deterministic planner", limit: 2, maxCharsPerHit: 200 },
+      { service }
+    );
+    assert.equal(output.result.hits[0]?.wikiId, "planning");
+    assert.equal(output.result.hits[0]?.path, "wiki/planning.md");
+  } finally {
+    await rm(root.rootDir, { recursive: true, force: true });
+  }
+});
+
+test("external wiki operation rejects empty query and unknown fields", async () => {
+  let configRead = false;
+  const service = {
+    get configRef() {
+      configRead = true;
+      return { externalWikis: [] };
+    },
+  } as unknown as EngramAccessService;
+
+  await assert.rejects(externalWikiSearchOperation.run({ query: "  " }, { service }), /query is required/i);
+  await assert.rejects(
+    externalWikiSearchOperation.run({ query: "topic", unexpected: true }, { service }),
+    /unrecognized key/i
+  );
+  assert.equal(configRead, false);
+});

package/src/external-wiki-access.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+
+import { defineOperation } from "./access-boundary.js";
+import {
+  type ExternalWikiSearchInput,
+  type ExternalWikiSearchResult,
+  searchExternalWikis,
+} from "./external-wiki-search.js";
+
+const externalWikiSearchSchema = z
+  .object({
+    query: z.string().trim().min(1, "query is required").max(2_048),
+    limit: z.number().int().min(1).max(20).optional(),
+    wikiId: z.string().trim().min(1).max(256).optional(),
+    maxCharsPerHit: z.number().int().min(1).max(8_000).optional(),
+  })
+  .strict();
+
+export interface ExternalWikiSearchOutput {
+  readonly result: ExternalWikiSearchResult;
+}
+
+export const externalWikiSearchOperation = defineOperation<ExternalWikiSearchInput, ExternalWikiSearchOutput>({
+  name: "external_wiki_search",
+  description: "Search configured external compiled-wiki roots and return cited snippets.",
+  schema: externalWikiSearchSchema,
+  fleetWide: true,
+  handler: async (input, ctx) => ({
+    result: await searchExternalWikis(ctx.service.configRef.externalWikis, input),
+  }),
+});