@remnic/core 1.1.1 → 1.1.3

package/dist/chunk-FP2373TW.js

@@ -0,0 +1,149 @@
+// src/secure-store/kdf.ts
+import { scryptSync, timingSafeEqual } from "crypto";
+import { createRequire } from "module";
+var requireArgon2 = createRequire(import.meta.url);
+var argon2Runtime;
+function loadArgon2Runtime() {
+  try {
+    argon2Runtime ??= requireArgon2("@node-rs/argon2");
+    return argon2Runtime;
+  } catch (cause) {
+    throw new Error(
+      "Argon2id KDF requires @node-rs/argon2 to be installed and loadable on this platform. Use scrypt compatibility mode for stores that must run without the Argon2 native binding.",
+      { cause }
+    );
+  }
+}
+var DEFAULT_SCRYPT_PARAMS = Object.freeze({
+  // 2^17. Hex-coding the literal would obscure the doubling chain.
+  N: 1 << 17,
+  r: 8,
+  p: 1,
+  keyLength: 32,
+  // 256 MiB ceiling — comfortably above the 128 MiB scrypt needs at N=2^17.
+  maxmem: 256 * 1024 * 1024
+});
+var DEFAULT_ARGON2ID_PARAMS = Object.freeze({
+  memoryKiB: 64 * 1024,
+  iterations: 3,
+  parallelism: 4,
+  keyLength: 32
+});
+var KDF_SALT_LENGTH = 16;
+var KDF_KEY_LENGTH = 32;
+function validateScryptParams(params) {
+  const { N, r, p, keyLength, maxmem } = params;
+  if (!Number.isInteger(N) || N < 2) {
+    throw new Error(`scrypt N must be an integer \u2265 2, got ${N}`);
+  }
+  if (N > 2 ** 30) {
+    throw new Error(`scrypt N is unreasonably large (max 2^30), got ${N}`);
+  }
+  if (!Number.isInteger(Math.log2(N))) {
+    throw new Error(`scrypt N must be a power of 2, got ${N}`);
+  }
+  if (!Number.isInteger(r) || r < 1) {
+    throw new Error(`scrypt r must be a positive integer, got ${r}`);
+  }
+  if (!Number.isInteger(p) || p < 1) {
+    throw new Error(`scrypt p must be a positive integer, got ${p}`);
+  }
+  if (!Number.isInteger(keyLength) || keyLength < 16) {
+    throw new Error(
+      `scrypt keyLength must be \u2265 16 (need 32 for AES-256), got ${keyLength}`
+    );
+  }
+  if (!Number.isInteger(maxmem) || maxmem < 1024) {
+    throw new Error(`scrypt maxmem must be a sane positive integer, got ${maxmem}`);
+  }
+}
+function validateArgon2idParams(params) {
+  const { memoryKiB, iterations, parallelism, keyLength } = params;
+  if (!Number.isInteger(memoryKiB) || memoryKiB < 8) {
+    throw new Error(`argon2id memoryKiB must be an integer \u2265 8, got ${memoryKiB}`);
+  }
+  if (!Number.isInteger(iterations) || iterations < 1) {
+    throw new Error(`argon2id iterations must be a positive integer, got ${iterations}`);
+  }
+  if (!Number.isInteger(parallelism) || parallelism < 1 || parallelism > 255) {
+    throw new Error(`argon2id parallelism must be an integer in [1, 255], got ${parallelism}`);
+  }
+  if (!Number.isInteger(keyLength) || keyLength !== KDF_KEY_LENGTH) {
+    throw new Error(
+      `argon2id keyLength must be ${KDF_KEY_LENGTH} (AES-256 requires a 32-byte key), got ${keyLength}`
+    );
+  }
+}
+function deriveKeyScrypt(passphrase, salt, params = DEFAULT_SCRYPT_PARAMS) {
+  if (typeof passphrase !== "string") {
+    throw new Error("passphrase must be a string");
+  }
+  if (passphrase.length === 0) {
+    throw new Error("passphrase must not be empty");
+  }
+  if (!(salt instanceof Uint8Array) || salt.length < 8) {
+    throw new Error(
+      `salt must be a Uint8Array of at least 8 bytes, got ${salt?.length ?? "non-buffer"}`
+    );
+  }
+  validateScryptParams(params);
+  return scryptSync(passphrase, Buffer.from(salt), params.keyLength, {
+    N: params.N,
+    r: params.r,
+    p: params.p,
+    maxmem: params.maxmem
+  });
+}
+function deriveKeyArgon2id(passphrase, salt, params = DEFAULT_ARGON2ID_PARAMS) {
+  if (typeof passphrase !== "string") {
+    throw new Error("passphrase must be a string");
+  }
+  if (passphrase.length === 0) {
+    throw new Error("passphrase must not be empty");
+  }
+  if (!(salt instanceof Uint8Array) || salt.length < 8) {
+    throw new Error(
+      `salt must be a Uint8Array of at least 8 bytes, got ${salt?.length ?? "non-buffer"}`
+    );
+  }
+  validateArgon2idParams(params);
+  const { Algorithm, Version, hashRawSync } = loadArgon2Runtime();
+  return hashRawSync(passphrase, {
+    algorithm: Algorithm.Argon2id,
+    version: Version.V0x13,
+    memoryCost: params.memoryKiB,
+    timeCost: params.iterations,
+    parallelism: params.parallelism,
+    outputLen: params.keyLength,
+    salt
+  });
+}
+function deriveKey(algorithm, passphrase, salt, params) {
+  if (algorithm === "scrypt") {
+    return deriveKeyScrypt(passphrase, salt, params);
+  }
+  if (algorithm === "argon2id") {
+    return deriveKeyArgon2id(passphrase, salt, params);
+  }
+  throw new Error(`unknown KDF algorithm: ${algorithm}`);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+export {
+  DEFAULT_SCRYPT_PARAMS,
+  DEFAULT_ARGON2ID_PARAMS,
+  KDF_SALT_LENGTH,
+  KDF_KEY_LENGTH,
+  validateScryptParams,
+  validateArgon2idParams,
+  deriveKeyScrypt,
+  deriveKeyArgon2id,
+  deriveKey,
+  constantTimeEqual
+};
+//# sourceMappingURL=chunk-FP2373TW.js.map

package/dist/chunk-FP2373TW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/secure-store/kdf.ts"],"sourcesContent":["/**\n * Key-derivation functions for the secure-store module.\n *\n * Issue #690 (PR 1/4) — pure primitives, no I/O.\n *\n * Naming note\n * -----------\n * The directory is named `secure-store/` — NOT `vault/` — because\n * `vault` is already a content-source concept in `native-knowledge.ts`\n * (Obsidian vaults: `ObsidianVaultState`, `vaultId`, `obsidianVaults`\n * config, etc.). Reusing the `vault` namespace for at-rest encryption\n * would cause symbol collisions and reader confusion.\n *\n * KDF choice — Argon2id primary, scrypt compatibility\n * ---------------------------------------------------\n * Issue #690 specifies Argon2id (OWASP m=64 MiB, t=3, p=4) as the\n * preferred KDF. We use `@node-rs/argon2` for the Argon2id runtime\n * and keep scrypt as the compatibility path for stores initialized\n * before Argon2id support landed.\n *\n * The algorithm name + params are persisted in the metadata file, so\n * stores keep deriving with the same KDF they were initialized with.\n *\n * Trade-off summary:\n *   - scrypt N=2^17, r=8, p=1 → ~128 MiB memory, ~150 ms on a modern\n *     laptop. Memory-hard. Resists GPU/ASIC attacks meaningfully.\n *   - Argon2id m=64 MiB, t=3, p=4 → ~64 MiB memory, similar wall\n *     time. Considered the modern best-in-class but requires native\n *     bindings.\n *\n * Both produce a 32-byte key suitable for AES-256-GCM.\n */\n\nimport { scryptSync, timingSafeEqual } from \"node:crypto\";\nimport { createRequire } from \"node:module\";\n\ntype Argon2Runtime = typeof import(\"@node-rs/argon2\");\n\nconst requireArgon2 = createRequire(import.meta.url);\nlet argon2Runtime: Argon2Runtime | undefined;\n\nfunction loadArgon2Runtime(): Argon2Runtime {\n  try {\n    argon2Runtime ??= requireArgon2(\"@node-rs/argon2\") as Argon2Runtime;\n    return argon2Runtime;\n  } catch (cause) {\n    throw new Error(\n      \"Argon2id KDF requires @node-rs/argon2 to be installed and loadable on this platform. \" +\n        \"Use scrypt compatibility mode for stores that must run without the Argon2 native binding.\",\n      { cause },\n    );\n  }\n}\n\n/** KDF algorithms supported by the secure-store metadata format. */\nexport type KdfAlgorithm = \"scrypt\" | \"argon2id\";\n\n/** Parameters for the scrypt KDF (RFC 7914). */\nexport interface ScryptParams {\n  /** CPU/memory cost. Must be a power of 2. Default 2^17 = 131072. */\n  N: number;\n  /** Block size. Default 8. */\n  r: number;\n  /** Parallelization. Default 1. */\n  p: number;\n  /** Output key length in bytes. Default 32 (AES-256). */\n  keyLength: number;\n  /** maxmem ceiling for scrypt; defaults to 256 MiB. */\n  maxmem: number;\n}\n\n/** Parameters for the Argon2id KDF. */\nexport interface Argon2idParams {\n  /** Memory cost in KiB. OWASP default 65536 (64 MiB). */\n  memoryKiB: number;\n  /** Time cost (iterations). OWASP default 3. */\n  iterations: number;\n  /** Parallelism. OWASP default 4. */\n  parallelism: number;\n  /** Output key length in bytes. Default 32 (AES-256). */\n  keyLength: number;\n}\n\n/** Strong scrypt defaults (OWASP-acceptable for 2024+). */\nexport const DEFAULT_SCRYPT_PARAMS: Readonly<ScryptParams> = Object.freeze({\n  // 2^17. Hex-coding the literal would obscure the doubling chain.\n  N: 1 << 17,\n  r: 8,\n  p: 1,\n  keyLength: 32,\n  // 256 MiB ceiling — comfortably above the 128 MiB scrypt needs at N=2^17.\n  maxmem: 256 * 1024 * 1024,\n});\n\n/** OWASP Argon2id defaults. */\nexport const DEFAULT_ARGON2ID_PARAMS: Readonly<Argon2idParams> = Object.freeze({\n  memoryKiB: 64 * 1024,\n  iterations: 3,\n  parallelism: 4,\n  keyLength: 32,\n});\n\n/** Salt length in bytes. 128 bits is the modern minimum. */\nexport const KDF_SALT_LENGTH = 16;\n\n/** Required derived-key length for AES-256 (32 bytes). */\nexport const KDF_KEY_LENGTH = 32;\n\n/**\n * Validate that scrypt parameters are within sane bounds and that\n * `N` is a power of 2 (required by RFC 7914).\n */\nexport function validateScryptParams(params: ScryptParams): void {\n  const { N, r, p, keyLength, maxmem } = params;\n  if (!Number.isInteger(N) || N < 2) {\n    throw new Error(`scrypt N must be an integer ≥ 2, got ${N}`);\n  }\n  // Cursor Low + codex P2: a `(N & (N - 1)) !== 0` check truncates\n  // to 32-bit semantics for `N >= 2**31`, so values like `5 * 2**30`\n  // would pass even though they are not powers of two, and absurdly\n  // large values like `2**33` would silently lock up the KDF. Use\n  // Math.log2-based detection plus an explicit upper bound at 2**30\n  // (already orders of magnitude past any practical memory budget)\n  // so out-of-range or non-power-of-two values are rejected loudly.\n  if (N > 2 ** 30) {\n    throw new Error(`scrypt N is unreasonably large (max 2^30), got ${N}`);\n  }\n  if (!Number.isInteger(Math.log2(N))) {\n    throw new Error(`scrypt N must be a power of 2, got ${N}`);\n  }\n  if (!Number.isInteger(r) || r < 1) {\n    throw new Error(`scrypt r must be a positive integer, got ${r}`);\n  }\n  if (!Number.isInteger(p) || p < 1) {\n    throw new Error(`scrypt p must be a positive integer, got ${p}`);\n  }\n  if (!Number.isInteger(keyLength) || keyLength < 16) {\n    throw new Error(\n      `scrypt keyLength must be ≥ 16 (need 32 for AES-256), got ${keyLength}`,\n    );\n  }\n  if (!Number.isInteger(maxmem) || maxmem < 1024) {\n    throw new Error(`scrypt maxmem must be a sane positive integer, got ${maxmem}`);\n  }\n}\n\n/** Validate Argon2id parameters before invoking the native KDF binding. */\nexport function validateArgon2idParams(params: Argon2idParams): void {\n  const { memoryKiB, iterations, parallelism, keyLength } = params;\n  if (!Number.isInteger(memoryKiB) || memoryKiB < 8) {\n    throw new Error(`argon2id memoryKiB must be an integer ≥ 8, got ${memoryKiB}`);\n  }\n  if (!Number.isInteger(iterations) || iterations < 1) {\n    throw new Error(`argon2id iterations must be a positive integer, got ${iterations}`);\n  }\n  if (!Number.isInteger(parallelism) || parallelism < 1 || parallelism > 255) {\n    throw new Error(`argon2id parallelism must be an integer in [1, 255], got ${parallelism}`);\n  }\n  if (!Number.isInteger(keyLength) || keyLength !== KDF_KEY_LENGTH) {\n    throw new Error(\n      `argon2id keyLength must be ${KDF_KEY_LENGTH} (AES-256 requires a 32-byte key), got ${keyLength}`,\n    );\n  }\n}\n\n/**\n * Derive a key from a passphrase + salt using scrypt.\n *\n * Pure: no I/O, no global state, deterministic for a given\n * (passphrase, salt, params) tuple.\n *\n * @throws if params are invalid.\n */\nexport function deriveKeyScrypt(\n  passphrase: string,\n  salt: Uint8Array,\n  params: ScryptParams = DEFAULT_SCRYPT_PARAMS,\n): Buffer {\n  if (typeof passphrase !== \"string\") {\n    throw new Error(\"passphrase must be a string\");\n  }\n  if (passphrase.length === 0) {\n    throw new Error(\"passphrase must not be empty\");\n  }\n  if (!(salt instanceof Uint8Array) || salt.length < 8) {\n    throw new Error(\n      `salt must be a Uint8Array of at least 8 bytes, got ${salt?.length ?? \"non-buffer\"}`,\n    );\n  }\n  validateScryptParams(params);\n  return scryptSync(passphrase, Buffer.from(salt), params.keyLength, {\n    N: params.N,\n    r: params.r,\n    p: params.p,\n    maxmem: params.maxmem,\n  });\n}\n\n/**\n * Derive a key from a passphrase + salt using Argon2id.\n *\n * The returned raw hash is used directly as the AES-256-GCM master key.\n * The same public KDF params are persisted in secure-store metadata so\n * unlock can reproduce the exact key later.\n */\nexport function deriveKeyArgon2id(\n  passphrase: string,\n  salt: Uint8Array,\n  params: Argon2idParams = DEFAULT_ARGON2ID_PARAMS,\n): Buffer {\n  if (typeof passphrase !== \"string\") {\n    throw new Error(\"passphrase must be a string\");\n  }\n  if (passphrase.length === 0) {\n    throw new Error(\"passphrase must not be empty\");\n  }\n  if (!(salt instanceof Uint8Array) || salt.length < 8) {\n    throw new Error(\n      `salt must be a Uint8Array of at least 8 bytes, got ${salt?.length ?? \"non-buffer\"}`,\n    );\n  }\n  validateArgon2idParams(params);\n  const { Algorithm, Version, hashRawSync } = loadArgon2Runtime();\n  return hashRawSync(passphrase, {\n    algorithm: Algorithm.Argon2id,\n    version: Version.V0x13,\n    memoryCost: params.memoryKiB,\n    timeCost: params.iterations,\n    parallelism: params.parallelism,\n    outputLen: params.keyLength,\n    salt,\n  });\n}\n\n/**\n * Algorithm-dispatching KDF. The algorithm name is recorded in the\n * metadata file so existing stores continue using their original KDF.\n */\nexport function deriveKey(\n  algorithm: KdfAlgorithm,\n  passphrase: string,\n  salt: Uint8Array,\n  params: ScryptParams | Argon2idParams,\n): Buffer {\n  if (algorithm === \"scrypt\") {\n    return deriveKeyScrypt(passphrase, salt, params as ScryptParams);\n  }\n  if (algorithm === \"argon2id\") {\n    return deriveKeyArgon2id(passphrase, salt, params as Argon2idParams);\n  }\n  throw new Error(`unknown KDF algorithm: ${algorithm as string}`);\n}\n\n/**\n * Constant-time equality for two derived keys / MACs. Re-exported so\n * callers don't reach into `node:crypto` directly for this primitive.\n */\nexport function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.length !== b.length) {\n    return false;\n  }\n  return timingSafeEqual(Buffer.from(a), Buffer.from(b));\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-RBBWYEFJ.js → chunk-G2WADRQ3.js}

@@ -216,4 +216,4 @@ export {
   getCausalTrajectoryStoreStatus,
   searchCausalTrajectories
 };
-//# sourceMappingURL=chunk-RBBWYEFJ.js.map
+//# sourceMappingURL=chunk-G2WADRQ3.js.map

package/dist/chunk-G7D6GZ5J.js

@@ -0,0 +1,48 @@
+// src/consolidation-operator.ts
+var CONSOLIDATION_OPERATORS = [
+  "split",
+  "merge",
+  "update",
+  "pattern-reinforcement"
+];
+var DERIVED_FROM_ENTRY_RE = /^(.+):(\d+)$/;
+var DERIVED_FROM_MEMORY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_:-]*$/;
+function looksLikeSnapshotEntry(entry) {
+  const match = entry.match(DERIVED_FROM_ENTRY_RE);
+  if (!match) return false;
+  const pathPart = match[1];
+  return pathPart.includes("/") || pathPart.includes(".");
+}
+function isValidDerivedFromEntry(entry) {
+  if (typeof entry !== "string") return false;
+  if (entry.length === 0) return false;
+  if (looksLikeSnapshotEntry(entry)) {
+    const match = entry.match(DERIVED_FROM_ENTRY_RE);
+    if (!match) return false;
+    const pathPart = match[1];
+    if (pathPart.length === 0 || pathPart.trim().length === 0) return false;
+    const versionNum = Number(match[2]);
+    return Number.isInteger(versionNum) && versionNum >= 0;
+  }
+  return DERIVED_FROM_MEMORY_ID_RE.test(entry);
+}
+function isConsolidationOperator(value) {
+  return typeof value === "string" && CONSOLIDATION_OPERATORS.includes(value);
+}
+var SEMANTIC_CONSOLIDATION_LLM_OPERATORS = [
+  "split",
+  "merge",
+  "update"
+];
+function isSemanticConsolidationLlmOperator(value) {
+  return typeof value === "string" && SEMANTIC_CONSOLIDATION_LLM_OPERATORS.includes(value);
+}
+
+export {
+  CONSOLIDATION_OPERATORS,
+  DERIVED_FROM_MEMORY_ID_RE,
+  isValidDerivedFromEntry,
+  isConsolidationOperator,
+  isSemanticConsolidationLlmOperator
+};
+//# sourceMappingURL=chunk-G7D6GZ5J.js.map

package/dist/chunk-G7D6GZ5J.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/consolidation-operator.ts"],"sourcesContent":["/**\n * consolidation-operator.ts — Standalone operator vocabulary + validators\n * for the consolidation subsystem (issue #561, All-Mem paper\n * arxiv:2603.19595).\n *\n * This module is intentionally dependency-free so storage, the `remnic\n * doctor` check (PR 4), and the undo CLI (PR 5) can import the validators\n * without dragging in the full consolidation engine — which in turn pulls\n * in the Codex materialize runner and creates a `storage → consolidation\n * → codex-materialize-runner → storage` import cycle.\n *\n * The `semantic-consolidation.ts` module re-exports these symbols so\n * existing import paths continue to work.\n */\n\n/**\n * Operator algebra for non-destructive consolidation.\n *\n * - `split`  — one source memory is rewritten as multiple smaller memories.\n * - `merge`  — multiple source memories are collapsed into one canonical\n *   memory.\n * - `update` — a newer value supersedes an older value within the same\n *   logical fact.\n * - `pattern-reinforcement` (issue #687 PR 2/4) — emitted by the\n *   pattern-reinforcement maintenance job when it clusters duplicate\n *   non-procedural memories and promotes the most recent member to\n *   canonical.  Unlike the other operators, the job does not produce\n *   page-versioning snapshots — it just stamps reinforcement metadata\n *   on the canonical and points superseded duplicates at it.  See\n *   `maintenance/pattern-reinforcement.ts`.\n */\nexport type ConsolidationOperator =\n  | \"split\"\n  | \"merge\"\n  | \"update\"\n  | \"pattern-reinforcement\";\n\n/**\n * Allowed values for the `derived_via` frontmatter field.  Used by storage\n * validation to reject unknown operator values on write.\n */\nexport const CONSOLIDATION_OPERATORS: readonly ConsolidationOperator[] = [\n  \"split\",\n  \"merge\",\n  \"update\",\n  \"pattern-reinforcement\",\n] as const;\n\n/**\n * Regular expression for validating a single `derived_from` entry.\n *\n * Format: `<non-empty memory path>:<integer version >= 0>`.  Matches the\n * `path:versionNumber` convention used by `page-versioning.ts` snapshots\n * (e.g. `\"facts/preferences.md:3\"`).  The path portion is greedy-last so\n * paths that themselves contain a colon remain parseable — only the final\n * `:<digits>` is consumed as the version.\n */\nconst DERIVED_FROM_ENTRY_RE = /^(.+):(\\d+)$/;\n\n/**\n * Regular expression for validating a memory-id `derived_from` entry\n * (issue #687 PR 2/4).  Pattern reinforcement records source memory IDs\n * directly rather than page-versioning snapshots, so we also need to\n * accept that shape.\n *\n * Memory IDs are alphanumeric with hyphens, underscores, or COLONS —\n * the namespace-prefixed form (e.g. `global:fact-abc-123`,\n * `entity:person-alice`) is a legitimate ID format already used\n * throughout the graph-retrieval code path (`stripDerivedFromVersion`).\n * The disambiguation against `<path>:<version>` is *not* \"no colons\n * allowed\" — it's \"the segment after the last colon must NOT be a\n * non-negative integer\" (PR #730 review feedback, Codex P1).\n *\n * Slashes and dots remain forbidden so paths cannot accidentally pass\n * as memory IDs.\n *\n * Exported so the consolidation-provenance integrity scanner (PR\n * #730 review feedback) can recognize bare memory IDs instead of\n * flagging them as malformed snapshot references.\n */\nexport const DERIVED_FROM_MEMORY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_:-]*$/;\n\n/**\n * Disambiguator: an entry is a `<path>:<version>` snapshot reference\n * iff it ends with `:<digits>` AND the left side contains a `/` or\n * `.` (path-shape).  Without the path-shape requirement a legitimate\n * namespace-prefixed memory id like `global:42` would be silently\n * misinterpreted as a snapshot reference.\n *\n * This mirrors the precedence used by `stripDerivedFromVersion` in\n * `graph-retrieval.ts`: only strip the trailing `:<digits>` when the\n * left side actually looks like a stored path.\n */\nfunction looksLikeSnapshotEntry(entry: string): boolean {\n  const match = entry.match(DERIVED_FROM_ENTRY_RE);\n  if (!match) return false;\n  const pathPart = match[1];\n  // A real snapshot path always contains a directory separator or a\n  // file extension dot.  Memory IDs use neither.\n  return pathPart.includes(\"/\") || pathPart.includes(\".\");\n}\n\n/**\n * Validate a `derived_from` entry string.  Returns `true` for either\n * - the snapshot format `<non-empty path>:<integer >= 0>` (issue #561), or\n * - a memory-id of the form `[A-Za-z0-9][A-Za-z0-9_:-]*` (issue #687\n *   PR 2/4 — used by pattern-reinforcement provenance).  Memory IDs\n *   may include `:` for namespace-prefixed forms like\n *   `global:fact-abc-123` (PR #730 review feedback, Codex P1).\n *\n * Disambiguation rule: only treat the entry as `<path>:<version>` when\n * the trailing segment after the last `:` is a non-negative integer\n * AND the left side looks like a path (contains `/` or `.`).\n * Otherwise treat the entire string as a memory ID.  This is the same\n * heuristic the graph retrieval path uses when splitting derived_from\n * references back into a memory id.\n *\n * Kept pure so storage and future CLI/doctor paths can share the same\n * validator.\n */\nexport function isValidDerivedFromEntry(entry: unknown): entry is string {\n  if (typeof entry !== \"string\") return false;\n  if (entry.length === 0) return false;\n  // Snapshot format takes precedence ONLY when the left side looks\n  // like a real path.  This avoids misclassifying memory IDs whose\n  // tail happens to be numeric (e.g. `global:42`).\n  if (looksLikeSnapshotEntry(entry)) {\n    const match = entry.match(DERIVED_FROM_ENTRY_RE);\n    if (!match) return false;\n    const pathPart = match[1];\n    if (pathPart.length === 0 || pathPart.trim().length === 0) return false;\n    const versionNum = Number(match[2]);\n    return Number.isInteger(versionNum) && versionNum >= 0;\n  }\n  // Otherwise treat as a memory ID.  Empty or `:`-only entries are\n  // already excluded by the leading-alphanumeric requirement of the\n  // regex.\n  return DERIVED_FROM_MEMORY_ID_RE.test(entry);\n}\n\n/**\n * Type guard for `ConsolidationOperator`.\n */\nexport function isConsolidationOperator(value: unknown): value is ConsolidationOperator {\n  return (\n    typeof value === \"string\" &&\n    (CONSOLIDATION_OPERATORS as readonly string[]).includes(value)\n  );\n}\n\n/**\n * Narrow operator vocabulary for the LLM-driven semantic-consolidation\n * pass (issue #561 PR 3).  This explicitly excludes\n * `\"pattern-reinforcement\"` (issue #687 PR 2/4), which is reserved for\n * the maintenance job and must NEVER be emitted by the consolidation\n * LLM.  Without this narrow gate, a hallucinated\n * `{\"operator\":\"pattern-reinforcement\"}` response from the LLM would\n * write misleading provenance on a semantic-consolidation memory\n * (Cursor Bugbot review, PR #730 head `aa1c2a8`).\n */\nexport type SemanticConsolidationLlmOperator = \"split\" | \"merge\" | \"update\";\n\nconst SEMANTIC_CONSOLIDATION_LLM_OPERATORS: readonly SemanticConsolidationLlmOperator[] = [\n  \"split\",\n  \"merge\",\n  \"update\",\n] as const;\n\n/**\n * Type guard restricted to the operator subset the\n * semantic-consolidation LLM is allowed to emit.  Use this in any\n * code path that validates LLM output — `isConsolidationOperator` is\n * for validating values that came from disk / internal callers.\n */\nexport function isSemanticConsolidationLlmOperator(\n  value: unknown,\n): value is SemanticConsolidationLlmOperator {\n  return (\n    typeof value === \"string\" &&\n    (SEMANTIC_CONSOLIDATION_LLM_OPERATORS as readonly string[]).includes(value)\n  );\n}\n"],"mappings":";AAyCO,IAAM,0BAA4D;AAAA,EACvE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAWA,IAAM,wBAAwB;AAuBvB,IAAM,4BAA4B;AAazC,SAAS,uBAAuB,OAAwB;AACtD,QAAM,QAAQ,MAAM,MAAM,qBAAqB;AAC/C,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,WAAW,MAAM,CAAC;AAGxB,SAAO,SAAS,SAAS,GAAG,KAAK,SAAS,SAAS,GAAG;AACxD;AAoBO,SAAS,wBAAwB,OAAiC;AACvE,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,MAAM,WAAW,EAAG,QAAO;AAI/B,MAAI,uBAAuB,KAAK,GAAG;AACjC,UAAM,QAAQ,MAAM,MAAM,qBAAqB;AAC/C,QAAI,CAAC,MAAO,QAAO;AACnB,UAAM,WAAW,MAAM,CAAC;AACxB,QAAI,SAAS,WAAW,KAAK,SAAS,KAAK,EAAE,WAAW,EAAG,QAAO;AAClE,UAAM,aAAa,OAAO,MAAM,CAAC,CAAC;AAClC,WAAO,OAAO,UAAU,UAAU,KAAK,cAAc;AAAA,EACvD;AAIA,SAAO,0BAA0B,KAAK,KAAK;AAC7C;AAKO,SAAS,wBAAwB,OAAgD;AACtF,SACE,OAAO,UAAU,YAChB,wBAA8C,SAAS,KAAK;AAEjE;AAcA,IAAM,uCAAoF;AAAA,EACxF;AAAA,EACA;AAAA,EACA;AACF;AAQO,SAAS,mCACd,OAC2C;AAC3C,SACE,OAAO,UAAU,YAChB,qCAA2D,SAAS,KAAK;AAE9E;","names":[]}

package/dist/chunk-H7XKCNR6.js

@@ -0,0 +1,60 @@
+// src/recall-disclosure-escalation.ts
+var DISCLOSURE_ESCALATION_MODES = [
+  "manual",
+  "auto"
+];
+function isDisclosureEscalationMode(value) {
+  return typeof value === "string" && DISCLOSURE_ESCALATION_MODES.includes(value);
+}
+var DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD = 0.5;
+function decideDisclosureEscalation(input) {
+  if (input.mode === "manual") {
+    return {
+      effective: input.originalDisclosure,
+      escalated: false,
+      reason: "escalation-mode=manual"
+    };
+  }
+  if (input.callerProvidedDisclosure) {
+    return {
+      effective: input.originalDisclosure,
+      escalated: false,
+      reason: "caller-explicit-disclosure"
+    };
+  }
+  if (input.originalDisclosure !== "chunk") {
+    return {
+      effective: input.originalDisclosure,
+      escalated: false,
+      reason: `original-disclosure=${input.originalDisclosure}-not-eligible-for-auto`
+    };
+  }
+  if (input.topKConfidence === void 0 || !Number.isFinite(input.topKConfidence)) {
+    return {
+      effective: input.originalDisclosure,
+      escalated: false,
+      reason: "no-top-k-confidence"
+    };
+  }
+  const threshold = Number.isFinite(input.threshold) && input.threshold >= 0 && input.threshold <= 1 ? input.threshold : DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD;
+  if (input.topKConfidence < threshold) {
+    return {
+      effective: "section",
+      escalated: true,
+      reason: `top-k-confidence=${input.topKConfidence.toFixed(3)}<${threshold}`
+    };
+  }
+  return {
+    effective: input.originalDisclosure,
+    escalated: false,
+    reason: `top-k-confidence=${input.topKConfidence.toFixed(3)}>=${threshold}`
+  };
+}
+
+export {
+  DISCLOSURE_ESCALATION_MODES,
+  isDisclosureEscalationMode,
+  DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD,
+  decideDisclosureEscalation
+};
+//# sourceMappingURL=chunk-H7XKCNR6.js.map

package/dist/chunk-H7XKCNR6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recall-disclosure-escalation.ts"],"sourcesContent":["/**\n * Recall disclosure auto-escalation policy (issue #677 PR 4/4).\n *\n * Pure helper that decides the *effective* disclosure depth for a recall\n * given the configured policy and the observed top-K confidence.  Lives\n * outside `access-service.ts` so the decision logic can be unit-tested\n * exhaustively without booting an orchestrator.\n *\n * Policy summary:\n *\n *   manual (default):\n *     The caller's `disclosure` is honored verbatim.  Auto-escalation\n *     does not run.\n *\n *   auto:\n *     If the caller did NOT explicitly specify a disclosure (i.e. the\n *     value in use is the system default) AND the recall's top-K\n *     confidence falls below the configured threshold, escalate from\n *     `chunk` to `section`.  `raw` is never auto-selected — it requires\n *     an explicit caller request because of its higher cost and the\n *     LCM-archive read paths it activates.  If the caller explicitly\n *     passed a disclosure (even `chunk`), the policy respects that\n *     choice and does not escalate.\n *\n * The threshold compares against `final` from the top result's score\n * decomposition.  When the snapshot has no results or no scores, no\n * escalation fires (`undefined` confidence is treated as \"skip\" rather\n * than \"always escalate\").\n */\n\nimport type { RecallDisclosure } from \"./types.js\";\n\nexport type DisclosureEscalationMode = \"manual\" | \"auto\";\n\nexport const DISCLOSURE_ESCALATION_MODES: readonly DisclosureEscalationMode[] = [\n  \"manual\",\n  \"auto\",\n] as const;\n\nexport function isDisclosureEscalationMode(\n  value: unknown,\n): value is DisclosureEscalationMode {\n  return (\n    typeof value === \"string\" &&\n    (DISCLOSURE_ESCALATION_MODES as readonly string[]).includes(value)\n  );\n}\n\n/**\n * Threshold defaults — applied when config-side coercion produces an\n * out-of-range or missing value.  0.5 is a deliberate midpoint:\n * confidently-served recalls (top-K >= 0.5) stay on the cheap chunk\n * tier; ambiguous recalls escalate to section.\n */\nexport const DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD = 0.5;\n\nexport interface DisclosureEscalationDecision {\n  /** The disclosure depth the caller should use to shape the response. */\n  effective: RecallDisclosure;\n  /**\n   * `true` when the policy escalated from the original disclosure;\n   * `false` when the original was kept (either by manual mode, by\n   * caller explicit choice, or because confidence stayed above the\n   * threshold).\n   */\n  escalated: boolean;\n  /**\n   * Human-readable reason for the decision.  Always populated; surfaces\n   * in operator-facing telemetry / debug paths.\n   */\n  reason: string;\n}\n\nexport interface DecideDisclosureEscalationInput {\n  /** The mode from config (`manual` | `auto`). */\n  mode: DisclosureEscalationMode;\n  /** Threshold in [0, 1]; values outside this range fall back to the default. */\n  threshold: number;\n  /** Disclosure resolved at request time (after default-fill). */\n  originalDisclosure: RecallDisclosure;\n  /**\n   * Whether the caller explicitly specified a disclosure value.  Auto\n   * mode only acts when the caller did NOT specify, so explicit\n   * `chunk` requests are not silently upgraded.\n   */\n  callerProvidedDisclosure: boolean;\n  /**\n   * Top-K confidence (`final` score from the highest-ranked result),\n   * or `undefined` when the snapshot has no scored results.\n   */\n  topKConfidence: number | undefined;\n}\n\n/**\n * Decide whether to escalate disclosure depth based on policy + signals.\n * Pure function — no IO, no state.\n */\nexport function decideDisclosureEscalation(\n  input: DecideDisclosureEscalationInput,\n): DisclosureEscalationDecision {\n  if (input.mode === \"manual\") {\n    return {\n      effective: input.originalDisclosure,\n      escalated: false,\n      reason: \"escalation-mode=manual\",\n    };\n  }\n\n  if (input.callerProvidedDisclosure) {\n    return {\n      effective: input.originalDisclosure,\n      escalated: false,\n      reason: \"caller-explicit-disclosure\",\n    };\n  }\n\n  // Only chunk → section auto-escalation is allowed.  Section and raw\n  // are never demoted; raw is never auto-selected.\n  if (input.originalDisclosure !== \"chunk\") {\n    return {\n      effective: input.originalDisclosure,\n      escalated: false,\n      reason: `original-disclosure=${input.originalDisclosure}-not-eligible-for-auto`,\n    };\n  }\n\n  if (\n    input.topKConfidence === undefined ||\n    !Number.isFinite(input.topKConfidence)\n  ) {\n    return {\n      effective: input.originalDisclosure,\n      escalated: false,\n      reason: \"no-top-k-confidence\",\n    };\n  }\n\n  const threshold =\n    Number.isFinite(input.threshold) &&\n    input.threshold >= 0 &&\n    input.threshold <= 1\n      ? input.threshold\n      : DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD;\n\n  if (input.topKConfidence < threshold) {\n    return {\n      effective: \"section\",\n      escalated: true,\n      reason: `top-k-confidence=${input.topKConfidence.toFixed(3)}<${threshold}`,\n    };\n  }\n\n  return {\n    effective: input.originalDisclosure,\n    escalated: false,\n    reason: `top-k-confidence=${input.topKConfidence.toFixed(3)}>=${threshold}`,\n  };\n}\n"],"mappings":";AAkCO,IAAM,8BAAmE;AAAA,EAC9E;AAAA,EACA;AACF;AAEO,SAAS,2BACd,OACmC;AACnC,SACE,OAAO,UAAU,YAChB,4BAAkD,SAAS,KAAK;AAErE;AAQO,IAAM,0CAA0C;AA2ChD,SAAS,2BACd,OAC8B;AAC9B,MAAI,MAAM,SAAS,UAAU;AAC3B,WAAO;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,WAAW;AAAA,MACX,QAAQ;AAAA,IACV;AAAA,EACF;AAEA,MAAI,MAAM,0BAA0B;AAClC,WAAO;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,WAAW;AAAA,MACX,QAAQ;AAAA,IACV;AAAA,EACF;AAIA,MAAI,MAAM,uBAAuB,SAAS;AACxC,WAAO;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,WAAW;AAAA,MACX,QAAQ,uBAAuB,MAAM,kBAAkB;AAAA,IACzD;AAAA,EACF;AAEA,MACE,MAAM,mBAAmB,UACzB,CAAC,OAAO,SAAS,MAAM,cAAc,GACrC;AACA,WAAO;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,WAAW;AAAA,MACX,QAAQ;AAAA,IACV;AAAA,EACF;AAEA,QAAM,YACJ,OAAO,SAAS,MAAM,SAAS,KAC/B,MAAM,aAAa,KACnB,MAAM,aAAa,IACf,MAAM,YACN;AAEN,MAAI,MAAM,iBAAiB,WAAW;AACpC,WAAO;AAAA,MACL,WAAW;AAAA,MACX,WAAW;AAAA,MACX,QAAQ,oBAAoB,MAAM,eAAe,QAAQ,CAAC,CAAC,IAAI,SAAS;AAAA,IAC1E;AAAA,EACF;AAEA,SAAO;AAAA,IACL,WAAW,MAAM;AAAA,IACjB,WAAW;AAAA,IACX,QAAQ,oBAAoB,MAAM,eAAe,QAAQ,CAAC,CAAC,KAAK,SAAS;AAAA,EAC3E;AACF;","names":[]}