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
/**
* Model-mined session signals (salience-lifecycle-enrichment, unit 2,
* t_1dace26d). Claims pinned here:
*
* 1. Phase one reads an ALREADY-IMPORTED session and returns a report
* carrying exactly one needs-llm-step envelope built on the spine.
* 2. The prompt mines USER turns only, mirroring the import path's rule,
* and the envelope is deterministic for a fixed set of turns.
* 3. A session with no imported turns, and one whose turns are all
* non-user, are refused BY NAME - never reported as an empty mine.
* 4. A session the capture boundary ignores is refused by name.
* 5. Phase two refuses an over-cap payload naming the cap and the count.
* 6. Phase two refuses an under-floor item naming the floor and the value.
* 7. A conforming payload writes `source_type: auto_extract` signals into
* `Brain/inbox/`, and each carries the session provenance.
* 8. The durability denylist rejects items by name, never silently.
* 9. Write approval on stages every accepted item into `Brain/pending/`
* instead, and writes nothing to the inbox.
* 10. A repeated payload dedups against the signals already on disk.
* 11. A write that fails PART WAY through the items is reported as the
* partial write it is: the error names the items already on disk and
* the one that failed, rather than leaving the caller to discover
* them.
* 21. A session whose mining record matches its current turn material is
* suppressed at plan time with a typed reason and the recorded
* breakdown as evidence, and stays suppressed while unchanged.
* 22. A re-import that changes the turns re-opens the session with no
* clearing step.
* 23. A corrupt mining ledger refuses the plan by name; it is never read
* as an empty ledger.
*/
import { afterEach, beforeEach, expect, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import {
AUTO_EXTRACT_CONFIDENCE_FLOOR,
AUTO_EXTRACT_PER_SESSION_CAP,
commitExtractedSignals,
EXTRACT_SIGNALS_STEP,
ExtractSignalsError,
ExtractSignalsWriteError,
planExtractSignals,
} from "../../../src/core/brain/extract-signals.ts";
import { listDeadLetters } from "../../../src/core/brain/dead-letter.ts";
import { NEEDS_LLM_STEP } from "../../../src/core/brain/llm-step.ts";
import {
EXTRACT_MINING_TOMBSTONE_SKIP_REASON,
planExtractSignalsPrefiltered,
} from "../../../src/core/brain/extract-signals-prefilter.ts";
import {
minedTurnsHash,
readSessionMiningLedger,
recordSessionMiningOutcome,
SESSION_MINING_LEDGER_SCHEMA_VERSION,
sessionMiningLedgerPath,
type SessionMiningEntry,
} from "../../../src/core/brain/session-mining-ledger.ts";
import { sessionMiningSurveysPath } from "../../../src/core/brain/session-mining-surveys.ts";
import {
ResponseCheckError,
SEMANTIC_VIOLATION_CODES,
} from "../../../src/core/brain/response-checks.ts";
import { ResponseShapeError } from "../../../src/core/brain/response-shape.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { brainConfigPath } from "../../../src/core/brain/paths.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { importSessionRecall } from "../../../src/core/brain/session-recall.ts";
import type { DedupIndexEntry } from "../../../src/core/brain/dedup-hash.ts";
import { parseSignal } from "../../../src/core/brain/signal.ts";
import { BRAIN_SIGNAL_SOURCE_TYPE } from "../../../src/core/brain/types.ts";
import type { SessionTurn } from "../../../src/core/brain/sessions/types.ts";
let vault: string;
const NOW = new Date("2026-08-22T10:00:00Z");
const SESSION = "sess-alpha";
/**
* Turns carry DISTINCT timestamps, as a real transcript does: the recall
* store orders raw turns chronologically and falls back to the record hash
* only for a tie, so a fixture that stamped one instant on every turn would
* pin the tie-break rather than the chronology the prompt depends on.
*/
let turnClock = 0;
function turn(id: string, role: SessionTurn["role"], text: string): SessionTurn {
turnClock += 1;
const stamp = String(turnClock).padStart(2, "0");
return { turnId: id, timestamp: `2026-08-22T09:${stamp}:00Z`, role, text };
}
function importTurns(sessionId: string, turns: ReadonlyArray<SessionTurn>): void {
importSessionRecall(vault, { sessionId, turns, createdAt: NOW.toISOString() });
}
function inboxFiles(): string[] {
const dir = join(vault, "Brain", "inbox");
return existsSync(dir)
? readdirSync(dir)
.filter((f) => f.endsWith(".md"))
.toSorted()
: [];
}
function pendingFiles(): string[] {
const dir = join(vault, "Brain", "pending");
return existsSync(dir)
? readdirSync(dir)
.filter((f) => f.endsWith(".md"))
.toSorted()
: [];
}
function item(overrides: Record<string, unknown> = {}): Record<string, unknown> {
return {
topic: "release-notes-style",
signal: "positive",
principle: "Name the release theme in the heading, never the ticket id.",
confidence: 0.9,
...overrides,
};
}
beforeEach(() => {
turnClock = 0;
vault = mkdtempSync(join(tmpdir(), "o2b-extract-signals-"));
mkdirSync(join(vault, "Brain"), { recursive: true });
importTurns(SESSION, [
turn("t1", "user", "Always name the release theme in the heading."),
turn("t2", "assistant", "Understood - I will use the theme."),
turn("t3", "user", "And never abbreviate the module names."),
]);
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
test("phase one carries exactly one spine envelope over the user turns", () => {
const plan = planExtractSignals(vault, SESSION, { now: NOW });
expect(plan.sessionId).toBe(SESSION);
expect(plan.turnsScanned).toBe(3);
expect(plan.turnsMined.map((t) => t.turnId)).toEqual(["t1", "t3"]);
// The surveyed hash names the material the plan put in front of the
// caller; the commit passes it back so the mining record keys on it.
expect(plan.surveyedTurnsHash).toBe(minedTurnsHash(plan.turnsMined));
expect(plan.llmStep.status).toBe(NEEDS_LLM_STEP);
expect(plan.llmStep.prompt).toContain("Always name the release theme");
// The assistant turn is not mining material.
expect(plan.llmStep.prompt).not.toContain("Understood - I will use the theme");
expect(plan.llmStep.schema_hints.length).toBeGreaterThan(0);
expect(plan.llmStep.target_path).toBe("Brain/inbox");
expect(plan.cap).toBe(AUTO_EXTRACT_PER_SESSION_CAP);
expect(plan.confidenceFloor).toBe(AUTO_EXTRACT_CONFIDENCE_FLOOR);
});
test("the envelope is deterministic for a fixed set of turns", () => {
const first = planExtractSignals(vault, SESSION, { now: NOW });
const second = planExtractSignals(vault, SESSION, { now: NOW });
expect(second.llmStep).toEqual(first.llmStep);
});
test("a session with no imported turns is refused by name", () => {
expect(() => planExtractSignals(vault, "sess-missing", { now: NOW })).toThrow(
ExtractSignalsError,
);
expect(() => planExtractSignals(vault, "sess-missing", { now: NOW })).toThrow(/sess-missing/);
});
test("a session whose turns are all non-user is refused by name", () => {
importTurns("sess-quiet", [turn("q1", "assistant", "Only I spoke here.")]);
expect(() => planExtractSignals(vault, "sess-quiet", { now: NOW })).toThrow(/user/);
});
test("a session the capture boundary ignores is refused by name", () => {
bootstrapBrain(vault);
const path = brainConfigPath(vault);
atomicWriteFileSync(
path,
`${readFileSync(path, "utf8")}\nsessions:\n ignore_patterns:\n - "cron-*"\n`,
);
importTurns("cron-nightly", [turn("c1", "user", "Nightly cron chatter.")]);
expect(() => planExtractSignals(vault, "cron-nightly", { now: NOW })).toThrow(/cron-nightly/);
expect(() => planExtractSignals(vault, "cron-nightly", { now: NOW })).toThrow(/ignore/);
});
test("an over-cap payload is refused naming the cap and the count", () => {
const overCap = AUTO_EXTRACT_PER_SESSION_CAP + 1;
const items = Array.from({ length: overCap }, (_v, i) => item({ topic: `topic-${i}` }));
let caught: unknown;
try {
commitExtractedSignals(vault, SESSION, { items }, { agent: "tester", now: NOW });
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(ResponseCheckError);
expect((caught as Error).message).toContain(String(AUTO_EXTRACT_PER_SESSION_CAP));
expect((caught as Error).message).toContain(String(overCap));
expect(inboxFiles()).toEqual([]);
});
test("an under-floor item is refused naming the floor and the value", () => {
const low = 0.11;
let caught: unknown;
try {
commitExtractedSignals(
vault,
SESSION,
{ items: [item({ confidence: low })] },
{ agent: "tester", now: NOW },
);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(ResponseCheckError);
expect((caught as Error).message).toContain(String(AUTO_EXTRACT_CONFIDENCE_FLOOR));
expect((caught as Error).message).toContain(String(low));
expect(inboxFiles()).toEqual([]);
});
test("a structurally malformed payload is refused by the shape layer", () => {
expect(() =>
commitExtractedSignals(
vault,
SESSION,
{ items: [{ topic: "t", signal: "sideways", principle: "p", confidence: 0.9 }] },
{ agent: "tester", now: NOW },
),
).toThrow(ResponseShapeError);
expect(inboxFiles()).toEqual([]);
});
test("a conforming payload writes auto_extract signals into the inbox", () => {
const res = commitExtractedSignals(
vault,
SESSION,
{
items: [item(), item({ topic: "module-names", principle: "Never abbreviate module names." })],
},
{ agent: "tester", now: NOW },
);
expect(res.written.length).toBe(2);
expect(res.staged).toBe(0);
const files = inboxFiles();
expect(files.length).toBe(2);
const body = readFileSync(join(vault, "Brain", "inbox", files[0]!), "utf8");
expect(body).toContain(`source_type: ${BRAIN_SIGNAL_SOURCE_TYPE.autoExtract}`);
expect(body).toContain(`session_ref: ${SESSION}`);
});
test("the durability denylist rejects an item by name rather than dropping it", () => {
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [item(), item({ topic: "noise", principle: "temporary scratch note" })] },
{
agent: "tester",
now: NOW,
durabilityDenylist: [/scratch/],
},
);
expect(res.written.length).toBe(1);
expect(res.rejected.map((r) => r.topic)).toEqual(["noise"]);
expect(res.rejected[0]!.reason.length).toBeGreaterThan(0);
});
test("write approval on stages every item into pending and writes no inbox file", () => {
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [item()] },
{ agent: "tester", now: NOW, writeApprovalEnabled: true },
);
expect(res.staged).toBe(1);
expect(pendingFiles().length).toBe(1);
expect(inboxFiles()).toEqual([]);
});
test("a repeated payload dedups against the signals already on disk", () => {
const payload = { items: [item()] };
commitExtractedSignals(vault, SESSION, payload, { agent: "tester", now: NOW });
const second = commitExtractedSignals(vault, SESSION, payload, { agent: "tester", now: NOW });
expect(second.written.length).toBe(0);
expect(second.deduped).toBe(1);
expect(inboxFiles().length).toBe(1);
});
test("a mid-loop write failure names what is already on disk and what failed", () => {
// The failing write is a real one, not a stub: `topic` becomes the
// signal's slug and a colon is not a legal filename character, so the
// second item cannot be written after the first already has been.
const items = [item(), item({ topic: "module:names", principle: "Never abbreviate a module." })];
let caught: unknown;
try {
commitExtractedSignals(vault, SESSION, { items }, { agent: "tester", now: NOW });
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(ExtractSignalsWriteError);
const err = caught as ExtractSignalsWriteError;
expect(err.topic).toBe("module:names");
expect(err.written.map((w) => w.topic)).toEqual(["release-notes-style"]);
expect(err.remaining).toBe(1);
// The accounting is in the message too, for a caller that only logs it.
expect(err.message).toContain(err.written[0]!.id);
// The first item stayed on disk: this is a partial write, and saying so
// is the whole point.
expect(inboxFiles().length).toBe(1);
});
test("the new source_type round-trips and an unknown member is still refused", () => {
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [item()] },
{ agent: "tester", now: NOW },
);
const parsed = parseSignal(res.written[0]!.path);
expect(parsed.source_type).toBe(BRAIN_SIGNAL_SOURCE_TYPE.autoExtract);
// The vocabulary is still closed: the parser refuses a member nobody
// declared, and names the whole legal set rather than a stale subset.
const path = res.written[0]!.path;
atomicWriteFileSync(
path,
readFileSync(path, "utf8").replace("source_type: auto_extract", "source_type: sideways"),
);
expect(() => parseSignal(path)).toThrow(/auto_extract/);
expect(() => parseSignal(path)).toThrow(/sideways/);
});
// ----- Write accounting and the durable dead letter (unit E) ---------------
//
// 12. Every commit reports its write accounting in the wave's shared
// reconciliation vocabulary - attempted / found / missing, the missing
// keys NAMED - on the success path and on the refusal alike.
// 13. A commit that lands nothing does not read as a success: the accounting
// says found 0, names every unwritten item, and carries the first real
// error.
// 14. A partial write leaves a DURABLE dead letter naming the unwritten
// items, so a caller that drops the response is not the only record of
// it - and the error says where that record landed.
test("a completed commit reports its accounting in the shared vocabulary", () => {
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [item(), item({ topic: "no-abbrev", principle: "Never abbreviate a module name." })] },
{ agent: "tester", now: NOW },
);
expect(res.reconciliation).toEqual({ attempted: 2, found: 2, missing: [] });
expect(listDeadLetters(vault)).toEqual([]);
});
test("a deduped or gate-rejected item is not counted as an attempted write", () => {
// Both are deliberate skips the result already names; folding them into
// `missing` would report a refusal the lane made as a loss it suffered.
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [item(), item({ topic: "noise", principle: "temporary scratch note" })] },
{ agent: "tester", now: NOW, durabilityDenylist: [/scratch/] },
);
expect(res.reconciliation).toEqual({ attempted: 1, found: 1, missing: [] });
expect(res.durabilityRejected).toBe(1);
});
test("a mid-loop write failure reports attempted, written and missing plus the first error", () => {
const items = [item(), item({ topic: "module:names", principle: "Never abbreviate a module." })];
let caught: unknown;
try {
commitExtractedSignals(vault, SESSION, { items }, { agent: "tester", now: NOW });
} catch (err) {
caught = err;
}
const err = caught as ExtractSignalsWriteError;
expect(err).toBeInstanceOf(ExtractSignalsWriteError);
expect(err.reconciliation.attempted).toBe(2);
expect(err.reconciliation.found).toBe(1);
expect(err.reconciliation.missing).toEqual(["items[1]:module:names"]);
expect(err.firstError).toBeDefined();
});
test("a commit that lands nothing never reads as a success", () => {
// The FIRST item fails, so nothing at all reaches disk.
const items = [item({ topic: "module:names" }), item({ topic: "no-abbrev" })];
let caught: unknown;
try {
commitExtractedSignals(vault, SESSION, { items }, { agent: "tester", now: NOW });
} catch (err) {
caught = err;
}
const err = caught as ExtractSignalsWriteError;
expect(err).toBeInstanceOf(ExtractSignalsWriteError);
expect(err.reconciliation.found).toBe(0);
expect(err.reconciliation.attempted).toBe(2);
expect(err.reconciliation.missing).toEqual(["items[0]:module:names", "items[1]:no-abbrev"]);
expect(inboxFiles()).toEqual([]);
});
test("a partial write leaves a durable dead letter naming the unwritten items", () => {
const items = [item(), item({ topic: "module:names", principle: "Never abbreviate a module." })];
let caught: unknown;
try {
commitExtractedSignals(vault, SESSION, { items }, { agent: "tester", now: NOW });
} catch (err) {
caught = err;
}
const err = caught as ExtractSignalsWriteError;
const letters = listDeadLetters(vault);
expect(letters).toHaveLength(1);
const letter = letters[0]!;
expect(letter.lane).toBe("extract-signals");
expect(letter.step).toBe(EXTRACT_SIGNALS_STEP);
expect(letter.reference).toBe(SESSION);
expect(letter.attempted).toBe(2);
expect(letter.found).toBe(1);
expect(letter.missing).toEqual(["items[1]:module:names"]);
expect(letter.outcome).toBe("partial");
expect(letter.first_error.length).toBeGreaterThan(0);
// The response says where the durable record is, so a caller that keeps
// the response can go straight to it.
expect(err.deadLetter.recorded).toBe(true);
if (err.deadLetter.recorded) expect(err.message).toContain(err.deadLetter.id);
});
// ----- Turn timestamps in the envelope (near-duplicate-defense, C1) --------
//
// 15. A mined turn carries the stored turn timestamp verbatim, and the
// transcript line shows it as `[turnId @ <timestamp>] text`.
// 16. A turn stored without a timestamp renders `[turnId] text`; the plan's
// clock is never substituted for the missing value.
test("a mined turn carries the stored timestamp verbatim into its transcript line", () => {
const plan = planExtractSignals(vault, SESSION, { now: NOW });
expect(plan.turnsMined.map((t) => t.timestamp)).toEqual([
"2026-08-22T09:01:00Z",
"2026-08-22T09:03:00Z",
]);
expect(plan.llmStep.prompt).toContain(
"[t1 @ 2026-08-22T09:01:00Z] Always name the release theme in the heading.",
);
expect(plan.llmStep.prompt).toContain(
"[t3 @ 2026-08-22T09:03:00Z] And never abbreviate the module names.",
);
// Assistant turns stay out, timestamp or not.
expect(plan.llmStep.prompt).not.toContain("[t2");
});
test("a turn without a stored timestamp renders bare and never borrows the clock", () => {
importTurns("sess-undated", [
{ turnId: "u1", timestamp: "", role: "user", text: "Keep the changelog terse." },
]);
const plan = planExtractSignals(vault, "sess-undated", { now: NOW });
expect(plan.turnsMined.map((t) => t.timestamp)).toEqual([""]);
expect(plan.llmStep.prompt).toContain("[u1] Keep the changelog terse.");
expect(plan.llmStep.prompt).not.toContain("[u1 @");
expect(plan.llmStep.prompt).not.toContain(NOW.toISOString());
});
// ----- Hygiene rules in the envelope (near-duplicate-defense, C2) ----------
//
// 17. The instruction carries five language-neutral rules: time bounds as
// ISO dates or intervals, conversational mechanics skipped, one rule
// per item, conditions kept, restatements dropped.
// 18. The rules name categories, never example words: the instruction and
// the schema hints quote no phrase and stay ASCII, so no language's
// vocabulary is baked into the kernel.
/** The instruction half of the prompt, everything before the transcript. */
function instruction(prompt: string): string {
return prompt.slice(0, prompt.indexOf("\n\n"));
}
test("the envelope instruction carries the five hygiene rules", () => {
const plan = planExtractSignals(vault, SESSION, { now: NOW });
const head = instruction(plan.llmStep.prompt);
expect(head).toContain("ISO 8601 date or interval");
expect(head).toContain("timestamp of the turn");
expect(head).toContain("conversational mechanics");
expect(head).toContain("one rule per item");
expect(head).toContain("condition");
expect(head).toContain("restatement");
expect(plan.llmStep.schema_hints.join("\n")).toContain("ISO 8601");
});
test("the hygiene rules name categories and quote no example words", () => {
const plan = planExtractSignals(vault, SESSION, { now: NOW });
const head = instruction(plan.llmStep.prompt);
const hints = plan.llmStep.schema_hints.filter((hint) => !hint.startsWith("payload:"));
for (const text of [head, ...hints]) {
expect(text).not.toMatch(/"/);
expect(text).toMatch(/^[\x20-\x7e]*$/);
}
});
// ----- Duplicate-topic refusal (near-duplicate-defense, C3) -----------------
//
// 19. Two items sharing a `topic` refuse the payload whole under the
// cross-item code, and the message names both indices and the topic.
// 20. The refusal lands before any write and before any item is hashed for
// dedup, so a refused payload leaves the vault and the index untouched.
/** A dedup index that counts every keyed read; one read follows every hash. */
class CountingDedup extends Map<string, DedupIndexEntry> {
lookups = 0;
override has(key: string): boolean {
this.lookups += 1;
return super.has(key);
}
override get(key: string): DedupIndexEntry | undefined {
this.lookups += 1;
return super.get(key);
}
}
test("a payload that repeats a topic is refused whole, naming both indices", () => {
const dedup = new CountingDedup();
const items = [
item(),
item({ topic: "module-names", principle: "Never abbreviate module names." }),
item({ principle: "Put the release theme in the heading." }),
];
let caught: unknown;
try {
commitExtractedSignals(vault, SESSION, { items }, { agent: "tester", now: NOW, dedup });
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(ResponseCheckError);
const err = caught as ResponseCheckError;
expect(err.code).toBe(SEMANTIC_VIOLATION_CODES.crossItem);
expect(err.message).toContain('items[0] and items[2] share topic "release-notes-style"');
expect(dedup.lookups).toBe(0);
expect(dedup.size).toBe(0);
expect(inboxFiles()).toEqual([]);
});
test("distinct topics pass the duplicate-topic rule", () => {
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [item(), item({ topic: "module-names", principle: "Never abbreviate modules." })] },
{ agent: "tester", now: NOW },
);
expect(res.written.map((w) => w.topic)).toEqual(["release-notes-style", "module-names"]);
});
// ----- The zero-yield mining tombstone at plan time (session-mining-economy)
//
// 21. A session whose mining record matches its current turn material is
// suppressed at plan time with a typed reason and the recorded
// breakdown as evidence - never an empty plan that reads as a clean
// run - and stays suppressed while the content is unchanged.
// 22. A re-import that changes the turns re-opens the session with no
// clearing step.
// 23. A corrupt mining ledger refuses the plan by name; it is never read
// as an empty ledger.
/** Records a zero-yield tombstone over the session's current mined material. */
function seedTombstone(): void {
const full = planExtractSignals(vault, SESSION, { now: NOW });
recordSessionMiningOutcome(
vault,
{
sessionId: SESSION,
minedContentHash: minedTurnsHash(full.turnsMined),
outcome: { written: 0, staged: 0, deduped: 2, durabilityRejected: 0 },
},
NOW,
);
}
test("a matching tombstone suppresses the plan with the recorded breakdown", async () => {
seedTombstone();
const plan = await planExtractSignalsPrefiltered(vault, SESSION, {
now: NOW,
decisionModel: null,
});
expect(plan.llmStep).toBeNull();
expect(plan.skipped).toEqual({
reason: EXTRACT_MINING_TOMBSTONE_SKIP_REASON,
miningOutcome: { written: 0, staged: 0, deduped: 2, durabilityRejected: 0 },
});
expect(plan.turnsMined).toEqual([]);
// Unchanged content stays suppressed on every later scan.
const again = await planExtractSignalsPrefiltered(vault, SESSION, {
now: NOW,
decisionModel: null,
});
expect(again.skipped).toEqual(plan.skipped);
});
test("a re-import that changes the turns re-opens the session", async () => {
seedTombstone();
importTurns(SESSION, [turn("t9", "user", "A turn imported after the barren mine.")]);
const plan = await planExtractSignalsPrefiltered(vault, SESSION, {
now: NOW,
decisionModel: null,
});
expect(plan.skipped).toBeUndefined();
expect(plan.llmStep).not.toBeNull();
expect(plan.turnsMined.map((t) => t.turnId)).toEqual(["t1", "t3", "t9"]);
});
test("a corrupt mining ledger refuses the plan by name", async () => {
seedTombstone();
const path = sessionMiningLedgerPath(vault);
writeFileSync(path, "{ truncated");
try {
await planExtractSignalsPrefiltered(vault, SESSION, { now: NOW, decisionModel: null });
throw new Error("expected the plan to refuse");
} catch (err) {
expect((err as Error).message).toContain("session mining ledger is corrupted JSON");
}
// The ledger was never reset by the refused read.
expect(readFileSync(path, "utf8")).toBe("{ truncated");
});
test("the session mining ledger schema version is pinned at 1", () => {
// Its own test, not a stapled assertion inside the corrupt-ledger
// error path: the value is load-bearing (the ledger's unknown-schema
// refusal names it) but it is a constant of the read contract, not
// part of any error-path contract.
expect(SESSION_MINING_LEDGER_SCHEMA_VERSION).toBe(1);
});
// ----- Record-at-commit (session-mining-economy) ----------------------------
//
// 24. Every successful commit records its outcome breakdown over the
// session's current mined turns: zero-yield as the tombstone's
// evidence, yield as the distilled state the census reports.
// 25. A commit that ends in a partial-write error records nothing - a
// failed run is not an outcome.
// 26. A turn imported between plan and commit is never suppressed unseen:
// a relayed plan hash that no longer matches records nothing and names
// why. Without a relay the plan's recorded survey stands in for it: the
// documented flow (plan, then a barren commit) tombstones while the
// session is unchanged, and a session that changed since the plan, two
// pending plans over different turns, or no plan at all withholds the
// tombstone by name. A yield records either way.
// 27. When the commit itself succeeds but the ledger write fails, the
// result names the failure and nothing throws; the field is absent
// whenever the ledger was not attempted or succeeded.
function ledgerEntry(): SessionMiningEntry | undefined {
return readSessionMiningLedger(vault).entries[SESSION];
}
/** A commit that answers `planExtractSignals`, attesting the surveyed hash. */
function commitAnsweringPlan(
items: ReadonlyArray<Record<string, unknown>>,
opts: Partial<{ durabilityDenylist: ReadonlyArray<RegExp>; writeApprovalEnabled: boolean }> = {},
): { plan: ReturnType<typeof planExtractSignals>; res: ReturnType<typeof commitExtractedSignals> } {
const plan = planExtractSignals(vault, SESSION, { now: NOW });
const res = commitExtractedSignals(
vault,
SESSION,
{ items },
{
agent: "tester",
now: NOW,
surveyedTurnsHash: plan.surveyedTurnsHash,
...opts,
},
);
return { plan, res };
}
test("an empty answer records the zero-yield tombstone over the planned material", () => {
const { plan, res } = commitAnsweringPlan([]);
expect(res.written).toEqual([]);
const entry = ledgerEntry();
expect(entry).toBeDefined();
expect(entry!.minedContentHash).toBe(plan.surveyedTurnsHash);
expect(entry!.minedContentHash).toBe(minedTurnsHash(plan.turnsMined));
expect(entry!.outcome).toEqual({ written: 0, staged: 0, deduped: 0, durabilityRejected: 0 });
expect(entry!.recordedAt).toBe("2026-08-22T10:00:00Z");
});
test("a commit whose items all dedupe records the zero-yield breakdown", () => {
commitAnsweringPlan([item()]);
const { res: second } = commitAnsweringPlan([item()]);
expect(second.written).toEqual([]);
expect(second.deduped).toBe(1);
expect(ledgerEntry()!.outcome).toEqual({
written: 0,
staged: 0,
deduped: 1,
durabilityRejected: 0,
});
});
test("a commit whose items all fail the durability gate records the refusals", () => {
const { res } = commitAnsweringPlan(
[item({ topic: "noise", principle: "temporary scratch note" })],
{
durabilityDenylist: [/scratch/],
},
);
expect(res.written).toEqual([]);
expect(res.durabilityRejected).toBe(1);
expect(ledgerEntry()!.outcome).toEqual({
written: 0,
staged: 0,
deduped: 0,
durabilityRejected: 1,
});
});
test("a yielding commit records its yield - the distilled state, not a tombstone", () => {
const { plan, res } = commitAnsweringPlan([item()]);
expect(res.written).toHaveLength(1);
expect(pendingFiles().length).toBe(0);
const entry = ledgerEntry();
expect(entry).toBeDefined();
expect(entry!.minedContentHash).toBe(plan.surveyedTurnsHash);
expect(entry!.outcome).toEqual({ written: 1, staged: 0, deduped: 0, durabilityRejected: 0 });
});
test("a staged yield records itself the same way", () => {
const { res } = commitAnsweringPlan([item()], { writeApprovalEnabled: true });
expect(res.staged).toBe(1);
expect(ledgerEntry()!.outcome).toEqual({
written: 1,
staged: 1,
deduped: 0,
durabilityRejected: 0,
});
});
test("a partial-write failure records nothing - a failed run is not a barren one", () => {
expect(() =>
commitExtractedSignals(
vault,
SESSION,
{ items: [item({ topic: "module:names" })] },
{ agent: "tester", now: NOW },
),
).toThrow(ExtractSignalsWriteError);
expect(inboxFiles()).toEqual([]);
expect(readSessionMiningLedger(vault).entries).toEqual({});
});
test("a relayed plan hash the session outgrew records nothing and names why", () => {
const plan = planExtractSignals(vault, SESSION, { now: NOW });
importTurns(SESSION, [turn("t9", "user", "Imported after the plan was built.")]);
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [] },
{
agent: "tester",
now: NOW,
surveyedTurnsHash: plan.surveyedTurnsHash,
},
);
// The verdict was earned over material the session no longer holds, so
// no record may claim the current turns.
expect(ledgerEntry()).toBeUndefined();
expect(res.miningLedgerFailure).toContain(plan.surveyedTurnsHash);
});
test("a turn imported between plan and commit is not suppressed unseen", async () => {
const plan = planExtractSignals(vault, SESSION, { now: NOW });
importTurns(SESSION, [turn("t9", "user", "Imported after the plan was built.")]);
commitExtractedSignals(
vault,
SESSION,
{ items: [] },
{
agent: "tester",
now: NOW,
surveyedTurnsHash: plan.surveyedTurnsHash,
},
);
// The tombstone covers the old material only, so the next plan still
// offers the new turn to a model.
const next = await planExtractSignalsPrefiltered(vault, SESSION, {
now: NOW,
decisionModel: null,
});
expect(next.skipped).toBeUndefined();
expect(next.turnsMined.map((t) => t.turnId)).toEqual(["t1", "t3", "t9"]);
});
/** The plan phase both surfaces run: it records the survey it hands out. */
function surfacePlan(): ReturnType<typeof planExtractSignalsPrefiltered> {
return planExtractSignalsPrefiltered(vault, SESSION, { now: NOW, decisionModel: null });
}
/** A commit that relays no plan hash, as the documented flow does. */
function commitWithoutRelay(
items: ReadonlyArray<Record<string, unknown>>,
): ReturnType<typeof commitExtractedSignals> {
return commitExtractedSignals(vault, SESSION, { items }, { agent: "tester", now: NOW });
}
test("the documented flow - plan, then a barren commit without a relay - tombstones", async () => {
const plan = await surfacePlan();
const res = commitWithoutRelay([]);
expect(res.miningLedgerFailure).toBeUndefined();
expect(ledgerEntry()?.minedContentHash).toBe(plan.surveyedTurnsHash);
expect((await surfacePlan()).skipped?.reason).toBe(EXTRACT_MINING_TOMBSTONE_SKIP_REASON);
});
test("re-planning unchanged turns keeps the survey unambiguous", async () => {
await surfacePlan();
await surfacePlan();
expect(commitWithoutRelay([]).miningLedgerFailure).toBeUndefined();
expect(ledgerEntry()).toBeDefined();
});
test("a turn imported after the plan withholds a relay-less tombstone and names why", async () => {
const plan = await surfacePlan();
importTurns(SESSION, [turn("t9", "user", "Imported after the plan was built.")]);
const res = commitWithoutRelay([]);
expect(ledgerEntry()).toBeUndefined();
expect(res.miningLedgerFailure).toContain("changed since the plan");
expect(res.miningLedgerFailure).toContain(plan.surveyedTurnsHash);
// The new turn was never offered to a model, so the next plan offers it.
const next = await surfacePlan();
expect(next.skipped).toBeUndefined();
expect(next.turnsMined.map((t) => t.turnId)).toEqual(["t1", "t3", "t9"]);
});
test("two pending plans over different turns withhold a relay-less tombstone", async () => {
await surfacePlan();
importTurns(SESSION, [turn("t9", "user", "Imported between the two plans.")]);
await surfacePlan();
// The commit cannot tell which of the two plans it answers.
const res = commitWithoutRelay([]);
expect(ledgerEntry()).toBeUndefined();
expect(res.miningLedgerFailure).toContain("2 plans over different turns");
});
test("a barren commit with no recorded plan withholds the tombstone and names why", () => {
const res = commitWithoutRelay([]);
expect(ledgerEntry()).toBeUndefined();
expect(res.miningLedgerFailure).toContain("no plan of this session was recorded");
});
test("a commit consumes the survey, so a second barren commit has none to attest", async () => {
await surfacePlan();
commitWithoutRelay([item()]);
const res = commitWithoutRelay([]);
expect(res.miningLedgerFailure).toContain("no plan of this session was recorded");
// The first commit's yield record stands; the barren one did not replace it.
expect(ledgerEntry()!.outcome.written).toBe(1);
});
test("a yield records without a relay or a survey - only the tombstone needs one", () => {
const res = commitWithoutRelay([item()]);
expect(res.written).toHaveLength(1);
expect(res.miningLedgerFailure).toBeUndefined();
expect(ledgerEntry()!.outcome.written).toBe(1);
});
test("a relayed hash still tombstones when no survey was recorded", () => {
const { res } = commitAnsweringPlan([]);
expect(res.miningLedgerFailure).toBeUndefined();
expect(ledgerEntry()).toBeDefined();
});
test("a survey the plan cannot record is named on the plan, and the relay still tombstones", async () => {
mkdirSync(dirname(sessionMiningSurveysPath(vault)), { recursive: true });
writeFileSync(sessionMiningSurveysPath(vault), "{ truncated");
const plan = await surfacePlan();
expect(plan.llmStep).not.toBeNull();
expect(plan.surveyRecordFailure).toContain("session mining surveys file is corrupted JSON");
// Without the relay the commit cannot attest the material...
expect(commitWithoutRelay([]).miningLedgerFailure).toContain("could not be read");
expect(ledgerEntry()).toBeUndefined();
// ...and with it the tombstone lands.
const relayed = commitExtractedSignals(
vault,
SESSION,
{ items: [] },
{ agent: "tester", now: NOW, surveyedTurnsHash: plan.surveyedTurnsHash },
);
expect(relayed.miningLedgerFailure).toBeUndefined();
expect(ledgerEntry()).toBeDefined();
});
test("a damaged survey row reads as ambiguous, never as one clean survey", async () => {
// A dropped row plus the next plan would look like a single survey and
// could attest material an earlier plan never offered.
mkdirSync(dirname(sessionMiningSurveysPath(vault)), { recursive: true });
writeFileSync(
sessionMiningSurveysPath(vault),
JSON.stringify({ schema_version: 1, surveys: { [SESSION]: { hashes: "not-a-list" } } }),
);
await surfacePlan();
expect(commitWithoutRelay([]).miningLedgerFailure).toContain("plans over different turns");
expect(ledgerEntry()).toBeUndefined();
});
test("a tombstone-suppressed plan hands out no envelope and records no survey", async () => {
await surfacePlan();
commitWithoutRelay([]);
const skipped = await surfacePlan();
expect(skipped.skipped?.reason).toBe(EXTRACT_MINING_TOMBSTONE_SKIP_REASON);
expect(existsSync(sessionMiningSurveysPath(vault))).toBe(true);
expect(JSON.parse(readFileSync(sessionMiningSurveysPath(vault), "utf8")).surveys).toEqual({});
});
/** Plants a corrupt mining ledger so a read of it refuses by name. */
function seedCorruptLedger(): void {
mkdirSync(dirname(sessionMiningLedgerPath(vault)), { recursive: true });
writeFileSync(sessionMiningLedgerPath(vault), "{ truncated");
}
test("a ledger write failure on a successful commit is named, never thrown", () => {
// The plan is built (and surveys the ledger) before the corruption, the
// way a real round does: the commit then attests its hash and the record
// attempt hits the corrupt file.
const plan = planExtractSignals(vault, SESSION, { now: NOW });
seedCorruptLedger();
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [] },
{
agent: "tester",
now: NOW,
surveyedTurnsHash: plan.surveyedTurnsHash,
},
);
expect(res.written).toEqual([]);
expect(res.miningLedgerFailure).toContain("session mining ledger is corrupted JSON");
// The vault was never touched by the failed record.
expect(inboxFiles()).toEqual([]);
});
test("a yield-bearing commit names a ledger failure too - it records like any other", () => {
const plan = planExtractSignals(vault, SESSION, { now: NOW });
seedCorruptLedger();
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [item()] },
{
agent: "tester",
now: NOW,
surveyedTurnsHash: plan.surveyedTurnsHash,
},
);
expect(res.written).toHaveLength(1);
expect(res.miningLedgerFailure).toContain("session mining ledger is corrupted JSON");
});
test("the ledger-failure field is absent when the record succeeded", () => {
const { res } = commitAnsweringPlan([]);
expect(ledgerEntry()).toBeDefined();
expect("miningLedgerFailure" in res).toBe(false);
});
test("a barren commit whose ledger record fails keeps the survey, so its retry tombstones", async () => {
const plan = await surfacePlan();
seedCorruptLedger();
expect(commitWithoutRelay([]).miningLedgerFailure).toContain(
"session mining ledger is corrupted JSON",
);
// The operator clears the damaged ledger and retries the same answer
// without a relay: the survey the failed commit read must still attest it.
rmSync(sessionMiningLedgerPath(vault));
const retry = commitWithoutRelay([]);
expect(retry.miningLedgerFailure).toBeUndefined();
expect(ledgerEntry()?.minedContentHash).toBe(plan.surveyedTurnsHash);
});
test("below local reach a survey store failure names no host path", async () => {
mkdirSync(dirname(sessionMiningSurveysPath(vault)), { recursive: true });
writeFileSync(sessionMiningSurveysPath(vault), "{ truncated");
const plan = await planExtractSignalsPrefiltered(vault, SESSION, {
now: NOW,
decisionModel: null,
closeHostErrors: true,
});
expect(plan.surveyRecordFailure).toBe("session mining surveys store failed (error)");
const res = commitExtractedSignals(
vault,
SESSION,
{ items: [] },
{ agent: "tester", now: NOW, closeHostErrors: true },
);
expect(res.miningLedgerFailure).toContain("session mining surveys store failed (error)");
expect(res.miningLedgerFailure).not.toContain(vault);
expect(res.miningLedgerFailure).not.toContain(tmpdir());
});