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
6.5 KB
Raw Blame
import { afterEach, describe, expect, test } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  checkpointPath,
  checkpointingEnabled,
  clearCheckpoint,
  computePlanId,
  readCheckpoint,
  recordCompleted,
} from "../../../../src/core/brain/ingest/checkpoint.ts";

function setupVault(): string {
  return mkdtempSync(join(tmpdir(), "o2b-ckpt-"));
}

const AT = new Date("2026-07-10T08:00:00Z");

/** Contract fingerprints for the plan-id fold: two values a contract change can move between. */
const CONTRACT_FP_A = "contract-fp-a";
const CONTRACT_FP_B = "contract-fp-b";

afterEach(() => {
  delete process.env["OSB_INGEST_NO_CHECKPOINT"];
});

describe("computePlanId", () => {
  test("is stable regardless of discovered-path order", () => {
    const a = computePlanId("docs", ["docs/b.md", "docs/a.md"], CONTRACT_FP_A);
    const b = computePlanId("docs", ["docs/a.md", "docs/b.md"], CONTRACT_FP_A);
    expect(a).toBe(b);
    expect(a).toMatch(/^[0-9a-f]{16}$/);
  });

  test("differs when the source dir or the path set differs", () => {
    const base = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_A);
    expect(computePlanId("notes", ["docs/a.md"], CONTRACT_FP_A)).not.toBe(base);
    expect(computePlanId("docs", ["docs/a.md", "docs/b.md"], CONTRACT_FP_A)).not.toBe(base);
  });

  test("differs when the extraction contract differs (t_586d5d8b)", () => {
    const base = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_A);
    expect(computePlanId("docs", ["docs/a.md"], CONTRACT_FP_B)).not.toBe(base);
  });
});

describe("plan id × extraction contract (t_586d5d8b)", () => {
  test("a checkpoint recorded under one contract is invisible to the next", () => {
    const vault = setupVault();
    try {
      const oldId = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_A);
      recordCompleted(vault, oldId, "docs", ["docs/a.md"], AT);
      expect(readCheckpoint(vault, oldId)).not.toBeNull();

      const newId = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_B);
      expect(readCheckpoint(vault, newId)).toBeNull(); // the old checkpoint cannot resume-skip
    } finally {
      rmSync(vault, { recursive: true, force: true });
    }
  });
});

describe("recordCompleted / readCheckpoint", () => {
  test("unions items across calls and reports them sorted", () => {
    const vault = setupVault();
    try {
      const planId = computePlanId("docs", ["docs/a.md", "docs/b.md", "docs/c.md"], CONTRACT_FP_A);
      recordCompleted(vault, planId, "docs", ["docs/b.md"], AT);
      recordCompleted(vault, planId, "docs", ["docs/a.md"], AT);
      const cp = readCheckpoint(vault, planId);
      expect(cp).not.toBeNull();
      expect(cp!.completed).toEqual(["docs/a.md", "docs/b.md"]);
      expect(cp!.plan_id).toBe(planId);
      expect(cp!.source_dir).toBe("docs");
    } finally {
      rmSync(vault, { recursive: true, force: true });
    }
  });

  test("re-recording the same set is a byte-identity no-op", () => {
    const vault = setupVault();
    try {
      const planId = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_A);
      expect(recordCompleted(vault, planId, "docs", ["docs/a.md"], AT)).toBe(true);
      const before = readFileSync(checkpointPath(vault, planId), "utf8");
      const later = new Date("2026-07-10T09:00:00Z");
      expect(recordCompleted(vault, planId, "docs", ["docs/a.md"], later)).toBe(false);
      const after = readFileSync(checkpointPath(vault, planId), "utf8");
      expect(after).toBe(before);
    } finally {
      rmSync(vault, { recursive: true, force: true });
    }
  });

  test("a corrupt checkpoint throws rather than silently resetting", () => {
    const vault = setupVault();
    try {
      const planId = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_A);
      const path = checkpointPath(vault, planId);
      recordCompleted(vault, planId, "docs", ["docs/a.md"], AT);
      writeFileSync(path, "{ not json", "utf8");
      expect(() => readCheckpoint(vault, planId)).toThrow(/corrupt/i);
    } finally {
      rmSync(vault, { recursive: true, force: true });
    }
  });

  test("an unknown schema_version throws", () => {
    const vault = setupVault();
    try {
      const planId = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_A);
      const path = checkpointPath(vault, planId);
      recordCompleted(vault, planId, "docs", ["docs/a.md"], AT);
      writeFileSync(path, JSON.stringify({ schema_version: 99, completed: [] }), "utf8");
      expect(() => readCheckpoint(vault, planId)).toThrow(/schema_version/);
    } finally {
      rmSync(vault, { recursive: true, force: true });
    }
  });

  test("rejects a plan id that could escape the checkpoint dir", () => {
    const vault = setupVault();
    try {
      expect(() => readCheckpoint(vault, "../../etc/passwd")).toThrow(/plan id/i);
    } finally {
      rmSync(vault, { recursive: true, force: true });
    }
  });
});

describe("clearCheckpoint", () => {
  test("removes the checkpoint file and reports whether it existed", () => {
    const vault = setupVault();
    try {
      const planId = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_A);
      recordCompleted(vault, planId, "docs", ["docs/a.md"], AT);
      expect(existsSync(checkpointPath(vault, planId))).toBe(true);
      expect(clearCheckpoint(vault, planId)).toBe(true);
      expect(existsSync(checkpointPath(vault, planId))).toBe(false);
      expect(clearCheckpoint(vault, planId)).toBe(false);
    } finally {
      rmSync(vault, { recursive: true, force: true });
    }
  });
});

describe("OSB_INGEST_NO_CHECKPOINT opt-out", () => {
  test("makes record/read inert", () => {
    const vault = setupVault();
    try {
      process.env["OSB_INGEST_NO_CHECKPOINT"] = "1";
      expect(checkpointingEnabled()).toBe(false);
      const planId = computePlanId("docs", ["docs/a.md"], CONTRACT_FP_A);
      expect(recordCompleted(vault, planId, "docs", ["docs/a.md"], AT)).toBe(false);
      expect(existsSync(checkpointPath(vault, planId))).toBe(false);
      expect(readCheckpoint(vault, planId)).toBeNull();
    } finally {
      rmSync(vault, { recursive: true, force: true });
    }
  });

  test("treats empty/0/false as still-enabled", () => {
    process.env["OSB_INGEST_NO_CHECKPOINT"] = "0";
    expect(checkpointingEnabled()).toBe(true);
    process.env["OSB_INGEST_NO_CHECKPOINT"] = "false";
    expect(checkpointingEnabled()).toBe(true);
    process.env["OSB_INGEST_NO_CHECKPOINT"] = "";
    expect(checkpointingEnabled()).toBe(true);
  });
});