@remnic/core 10.0.49 → 10.0.51

package/src/storage-startup-nonblocking-migration.test.ts

@@ -0,0 +1,183 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, readdir, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { StorageManager } from "./storage.js";
+import { sleep } from "./utils/sleep.js";
+
+// Issue #3139 (Q2 briefing 60s ceiling): the CLI briefing path awaits
+// orchestrator.initialize(), which awaited storage.ensureDirectories(), which
+// awaited the entity canonical-id migration lock/replay (up to a 300s bounded
+// wait on a busy lock). Startup READ readiness must not sit behind that
+// migration; writes must. These tests pin the boundary with the real on-disk
+// migration lock and a real temp corpus — no orchestrator stubs. Every wait is
+// bounded so a regression fails fast instead of stalling the run.
+
+const MIGRATION_LOCK_FILE = path.join("state", "entity-canonical-id-migration.lock");
+const MIGRATION_JOURNAL_FILE = path.join("state", "entity-canonical-id-migration-v1.json");
+const READINESS_BUDGET_MS = 500;
+const BARRIER_PROBE_MS = 250;
+
+async function withMemoryDir(run: (dir: string) => Promise<void>): Promise<void> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-startup-migration-"));
+  try {
+    await run(dir);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Hold the migration's own cross-process lock (the exact file
+ * migrateLegacyEntityCanonicalIds acquires via withHeldFileLock: poll 50ms,
+ * stale 60s — a hold for the lifetime of one test). Returns the release.
+ */
+async function gateMigration(dir: string): Promise<() => Promise<void>> {
+  const lockPath = path.join(dir, MIGRATION_LOCK_FILE);
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  await writeFile(lockPath, `${process.pid} startup-migration-test ${new Date().toISOString()}\n`);
+  return () => unlink(lockPath);
+}
+
+async function journalComplete(dir: string): Promise<boolean> {
+  try {
+    // SAFETY: the journal is written by this test fixture and carries an optional boolean `complete`.
+    const state = JSON.parse(await readFile(path.join(dir, MIGRATION_JOURNAL_FILE), "utf8")) as {
+      complete?: boolean;
+    };
+    return state.complete === true;
+  } catch {
+    return false;
+  }
+}
+
+test("startup read readiness can defer the entity canonical-id migration", async () => {
+  await withMemoryDir(async (dir) => {
+    const storage = new StorageManager(dir);
+    const releaseGate = await gateMigration(dir);
+    const readiness = storage.ensureDirectories({ waitForEntityMigration: false });
+    // Regression: on the awaited path this call sits behind the held lock and
+    // only surfaces after the 300s bounded wait. The startup option must
+    // settle while the lock is still held — asserted against a bounded race
+    // so main fails behaviorally in ~500ms instead of stalling the job.
+    let failure: unknown;
+    try {
+      const outcome = await Promise.race([readiness, sleep(READINESS_BUDGET_MS).then(() => "timeout")]);
+      assert.notEqual(outcome, "timeout", "startup read readiness must not wait for the gated migration");
+      assert.equal(existsSync(path.join(dir, "entities")), true);
+      assert.equal(
+        existsSync(path.join(dir, MIGRATION_LOCK_FILE)),
+        true,
+        "the deferred startup must not take the migration lock",
+      );
+      assert.equal(
+        existsSync(path.join(dir, MIGRATION_JOURNAL_FILE)),
+        false,
+        "the deferred startup must not run the migration",
+      );
+    } catch (err) {
+      failure = err;
+    } finally {
+      await releaseGate();
+    }
+    // The write-side ensure still runs the migration and awaits it.
+    await readiness;
+    await storage.ensureDirectories();
+    if (failure !== undefined) throw failure;
+    assert.equal(await journalComplete(dir), true);
+    // Normal entity writes still work after the deferred migration settles.
+    await storage.writeEntity("Alice", "person", ["Alice works on Remnic"]);
+  });
+});
+
+test("default ensureDirectories still waits behind a held migration lock", async () => {
+  await withMemoryDir(async (dir) => {
+    const storage = new StorageManager(dir);
+    const releaseGate = await gateMigration(dir);
+    let settled = false;
+    let setupError: Error | undefined;
+    const gatedSetup = storage.ensureDirectories().then(
+      () => {
+        settled = true;
+      },
+      (err: Error) => {
+        setupError = err;
+        settled = true;
+      },
+    );
+    let failure: unknown;
+    try {
+      await sleep(BARRIER_PROBE_MS);
+      assert.equal(settled, false, "default ensureDirectories must not resolve while the migration lock is held");
+    } catch (err) {
+      failure = err;
+    } finally {
+      await releaseGate();
+    }
+    await gatedSetup;
+    assert.equal(setupError, undefined);
+    if (failure !== undefined) throw failure;
+    assert.equal(await journalComplete(dir), true);
+  });
+});
+
+test("deferred startup still refuses unsafe entity entries before serving reads", async () => {
+  const outside = await mkdtemp(path.join(os.tmpdir(), "remnic-startup-migration-outside-"));
+  try {
+    await withMemoryDir(async (dir) => {
+      const storage = new StorageManager(dir);
+      await mkdir(path.join(dir, "entities"), { recursive: true });
+      await symlink(path.join(outside, "leaked.md"), path.join(dir, "entities", "leaked.md"));
+      await assert.rejects(
+        () => storage.ensureDirectories({ waitForEntityMigration: false }),
+        /Refusing entity canonical-id migration through symlink/,
+      );
+    });
+  } finally {
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("entity writes queue behind the migration they trigger", async () => {
+  await withMemoryDir(async (dir) => {
+    const storage = new StorageManager(dir);
+    const releaseGate = await gateMigration(dir);
+    const readiness = storage.ensureDirectories({ waitForEntityMigration: false });
+    const { promise: written, resolve: writeSettled } = Promise.withResolvers<void>();
+    let writeError: Error | undefined;
+    let failure: unknown;
+    try {
+      const outcome = await Promise.race([readiness, sleep(READINESS_BUDGET_MS).then(() => "timeout")]);
+      assert.notEqual(outcome, "timeout", "startup read readiness must not wait for the gated migration");
+      // A real entity write must queue behind the migration it triggers — the
+      // deferred startup opens READ readiness only.
+      storage.writeEntity("Alice", "person", ["Alice works on Remnic"]).then(
+        () => writeSettled(),
+        (err: Error) => {
+          writeError = err;
+          writeSettled();
+        },
+      );
+      const writeProbe = await Promise.race([written, sleep(BARRIER_PROBE_MS).then(() => "pending")]);
+      assert.equal(writeProbe, "pending", "entity writes must queue behind the migration they trigger");
+    } catch (err) {
+      failure = err;
+    } finally {
+      await releaseGate();
+    }
+    await readiness;
+    await storage.ensureDirectories();
+    if (failure === undefined) {
+      const settled = await Promise.race([written, sleep(10_000).then(() => "deadline")]);
+      assert.notEqual(settled, "deadline", "entity write must complete once the gate releases");
+      assert.equal(writeError, undefined);
+      const entries = await readdir(path.join(dir, "entities"));
+      assert.equal(entries.some((name) => name.endsWith(".md")), true, "entity file must land after the migration settles");
+    }
+    if (failure !== undefined) throw failure;
+  });
+});

package/src/storage.ts

@@ -1923,6 +1923,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   onCatalogWrite?: () => void;
   /** Post-write embedding hook (#2019). Installed by the orchestrator; fire-and-forget. */
   onMemoryWrite?: (filePath: string) => void;
+  /** Request search maintenance after a completed entity replay. */
+  onEntityMigrationComplete?: () => void;
   private notifyMemoryWrite(filePath: string): void {
     try {
       this.onMemoryWrite?.(filePath);
@@ -4834,13 +4836,16 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     candidateBatchPaths: string[],
     remainingSlots: number,
     remainingInspectionBudget: number,
-    readBatchSize: number
+    readBatchSize: number,
+    options?: CorpusReadOptions
   ): Promise<{ memories: MemoryFile[]; filePaths: string[] }> {
     const memories: MemoryFile[] = [];
     const filePaths: string[] = [];
     const normalizedReadBatchSize = this.normalizeMemoryReadBatchSize(readBatchSize);
 
     for (let index = 0; index < candidateBatchPaths.length; ) {
+      // Per batch: an abandoned caller must not keep the scan running (#3139).
+      checkCorpusReadAbort(options);
       if (memories.length >= remainingSlots || filePaths.length >= remainingInspectionBudget) break;
       const availableSlots = remainingSlots - memories.length;
       const availableInspectionBudget = remainingInspectionBudget - filePaths.length;
@@ -4853,7 +4858,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       index += candidatePaths.length;
       if (candidatePaths.length === 0) break;
       filePaths.push(...candidatePaths);
-      const parsedMemories = await this.readParsedMemoriesFromPaths(candidatePaths, candidatePaths.length);
+      const parsedMemories = await this.readParsedMemoriesFromPaths(candidatePaths, candidatePaths.length, options);
       if (parsedMemories.length === 0) continue;
       memories.push(...parsedMemories.slice(0, availableSlots));
     }

package/src/testing/subjects/entity-migration-completion-cache.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Lifecycle matrix subject for the amortized entity migration-completion
+ * cache. Exercises the helper only through StorageManager.readEntity — never
+ * a direct cache test double.
+ */
+import assert from "node:assert/strict";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { StorageManager } from "../../storage.js";
+import { type LifecycleSubject, type MatrixRow, runLifecycleMatrix } from "../lifecycle-matrix.js";
+import { mkTempMemoryDir } from "../orchestrator-lite.js";
+
+interface CompletionCacheState {
+  dir: string;
+  previousId: string;
+  reader: StorageManager;
+  warmMiss: string;
+  afterAlias?: string;
+  afterRestart?: string;
+  restarted?: StorageManager;
+}
+
+const subject: LifecycleSubject<CompletionCacheState> = {
+  async setup(row: MatrixRow): Promise<CompletionCacheState> {
+    const dir = await mkTempMemoryDir(`entity-mig-complete-${row.id}`);
+    try {
+      const seed = new StorageManager(dir);
+      const previousId = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
+      await seed.ensureDirectories();
+      const reader = new StorageManager(dir);
+      await reader.ensureDirectories({ waitForEntityMigration: false });
+      return { dir, previousId, reader, warmMiss: "" };
+    } catch (error) {
+      await rm(dir, { recursive: true, force: true });
+      throw error;
+    }
+  },
+
+  async exercise(state: CompletionCacheState, row: MatrixRow): Promise<void> {
+    // Warm the amortized completion verdict on a miss (key + fingerprint path).
+    state.warmMiss = await state.reader.readEntity("project-missing");
+
+    await mkdir(path.join(state.dir, "config"), { recursive: true });
+    await writeFile(path.join(state.dir, "config", "aliases.json"), JSON.stringify({ café: "coffee" }));
+    await state.reader.loadAliases();
+    const canonical = state.reader.normalizeEntityName("Café", "project");
+    assert.notEqual(canonical, state.previousId, `${row.id}: alias must move the canonical id`);
+    state.afterAlias = await state.reader.readEntity(canonical);
+
+    if (row.dimensions.restart) {
+      const restarted = new StorageManager(state.dir);
+      state.restarted = restarted;
+      await restarted.ensureDirectories({ waitForEntityMigration: false });
+      await restarted.loadAliases();
+      state.afterRestart = await restarted.readEntity(restarted.normalizeEntityName("Café", "project"));
+    }
+
+    if (row.dimensions.dedupeOrReplay) {
+      // Second miss with stable inputs must stay a cheap empty miss (no throw).
+      assert.equal(await state.reader.readEntity("project-missing-again"), "");
+    }
+  },
+
+  async invariants(state: CompletionCacheState, row: MatrixRow): Promise<void> {
+    assert.equal(state.warmMiss, "", `${row.id}: warm miss must return empty`);
+    assert.match(
+      state.afterAlias ?? "",
+      /Synthetic legacy fact/,
+      `${row.id}: alias drift must not hide the entity behind a stale completion cache`,
+    );
+    if (row.dimensions.restart) {
+      assert.match(
+        state.afterRestart ?? "",
+        /Synthetic legacy fact/,
+        `${row.id}: restarted reader must still resolve the alias-moved entity`,
+      );
+    }
+  },
+
+  async teardown(state: CompletionCacheState): Promise<void> {
+    // The deferred startup replay runs in the background; let it finish before the directory goes.
+    await state.reader.drainEntityCanonicalIdMigration();
+    await state.restarted?.drainEntityCanonicalIdMigration();
+    StorageManager.clearAllStaticCaches();
+    await rm(state.dir, { recursive: true, force: true });
+  },
+};
+
+runLifecycleMatrix("entity-migration-completion-cache", subject);

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":[]}

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

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/access-observe-write-category.ts"],"sourcesContent":["/**\n * Category-alias split + replay restamp for observe/write (#2829).\n * Extracted from access-observe-write-surface.ts to stay under the 1200-line cap.\n *\n * The wire schema already maps an alias to \"fact\". `rawCategory` is the\n * caller's spelling: it must not reach the write candidate or fingerprint,\n * and a replay must rebuild the note from THIS request's spelling.\n */\nimport {\n  canonicalCategoryForAlias,\n  categoryAliasCoercion,\n  reapplyCategoryCoercion,\n  type CategoryAliasCoercion,\n  type MemoryCategoryAlias,\n} from \"./access-schema.js\";\n\nexport { reapplyCategoryCoercion };\nexport { applyBriefingLocationContext } from \"./location/tagging.js\";\n\nexport function splitCanonicalWriteRequest<T extends { rawCategory?: string; category?: string }>(\n  request: T,\n): {\n  canonical: Omit<T, \"rawCategory\">;\n  categoryCoercion: CategoryAliasCoercion | undefined;\n} {\n  const { rawCategory, ...canonical } = request;\n  // #2962: a direct service caller bypasses the wire schema, so an accepted\n  // alias can still sit on `category`. Canonicalize it at the same boundary\n  // the schema's transform covers for HTTP/MCP/CLI, minting the retained\n  // spelling from the request itself. A schema-minted `rawCategory` always\n  // wins (it names the spelling the transform actually canonicalized);\n  // near-misses pass through untouched and reject at the write candidate\n  // with the attempted category echoed.\n  if (rawCategory === undefined && typeof canonical.category === \"string\") {\n    const mapped = canonicalCategoryForAlias(canonical.category);\n    if (mapped !== undefined) {\n      const from = canonical.category as MemoryCategoryAlias;\n      return {\n        canonical: { ...canonical, category: mapped } as Omit<T, \"rawCategory\">,\n        categoryCoercion: { from, to: mapped },\n      };\n    }\n  }\n  return { canonical, categoryCoercion: categoryAliasCoercion(rawCategory) };\n}\n"],"mappings":";;;;;;AAmBO,SAAS,2BACd,SAIA;AACA,QAAM,EAAE,aAAa,GAAG,UAAU,IAAI;AAQtC,MAAI,gBAAgB,UAAa,OAAO,UAAU,aAAa,UAAU;AACvE,UAAM,SAAS,0BAA0B,UAAU,QAAQ;AAC3D,QAAI,WAAW,QAAW;AACxB,YAAM,OAAO,UAAU;AACvB,aAAO;AAAA,QACL,WAAW,EAAE,GAAG,WAAW,UAAU,OAAO;AAAA,QAC5C,kBAAkB,EAAE,MAAM,IAAI,OAAO;AAAA,MACvC;AAAA,IACF;AAAA,EACF;AACA,SAAO,EAAE,WAAW,kBAAkB,sBAAsB,WAAW,EAAE;AAC3E;","names":[]}