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
20.8 KB
Raw Blame
/**
 * The blank-session-identity check (t_22d58fa7), and the census that
 * keeps its kind classification honest.
 *
 * Readers across the continuity surface used to coerce a missing or
 * non-string `session_id` to "" - a phantom identity no writer ever
 * stamped. The readers now treat absence as no-session explicitly, and
 * this check is the vault-level mirror of that decision: it COUNTS the
 * records that name no session, one issue per affected kind, and does
 * nothing else. No `fix` field (a session no writer stamped cannot be
 * restored from the record, and the ledger is append-only history), no
 * payload rewrite, and an unreadable ledger is an uncertainty rather
 * than a clean bill.
 *
 * The census half exists because most of the ledger is sessionless BY
 * DESIGN: the telemetry lanes (`gate-telemetry.ts`, `recall-telemetry.ts`,
 * `observed-use.ts`, `recent-turns.ts`, `token-impact.ts`,
 * `context-pack-evidence.ts`, `context-pack-outcome.ts`,
 * `context-receipts.ts`) stamp the key only when their lane has a session
 * in scope, `appendContinuitySourceInvalidation` writes only `{reason}`,
 * and the remaining kinds correlate their session outside the payload key
 * entirely. Counting those put a permanent warning on every used vault
 * and made `--strict` unexitable, so the check counts only the kinds
 * whose writer stamps `session_id` unconditionally from a required
 * input. The census pins that classification three ways: every kind in
 * the `ContinuityRecordKind` union is classified exactly once, the named
 * sessionless writers' files stay out of the count (a behavioural case
 * per kind), and each kind's pinned writer file still has the stamp
 * shape its classification claims.
 */

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

import { lexSource } from "../../helpers/source-lexer.ts";
import { emitGateTelemetry } from "../../../src/core/brain/gate-telemetry.ts";
import {
  appendContinuityRecord,
  appendContinuitySourceInvalidation,
} from "../../../src/core/brain/continuity/store.ts";
import type {
  AppendContinuityRecordInput,
  ContinuityRecordKind,
} from "../../../src/core/brain/continuity/types.ts";
import { runDoctor } from "../../../src/core/brain/doctor.ts";
import {
  SESSION_IDENTITY_CHECK_CODE,
  SESSION_IDENTITY_CHECKED_KINDS,
  sessionIdentityCheck,
} from "../../../src/core/brain/doctor/session-identity-check.ts";
import type { DoctorUncertainEntry } from "../../../src/core/brain/doctor/report.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import type { DoctorIssue } from "../../../src/core/brain/types.ts";

let tmp: string;
let vault: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-session-identity-"));
  vault = join(tmp, "vault");
  bootstrapBrain(vault);
});

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

function seed(
  payload: Record<string, unknown>,
  kind: AppendContinuityRecordInput["kind"] = "session_turn",
): void {
  appendContinuityRecord(vault, {
    kind,
    createdAt: "2026-06-01T00:00:00.000Z",
    payload,
  });
}

function findings(): { issues: DoctorIssue[]; uncertain: DoctorUncertainEntry[] } {
  const issues: DoctorIssue[] = [];
  const uncertain: DoctorUncertainEntry[] = [];
  sessionIdentityCheck.run(
    {
      vault,
      now: new Date("2026-06-02T00:00:00.000Z"),
      logs: [],
    } as unknown as Parameters<typeof sessionIdentityCheck.run>[0],
    { issues, uncertain },
  );
  return { issues, uncertain };
}

describe("blank-session-identity counts, and only counts", () => {
  test("one issue per affected kind, carrying the count, with no fix field", () => {
    seed({ turn_id: "t1", text: "names no session" });
    seed({ turn_id: "t2", text: "names no session either" });
    seed({ depth: 1, summary: "node names no session" }, "session_summary_node");
    seed({ session_id: "sess-real", turn_id: "t3", text: "attributed" });

    const { issues, uncertain } = findings();
    expect(uncertain).toEqual([]);
    expect(issues.map((issue) => issue.message)).toEqual([
      expect.stringContaining("1 session_summary_node"),
      expect.stringContaining("2 session_turn"),
    ]);
    for (const issue of issues) {
      expect(issue.severity).toBe("warning");
      expect(issue.code).toBe(SESSION_IDENTITY_CHECK_CODE);
      expect("fix" in issue).toBe(false);
    }
  });

  test("an empty-string or non-string session_id counts as blank, never as an identity", () => {
    seed({ session_id: "", turn_id: "t1", text: "blank string" });
    seed({ session_id: 42, turn_id: "t2", text: "numeric" });

    const { issues } = findings();
    expect(issues.length).toBe(1);
    expect(issues[0]!.message).toContain("2 session_turn");
  });

  test("every kind whose writer stamps a session is counted when its id is blank", () => {
    // Regression: the census narrowed the count to the session-scoped
    // kinds; each of them must still count exactly as before, one issue
    // per kind, kinds in deterministic order.
    const checked: ReadonlyArray<AppendContinuityRecordInput["kind"]> = [
      "decision_model_extract_commit",
      "post_compact_audit",
      "pre_compact_extract",
      "session_summary_digest",
      "session_summary_node",
      "session_turn",
    ];
    for (const kind of checked) seed({}, kind);

    const { issues, uncertain } = findings();
    expect(uncertain).toEqual([]);
    expect(issues.length).toBe(checked.length);
    expect(issues.map((issue) => issue.message)).toEqual(
      [
        "1 decision_model_extract_commit",
        "1 post_compact_audit",
        "1 pre_compact_extract",
        "1 session_summary_digest",
        "1 session_summary_node",
        "1 session_turn",
      ].map((fragment) => expect.stringContaining(fragment)),
    );
  });

  test("a clean ledger is quiet", () => {
    seed({ session_id: "sess-a", turn_id: "t1", text: "attributed" });
    expect(findings().issues).toEqual([]);
  });

  test("an unreadable ledger is an uncertain stream outcome, never a throw or a finding", () => {
    // A regular file where the continuity directory belongs: the listing
    // fails for a reason that is not absence, which is precisely what the
    // uncertainty stream exists for.
    const continuity = join(vault, "Brain", "log", "continuity");
    mkdirSync(join(vault, "Brain", "log"), { recursive: true });
    writeFileSync(continuity, "not a directory\n");

    const { issues, uncertain } = findings();
    expect(issues).toEqual([]);
    expect(uncertain.length).toBe(1);
    expect(uncertain[0]!.code).toBe("vault-walk-entry-skipped");
  });

  test("an absent ledger is the ordinary quiet case, not uncertainty", () => {
    rmSync(join(vault, "Brain", "log", "continuity"), { recursive: true, force: true });
    const { issues, uncertain } = findings();
    expect(issues).toEqual([]);
    expect(uncertain).toEqual([]);
  });
});

describe("blank-session-identity skips the sessionless-by-design kinds", () => {
  test("sessionless gate telemetry and a source invalidation leave the check silent and the vault clean", () => {
    // The review's reproduction: a vault whose ONLY continuity records
    // are one gate decision written with no session in scope (exactly
    // what `emitGateTelemetry` does under the recall-gate opt-in) and
    // one source invalidation (which writes only `{reason}`). Both are
    // sessionless by design, so this check counts nothing, `brain
    // doctor` reads clean, and `--strict` (which exits 2 exactly when
    // the pass has warnings) exits 0.
    emitGateTelemetry(vault, {
      host: "cli",
      prompt: "what changed",
      retrieve: false,
      reason: "no-index",
    });
    appendContinuitySourceInvalidation(vault, {
      createdAt: "2026-06-01T00:00:00.000Z",
      source: { id: "src-1" },
      reason: "source deleted",
    });

    const { issues, uncertain } = findings();
    expect(uncertain).toEqual([]);
    expect(issues).toEqual([]);

    const result = runDoctor(vault);
    expect(result.warnings).toEqual([]);
  });

  test("every sessionless-by-design kind produces no issue, taken one record at a time", () => {
    // The behavioural half of the census: each kind classified
    // sessionless below (minus `source_invalidation`, covered above
    // through its writer) is seeded as the sessionless record its
    // writer legitimately produces, and the check must stay silent on
    // every one of them.
    const { sessionlessKinds } = classification();
    expect(sessionlessKinds.length).toBeGreaterThan(10);
    for (const kind of sessionlessKinds) {
      if (kind === "source_invalidation") continue; // writer-level case above
      appendContinuityRecord(vault, {
        kind: kind as AppendContinuityRecordInput["kind"],
        createdAt: "2026-06-01T00:00:00.000Z",
        payload: {},
      });
    }

    const { issues } = findings();
    expect(issues).toEqual([]);
  });
});

describe("blank-session-identity runs in the pass", () => {
  test("runDoctor reports the count with zero config", () => {
    seed({ turn_id: "t1", text: "names no session" });
    const result = runDoctor(vault);
    const warning = result.warnings.find((issue) => issue.code === SESSION_IDENTITY_CHECK_CODE);
    expect(warning).toBeDefined();
    expect(warning!.message).toContain("1 session_turn");
  });

  test("a clean vault stays clean", () => {
    const result = runDoctor(vault);
    expect(result.warnings.some((issue) => issue.code === SESSION_IDENTITY_CHECK_CODE)).toBe(false);
  });
});

// ---------------------------------------------------------------------------
// The classification census.
//
// Mirrors the sibling censuses: a lexed view of each module
// (`tests/helpers/source-lexer.ts`), so a kind discussed in a docblock is
// not a writer and a stamp named in a string literal is not a site.
// ---------------------------------------------------------------------------

const SRC_ROOT = join(import.meta.dir, "..", "..", "..", "src");

/** The store's append primitives - binding one is what makes a module a writer. */
const APPEND_PRIMITIVES: ReadonlyArray<string> = Object.freeze([
  "appendContinuityRecord",
  "appendContinuityRecords",
  "appendContinuitySourceInvalidation",
]);

/**
 * A payload stamp written unconditionally, from a required binding.
 * `session_id: sessionId`, `session_id: input.sessionId`, or the same
 * stamp under the shared key constant the hook writers use
 * (`[CONTINUITY_SESSION_ID_KEY]: sessionId`). (`session_id?: string` in
 * an interface is not a stamp; a read of `payload["session_id"]` is not
 * one either.)
 */
const UNCONDITIONAL_STAMP_RE = /(?:session_id|\[CONTINUITY_SESSION_ID_KEY\]): [A-Za-z$_]/;

/**
 * The conditional-spread shape the sessionless lanes stamp with:
 * `...(input.sessionId !== undefined ? { session_id: ... } : {})`, under
 * either spelling of the key.
 */
const CONDITIONAL_STAMP_RE = /\? \{ (?:\[CONTINUITY_SESSION_ID_KEY\]|session_id\b)/;

/** The Stop hook that writes `reply_presence`, outside src. */
const HOOK_WRITER = "../hooks/answer-quote-check.ts";

/**
 * Every kind the census classifies, with the module(s) whose code shapes
 * that kind's payload. The writers of `source_invalidation` all funnel
 * through `appendContinuitySourceInvalidation`, whose `{reason}` payload
 * is fixed at the store and whose input type carries no session field.
 */
const KIND_WRITERS: ReadonlyArray<{
  readonly kind: ContinuityRecordKind;
  /** Session-scoped: the writer stamps `session_id` unconditionally. */
  readonly sessionScoped: boolean;
  readonly writers: ReadonlyArray<string>;
}> = Object.freeze([
  { kind: "context_receipt", sessionScoped: false, writers: ["core/brain/context-receipts.ts"] },
  { kind: "recall_telemetry", sessionScoped: false, writers: ["core/brain/recall-telemetry.ts"] },
  { kind: "gate_telemetry", sessionScoped: false, writers: ["core/brain/gate-telemetry.ts"] },
  {
    kind: "pre_compact_extract",
    sessionScoped: true,
    writers: ["core/brain/pre-compact-extract.ts"],
  },
  {
    kind: "post_compact_audit",
    sessionScoped: true,
    writers: ["core/brain/post-compact-audit.ts"],
  },
  {
    kind: "session_turn",
    sessionScoped: true,
    writers: ["core/brain/session-recall.ts"],
  },
  { kind: "recent_turn", sessionScoped: false, writers: ["core/brain/recent-turns.ts"] },
  {
    kind: "session_summary_node",
    sessionScoped: true,
    writers: ["core/brain/session-recall.ts"],
  },
  {
    kind: "session_summary_digest",
    sessionScoped: true,
    writers: ["core/brain/session-summary.ts"],
  },
  {
    kind: "generation_report",
    sessionScoped: false,
    writers: ["core/brain/generation-reports.ts"],
  },
  { kind: "ingest_dedup", sessionScoped: false, writers: ["core/brain/dedup-telemetry.ts"] },
  { kind: "mcp_route_latency", sessionScoped: false, writers: ["core/brain/mcp-route-metrics.ts"] },
  { kind: "token_impact", sessionScoped: false, writers: ["core/brain/token-impact.ts"] },
  {
    kind: "token_impact_outcome",
    sessionScoped: false,
    writers: ["core/brain/token-impact.ts"],
  },
  {
    kind: "context_pack_outcome",
    sessionScoped: false,
    writers: ["core/brain/context-pack-outcome.ts"],
  },
  {
    kind: "context_pack_evidence",
    sessionScoped: false,
    writers: ["core/brain/context-pack-evidence.ts"],
  },
  { kind: "host_memory_write", sessionScoped: false, writers: ["core/brain/host-memory-write.ts"] },
  { kind: "recall_observed_use", sessionScoped: false, writers: ["core/brain/observed-use.ts"] },
  { kind: "skill_invoked", sessionScoped: false, writers: ["core/brain/sessions/import.ts"] },
  {
    kind: "source_invalidation",
    sessionScoped: false,
    writers: [
      "core/brain/continuity/store.ts",
      "core/brain/document-retire.ts",
      "core/brain/source-cleanup.ts",
      "core/brain/portability/knowledge-pack.ts",
    ],
  },
  { kind: "negative_recall", sessionScoped: false, writers: ["core/brain/gate-telemetry.ts"] },
  { kind: "decision_model_call", sessionScoped: false, writers: ["core/decision-model/record.ts"] },
  {
    // Cycle 20261020: the preregistered eval's grade cache. Machine-side
    // evidence keyed by spec hash, fixture hash and item ids - no session
    // correlation anywhere in the payload, exactly like the call record
    // beside it.
    kind: "decision_model_eval_grade",
    sessionScoped: false,
    writers: ["core/decision-model/record.ts"],
  },
  {
    // Agent-presence (t_635e3e72): one record per COMPLETED benchmark-gated
    // rewrite gate run. Machine-side evidence keyed by skill, spec hash and
    // round ids - a scoring pass no host session took part in, so
    // sessionless exactly like the decision-model eval grade beside it.
    kind: "skill_rewrite_eval_grade",
    sessionScoped: false,
    writers: ["core/brain/skill-proposals.ts"],
  },
  {
    kind: "decision_model_extract_commit",
    sessionScoped: true,
    writers: ["core/brain/extract-signals-prefilter.ts"],
  },
  {
    kind: "session_entity_mention",
    sessionScoped: false,
    writers: ["core/brain/link-graph/session-mining.ts"],
  },
  {
    kind: "receipt_compaction",
    sessionScoped: false,
    writers: ["core/brain/receipts/compact.ts"],
  },
  {
    // The verified-delivery wave's additive kind (t_f8510c55): the
    // answer-quote-check Stop hook's per-turn fold of per-injected-note
    // verdicts. Written ONLY by the Stop hook, outside src - the one
    // kind whose writer lives past the src root, named with its root so
    // the writer-shape check reads it where it lives. The hook appends
    // the record only when the host names a session, and stamps the key
    // on every payload it appends, so a record never exists without one:
    // session-scoped, exactly like the session_turn lane.
    kind: "reply_presence",
    sessionScoped: true,
    writers: [HOOK_WRITER],
  },
]);

/**
 * A benchmark fixture writes throwaway ledgers for timing runs, not a
 * vault a doctor pass will ever examine. Named here so the writer
 * population below accounts for it by name rather than by silence.
 */
const FIXTURE_WRITER = "core/bench/fixture.ts";

/** Every .ts file under src, as POSIX paths relative to it, sorted. */
function srcModulePaths(): ReadonlyArray<string> {
  const out: string[] = [];
  const walk = (dir: string): void => {
    for (const name of readdirSync(dir).toSorted()) {
      const abs = join(dir, name);
      if (statSync(abs).isDirectory()) {
        walk(abs);
        continue;
      }
      if (name.endsWith(".ts")) out.push(relative(SRC_ROOT, abs).split(sep).join("/"));
    }
  };
  walk(SRC_ROOT);
  return out;
}

/** The `ContinuityRecordKind` union, read out of `types.ts` at census time. */
function declaredKinds(): ReadonlyArray<string> {
  const view = lexSource(
    readFileSync(join(SRC_ROOT, "core", "brain", "continuity", "types.ts"), "utf8"),
  );
  const start = view.withoutComments.indexOf("export type ContinuityRecordKind");
  const end = view.withoutComments.indexOf(";", start);
  const union = view.withoutComments.slice(start, end);
  return [...union.matchAll(/"([a-z_]+)"/g)].map((match) => match[1]!);
}

/** The census tables, checked for internal consistency once per run. */
function classification(): {
  readonly checkedKinds: ReadonlyArray<ContinuityRecordKind>;
  readonly sessionlessKinds: ReadonlyArray<ContinuityRecordKind>;
} {
  const checked = KIND_WRITERS.filter((row) => row.sessionScoped).map((row) => row.kind);
  const sessionless = KIND_WRITERS.filter((row) => !row.sessionScoped).map((row) => row.kind);
  return { checkedKinds: checked, sessionlessKinds: sessionless };
}

describe("blank-session-identity classification census", () => {
  test("the sweep sees the vault-facing src tree", () => {
    // A census over an empty sweep is a claim about a census; pin the
    // population's scale and a load-bearing member's presence.
    const paths = srcModulePaths();
    expect(paths.length).toBeGreaterThan(100);
    expect(paths).toContain("core/brain/continuity/types.ts");
  });

  test("the check's allowlist is exactly the session-scoped classification", () => {
    const { checkedKinds } = classification();
    expect([...SESSION_IDENTITY_CHECKED_KINDS].toSorted()).toEqual(checkedKinds.toSorted());
  });

  test("every declared kind is classified exactly once, session-scoped or sessionless by design", () => {
    const declared = declaredKinds();
    const { checkedKinds, sessionlessKinds } = classification();
    // The union parse must have read the real population, not a fragment.
    expect(declared.length).toBeGreaterThanOrEqual(20);
    expect(declared.toSorted()).toEqual([...checkedKinds, ...sessionlessKinds].toSorted());
    expect(new Set([...checkedKinds].filter((k) => sessionlessKinds.includes(k))).size).toBe(0);
  });

  test("each kind's writer files exist and carry the stamp shape its classification claims", () => {
    for (const row of KIND_WRITERS) {
      for (const writer of row.writers) {
        const view = lexSource(readFileSync(join(SRC_ROOT, writer), "utf8"));
        const stamps = UNCONDITIONAL_STAMP_RE.test(view.withoutComments);
        const conditional = CONDITIONAL_STAMP_RE.test(view.withoutComments);
        if (row.sessionScoped) {
          // A session-scoped writer stamps unconditionally and never
          // behind the conditional spread - otherwise a sessionless
          // lane could belong on this side of the census.
          expect(stamps, `${writer} should stamp session_id unconditionally`).toBe(true);
          expect(conditional, `${writer} should not stamp session_id conditionally`).toBe(false);
        } else {
          // A sessionless writer either stamps only conditionally or
          // never touches the payload key at all (its session
          // correlation lives elsewhere).
          expect(conditional || !stamps, `${writer} should be sessionless by design`).toBe(true);
        }
      }
    }
  });

  test("the writer population is exactly the classified writers plus the named fixture", () => {
    // Any module that binds an append primitive writes SOME kind's
    // payload; if it is not classified above, its kinds are counted (or
    // spared) by a writer this census never read. Exempted: the bench
    // fixture, which writes throwaway ledgers for timing runs, and the
    // Stop hook, which writes `reply_presence` from outside the src
    // tree this population walks - both named writers above, never
    // silent ones.
    const writers = new Set(
      KIND_WRITERS.flatMap((row) => row.writers).filter((writer) => writer !== HOOK_WRITER),
    );
    const population = srcModulePaths().filter((path) => {
      const code = lexSource(readFileSync(join(SRC_ROOT, path), "utf8")).code;
      return APPEND_PRIMITIVES.some((primitive) => code.includes(primitive));
    });
    expect(population.toSorted()).toEqual([...writers, FIXTURE_WRITER].toSorted());
  });
});