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
11.6 KB
Raw Blame
/**
 * Post-creation expiration mutation (unit 3c / t_5e338af1).
 *
 * The defect, both halves of it. `expiration_date` had a validator, a
 * writer parameter on both artifact kinds, and a fully-wired read side -
 * and no surface anywhere that set it. A memory's lifetime could
 * therefore be declared only by a caller writing straight to the core
 * API, and could never be changed at all: nothing in the tree rewrites
 * that field after the write. `brain_update_note` cannot reach a
 * preference (its path envelope refuses the `Brain/` root, and that
 * refusal is load-bearing), so the mutation needs a surface of its own.
 *
 * Claims pinned here:
 *
 *  1. Setting an expiration on a signal or a preference stamps the
 *     NORMALISED value and leaves every other frontmatter field intact.
 *  2. Changing an existing expiration replaces it; clearing removes the
 *     key entirely rather than writing an empty string.
 *  3. Every value goes through `normalizeExpirationDate`, so an
 *     unparseable date is refused by name and the file is untouched.
 *  4. An id that names no artifact is refused by name - never a silent
 *     no-op that reads as success.
 *  5. An artifact mutated to expire drops out of the DEFAULT query after
 *     its date and comes back under `showExpired`, which is the whole
 *     point of setting one.
 *  6. `changed: false` means what it says: the stored value is compared
 *     through the same chokepoint the incoming one goes through, so an
 *     equivalent spelling writes no bytes and logs no event.
 */

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

import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { regenerateActive } from "../../../src/core/brain/active.ts";
import {
  EXPIRATION_CLEAR,
  ExpirationTargetNotFoundError,
  ExpirationValueError,
  setExpiration,
} from "../../../src/core/brain/expiration-set.ts";
import { queryByRuleTopic } from "../../../src/core/brain/query.ts";
import { resolveAppendShardId } from "../../../src/core/brain/ledger-shards.ts";
import { logShardJsonlPath } from "../../../src/core/brain/paths.ts";
import { writePreference } from "../../../src/core/brain/preference.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";

let vault: string;
let configHome: string;
let configPath: string;

const CREATED = "2026-06-01T00:00:00Z";

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-expiration-set-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-expiration-set-cfg-"));
  configPath = join(configHome, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${vault}\n`);
  bootstrapBrain(vault, { configPath });
});

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

/** Frontmatter lines of a page, minus the one field under test. */
function frontmatterLines(text: string): string[] {
  return text
    .split("\n---")[0]!
    .split("\n")
    .filter((l) => l.length > 0 && !l.startsWith("expiration_date:"));
}

/** Every byte of the observation log, so a no-op can be shown to append none. */
function logSnapshot(): string {
  const dir = join(vault, "Brain", "log");
  if (!existsSync(dir)) return "";
  return readdirSync(dir)
    .toSorted()
    .map((name) => `${name}\n${readFileSync(join(dir, name), "utf8")}`)
    .join("");
}

function seedSignal(): string {
  return writeSignal(vault, {
    topic: "staging-endpoint",
    signal: "positive",
    agent: "tester",
    principle: "Use the staging endpoint.",
    created_at: CREATED,
    date: "2026-06-01",
    slug: "staging-endpoint",
    scope: "coding",
  }).id;
}

function seedPreference(): string {
  return writePreference(
    vault,
    {
      slug: "staging-endpoint",
      topic: "staging-endpoint",
      principle: "Use the staging endpoint.",
      created_at: CREATED,
      unconfirmed_until: CREATED,
      confirmed_at: CREATED,
      status: "confirmed",
      evidenced_by: [],
      scope: "coding",
    },
    { configPath },
  ).id;
}

describe("setting an expiration", () => {
  test("updates the digest if the expiration saves but the audit append fails", () => {
    const id = seedPreference();
    const now = new Date("2026-07-16T12:00:00Z");
    const digest = regenerateActive(vault, { now }).path;
    expect(readFileSync(digest, "utf8")).toContain(id);
    const logPath = logShardJsonlPath(vault, "2026-07-16", resolveAppendShardId());
    mkdirSync(logPath, { recursive: true });
    expect(() => setExpiration(vault, id, "2026-07-15", { now })).toThrow("EISDIR");
    const page = join(vault, "Brain", "preferences", `${id}.md`);
    expect(readFileSync(page, "utf8")).toContain("expiration_date: 2026-07-15");
    expect(readFileSync(digest, "utf8")).not.toContain(id);
  });

  test("the digest drops expired preferences and restores them when expiration is cleared", () => {
    const id = seedPreference();
    const now = new Date("2026-07-16T12:00:00Z");
    const digest = regenerateActive(vault, { now }).path;
    expect(readFileSync(digest, "utf8")).toContain(id);
    setExpiration(vault, id, "2026-07-15", { now });
    expect(readFileSync(digest, "utf8")).toContain("## Confirmed (0)");
    expect(readFileSync(digest, "utf8")).not.toContain(id);
    expect(existsSync(join(vault, "Brain", "preferences", `${id}.md`))).toBe(true);
    setExpiration(vault, id, EXPIRATION_CLEAR, { now });
    expect(readFileSync(digest, "utf8")).toContain("## Confirmed (1)");
    expect(readFileSync(digest, "utf8")).toContain(id);
  });

  test("stamps a signal and leaves its other frontmatter alone", () => {
    const id = seedSignal();
    const before = readFileSync(join(vault, "Brain/inbox", `${id}.md`), "utf8");
    const res = setExpiration(vault, id, "2026-07-15");
    expect(res.id).toBe(id);
    expect(res.expiration).toBe("2026-07-15");
    expect(res.previous).toBeNull();

    const after = readFileSync(join(vault, res.path), "utf8");
    expect(after).toContain("expiration_date: 2026-07-15");
    // Every other field survives: compare the frontmatter line sets minus
    // the one this call is allowed to add.
    expect(frontmatterLines(after)).toEqual(frontmatterLines(before));
  });

  test("stamps a preference the same way", () => {
    const id = seedPreference();
    const res = setExpiration(vault, id, "2026-07-15");
    expect(res.path).toBe(`Brain/preferences/${id}.md`);
    expect(readFileSync(join(vault, res.path), "utf8")).toContain("expiration_date: 2026-07-15");
  });

  test("normalises the value rather than storing it verbatim", () => {
    const id = seedSignal();
    const res = setExpiration(vault, id, "  2026-07-15  ");
    expect(res.expiration).toBe("2026-07-15");
  });
});

describe("changing and clearing", () => {
  test("a second set replaces the date and reports the previous one", () => {
    const id = seedSignal();
    setExpiration(vault, id, "2026-07-15");
    const res = setExpiration(vault, id, "2026-09-01");
    expect(res.previous).toBe("2026-07-15");
    expect(res.expiration).toBe("2026-09-01");
    expect(readFileSync(join(vault, res.path), "utf8")).not.toContain("2026-07-15");
  });

  test("clearing removes the key rather than writing an empty value", () => {
    const id = seedSignal();
    setExpiration(vault, id, "2026-07-15");
    const res = setExpiration(vault, id, EXPIRATION_CLEAR);
    expect(res.expiration).toBeNull();
    expect(res.previous).toBe("2026-07-15");
    const after = readFileSync(join(vault, res.path), "utf8");
    expect(after).not.toContain("expiration_date");
  });

  test("re-setting the same lifetime writes nothing and logs nothing", () => {
    const id = seedSignal();
    const first = setExpiration(vault, id, "2026-07-15");
    expect(first.changed).toBe(true);

    // The two spellings of one lifetime: what is on disk carries padding
    // - a hand edit, or a writer that quoted the scalar - and the caller
    // sends the plain date. Comparing the raw stored value against the
    // normalised new one made this a rewrite plus an audit event
    // describing a change that did not happen.
    const file = join(vault, first.path);
    atomicWriteFileSync(
      file,
      readFileSync(file, "utf8").replace(
        "expiration_date: 2026-07-15",
        'expiration_date: "2026-07-15 "',
      ),
    );
    const bytesBefore = readFileSync(file, "utf8");
    const logBefore = logSnapshot();

    const res = setExpiration(vault, id, "  2026-07-15  ");
    expect(res.changed).toBe(false);
    expect(res.expiration).toBe("2026-07-15");
    expect(readFileSync(file, "utf8")).toBe(bytesBefore);
    expect(logSnapshot()).toBe(logBefore);
  });

  test("a stored value the validator cannot parse is never equal, so the set repairs it", () => {
    const id = seedSignal();
    const first = setExpiration(vault, id, "2026-07-15");
    const file = join(vault, first.path);
    atomicWriteFileSync(
      file,
      readFileSync(file, "utf8").replace("expiration_date: 2026-07-15", "expiration_date: junk"),
    );
    const res = setExpiration(vault, id, "2026-07-15");
    expect(res.changed).toBe(true);
    expect(readFileSync(file, "utf8")).toContain("expiration_date: 2026-07-15");
  });

  test("clearing an artifact that has none is reported, not invented", () => {
    const id = seedSignal();
    const res = setExpiration(vault, id, EXPIRATION_CLEAR);
    expect(res.expiration).toBeNull();
    expect(res.previous).toBeNull();
    expect(res.changed).toBe(false);
  });
});

describe("refusals", () => {
  test("an unparseable date is refused by name and writes nothing", () => {
    const id = seedSignal();
    const before = readFileSync(join(vault, "Brain/inbox", `${id}.md`), "utf8");
    expect(() => setExpiration(vault, id, "next tuesday")).toThrow(ExpirationValueError);
    expect(readFileSync(join(vault, "Brain/inbox", `${id}.md`), "utf8")).toBe(before);
  });

  test("an impossible calendar date is refused too", () => {
    const id = seedSignal();
    expect(() => setExpiration(vault, id, "2026-13-40")).toThrow(ExpirationValueError);
  });

  test("an id naming no artifact is refused rather than silently succeeding", () => {
    expect(() => setExpiration(vault, "pref-nobody-home", "2026-07-15")).toThrow(
      ExpirationTargetNotFoundError,
    );
  });
});

describe("what an expiration is FOR", () => {
  test("a mutated artifact drops out of the default query after its date", () => {
    const signalId = seedSignal();
    seedPreference();
    setExpiration(vault, signalId, "2026-07-15");

    const live = queryByRuleTopic(vault, "staging-endpoint", {
      now: new Date("2026-07-15T12:00:00Z"),
    });
    expect(live.signals.map((s) => s.id)).toContain(signalId);

    const lapsed = queryByRuleTopic(vault, "staging-endpoint", {
      now: new Date("2026-07-16T00:00:01Z"),
    });
    expect(lapsed.signals.map((s) => s.id)).not.toContain(signalId);

    const audited = queryByRuleTopic(vault, "staging-endpoint", {
      now: new Date("2026-07-16T00:00:01Z"),
      showExpired: true,
    });
    expect(audited.signals.map((s) => s.id)).toContain(signalId);
  });

  test("clearing puts it back in the default query", () => {
    const signalId = seedSignal();
    setExpiration(vault, signalId, "2026-07-15");
    setExpiration(vault, signalId, EXPIRATION_CLEAR);
    const after = queryByRuleTopic(vault, "staging-endpoint", {
      now: new Date("2027-01-01T00:00:00Z"),
    });
    expect(after.signals.map((s) => s.id)).toContain(signalId);
  });
});