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
10.7 KB
Raw Blame
/**
 * Post-import read-back census (nothing-writes-silently, Unit F).
 *
 * The claims this suite pins:
 *
 *   1. A census NAMES the keys it could not read back. `attempted: 2,
 *      found: 1` with nothing else is the misleading no-op this unit
 *      removes, so the shared reconciliation vocabulary is the only
 *      constructor and a bare count cannot be built.
 *   2. A clean import reports `complete`; one whose items no longer read
 *      back reports `partial` with the losses named.
 *   3. The sessions lane reads back over the dedup hashes the import
 *      already keys its signals on - no second index, no second hash.
 *   4. The ingest lane reads back over the content manifest, and a claimed
 *      path whose recorded hash no longer matches the bytes on disk is not
 *      counted as found. A recorded claim nobody can reproduce is exactly
 *      the gap the census exists to name.
 *   5. A key claimed twice is one claim: the census cannot inflate
 *      `attempted` by repeating itself.
 *   6. The serialized payload both lanes emit is one shape, so a CLI and an
 *      MCP reading of the same census cannot drift.
 */

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

import { DEFAULT_BRAIN_CONFIG_YAML } from "../../../src/core/brain/config-template.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { brainDirs } from "../../../src/core/brain/paths.ts";
import { computeDedupHash } from "../../../src/core/brain/dedup-hash.ts";
import {
  readManifest,
  updateManifest,
  writeManifestAtomic,
} from "../../../src/core/brain/ingest/content-manifest.ts";
import { importSession } from "../../../src/core/brain/sessions/import.ts";
import {
  buildReadBackCensus,
  censusIngestedPaths,
  censusSessionSignals,
  serializeImportCensus,
} from "../../../src/core/brain/import-census.ts";
import { RECONCILIATION_OUTCOME } from "../../../src/core/reconciliation-report.ts";

let vault: string;

const NOW = new Date("2026-08-15T10:00:00Z");

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-import-census-"));
  const dirs = brainDirs(vault);
  for (const d of [dirs.brain, dirs.inbox, dirs.processed, dirs.preferences, dirs.log]) {
    mkdirSync(d, { recursive: true });
  }
  atomicWriteFileSync(join(dirs.brain, "config.yaml"), DEFAULT_BRAIN_CONFIG_YAML);
});

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

/** One Claude-format transcript carrying the given turn texts. */
function writeSessionFile(name: string, texts: readonly string[]): string {
  const path = join(vault, name);
  const lines = texts.map((text, index) =>
    JSON.stringify({
      type: "user",
      parentUuid: null,
      entrypoint: "cli",
      uuid: `u${index}`,
      timestamp: "2026-08-15T09:00:00.000Z",
      sessionId: "s1",
      message: { role: "user", content: [{ type: "text", text }] },
    }),
  );
  writeFileSync(path, lines.join("\n") + "\n", "utf8");
  return path;
}

function marker(topic: string, principle: string): string {
  return `@osb feedback positive topic=${topic} principle="${principle}"`;
}

function hashOf(topic: string, principle: string): string {
  return computeDedupHash({ topic, signal: "positive", principle });
}

function inboxFiles(): string[] {
  return readdirSync(brainDirs(vault).inbox).filter((n) => n.endsWith(".md"));
}

function writeVaultFile(rel: string, content: string): void {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, content, "utf8");
}

describe("buildReadBackCensus", () => {
  test("names every key the read-back could not find and calls the run partial", () => {
    const present = new Set(["a", "c"]);
    const census = buildReadBackCensus(["a", "b", "c", "d"], (key) => present.has(key));
    expect(census.attempted).toBe(4);
    expect(census.found).toBe(2);
    expect([...census.missing]).toEqual(["b", "d"]);
    expect(census.outcome).toBe(RECONCILIATION_OUTCOME.partial);
  });

  test("a clean read-back is complete with an empty missing list", () => {
    const census = buildReadBackCensus(["a", "b"], () => true);
    expect(census.attempted).toBe(2);
    expect(census.found).toBe(2);
    expect([...census.missing]).toEqual([]);
    expect(census.outcome).toBe(RECONCILIATION_OUTCOME.complete);
  });

  test("a key claimed twice is one claim, so attempted cannot be inflated", () => {
    const census = buildReadBackCensus(["a", "a", "b"], (key) => key === "a");
    expect(census.attempted).toBe(2);
    expect(census.found).toBe(1);
    expect([...census.missing]).toEqual(["b"]);
  });

  test("claiming nothing is complete, not an error", () => {
    const census = buildReadBackCensus([], () => false);
    expect(census.attempted).toBe(0);
    expect(census.outcome).toBe(RECONCILIATION_OUTCOME.complete);
  });

  test("the serialized payload carries the named keys, never a bare count", () => {
    const wire = serializeImportCensus(buildReadBackCensus(["a", "b"], (k) => k === "a"));
    expect(wire).toEqual({
      attempted: 2,
      found: 1,
      missing: ["b"],
      outcome: RECONCILIATION_OUTCOME.partial,
    });
  });
});

describe("censusSessionSignals - the sessions lane reads back its dedup hashes", () => {
  test("every signal the import wrote reads back, and the run is complete", async () => {
    const path = writeSessionFile("s.jsonl", [
      marker("census-one", "Keep the first rule"),
      marker("census-two", "Keep the second rule"),
    ]);
    const result = await importSession(vault, path, { agent: "@t", now: NOW });
    expect(result.signals_created).toBe(2);

    const claimed = [
      hashOf("census-one", "Keep the first rule"),
      hashOf("census-two", "Keep the second rule"),
    ];
    const census = censusSessionSignals(vault, claimed);
    expect(census.attempted).toBe(2);
    expect(census.found).toBe(2);
    expect(census.outcome).toBe(RECONCILIATION_OUTCOME.complete);
  });

  test("a signal removed after the write is named by its hash, not merely counted", async () => {
    const path = writeSessionFile("s.jsonl", [
      marker("census-one", "Keep the first rule"),
      marker("census-two", "Keep the second rule"),
    ]);
    await importSession(vault, path, { agent: "@t", now: NOW });

    // The synthetic loss: one signal disappears between the write and the
    // read-back, which is precisely the case a bare counter reports as fine.
    const victim = inboxFiles().find((n) => n.includes("census-two"));
    expect(victim).toBeDefined();
    unlinkSync(join(brainDirs(vault).inbox, victim!));

    const lost = hashOf("census-two", "Keep the second rule");
    const census = censusSessionSignals(vault, [hashOf("census-one", "Keep the first rule"), lost]);
    expect(census.attempted).toBe(2);
    expect(census.found).toBe(1);
    expect([...census.missing]).toEqual([lost]);
    expect(census.outcome).toBe(RECONCILIATION_OUTCOME.partial);
  });

  test("the import result carries the census of what it claims to have written", async () => {
    const path = writeSessionFile("s.jsonl", [marker("census-rides", "Ride the result")]);
    const result = await importSession(vault, path, { agent: "@t", now: NOW });
    expect(result.census.attempted).toBe(result.signals_created);
    expect(result.census.found).toBe(1);
    expect([...result.census.missing]).toEqual([]);
    expect(result.census.outcome).toBe(RECONCILIATION_OUTCOME.complete);
  });

  test("a dry run claims nothing, so its census is complete over zero", async () => {
    const path = writeSessionFile("s.jsonl", [marker("census-dry", "Rehearse only")]);
    const result = await importSession(vault, path, { agent: "@t", dryRun: true, now: NOW });
    expect(result.signals_created).toBe(0);
    expect(result.census.attempted).toBe(0);
    expect(result.census.outcome).toBe(RECONCILIATION_OUTCOME.complete);
  });
});

describe("censusIngestedPaths - the ingest lane reads back its content hashes", () => {
  test("paths the manifest still confirms are found", () => {
    writeVaultFile("Docs/a.md", "alpha\n");
    writeVaultFile("Docs/b.md", "beta\n");
    updateManifest(vault, ["Docs/a.md", "Docs/b.md"]);

    const census = censusIngestedPaths(vault, ["Docs/a.md", "Docs/b.md"]);
    expect(census.attempted).toBe(2);
    expect(census.found).toBe(2);
    expect(census.outcome).toBe(RECONCILIATION_OUTCOME.complete);
  });

  test("a retired source whose bytes are unchanged is found, not a lost write", () => {
    // The resurrect guard marks the entry retired_into a canonical page
    // and leaves the SOURCE on disk (only the derived copy is removed).
    // The read-back then runs again over the same plan's completed set
    // (reconcilePlan). Recorded, on disk, still hashing to the recorded
    // digest - that is the found definition, so the marker must not
    // turn a claim the vault can reproduce into a false lost-write
    // alarm.
    writeVaultFile("Docs/a.md", "alpha\n");
    updateManifest(vault, ["Docs/a.md"]);
    const manifest = readManifest(vault);
    writeManifestAtomic(
      vault,
      {
        ...manifest.entries,
        "Docs/a.md": {
          ...manifest.entries["Docs/a.md"]!,
          retired_into: "Brain/sources/src-canonical.md",
        },
      },
      manifest.contract,
    );

    const census = censusIngestedPaths(vault, ["Docs/a.md"]);
    expect(census.found).toBe(1);
    expect([...census.missing]).toEqual([]);
    expect(census.outcome).toBe(RECONCILIATION_OUTCOME.complete);
  });

  test("a claimed path deleted after the write is named", () => {
    writeVaultFile("Docs/a.md", "alpha\n");
    writeVaultFile("Docs/b.md", "beta\n");
    updateManifest(vault, ["Docs/a.md", "Docs/b.md"]);
    unlinkSync(join(vault, "Docs/b.md"));

    const census = censusIngestedPaths(vault, ["Docs/a.md", "Docs/b.md"]);
    expect(census.found).toBe(1);
    expect([...census.missing]).toEqual(["Docs/b.md"]);
    expect(census.outcome).toBe(RECONCILIATION_OUTCOME.partial);
  });

  test("a claimed path the manifest never recorded is missing, not silently fine", () => {
    writeVaultFile("Docs/a.md", "alpha\n");
    writeVaultFile("Docs/b.md", "beta\n");
    updateManifest(vault, ["Docs/a.md"]);

    const census = censusIngestedPaths(vault, ["Docs/a.md", "Docs/b.md"]);
    expect([...census.missing]).toEqual(["Docs/b.md"]);
  });

  test("a claimed path whose bytes no longer match the recorded hash is missing", () => {
    writeVaultFile("Docs/a.md", "alpha\n");
    updateManifest(vault, ["Docs/a.md"]);
    writeVaultFile("Docs/a.md", "alpha rewritten\n");

    const census = censusIngestedPaths(vault, ["Docs/a.md"]);
    expect(census.found).toBe(0);
    expect([...census.missing]).toEqual(["Docs/a.md"]);
  });
});