@remnic/core 10.0.50 → 10.0.52

package/src/orchestrator-entity-write-failure.test.ts

@@ -0,0 +1,370 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+
+import { SmartBuffer } from "./buffer.js";
+import { resetExtractionLlmHealthForTests } from "./extraction-llm-health.js";
+import { Orchestrator } from "./orchestrator.js";
+import { ContentHashIndex } from "./storage.js";
+import {
+  cleanupDir,
+  harmonicNodeStoreStatus,
+  makeHarmonicLifecycleConfig,
+  makeLifecycleConfig,
+  mkTempMemoryDir,
+  stubExtraction,
+} from "./testing/orchestrator-lite.js";
+import type { ExtractionResult } from "./types.js";
+
+/** Owner contract for the private Orchestrator temporal/tag batch hook. */
+const FACT = "Project Alpha uses a queue for background processing.";
+
+for (const includeFact of [false, true]) {
+  test(`#3228: entity write failure retains input${includeFact ? " after a committed fact" : ""}`, async () => {
+    const memoryDir = await mkTempMemoryDir("entity-write-failure");
+    const config = makeLifecycleConfig(memoryDir, {
+      chunkingEnabled: false,
+      multiGraphMemoryEnabled: false,
+      factDeduplicationEnabled: true,
+      extractionMinImportanceLevel: "trivial",
+      entityActivityLogEnabled: false,
+    });
+    const orchestrator = new Orchestrator(config);
+    const storage = await orchestrator.getStorageForNamespace();
+    const writeEntity = storage.writeEntity.bind(storage);
+    try {
+      await storage.ensureDirectories();
+      const entityName = storage.normalizeEntityName("Alpha", "project");
+      await orchestrator.buffer.load();
+      const bufferKey = "entity-write-failure";
+      await orchestrator.buffer.addTurn(bufferKey, {
+        role: "user",
+        content: FACT,
+        sessionKey: bufferKey,
+        timestamp: "2026-10-01T12:00:00.000Z",
+        sourceValidAt: "2026-10-01T12:00:00.000Z",
+        persistProcessedFingerprint: true,
+      });
+      await orchestrator.buffer.flushPendingSave({ throwOnFailure: true });
+      const turns = orchestrator.buffer.getTurns(bufferKey);
+      assert.equal(turns.length, 1, "the source turn must be durably buffered before extraction");
+      const before = await storage.loadMeta();
+      const extractionCalls = stubExtraction(orchestrator, (): ExtractionResult => ({
+        facts: includeFact
+          ? [{ content: FACT, category: "fact", confidence: 0.9, tags: [] }]
+          : [],
+        entities: [{ name: "Alpha", type: "project", facts: ["Uses a queue"] }],
+        questions: [],
+        profileUpdates: [],
+      }));
+      const writeFailure = Object.assign(new Error("synthetic entity write denied"), { code: "EACCES" });
+      let entityWriteAttempts = 0;
+      storage.writeEntity = async (...args: Parameters<typeof writeEntity>) => {
+        entityWriteAttempts += 1;
+        assert.deepEqual(args.slice(0, 3), ["Alpha", "project", ["Uses a queue"]]);
+        throw writeFailure;
+      };
+      let commits = 0;
+      const options = { bufferKey, onDurableCommit: () => { commits += 1; } };
+
+      await assert.rejects(
+        orchestrator.runExtraction(turns, options),
+        (error: Error) => error === writeFailure,
+        "the original entity I/O failure must reach the caller",
+      );
+      assert.equal(entityWriteAttempts, 1, "the failure must come from the real entity persistence path");
+      assert.equal(commits, 0, "a failed batch must not signal durable completion");
+      assert.deepEqual(orchestrator.buffer.getTurns(bufferKey), turns);
+      const retainedBuffer = new SmartBuffer(config, storage);
+      await retainedBuffer.load();
+      assert.deepEqual(retainedBuffer.getTurns(bufferKey), turns, "source turns must remain on disk too");
+      const failedMeta = await storage.loadMeta();
+      assert.equal(failedMeta.processedExtractionFingerprints?.length ?? 0, 0);
+      assert.equal(failedMeta.extractionCount, before.extractionCount);
+      assert.equal(await storage.readEntity(entityName), "", "the failed entity was not written");
+
+      const factsBeforeRetry = (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "fact");
+      assert.equal(factsBeforeRetry.length, includeFact ? 1 : 0);
+      if (includeFact) {
+        const hashes = new ContentHashIndex(path.join(storage.dir, "state"));
+        await hashes.load();
+        assert.equal(hashes.has(FACT), true, "the earlier fact's deferred hash must be durable before rejection");
+      }
+
+      storage.writeEntity = writeEntity;
+      const retried = await orchestrator.runExtraction(turns, options);
+      assert.equal(retried.status, "completed");
+      assert.equal(retried.persistedCount, 1, "retry writes the entity, not another copy of an earlier fact");
+      assert.equal(commits, 1);
+      assert.match(await storage.readEntity(entityName), /Uses a queue/);
+      assert.equal((await storage.listEntityNames()).length, 1);
+      const factsAfterRetry = (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "fact");
+      assert.deepEqual(
+        factsAfterRetry.map((m) => m.frontmatter.id),
+        factsBeforeRetry.map((m) => m.frontmatter.id),
+        "retry must preserve the already committed fact without duplicating it",
+      );
+      assert.equal((await storage.loadMeta()).processedExtractionFingerprints?.length, 1);
+      assert.equal(orchestrator.buffer.getTurns(bufferKey).length, 0);
+      const clearedBuffer = new SmartBuffer(config, storage);
+      await clearedBuffer.load();
+      assert.equal(clearedBuffer.getTurns(bufferKey).length, 0);
+      assert.equal((await orchestrator.runExtraction(turns, options)).reason, "processed_fingerprint");
+      assert.equal(extractionCalls.length, 2, "only the failed attempt and successful retry call the extractor");
+      assert.equal(commits, 1, "processed replay must not emit a second commit");
+    } finally {
+      storage.writeEntity = writeEntity;
+      try {
+        await orchestrator.destroy();
+      } finally {
+        resetExtractionLlmHealthForTests();
+        await cleanupDir(memoryDir);
+      }
+    }
+  });
+}
+
+test("#3231: entity failure after a committed fact still runs deferred post-write maintenance", async () => {
+  // Partial-success path: fact (preference) is durable, later writeEntity throws.
+  // Batch-end finalization in persistExtraction (hash flush, behavior ledger,
+  // harmonic construction, temporal/tag index) and runExtraction's
+  // requestQmdMaintenance must still cover the earlier durable write. Retry
+  // exact-dedupes the fact (`continue`), so those effects are not re-queued.
+  const memoryDir = await mkTempMemoryDir("entity-write-failure-maintenance");
+  const preference =
+    "Prefers terse queue names for background jobs in Project Alpha.";
+  const config = makeHarmonicLifecycleConfig(memoryDir, {
+    chunkingEnabled: false,
+    multiGraphMemoryEnabled: false,
+    factDeduplicationEnabled: true,
+    extractionMinImportanceLevel: "trivial",
+    entityActivityLogEnabled: false,
+    queryAwareIndexingEnabled: true,
+  });
+  const orchestrator = new Orchestrator(config);
+  const storage = await orchestrator.getStorageForNamespace();
+  const writeEntity = storage.writeEntity.bind(storage);
+  const temporalIdBatches: string[][] = [];
+  // Bracket access is TypeScript's typed escape hatch for the private method; the spy only wraps and restores it.
+  const originalTemporal = orchestrator["updateTemporalTagIndexes"].bind(orchestrator);
+  orchestrator["updateTemporalTagIndexes"] = async (target, persistedIds) => {
+    temporalIdBatches.push([...persistedIds]);
+    return originalTemporal(target, persistedIds);
+  };
+  let qmdMaintenanceCalls = 0;
+  const originalQmd = orchestrator.requestQmdMaintenance.bind(orchestrator);
+  orchestrator.requestQmdMaintenance = () => {
+    qmdMaintenanceCalls += 1;
+    originalQmd();
+  };
+  try {
+    await storage.ensureDirectories();
+    await orchestrator.buffer.load();
+    const bufferKey = "entity-write-failure-maintenance";
+    await orchestrator.buffer.addTurn(bufferKey, {
+      role: "user",
+      content: preference,
+      sessionKey: bufferKey,
+      timestamp: "2026-10-01T12:00:00.000Z",
+      sourceValidAt: "2026-10-01T12:00:00.000Z",
+      persistProcessedFingerprint: true,
+    });
+    await orchestrator.buffer.flushPendingSave({ throwOnFailure: true });
+    const turns = orchestrator.buffer.getTurns(bufferKey);
+    assert.equal(turns.length, 1);
+    stubExtraction(orchestrator, (): ExtractionResult => ({
+      facts: [
+        {
+          content: preference,
+          category: "preference",
+          confidence: 0.95,
+          tags: ["queue-naming"],
+        },
+      ],
+      entities: [{ name: "Alpha", type: "project", facts: ["Uses a queue"] }],
+      questions: [],
+      profileUpdates: [],
+    }));
+    const writeFailure = Object.assign(new Error("synthetic entity write denied"), {
+      code: "EACCES",
+    });
+    storage.writeEntity = async () => {
+      throw writeFailure;
+    };
+
+    await assert.rejects(
+      orchestrator.runExtraction(turns, { bufferKey }),
+      (error: Error) => error === writeFailure,
+      "entity I/O failure must still reach the caller",
+    );
+
+    const facts = (await storage.readAllMemories()).filter(
+      (m) => m.frontmatter.category === "preference",
+    );
+    assert.equal(facts.length, 1, "the preference fact must remain durable");
+    const factId = facts[0]!.frontmatter.id;
+    const hashes = new ContentHashIndex(path.join(storage.dir, "state"));
+    await hashes.load();
+    assert.equal(hashes.has(preference), true, "deferred fact hash must flush before rejection");
+
+    const signals = await storage.readBehaviorSignals(50);
+    assert.ok(
+      signals.some(
+        (s) => s.memoryId === factId && s.signalType === "preference_affinity",
+      ),
+      "batch-end behavior-signal append must cover the committed preference before rethrow",
+    );
+
+    const harmonic = await harmonicNodeStoreStatus(memoryDir);
+    assert.equal(harmonic.nodes.invalid, 0);
+    assert.ok(
+      harmonic.nodes.valid > 0 && (harmonic.latestNode?.sourceMemoryIds ?? []).includes(factId),
+      "batch-end harmonic construction must cover the committed fact before rethrow",
+    );
+
+    assert.ok(
+      temporalIdBatches.some((ids) => ids.includes(factId)),
+      "batch-end temporal/tag index update must include the committed fact before rethrow",
+    );
+    assert.ok(
+      qmdMaintenanceCalls > 0,
+      "partial durable writes must still schedule QMD reindex before the entity error propagates",
+    );
+
+    // Retry exact-dedupes the preference (`continue`), so missing deferred
+    // effects are not re-queued. Prove the failure-path finalization is the
+    // only chance they have to land.
+    storage.writeEntity = writeEntity;
+    const retried = await orchestrator.runExtraction(turns, { bufferKey });
+    assert.equal(retried.status, "completed");
+    assert.equal(
+      (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "preference").length,
+      1,
+      "retry must not duplicate the already-committed preference",
+    );
+    assert.ok(
+      (await storage.readBehaviorSignals(50)).some(
+        (s) => s.memoryId === factId && s.signalType === "preference_affinity",
+      ),
+      "behavior signals must survive retry without relying on re-queue from the deduped fact",
+    );
+    assert.ok(
+      ((await harmonicNodeStoreStatus(memoryDir)).latestNode?.sourceMemoryIds ?? []).includes(factId),
+      "harmonic records must survive retry without relying on re-queue from the deduped fact",
+    );
+  } finally {
+    storage.writeEntity = writeEntity;
+    orchestrator.requestQmdMaintenance = originalQmd;
+    orchestrator["updateTemporalTagIndexes"] = originalTemporal;
+    try {
+      await orchestrator.destroy();
+    } finally {
+      resetExtractionLlmHealthForTests();
+      await cleanupDir(memoryDir);
+    }
+  }
+});
+
+test("#3231 P2: a post-write contradiction-resolve failure still finalizes the durable fact", async () => {
+  // The fact is durable (writeSealedMemory returned) when
+  // applyDeferredContradictionResolve rejects. Its behavior signal, harmonic
+  // node, temporal/tag index entry and QMD request must not depend on code
+  // that runs after that catch; retry exact-dedupes the fact.
+  const memoryDir = await mkTempMemoryDir("contradiction-resolve-failure-maintenance");
+  const preference = "Prefers terse queue names for background jobs in Project Beta.";
+  const config = makeHarmonicLifecycleConfig(memoryDir, {
+    chunkingEnabled: false,
+    multiGraphMemoryEnabled: false,
+    factDeduplicationEnabled: true,
+    extractionMinImportanceLevel: "trivial",
+    entityActivityLogEnabled: false,
+    queryAwareIndexingEnabled: true,
+  });
+  const orchestrator = new Orchestrator(config);
+  const storage = await orchestrator.getStorageForNamespace();
+  const temporalIdBatches: string[][] = [];
+  const originalTemporal = orchestrator["updateTemporalTagIndexes"].bind(orchestrator);
+  orchestrator["updateTemporalTagIndexes"] = async (target, persistedIds) => {
+    temporalIdBatches.push([...persistedIds]);
+    return originalTemporal(target, persistedIds);
+  };
+  let qmdMaintenanceCalls = 0;
+  const originalQmd = orchestrator.requestQmdMaintenance.bind(orchestrator);
+  orchestrator.requestQmdMaintenance = () => {
+    qmdMaintenanceCalls += 1;
+    originalQmd();
+  };
+  const originalResolve = orchestrator["applyDeferredContradictionResolve"].bind(orchestrator);
+  const resolveFailure = new Error("synthetic contradiction resolve failure");
+  orchestrator["applyDeferredContradictionResolve"] = async () => {
+    throw resolveFailure;
+  };
+  try {
+    await storage.ensureDirectories();
+    await orchestrator.buffer.load();
+    const bufferKey = "contradiction-resolve-failure-maintenance";
+    await orchestrator.buffer.addTurn(bufferKey, {
+      role: "user",
+      content: preference,
+      sessionKey: bufferKey,
+      timestamp: "2026-10-01T12:00:00.000Z",
+      sourceValidAt: "2026-10-01T12:00:00.000Z",
+      persistProcessedFingerprint: true,
+    });
+    await orchestrator.buffer.flushPendingSave({ throwOnFailure: true });
+    const turns = orchestrator.buffer.getTurns(bufferKey);
+    stubExtraction(orchestrator, (): ExtractionResult => ({
+      facts: [
+        {
+          content: preference,
+          category: "preference",
+          confidence: 0.95,
+          tags: ["queue-naming"],
+        },
+      ],
+      entities: [],
+      questions: [],
+      profileUpdates: [],
+    }));
+
+    await assert.rejects(
+      orchestrator.runExtraction(turns, { bufferKey }),
+      (error: Error) => error === resolveFailure,
+      "the post-write failure must still reach the caller",
+    );
+
+    const facts = (await storage.readAllMemories()).filter(
+      (m) => m.frontmatter.category === "preference",
+    );
+    assert.equal(facts.length, 1, "the preference fact must remain durable");
+    const factId = facts[0]!.frontmatter.id;
+    assert.ok(
+      (await storage.readBehaviorSignals(50)).some(
+        (s) => s.memoryId === factId && s.signalType === "preference_affinity",
+      ),
+      "the durable fact's behavior signal must land before the rethrow",
+    );
+    assert.ok(
+      ((await harmonicNodeStoreStatus(memoryDir)).latestNode?.sourceMemoryIds ?? []).includes(factId),
+      "the durable fact's harmonic node must land before the rethrow",
+    );
+    assert.ok(
+      temporalIdBatches.some((ids) => ids.includes(factId)),
+      "the durable fact's temporal/tag index update must run before the rethrow",
+    );
+    assert.ok(
+      qmdMaintenanceCalls > 0,
+      "a durable fact that is the only write must still schedule QMD reindex",
+    );
+  } finally {
+    orchestrator["applyDeferredContradictionResolve"] = originalResolve;
+    orchestrator.requestQmdMaintenance = originalQmd;
+    orchestrator["updateTemporalTagIndexes"] = originalTemporal;
+    try {
+      await orchestrator.destroy();
+    } finally {
+      resetExtractionLlmHealthForTests();
+      await cleanupDir(memoryDir);
+    }
+  }
+});

package/src/orchestrator.ts

@@ -865,6 +865,7 @@ export class Orchestrator {
         invalidateGraphEdgeCache: (storage) => this.graphIndexFor(storage).invalidateEdgeCache(),
         updateTemporalTagIndexes: (storage, persistedIds) =>
           this.updateTemporalTagIndexes(storage, persistedIds),
+        requestQmdMaintenance: () => this.requestQmdMaintenance(),
       });
     }
     return this._extractionPersistCoordinator;

package/src/storage/entity-canonical-id-migration.ts

@@ -46,7 +46,7 @@ const ENTITY_MAPPING_RESCAN_MAX_PASSES = 3;
 const EntityCanonicalIdMigrationStateSchema = z.object({
   version: z.literal(ENTITY_CANONICAL_ID_MIGRATION_VERSION),
   complete: z.boolean(),
-  mappings: z.record(z.string().min(1)),
+  mappings: z.record(z.string(), z.string().min(1)),
   completionFingerprint: z.string().optional(),
   /**
    * Pairs the migration refused to resolve, PARKED rather than dropped.
@@ -55,7 +55,7 @@ const EntityCanonicalIdMigrationStateSchema = z.object({
    * still naming the legacy id would never be rewritten. Optional so a journal
    * written by an older build still parses.
    */
-  blocked: z.record(z.string().min(1)).optional(),
+  blocked: z.record(z.string(), z.string().min(1)).optional(),
 });
 
 type EntityCanonicalIdMigrationState = z.infer<typeof EntityCanonicalIdMigrationStateSchema>;

package/dist/chunk-23ZLN5X6.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/extraction-span-wire.ts"],"sourcesContent":["/**\n * Extraction seam for span mode (issue #2333 leftover slice + #2952).\n *\n * Default off. Callers pass `enabled` to `applySpanMode`. The provider JSON\n * schema is mode-aware so off-mode structured output cannot advertise `span`.\n */\n\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\nimport type { ExtractionSpanConfig } from \"./extraction-span-config.js\";\nimport { parseSpanOffsets, type ParsedSpan } from \"./extraction-span.js\";\nimport { ExtractionProviderOutputSchema } from \"./schemas.js\";\n\nexport function applySpanMode(opts: {\n  enabled?: boolean | 0 | 1;\n  text: string;\n  start: number;\n  end: number;\n}): ParsedSpan {\n  return parseSpanOffsets(opts.text, { start: opts.start, end: opts.end }, opts.enabled);\n}\n\nconst JSON_SCHEMA_OPTS = { $refStrategy: \"none\" as const, effectStrategy: \"input\" as const };\n\nconst EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN = zodToJsonSchema(\n  ExtractionProviderOutputSchema,\n  JSON_SCHEMA_OPTS,\n) as Record<string, unknown>;\n\ntype FactItems = {\n  properties?: Record<string, unknown>;\n  required?: string[];\n};\n\nfunction omitFactSpan(schema: Record<string, unknown>): Record<string, unknown> {\n  const clone = structuredClone(schema) as {\n    properties?: { facts?: { items?: FactItems } };\n  };\n  const items = clone.properties?.facts?.items;\n  if (!items?.properties || !(\"span\" in items.properties)) {\n    throw new Error(\"extraction provider schema is missing facts.items.properties.span\");\n  }\n  delete items.properties.span;\n  if (Array.isArray(items.required)) {\n    items.required = items.required.filter((key) => key !== \"span\");\n  }\n  return clone as Record<string, unknown>;\n}\n\nconst EXTRACTION_PROVIDER_JSON_SCHEMA_WITHOUT_SPAN = omitFactSpan(\n  EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN,\n);\n\n/** Provider JSON schema: `span` is present in on/shadow, absent in off. */\nexport function extractionProviderJsonSchema(\n  spanMode: ExtractionSpanConfig[\"spanMode\"] = \"off\",\n): Record<string, unknown> {\n  return spanMode === \"off\"\n    ? EXTRACTION_PROVIDER_JSON_SCHEMA_WITHOUT_SPAN\n    : EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN;\n}\n\nexport function extractionProviderResponseFormat(spanMode: ExtractionSpanConfig[\"spanMode\"] = \"off\") {\n  return {\n    type: \"json_schema\" as const,\n    json_schema: {\n      name: \"extraction_result\",\n      schema: extractionProviderJsonSchema(spanMode),\n      strict: false,\n    },\n  };\n}\n"],"mappings":";;;;;;;;AAOA,SAAS,uBAAuB;AAKzB,SAAS,cAAc,MAKf;AACb,SAAO,iBAAiB,KAAK,MAAM,EAAE,OAAO,KAAK,OAAO,KAAK,KAAK,IAAI,GAAG,KAAK,OAAO;AACvF;AAEA,IAAM,mBAAmB,EAAE,cAAc,QAAiB,gBAAgB,QAAiB;AAE3F,IAAM,4CAA4C;AAAA,EAChD;AAAA,EACA;AACF;AAOA,SAAS,aAAa,QAA0D;AAC9E,QAAM,QAAQ,gBAAgB,MAAM;AAGpC,QAAM,QAAQ,MAAM,YAAY,OAAO;AACvC,MAAI,CAAC,OAAO,cAAc,EAAE,UAAU,MAAM,aAAa;AACvD,UAAM,IAAI,MAAM,mEAAmE;AAAA,EACrF;AACA,SAAO,MAAM,WAAW;AACxB,MAAI,MAAM,QAAQ,MAAM,QAAQ,GAAG;AACjC,UAAM,WAAW,MAAM,SAAS,OAAO,CAAC,QAAQ,QAAQ,MAAM;AAAA,EAChE;AACA,SAAO;AACT;AAEA,IAAM,+CAA+C;AAAA,EACnD;AACF;AAGO,SAAS,6BACd,WAA6C,OACpB;AACzB,SAAO,aAAa,QAChB,+CACA;AACN;AAEO,SAAS,iCAAiC,WAA6C,OAAO;AACnG,SAAO;AAAA,IACL,MAAM;AAAA,IACN,aAAa;AAAA,MACX,MAAM;AAAA,MACN,QAAQ,6BAA6B,QAAQ;AAAA,MAC7C,QAAQ;AAAA,IACV;AAAA,EACF;AACF;","names":[]}

package/dist/chunk-3MUKQQ7A.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/access-errors.ts"],"sourcesContent":["/**\n * Tool-surface error enrichment: nearest-tool suggestions and arg-shape hints.\n *\n * Each function is a pure message builder — it returns a better error string\n * without changing semantics, status codes, or rejection behavior.\n *\n * @module access-errors\n */\n\nimport type { ZodError } from \"zod\";\n\n// ─── Existing error classes (restored from pre-#3042) ─────────────────────\n\n/** Authenticated caller lacks the required authorization (HTTP 403). */\nexport class EngramAccessForbiddenError extends Error {}\n\n/** Invalid caller input (HTTP 400). */\nexport class EngramAccessInputError extends Error {}\n\n/**\n * A write rejected by the namespace write-ACL (issue #1888). Subclasses\n * EngramAccessInputError so every existing catch/HTTP-400 mapping still\n * applies, but carries the attempted namespace + principal so the observe/\n * write surfaces can dead-letter the payload before re-throwing (fail-closed\n * placement is unchanged; only the destroyed-payload behavior is fixed).\n */\nexport class NamespaceNotWritableError extends EngramAccessInputError {\n  constructor(\n    readonly attemptedNamespace: string,\n    readonly principal: string | undefined,\n    message?: string,\n  ) {\n    super(message ?? `namespace is not writable: ${attemptedNamespace}`);\n    this.name = \"NamespaceNotWritableError\";\n  }\n}\n\n// ─── Levenshtein distance ─────────────────────────────────────────────────\n\n/**\n * Standard Levenshtein edit distance. O(n*m) over bounded inputs.\n * Exported so the test can verify it without importing private helpers.\n */\nexport function levenshtein(a: string, b: string): number {\n  const an = a.length;\n  const bn = b.length;\n  // Fast paths for empty strings.\n  if (an === 0) return bn;\n  if (bn === 0) return an;\n\n  // Use two rows to keep memory O(min(n,m)).\n  let prev: number[] = [];\n  let curr: number[] = [];\n\n  // Align loops to the shorter string.\n  const [shorter, longer, sn, ln] =\n    an < bn ? [a, b, an, bn] : [b, a, bn, an];\n\n  for (let i = 0; i <= sn; i++) prev[i] = i;\n\n  for (let j = 1; j <= ln; j++) {\n    curr[0] = j;\n    for (let i = 1; i <= sn; i++) {\n      const cost = shorter[i - 1] === longer[j - 1] ? 0 : 1;\n      curr[i] = Math.min(\n        prev[i] + 1,       // deletion\n        curr[i - 1] + 1,   // insertion\n        prev[i - 1] + cost, // substitution\n      );\n    }\n    [prev, curr] = [curr, prev];\n  }\n  return prev[sn];\n}\n\n// ─── Similar-name helpers ─────────────────────────────────────────────────\n\nconst SUGGESTION_DISTANCE_CAP = 3;\n/**\n * Upper bound on the requested tool name. Anything longer is rejected before\n * the O(n*m) Levenshtein pass (#3042 review, P2): a 128 KB request over ~30\n * tools would otherwise run hundreds of millions of comparisons and block\n * the server event loop. The repo documents 64 chars as the tool-name shape;\n * this matches the limit enforced by every published surface.\n */\nexport const SUGGESTION_REQUEST_MAX_LEN = 64;\n\nexport interface SuggestionCandidate {\n  name: string;\n  distance: number;\n}\n\n/**\n * Find the nearest registered tool names by Levenshtein distance.\n * Results are sorted by distance ascending then name ascending (deterministic).\n * Only names with distance <= {@link SUGGESTION_DISTANCE_CAP} are returned;\n * when no name is that close the caller falls back to listing the full set.\n */\nexport function nearestSuggestions(\n  requested: string,\n  registeredNames: readonly string[],\n): SuggestionCandidate[] {\n  // Defense in depth: the entry point already caps; this guards any direct\n  // caller of the helper from an unbounded Levenshtein pass (issue #3042).\n  if (requested.length > SUGGESTION_REQUEST_MAX_LEN) return [];\n  const candidates: SuggestionCandidate[] = [];\n  for (const name of registeredNames) {\n    const distance = levenshtein(requested.toLowerCase(), name.toLowerCase());\n    if (distance <= SUGGESTION_DISTANCE_CAP) {\n      candidates.push({ name, distance });\n    }\n  }\n  // Total comparator: distance asc, then name asc.\n  candidates.sort((a, b) => {\n    if (a.distance !== b.distance) return a.distance < b.distance ? -1 : 1;\n    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;\n  });\n  return candidates;\n}\n\n/**\n * Build a human-readable \"did you mean?\" suggestion string.\n * When no close match is found, returns a fallback listing.\n */\nfunction buildSuggestion(\n  requested: string,\n  registeredNames: readonly string[],\n): string {\n  const suggestions = nearestSuggestions(requested, registeredNames);\n  if (suggestions.length === 0) {\n    return `Registered tools: ${registeredNames.join(\", \")}`;\n  }\n  return `Did you mean ${suggestions.map((s) => s.name).join(\", \")}?`;\n}\n\n/**\n * Read a Zod type tag without asserting a shape.\n *\n * Zod keeps its discriminant at `_def.typeName`. Both hops are narrowed with\n * `in`/`typeof` rather than an inline cast, so a non-Zod object yields\n * `undefined` instead of a fabricated read.\n */\nfunction zodTypeName(schema: unknown): string | undefined {\n  if (typeof schema !== \"object\" || schema === null || !(\"_def\" in schema)) return undefined;\n  const def = schema._def;\n  if (typeof def !== \"object\" || def === null || !(\"typeName\" in def)) return undefined;\n  return typeof def.typeName === \"string\" ? def.typeName : undefined;\n}\n\n/** Read `_def.<key>` with the same narrowing discipline. */\nfunction zodDefField(schema: unknown, key: string): unknown {\n  if (typeof schema !== \"object\" || schema === null || !(\"_def\" in schema)) return undefined;\n  const def = schema._def;\n  if (typeof def !== \"object\" || def === null) return undefined;\n  return Object.hasOwn(def, key) ? (def as Record<string, unknown>)[key] : undefined;\n}\n\n/**\n * Reverse-engineer ONE synthetic example value from a Zod schema type.\n * Returns a deterministic placeholder intended to round-trip through parse().\n */\nfunction exampleFromSchema(schema: unknown): unknown {\n  switch (zodTypeName(schema)) {\n    case \"ZodString\":\n      return \"<string>\";\n    case \"ZodNumber\":\n      return 42;\n    case \"ZodBoolean\":\n      return true;\n    case \"ZodNullable\":\n      return null;\n    case \"ZodArray\":\n      return [];\n    case \"ZodOptional\":\n      // Optional fields are omitted from the example rather than sent as null.\n      return undefined;\n    case \"ZodEnum\": {\n      const values = zodDefField(schema, \"values\");\n      return Array.isArray(values) && values.length > 0 ? values[0] : \"<value>\";\n    }\n    case \"ZodObject\": {\n      const shapeFn = zodDefField(schema, \"shape\");\n      const shape = typeof shapeFn === \"function\" ? shapeFn() : undefined;\n      if (typeof shape !== \"object\" || shape === null) return {};\n      const result: Record<string, unknown> = {};\n      for (const key of Object.getOwnPropertyNames(shape)) {\n        if (!Object.hasOwn(shape, key)) continue;\n        const field = (shape as Record<string, unknown>)[key];\n        const value = exampleFromSchema(field);\n        if (value !== undefined) result[key] = value;\n      }\n      return result;\n    }\n    default:\n      return undefined;\n  }\n}\n/**\n * Build an enriched \"unknown tool\" error message.\n *\n * @param requested - the tool name the caller used\n * @param registeredNames - ALL registered tool names (including aliases)\n */\nexport function unknownToolError(\n  requested: string,\n  registeredNames: readonly string[],\n): string {\n  // Cap the request before the suggestion pass: a 128 KB name would otherwise\n  // pay O(n*m) per registered tool (issue #3042 review, P2). The cap matches\n  // the documented tool-name shape; an over-long request is rejected with a\n  // teaching message rather than a silent truncate.\n  if (requested.length > SUGGESTION_REQUEST_MAX_LEN) {\n    return `Unknown tool: name exceeds ${SUGGESTION_REQUEST_MAX_LEN} characters (got ${requested.length}).`;\n  }\n  const suggestion = buildSuggestion(requested, registeredNames);\n  return `Unknown tool: ${requested}. ${suggestion}`;\n}\n\n/**\n * Build an enriched \"invalid arguments\" error message.\n *\n * The example is generated from the schema (never hand-written, so it cannot\n * drift) and is shown ONLY when it round-trips through that same schema. It\n * carries schema-derived fields only: injecting the tool name would add an\n * unrecognized property and fail a `.strict()` object (#3035 review finding).\n *\n * @param tool - the tool name that received the invalid args\n * @param zodError - the ZodError from parse()\n * @param schema - the original Zod schema, used to generate the example\n */\nexport function invalidArgsError(\n  tool: string,\n  zodError: ZodError,\n  schema?: unknown,\n): string {\n  const issues = zodError.issues.map((issue) => {\n    const path = issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n    // `expected` exists only on the invalid_type / invalid_literal variants of\n    // ZodIssue, so it is read through a presence check rather than assumed.\n    const expected = \"expected\" in issue ? issue.expected : undefined;\n    return expected === undefined\n      ? `${path}: ${issue.message}`\n      : `${path}: ${issue.message} (expected ${String(expected)})`;\n  });\n  let message = `Invalid arguments for \"${tool}\": ${issues.join(\"; \")}`;\n  if (!schema) return message;\n\n  const example = exampleFromSchema(schema);\n  if (!example || typeof example !== \"object\" || Object.keys(example).length === 0) {\n    return message;\n  }\n\n  // Withhold an example that cannot parse against its own schema: a\n  // non-round-tripping example is misinformation, worse than none. Narrowed\n  // with `in`/`typeof` rather than an inline cast so the shape is checked.\n  let roundTrips = false;\n  if (typeof schema === \"object\" && \"safeParse\" in schema) {\n    const parser = schema.safeParse;\n    if (typeof parser === \"function\") {\n      try {\n        const parsed: unknown = parser.call(schema, example);\n        roundTrips =\n          typeof parsed === \"object\"\n          && parsed !== null\n          && \"success\" in parsed\n          && parsed.success === true;\n      } catch {\n        roundTrips = false;\n      }\n    }\n  }\n\n  return roundTrips ? `${message}. Example arguments: ${JSON.stringify(example)}` : message;\n}\n"],"mappings":"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","names":[]}