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
12.8 KB
Raw Blame
/**
 * What an audit row of a store-only schema apply attests (task 3.12,
 * design D19 item 1): the records its own apply wrote, plus records rows
 * it has seen already attest, never every record that happens to decide
 * the pack. A deciding record no row attests is a finding the apply
 * refuses over, unless the operator adopts it by name. The migration's
 * import attests its records with a baseline row, and rows written before
 * rows named records keep the digest comparison.
 */
import { afterEach, describe, expect, setDefaultTimeout, setSystemTime, test } from "bun:test";
import { appendFileSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";

import { brainConfigPath } from "../../../src/core/brain/paths.ts";
import { appendAuditRecord } from "../../../src/core/reliability/audit.ts";
import { applySchemaAdminMutations } from "../../../src/core/brain/schema-admin.ts";
import {
  assessSchemaPackIntegrity,
  computeSchemaPackDigest,
  schemaMutationAuditDir,
} from "../../../src/core/brain/schema-integrity.ts";
import type { SchemaMutation } from "../../../src/core/brain/schema-mutate.ts";
import { loadSchemaPack } from "../../../src/core/brain/schema-pack.ts";
import { appendRecord } from "../../../src/core/store/appender.ts";
import { SETTING_ENTRY_KIND, SETTING_SET_KIND } from "../../../src/core/store/constants.ts";
import { bodyChecksum, type StoreRecord } from "../../../src/core/store/envelope.ts";
import { openStore } from "../../../src/core/store/store-open.ts";
import { importBrainSettings } from "../../../src/core/store-migration/brain-settings.ts";
import { runCli } from "../../helpers/run-cli.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";
import { makeStoreEnv, type StoreEnv } from "../store/fixtures/store-env.ts";
import { ledgerRows, partitionRecords, switchDevice } from "./store-only/fixtures.ts";
import { sync, twoMachines, use, type Machine } from "./store-only/two-machines.ts";

setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

let env: StoreEnv | null = null;
afterEach(() => {
  env?.cleanup();
  env = null;
  setSystemTime();
});

let step = 0;
/** A fixed clock past the fixtures' own wall time, one second per step. */
function tick(): Date {
  step += 1;
  const now = new Date(Date.UTC(2030, 0, 1, 12, 0, step));
  setSystemTime(now);
  return now;
}

const addType = (token: string): SchemaMutation => ({
  op: "add_type",
  category: "page_types",
  token,
});

async function apply(
  m: Machine | StoreEnv,
  mutations: SchemaMutation[],
  extra: { adoptUnattested?: boolean; authority?: "human" | "agent"; reason?: string } = {},
) {
  if ("device" in m) use(m);
  return await applySchemaAdminMutations(m.vault, mutations, {
    actor: "operator-ann",
    now: tick(),
    authority: "human",
    ...extra,
  });
}

/** One shared settings record no apply wrote. */
function forge(m: Machine, kind: string, body: Record<string, unknown>): string {
  use(m);
  tick();
  return appendRecord(openStore({ root: m.storeRoot, device: m.device }), {
    partition: "shared",
    stream: "settings",
    kind,
    agent: "other-tool",
    body,
  }).record.id;
}

const forgedEntry = {
  authority: "agent",
  key: "brain.schema.page_types",
  entry: "forged",
  present: true,
};

type Row = { audit_dir?: string; record?: { action?: string; details?: Record<string, unknown> } };
const schemaRows = (root: string, partition: "shared" | "private") =>
  (ledgerRows(root, partition, "reliability-audit") as Row[]).filter(
    (row) => row.audit_dir === "schema-mutations",
  );

describe("an unattested record under an apply", () => {
  test("the apply refuses with a named reason, and another machine's apply attests nothing of it", async () => {
    env = makeStoreEnv("osb-schema-attest-forged-");
    const [a, b] = twoMachines(env);
    await apply(a, [addType("paper")]);
    sync(a, b);
    forge(b, SETTING_ENTRY_KIND, forgedEntry);
    await expect(apply(b, [addType("memo")])).rejects.toMatchObject({
      code: "unattested_schema_records",
    });
    // A never saw the forged record; its apply cannot attest it.
    await apply(a, [addType("person")]);
    sync(a, b);
    sync(b, a);
    for (const m of [a, b]) {
      use(m);
      expect(loadSchemaPack(m.vault).declarations.page_types).toContain("forged");
      expect(assessSchemaPackIntegrity(m.vault).status).toBe("modified");
    }
  });

  test("the operator adopts it by name: the row records the adoption and the pack is attested again", async () => {
    env = makeStoreEnv("osb-schema-attest-adopt-");
    const [a, b] = twoMachines(env);
    await apply(a, [addType("paper")]);
    sync(a, b);
    const forged = forge(b, SETTING_ENTRY_KIND, forgedEntry);
    await apply(b, [addType("memo")], { adoptUnattested: true, authority: "human" });
    const [row] = schemaRows(b.storeRoot, "shared").slice(-1);
    expect(row?.record?.details).toMatchObject({ adopted: [forged], adopted_by: "operator-ann" });
    sync(b, a);
    for (const m of [a, b]) {
      use(m);
      expect(assessSchemaPackIntegrity(m.vault).status).toBe("ok");
    }
  });

  test("an agent cannot adopt", async () => {
    env = makeStoreEnv("osb-schema-attest-agent-");
    const [a, b] = twoMachines(env);
    await apply(a, [addType("paper")]);
    sync(a, b);
    forge(b, SETTING_ENTRY_KIND, forgedEntry);
    await expect(
      apply(b, [addType("memo")], { adoptUnattested: true, authority: "agent" }),
    ).rejects.toMatchObject({ code: "unattested_schema_records" });
  });

  test("the CLI adopts with --adopt-unattested and names the operator", async () => {
    env = makeStoreEnv("osb-schema-attest-cli-");
    const [a, b] = twoMachines(env);
    await apply(a, [addType("paper")]);
    sync(a, b);
    const forged = forge(b, SETTING_ENTRY_KIND, forgedEntry);
    const args = ["brain", "schema", "apply", "--mutation", JSON.stringify(addType("memo"))];
    const opts = { env: { ...process.env, OPEN_SECOND_BRAIN_CONFIG: b.configPath } };
    const refused = await runCli([...args, "--actor", "ann"], opts);
    expect(refused.returncode).not.toBe(0);
    expect(refused.stderr).toContain("--adopt-unattested");
    const adopted = await runCli([...args, "--actor", "ann", "--adopt-unattested"], opts);
    expect(adopted.returncode).toBe(0);
    const [row] = schemaRows(b.storeRoot, "shared").slice(-1);
    expect(row?.record?.details).toMatchObject({ adopted: [forged], adopted_by: "ann" });
  });
});

describe("a record the attestation names", () => {
  test("is attested only in the version the row saw: another body under its id is a finding", async () => {
    env = makeStoreEnv("osb-schema-attest-reused-id-");
    const [a] = twoMachines(env);
    await apply(a, [addType("paper")]);
    expect(assessSchemaPackIntegrity(a.vault).status).toBe("ok");
    const original = partitionRecords(a.storeRoot, "shared").find(
      (r) => r.kind === SETTING_ENTRY_KIND && r.body["entry"] === "paper",
    )!;
    // Another version of the attested record: same id, another body, a
    // checksum that matches it. Ordered first among the versions of the id.
    const body = { ...original.body, authority: "agent", entry: "forged" };
    const forged: StoreRecord = { ...original, body, sum: bodyChecksum(body) };
    appendFileSync(shardHolding(a.storeRoot, original.id), `${JSON.stringify(forged)}\n`);
    use(a);
    expect(loadSchemaPack(a.vault).declarations.page_types).toEqual(["forged"]);
    expect(assessSchemaPackIntegrity(a.vault).status).toBe("modified");
    await expect(apply(a, [addType("memo")])).rejects.toMatchObject({
      code: "unattested_schema_records",
    });
  });
});

describe("a record under brain.schema. that no pack field reads", () => {
  test("is not attested and does not hold up the next apply", async () => {
    env = makeStoreEnv("osb-schema-attest-not-a-field-");
    const [a] = twoMachines(env);
    await apply(a, [addType("paper")]);
    forge(a, SETTING_SET_KIND, { authority: "human", key: "brain.schema.notes", value: ["x"] });
    use(a);
    expect(assessSchemaPackIntegrity(a.vault).status).toBe("ok");
    await apply(a, [addType("memo")]);
    expect(loadSchemaPack(a.vault).declarations.page_types).toEqual(["paper", "memo"]);
  });
});

/** The shard file of `root/shared/settings` that holds record `id`. */
function shardHolding(root: string, id: string): string {
  const dir = join(root, "shared", "settings");
  const found = (readdirSync(dir, { recursive: true }) as string[])
    .map((rel) => join(dir, rel))
    .find((path) => path.endsWith(".jsonl") && readFileSync(path, "utf8").includes(id));
  if (found === undefined) throw new Error(`no settings shard holds ${id}`);
  return found;
}

describe("adoption on its own", () => {
  test("o2b brain schema apply --adopt-unattested adopts with no mutation and changes no entry", async () => {
    env = makeStoreEnv("osb-schema-attest-adopt-only-");
    const [a, b] = twoMachines(env);
    await apply(a, [addType("paper")]);
    sync(a, b);
    const forged = forge(b, SETTING_ENTRY_KIND, forgedEntry);
    use(b);
    const before = loadSchemaPack(b.vault);
    const opts = { env: { ...process.env, OPEN_SECOND_BRAIN_CONFIG: b.configPath } };
    const adopted = await runCli(
      ["brain", "schema", "apply", "--adopt-unattested", "--actor", "ann"],
      opts,
    );
    expect(adopted.stderr).toBe("");
    expect(adopted.returncode).toBe(0);
    const [row] = schemaRows(b.storeRoot, "shared").slice(-1);
    expect(row?.record?.details).toMatchObject({
      applied: 0,
      adopted: [forged],
      adopted_by: "ann",
    });
    expect(loadSchemaPack(b.vault)).toEqual(before);
    expect(assessSchemaPackIntegrity(b.vault).status).toBe("ok");
    // Without the flag, an apply still needs a mutation.
    const bare = await runCli(["brain", "schema", "apply", "--actor", "ann"], opts);
    expect(bare.returncode).not.toBe(0);
    expect(bare.stderr).toContain("--mutation");
  });
});

describe("adoption on its own on an unswitched machine", () => {
  test("is refused, and _brain.yaml is left as it is", async () => {
    env = makeStoreEnv("osb-schema-attest-adopt-unswitched-", { dualWrite: false });
    const config = "schema_version: 1\nschema:\n  page_types: [ Paper ]\n";
    writeFileSync(brainConfigPath(env.vault), config);
    const opts = { env: { ...process.env, OPEN_SECOND_BRAIN_CONFIG: env.configPath } };
    const refused = await runCli(
      ["brain", "schema", "apply", "--adopt-unattested", "--actor", "ann"],
      opts,
    );
    expect(refused.returncode).not.toBe(0);
    expect(refused.stderr).toContain("store-only machine");
    expect(readFileSync(brainConfigPath(env.vault), "utf8")).toBe(config);
  });
});

describe("the migration's import", () => {
  test("attests the records it wrote, so the first apply after the switch goes through", async () => {
    env = makeStoreEnv("osb-schema-attest-import-");
    writeFileSync(
      brainConfigPath(env.vault),
      "schema_version: 1\nschema:\n  page_types:\n    - paper\n    - memo\n",
    );
    tick();
    importBrainSettings(env.vault, openStore({ root: env.storeRoot, device: "dev-a" }), "migrator");
    switchDevice(env.storeRoot);
    await apply(env, [addType("person")]);
    expect(loadSchemaPack(env.vault).declarations.page_types).toEqual(["paper", "memo", "person"]);
    expect(assessSchemaPackIntegrity(env.vault).status).toBe("ok");
  });
});

describe("audit rows written before rows named records", () => {
  test("keep the digest comparison, and an apply over the pack they attest goes through", async () => {
    env = makeStoreEnv("osb-schema-attest-legacy-");
    switchDevice(env.storeRoot);
    const [a] = twoMachines(env);
    forge(a, SETTING_SET_KIND, {
      authority: "human",
      key: "brain.schema.page_types",
      value: ["paper"],
    });
    use(a);
    // A row of that time: a digest, no `decided`.
    appendAuditRecord(
      schemaMutationAuditDir(a.vault),
      {
        timestamp: tick().toISOString(),
        actor: "old",
        action: "schema_apply_mutations",
        target: "store:shared/settings/brain.schema",
        ok: true,
        details: { applied: 1, pack_digest: computeSchemaPackDigest(loadSchemaPack(a.vault)) },
      },
      a.vault,
      { attestsShared: true },
    );
    expect(assessSchemaPackIntegrity(a.vault).status).toBe("ok");
    await apply(a, [addType("memo")]);
    expect(assessSchemaPackIntegrity(a.vault).status).toBe("ok");
  });
});

describe("a shared row whose mutations are withheld", () => {
  test("still names the records it attests", async () => {
    env = makeStoreEnv("osb-schema-attest-withheld-");
    switchDevice(env.storeRoot);
    await apply(env, [addType("paper")], { reason: "<private>why</private>" });
    const [row] = schemaRows(env.storeRoot, "shared");
    expect(row?.record?.details?.["withheld"]).toBeDefined();
    expect(row?.record?.details?.["mutations"]).toBeUndefined();
    const decided = row?.record?.details?.["decided"];
    expect(Array.isArray(decided) && decided.length > 0).toBe(true);
  });
});