Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
24.0 KB
Raw Blame
/**
 * Session-entity mining (recall-quality wave, Lane B / t_13a82a31).
 *
 * The miner is the precision-biased inverse of fact extraction: where
 * `extractFacts` strips code spans before matching, mining treats them as
 * the HIGHEST-precision source, because an identifier someone wrapped in
 * backticks is an identifier on purpose. Every family below is a
 * structural shape - no natural-language word list in any language - and
 * every side key is family-scoped and CASE-PRESERVING (NFC + trim only),
 * because symbols and paths are case-sensitive and the entity kernel's
 * lowercase fold is promotion's business, not the ledger's.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { join } from "node:path";

import {
  FAKE_QUERY_KEY,
  FAKE_VENDOR_KEY,
  fakeCredential,
} from "../../../helpers/fake-credentials.ts";
import { extractFacts } from "../../../../src/core/brain/fact-extract.ts";
import {
  appendContinuityRecord,
  continuityLogDir,
} from "../../../../src/core/brain/continuity/store.ts";
import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import {
  SessionCoverageEntityUnknownError,
  resolveEntityMentionRows,
} from "../../../../src/core/brain/session-recall.ts";
import {
  MAX_MINED_KEYS_PER_SESSION,
  MINED_KEY_MAX_LENGTH,
  SESSION_ENTITY_MENTION_KIND,
  SESSION_MINING_FAMILIES,
  isSecretShapedMention,
  mineAndRecordTurn,
  mineTurnEntities,
  miningDedupeId,
  miningKey,
} from "../../../../src/core/brain/link-graph/session-mining.ts";

/** Flat list of (family, key) pairs, for order-insensitive assertions. */
function mined(text: string): ReadonlyArray<readonly [string, string]> {
  return mineTurnEntities(text).map((m) => [m.family, m.key] as const);
}

describe("session-mining families", () => {
  test("the family set is exactly the four precision families", () => {
    expect([...SESSION_MINING_FAMILIES].toSorted()).toEqual([
      "path",
      "qualified-ident",
      "symbol",
      "url",
    ]);
  });

  test("symbol: inline code spans yield their identifier-shaped content", () => {
    const out = mined("call `SessionStore` and `foo_bar` from `FTS5`.");
    expect(out).toContainEqual(["symbol", "SessionStore"]);
    expect(out).toContainEqual(["symbol", "foo_bar"]);
    expect(out).toContainEqual(["symbol", "FTS5"]);
  });

  test("symbol: fenced code blocks are harvested token by token", () => {
    const text = ["```ts", "const store = new MyClass();", "load_tree(path);", "```"].join("\n");
    const out = mined(text);
    expect(out).toContainEqual(["symbol", "MyClass"]);
    expect(out).toContainEqual(["symbol", "load_tree"]);
  });

  test("symbol: prose without code spans is never mined as a symbol", () => {
    expect(mined("the SessionStore class and foo_bar live in prose")).toEqual([]);
  });

  test("symbol: a non-identifier code span (prose in backticks) is refused", () => {
    expect(mined("the rule is `keep it simple` today")).toEqual([]);
  });

  test("the code cue is canonical's: $HOME and MCP::SERVER are not symbols", () => {
    // The two code-shape definitions must agree. canonical.ts's
    // CODE_SHAPE_CHAR_RE is `[_./\p{N}]` and its camel-hump test wants a
    // lowercase-LETTER predecessor, so `$HOME` and `MCP::SERVER` carry no
    // code shape there - the doctor's shouted-heading verdict rejects
    // them, and a mined key the doctor rejects defeats the promotion
    // bypass mining was meant to feed.
    expect(mined("export `$HOME` and point `MCP::SERVER` at it")).toEqual([]);
    // The cue the canonical class does carry keeps mining.
    expect(mined("wire `MCP_Server` up today")).toContainEqual(["symbol", "MCP_Server"]);
  });

  test("qualified-ident: dotted and double-colon shapes of two or more segments", () => {
    const out = mined("wire osb.core.SessionStore through my_pkg::loader next");
    expect(out).toContainEqual(["qualified-ident", "osb.core.SessionStore"]);
    expect(out).toContainEqual(["qualified-ident", "my_pkg::loader"]);
  });

  test("qualified-ident: a shape needs a structural cue, plain prose pairs stay out", () => {
    // `alpha.beta` carries no digit, underscore or internal uppercase, so
    // it is indistinguishable from a name - refused. A third segment, a
    // digit, an underscore or a camel hump is the cue.
    expect(mined("read alpha.beta today")).toEqual([]);
    expect(mined("read alpha.beta.gamma today")).toContainEqual([
      "qualified-ident",
      "alpha.beta.gamma",
    ]);
    expect(mined("see Module2.method here")).toContainEqual(["qualified-ident", "Module2.method"]);
  });

  test("qualified-ident: one-letter segments stay out (no e.g / i.e captures)", () => {
    expect(mined("arrive e.g. today, i.e. tomorrow")).toEqual([]);
  });

  test("url: the fact-extract URL family is reproduced exactly on prose", () => {
    const text = "pin https://osb.example/run?dry=1 and http://intra.internal:8080/status";
    const factUrls = extractFacts(text)
      .filter((f) => f.family === "url")
      .map((f) => f.text)
      .toSorted();
    const minedUrls = mined(text)
      .filter(([family]) => family === "url")
      .map(([, key]) => key)
      .toSorted();
    expect(minedUrls).toEqual(factUrls);
    expect(minedUrls.length).toBe(2);
  });

  test("path: both slash directions with an extension", () => {
    const out = mined("edit src/core/store.ts then .\\notes\\idea.md and /usr/local/bin/run.sh");
    expect(out).toContainEqual(["path", "src/core/store.ts"]);
    expect(out).toContainEqual(["path", ".\\notes\\idea.md"]);
    expect(out).toContainEqual(["path", "/usr/local/bin/run.sh"]);
  });

  test("path: a separator without an extension is not a path", () => {
    expect(mined("look in src/core for it")).toEqual([]);
  });

  test("path: a host home path mines home-relative, never with the username", () => {
    // The design's "never a host absolute path" rule: a username in a
    // mined key reaches hallways.md and promoted pages, so the home
    // directory is replaced by `~` before the key is minted.
    const home = homedir();
    const out = mined(
      `see ${home}/notes/todo.md, /home/alice/notes/x.md and C:\\Users\\bob\\docs\\plan.md`,
    );
    expect(out).toContainEqual(["path", "~/notes/todo.md"]);
    expect(out).toContainEqual(["path", "~/notes/x.md"]);
    expect(out).toContainEqual(["path", "~\\docs\\plan.md"]);
    expect(out.some(([, key]) => key.includes("alice") || key.includes("bob"))).toBe(false);
    expect(out.some(([, key]) => key.startsWith("/home/") || key.includes("\\Users\\"))).toBe(
      false,
    );
  });

  test("path: a non-home path keeps its form", () => {
    const out = mined("edit src/core/store.ts and /usr/local/bin/run.sh today");
    expect(out).toContainEqual(["path", "src/core/store.ts"]);
    expect(out).toContainEqual(["path", "/usr/local/bin/run.sh"]);
  });

  test("families do not re-read inside each other: a URL is one mention, not three", () => {
    const out = mined("clone https://osb.example/repo.git now");
    expect(out).toEqual([["url", "https://osb.example/repo.git"]]);
  });

  test("span offsets stay aligned across a long turn: the URL claim lands where it must", () => {
    // A long turn pushes the URL (and the code span beside it) far past the
    // first line, so the claimed-range bookkeeping must hold its
    // lines->joined offsets over hundreds of lines: a drifted offset would
    // misplace the URL's claim and let the prose passes re-read inside it
    // or swallow the code span.
    const filler = Array.from({ length: 400 }, (_, i) => `filler line ${i} of plain prose`);
    const text = [
      ...filler,
      "see https://osb.example/deep/link and `OffsetPinStore`",
      ...filler,
    ].join("\n");
    const out = mined(text);
    expect(out).toContainEqual(["url", "https://osb.example/deep/link"]);
    expect(out).toContainEqual(["symbol", "OffsetPinStore"]);
    expect(out.filter(([family]) => family === "url")).toHaveLength(1);
  });

  test("code spans own their content: a path in a code span is a symbol, not a path", () => {
    const out = mined("run `src/core/store.ts` first");
    expect(out).toEqual([["symbol", "src/core/store.ts"]]);
  });

  test("mentions are deduped within a turn and deterministic", () => {
    const text = "use `SessionStore` twice `SessionStore` and once more";
    const first = mineTurnEntities(text);
    const second = mineTurnEntities(text);
    expect([...first]).toEqual([...second]);
    expect(first.filter((m) => m.key === "SessionStore").length).toBe(1);
  });

  test("oversized lines are capped, never scanned in full", () => {
    const blob = `x`.repeat(20000);
    const out = mined(`see ${blob}/evil.ts here`);
    expect(out).toEqual([]);
  });
});

describe("mining keys", () => {
  test("case is preserved: two casings of one symbol are two keys", () => {
    expect(miningKey("SessionStore")).toBe("SessionStore");
    expect(miningKey("sessionstore")).toBe("sessionstore");
    expect(miningKey("SessionStore")).not.toBe(miningKey("sessionstore"));
  });

  test("keys normalize to NFC and trim, nothing else", () => {
    const composed = "caf\u00e9";
    const decomposed = "cafe\u0301";
    expect(miningKey(decomposed)).toBe(miningKey(composed));
    expect(miningKey("  MyClass  ")).toBe("MyClass");
  });

  test("keys are length-capped, not unbounded", () => {
    expect(miningKey("A".repeat(5000)).length).toBeLessThanOrEqual(MINED_KEY_MAX_LENGTH);
  });
});

describe("secret-shaped refusal", () => {
  test("a vendor-prefixed key inside a code span is refused", () => {
    const text = `the key is \`${FAKE_VENDOR_KEY}\` in the config`;
    expect(isSecretShapedMention("symbol", FAKE_VENDOR_KEY)).toBe(true);
    expect(mined(text)).toEqual([]);
  });

  test("a credential URL (user:pass@host) is refused", () => {
    const pass = fakeCredential("hu", "nter2");
    const url = `https://deploy:${pass}@osb.example/repo.git`;
    expect(isSecretShapedMention("url", url)).toBe(true);
    expect(mined(`clone ${url} now`)).toEqual([]);
  });

  test("a token query form is refused", () => {
    const tok = fakeCredential("tok", "en-9f8e7d6c5b");
    const url = `https://osb.example/pull?token=${tok}`;
    expect(isSecretShapedMention("url", url)).toBe(true);
    expect(mined(`fetch ${url} today`)).toEqual([]);
  });

  test("a credential query parameter refuses the URL whole, by name", () => {
    // The redactor's exact-name pass catches `token=`/`key=`; the sibling
    // spellings a mined URL meets in the wild must refuse too - the ledger
    // keeps the mention id verbatim in sourceRefs[].id, so the
    // credential-bearing URL must never be minted at all.
    const url = `https://osb.example/v1/data?api_key=${FAKE_QUERY_KEY}&dry=1`;
    expect(isSecretShapedMention("url", url)).toBe(true);
    expect(mined(`fetch ${url} today`)).toEqual([]);
  });

  test("the sibling credential spellings refuse too: apikey, api-key, access_token, auth_token", () => {
    for (const name of ["apikey", "api-key", "access_token", "auth_token"]) {
      const url = `https://osb.example/v1/data?${name}=${FAKE_QUERY_KEY}`;
      expect(isSecretShapedMention("url", url)).toBe(true);
      expect(mined(`fetch ${url} today`)).toEqual([]);
    }
  });

  test("the credential-param refusal is case-insensitive", () => {
    expect(isSecretShapedMention("url", `https://osb.example/?API_KEY=${FAKE_QUERY_KEY}`)).toBe(
      true,
    );
    expect(isSecretShapedMention("url", `https://osb.example/?Auth-Token=${FAKE_QUERY_KEY}`)).toBe(
      true,
    );
  });

  test("a name-shaped path or parameter is not a credential: no over-refusal", () => {
    expect(isSecretShapedMention("url", "https://osb.example/settings/api_keys?page=2")).toBe(
      false,
    );
    expect(isSecretShapedMention("url", "https://osb.example/?api_key_version=2")).toBe(false);
    expect(isSecretShapedMention("url", "https://osb.example/run?dry=1")).toBe(false);
  });

  test("a credential URL with the token in its PATH is refused: Telegram bot shape", () => {
    // The ledger keeps a mention's sourceRefs[].id verbatim, so a
    // credential-bearing URL must never be minted at all - whichever
    // segment carries the credential. A bot token lives in the path.
    const bot = fakeCredential("123456789:", "AAHxyzABCdefGHIjklMNOpqrsTUVwxyz12345");
    const url = `https://api.telegram.org/bot${bot}/sendMessage`;
    expect(isSecretShapedMention("url", url)).toBe(true);
    expect(mined(`post ${url} now`)).toEqual([]);
  });

  test("a vendor webhook URL is refused: Slack incoming-hook shape", () => {
    const hook = fakeCredential("Xx1", "9f8e7d6c5b4a3210011223344");
    const url = `https://hooks.slack.com/services/T0000000/B0000000/${hook}`;
    expect(isSecretShapedMention("url", url)).toBe(true);
    expect(mined(`post ${url} now`)).toEqual([]);
  });

  test("credential query spellings refuse too: private_token and client_secret", () => {
    for (const name of ["private_token", "client_secret"]) {
      const url = `https://osb.example/v1/data?${name}=${FAKE_QUERY_KEY}`;
      expect(isSecretShapedMention("url", url)).toBe(true);
      expect(mined(`fetch ${url} today`)).toEqual([]);
    }
  });

  test("a fragment parameter refuses the URL: the implicit-flow shape", () => {
    // `#access_token=...` never reaches the query-pass boundary (`?`/`&`),
    // so the fragment separator is a boundary too.
    const url = `https://app.example.com/cb#access_token=${FAKE_QUERY_KEY}`;
    expect(isSecretShapedMention("url", url)).toBe(true);
    expect(mined(`open ${url} today`)).toEqual([]);
  });

  test("a fragment that names no credential keeps the URL: no over-refusal", () => {
    expect(isSecretShapedMention("url", "https://osb.example/docs#section-2")).toBe(false);
    expect(isSecretShapedMention("url", "https://osb.example/run?dry=1#top")).toBe(false);
  });

  test("a plain public URL is not refused", () => {
    expect(isSecretShapedMention("url", "https://osb.example/run?dry=1")).toBe(false);
  });

  test("ordinary identifiers are not refused", () => {
    expect(isSecretShapedMention("symbol", "SessionStore")).toBe(false);
    expect(isSecretShapedMention("symbol", "foo_bar")).toBe(false);
    expect(isSecretShapedMention("path", "src/core/store.ts")).toBe(false);
  });
});

describe("dedupe granularity", () => {
  test("the dedupe id is (family, key, sessionRef) - same key, other session, other id", () => {
    const a = miningDedupeId("symbol", "SessionStore", "s1.jsonl");
    expect(miningDedupeId("symbol", "SessionStore", "s1.jsonl")).toBe(a);
    expect(miningDedupeId("symbol", "SessionStore", "s2.jsonl")).not.toBe(a);
    expect(miningDedupeId("path", "SessionStore", "s1.jsonl")).not.toBe(a);
  });
});

describe("mineAndRecordTurn", () => {
  // bootstrapBrain(vault) bare is the shape the sibling link-graph tests use.
  let vault: string;

  beforeEach(() => {
    vault = mkdtempSync(join(tmpdir(), "o2b-mine-record-"));
    bootstrapBrain(vault);
  });

  afterEach(() => {
    rmSync(vault, { recursive: true, force: true });
  });

  const NOW = new Date("2026-06-13T12:00:00Z");

  function input(
    overrides: Partial<Parameters<typeof mineAndRecordTurn>[1]> = {},
  ): Parameters<typeof mineAndRecordTurn>[1] {
    return {
      vault,
      text: "touch `SessionStore` and src/core/store.ts today",
      sessionRef: "s1.jsonl",
      turnId: "t1",
      now: NOW,
      seen: new Set(),
      ...overrides,
    };
  }

  function ledgerLines(): number {
    const dir = continuityLogDir(vault);
    let isDir = false;
    try {
      isDir = statSync(dir).isDirectory();
    } catch {
      isDir = false;
    }
    if (!isDir) return 0;
    let count = 0;
    for (const entry of readdirSync(dir)) {
      if (!entry.endsWith(".jsonl")) continue;
      count += readFileSync(join(dir, entry), "utf8").trim().split("\n").filter(Boolean).length;
    }
    return count;
  }

  test("an applied turn writes its mentions and counts them extracted", () => {
    const seen = new Set<string>();
    const out = mineAndRecordTurn(vault, input({ seen }));
    expect(out.extracted).toBe(2);
    expect(out.ledgerFailed).toBe(0);
    expect(out.secretRefused).toBe(0);
    expect(ledgerLines()).toBe(2);
    // The written mentions are marked seen, so a re-fold dedupes.
    expect(seen.size).toBe(2);
  });

  test("a fresh run seeds its dedupe set from the ledger: a re-import dedupes", () => {
    // A re-import starts from an empty caller-owned set - the shape every
    // new process has. The first turn of the run reads the existing
    // mention rows once and seeds the set from them, so the re-import
    // folds to dedupe counters instead of appending duplicate rows.
    mineAndRecordTurn(vault, input());
    expect(ledgerLines()).toBe(2);

    const reimport = mineAndRecordTurn(vault, input({ seen: new Set() }));
    expect(reimport.extracted).toBe(0);
    expect(reimport.deduped).toBe(2);
    expect(ledgerLines()).toBe(2);
  });

  test("a failed ledger append is counted by name, never silent", () => {
    // Sabotage: a regular file where the continuity ledger's directory must
    // be, so every append throws. The telemetry-grade tolerance holds - the
    // turn must never fail - but the never-silent convention demands the
    // failures be COUNTED, not swallowed.
    writeFileSync(continuityLogDir(vault), "not a directory\n");
    const out = mineAndRecordTurn(vault, input());
    expect(out.extracted).toBe(0);
    expect(out.ledgerFailed).toBe(2);
    expect(ledgerLines()).toBe(0);
  });

  test("a failed append leaves the mention unseen, so it re-folds on a later run", () => {
    writeFileSync(continuityLogDir(vault), "not a directory\n");
    const seen = new Set<string>();
    mineAndRecordTurn(vault, input({ seen }));
    expect(seen.size).toBe(0);
    // Repair the ledger: the same mention re-folds and lands.
    rmSync(continuityLogDir(vault), { force: true });
    const retried = mineAndRecordTurn(vault, input({ seen }));
    expect(retried.extracted).toBe(2);
    expect(retried.ledgerFailed).toBe(0);
  });

  test("a fence holding a refused URL still mines the symbols around it", () => {
    // The old fence pass skipped a block WHOLE when the URL pass claimed
    // anything inside it, so one link silently deleted every symbol in the
    // fence. The URL stays the URL pass's - refused here, counted - and
    // the tokens around it are still mined, with the URL's own text masked
    // out so a refusal cannot re-enter the ledger as a symbol key.
    const text = [
      "```",
      "const hook = loadWebhook();",
      `see https://osb.example/pull?token=${FAKE_QUERY_KEY} inside`,
      "```",
    ].join("\n");
    const seen = new Set<string>();
    const out = mineAndRecordTurn(vault, input({ text, seen }));
    expect(out.secretRefused).toBe(1);
    expect(out.extracted).toBe(1);
    expect(mined(text)).toEqual([["symbol", "loadWebhook"]]);
  });
});

describe("the per-session key cap", () => {
  // Same harness shape as the mineAndRecordTurn block above.
  let vault: string;

  beforeEach(() => {
    vault = mkdtempSync(join(tmpdir(), "o2b-mining-cap-"));
    bootstrapBrain(vault);
  });

  afterEach(() => {
    rmSync(vault, { recursive: true, force: true });
  });

  const NOW = new Date("2026-06-13T12:00:00Z");

  function ledgerMentionRows(): number {
    const dir = continuityLogDir(vault);
    let count = 0;
    for (const entry of readdirSync(dir)) {
      if (!entry.endsWith(".jsonl")) continue;
      for (const line of readFileSync(join(dir, entry), "utf8").trim().split("\n")) {
        if (line.includes(SESSION_ENTITY_MENTION_KIND)) count++;
      }
    }
    return count;
  }

  test("an over-cap session stops minting and counts the overflow, never silently", () => {
    const seen = new Set<string>();
    // One hostile turn carrying more distinct keys than a session may
    // hold, one span per line (each line stays under the per-line scan
    // cap, so every span is really scanned).
    const overCap = MAX_MINED_KEYS_PER_SESSION + 10;
    const text = Array.from({ length: overCap }, (_, i) => `\`Cap_key_${i}\``).join("\n");
    const first = mineAndRecordTurn(vault, {
      vault,
      text,
      sessionRef: "hostile.jsonl",
      turnId: "u-1",
      now: NOW,
      seen,
    });
    expect(first.extracted).toBe(MAX_MINED_KEYS_PER_SESSION);
    expect(first.capOverflow).toBe(10);
    expect(ledgerMentionRows()).toBe(MAX_MINED_KEYS_PER_SESSION);

    // A later turn of the SAME session mints nothing: every fresh key is
    // overflow now, counted by name.
    const second = mineAndRecordTurn(vault, {
      vault,
      text: "`Cap_after_a` `Cap_after_b`",
      sessionRef: "hostile.jsonl",
      turnId: "u-2",
      now: NOW,
      seen,
    });
    expect(second.extracted).toBe(0);
    expect(second.capOverflow).toBe(2);
    expect(ledgerMentionRows()).toBe(MAX_MINED_KEYS_PER_SESSION);
  });

  test("the cap is per session: another session in the run keeps its own budget", () => {
    const seen = new Set<string>();
    const hostile = Array.from(
      { length: MAX_MINED_KEYS_PER_SESSION },
      (_, i) => `\`Cap_full_${i}\``,
    ).join("\n");
    mineAndRecordTurn(vault, {
      vault,
      text: hostile,
      sessionRef: "hostile.jsonl",
      turnId: "u-1",
      now: NOW,
      seen,
    });
    const other = mineAndRecordTurn(vault, {
      vault,
      text: "`Cap_calm_key`",
      sessionRef: "calm.jsonl",
      turnId: "u-1",
      now: NOW,
      seen,
    });
    expect(other.extracted).toBe(1);
    expect(other.capOverflow).toBe(0);
  });
});

describe("resolveEntityMentionRows (read-side entity wiring, t_2c2a883c)", () => {
  let vault: string;

  beforeEach(() => {
    vault = mkdtempSync(join(tmpdir(), "o2b-entity-rows-"));
    bootstrapBrain(vault);
  });

  afterEach(() => {
    rmSync(vault, { recursive: true, force: true });
  });

  function row(sessionRef: string, turnId: string, key = "SessionStore", family = "symbol"): void {
    appendContinuityRecord(vault, {
      kind: SESSION_ENTITY_MENTION_KIND,
      createdAt: "2026-06-13T12:00:00.000Z",
      sourceRefs: [{ id: `${sessionRef}:${turnId}:${family}:${key}` }],
      payload: { family, key, session_ref: sessionRef, turn_id: turnId },
    });
  }

  test("an entity key resolves to its mention rows across sessions and families", () => {
    row("s1.jsonl", "t1");
    row("s2.jsonl", "t7");
    row("s2.jsonl", "t9", "SessionStore", "path");

    const rows = resolveEntityMentionRows(vault, "SessionStore");
    expect(rows.map((r) => [r.session_ref, r.turn_id, r.family])).toEqual([
      ["s1.jsonl", "t1", "symbol"],
      ["s2.jsonl", "t7", "symbol"],
      ["s2.jsonl", "t9", "path"],
    ]);
  });

  test("keys are case-preserving and private or malformed rows never resolve", () => {
    row("s1.jsonl", "t1");
    row("s1.jsonl", "t2", "sessionstore");
    appendContinuityRecord(vault, {
      kind: SESSION_ENTITY_MENTION_KIND,
      createdAt: "2026-06-13T12:00:00.000Z",
      sourceRefs: [{ id: "s1.jsonl:t3:symbol:SessionStore" }],
      private: true,
      payload: { family: "symbol", key: "SessionStore", session_ref: "s1.jsonl", turn_id: "t3" },
    });
    appendContinuityRecord(vault, {
      kind: SESSION_ENTITY_MENTION_KIND,
      createdAt: "2026-06-13T12:00:00.000Z",
      sourceRefs: [{ id: "s1.jsonl:t4:symbol:SessionStore" }],
      payload: { family: "symbol", session_ref: "s1.jsonl", turn_id: "t4" },
    });

    const rows = resolveEntityMentionRows(vault, "SessionStore");
    expect(rows.map((r) => r.turn_id)).toEqual(["t1"]);
    expect(() => resolveEntityMentionRows(vault, "sessionstore")).not.toThrow();
  });

  test("an unknown key raises the typed coverage error, never an empty silent result", () => {
    let probe: SessionCoverageEntityUnknownError | null = null;
    try {
      resolveEntityMentionRows(vault, "NoSuchKey");
    } catch (err) {
      probe = err as SessionCoverageEntityUnknownError;
    }
    expect(probe).not.toBeNull();
    expect(probe).toBeInstanceOf(SessionCoverageEntityUnknownError);
    expect(probe!.entityKey).toBe("NoSuchKey");
    expect(probe!.reason).toBe("no_mention_rows");
    expect(probe!.message).toContain("NoSuchKey");
  });
});