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
15.4 KB
Raw Blame
/**
 * The defect: `exportBankBundle` composed four sections and
 * `importBankBundle` reconstructed one. Preferences travelled inside the
 * envelope and came back out as a count - `preferencesCarried` - so a
 * bundle taken as a backup could be imported into an empty vault and
 * report success while every rule it carried stayed on the floor. The
 * stated reason was that preferences have a confidence and audit
 * lifecycle a naive restore would overwrite; the fix is not to bypass
 * that lifecycle but to route the restore through the transaction that
 * owns it (`writePreferenceTxn`), so the trial window, the confidence
 * band, the revision counter and the audit trail are maintained.
 *
 * A second defect made the first one unfixable: the export projection
 * carried neither `unconfirmed_until` (required by every preference
 * write, with no other source) nor `revision` (the only ordering that
 * can tell a restore from a rewind). A backup that cannot express the
 * trial window cannot restore it.
 *
 * What this file deliberately does NOT cover:
 *   - the page-graph half of the import (`graph-import.test.ts` owns it);
 *   - page contracts and the sources dashboard, which remain reported as
 *     carried-not-restored and are asserted only at the section level;
 *   - concurrent importers racing for the same lockfile - the lock
 *     collision path is exercised by `preference-txn.test.ts`;
 *   - the CLI rendering of the result (`tests/cli/bank-bundle-cli.test.ts`).
 */

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

import {
  BANK_BUNDLE_SCHEMA_VERSION,
  exportBankBundle,
  importBankBundle,
  type BankBundle,
  type BankImportResult,
} from "../../../../src/core/brain/portability/bundle.ts";
import {
  PREFERENCE_FIELDS_NOT_RESTORED,
  PREFERENCE_RESTORE_FAILURE,
} from "../../../../src/core/brain/portability/preference-restore.ts";
import type { ExportedPreferenceRow } from "../../../../src/core/brain/export.ts";
import {
  writePreference,
  type WritePreferenceInput,
} from "../../../../src/core/brain/preference.ts";
import { readPrefAudit } from "../../../../src/core/brain/pref-audit.ts";
import { brainDirs, preferencePath } from "../../../../src/core/brain/paths.ts";
import { BRAIN_CONFIDENCE, BRAIN_PREFERENCE_STATUS } from "../../../../src/core/brain/types.ts";

let src: string;
let dest: string;

beforeEach(() => {
  src = mkdtempSync(join(tmpdir(), "o2b-bundle-rt-src-"));
  dest = mkdtempSync(join(tmpdir(), "o2b-bundle-rt-dest-"));
  for (const vault of [src, dest]) {
    mkdirSync(brainDirs(vault).preferences, { recursive: true });
    mkdirSync(brainDirs(vault).log, { recursive: true });
  }
});

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

/**
 * A preference whose every exported field carries a non-default value,
 * so a field that silently fails to restore cannot hide behind a
 * default that happens to match.
 */
function richPreference(overrides: Partial<WritePreferenceInput> = {}): WritePreferenceInput {
  return {
    slug: "alpha-rule",
    topic: "writing",
    principle: "state the rule in the imperative and name the artifact it governs",
    created_at: "2026-05-01T00:00:00Z",
    unconfirmed_until: "2026-05-08T00:00:00Z",
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    evidenced_by: ["[[sig-2026-05-01-alpha]]", "[[sig-2026-05-02-alpha]]"],
    confirmed_at: "2026-05-02T00:00:00Z",
    scope: "writing",
    applied_count: 4,
    violated_count: 1,
    last_evidence_at: "2026-05-03T00:00:00Z",
    confidence: BRAIN_CONFIDENCE.medium,
    confidence_value: 0.625,
    pinned: true,
    revision: 3,
    aliases: ["[[pref-alpha-old]]"],
    extraTags: ["brain/imported"],
    howToApply: "Apply it when the artifact is prose, not when it is code.",
    ...overrides,
  };
}

describe("bank bundle preference round-trip", () => {
  test("every exported preference field round-trips, or the result names it", () => {
    writePreference(src, richPreference());
    const bundle = exportBankBundle(src);
    // `trustedRestore` on purpose: this test's subject is EXPORT/IMPORT
    // field fidelity, so the untrusted default's status demotion
    // (t_sec_bank_demote, owned by legacy-bundle-restore.test.ts) would
    // drown the measurement in states the restore did choose to change.
    const result = importBankBundle(dest, bundle, { mode: "skip", trustedRestore: true });

    const before = bundle.preferences[0]!;
    const after = exportBankBundle(dest).preferences.find((r) => r.id === before.id);
    expect(after).toBeDefined();

    // The field set is derived from what the exporter actually emitted,
    // never from a list written here: a field added to the projection
    // shows up in this loop the moment it ships.
    const fields = Object.keys(before) as ReadonlyArray<keyof ExportedPreferenceRow>;
    expect(fields.length).toBeGreaterThan(10);
    const drifted = fields.filter(
      (field) => JSON.stringify(before[field]) !== JSON.stringify(after![field]),
    );
    for (const field of drifted) {
      expect(result.preferences.fieldsNotRestored).toContain(field);
    }
    // No stale names: a field named as not-restored must still exist.
    for (const named of result.preferences.fieldsNotRestored) {
      expect(fields).toContain(named);
    }
    // Non-vacuous: the rendered body is the one field a write cannot
    // reconstruct, and this fixture carries prose that proves it.
    expect(drifted).toContain("body");
    expect(PREFERENCE_FIELDS_NOT_RESTORED).toContain("body");
  });

  test("every bundle section is accounted for in the import result", () => {
    writePreference(src, richPreference());
    const bundle = exportBankBundle(src);
    const result = importBankBundle(dest, bundle, { mode: "skip" });

    // Declared once, keyed by section: a new section on BankBundle has
    // to be added here, which is the moment someone decides whether it
    // restores or is reported as carried.
    const REPORTED_AS: Readonly<Record<string, keyof BankImportResult | null>> = Object.freeze({
      schema: "schema",
      generated_at: null,
      vault_basename: null,
      graph: "graph",
      preferences: "preferences",
      pages: "pagesCarried",
      sources: "sourcesCarried",
    });
    for (const section of Object.keys(bundle) as ReadonlyArray<keyof BankBundle>) {
      expect(Object.keys(REPORTED_AS)).toContain(section);
      const reported = REPORTED_AS[section];
      if (reported !== null) expect(result[reported!]).toBeDefined();
    }
    expect(result.pagesCarried).toBe(bundle.pages.length);
    expect(result.sourcesCarried).toBe(true);
  });

  test("the trial window and confidence band survive the restore", () => {
    writePreference(
      src,
      richPreference({
        slug: "trial-rule",
        status: BRAIN_PREFERENCE_STATUS.unconfirmed,
        confirmed_at: null,
        unconfirmed_until: "2026-09-30T00:00:00Z",
        confidence: BRAIN_CONFIDENCE.low,
        confidence_value: 0.125,
      }),
    );
    // `trustedRestore`: this test's subject is field fidelity, and the
    // untrusted default restarts every row's trial window (M4).
    const result = importBankBundle(dest, exportBankBundle(src), {
      mode: "skip",
      trustedRestore: true,
    });
    expect(result.preferences.failed).toEqual([]);

    const restored = exportBankBundle(dest).preferences.find((r) => r.id === "pref-trial-rule")!;
    expect(restored.unconfirmed_until).toBe("2026-09-30T00:00:00Z");
    expect(restored.status).toBe(BRAIN_PREFERENCE_STATUS.unconfirmed);
    expect(restored.confirmed_at).toBeNull();
    expect(restored.confidence).toBe(BRAIN_CONFIDENCE.low);
    expect(restored.confidence_value).toBe(0.125);
  });

  test("the restore is recorded in the audit trail as a restore", () => {
    writePreference(src, richPreference());
    const result = importBankBundle(dest, exportBankBundle(src), { mode: "skip" });
    expect(result.preferences.restored).toContain("pref-alpha-rule");

    const audit = readPrefAudit(dest, "pref-alpha-rule");
    expect(audit.warnings).toEqual([]);
    expect(audit.records.length).toBe(1);
    const record = audit.records[0]!;
    expect(record.reason).toBe("bundle_restore");
    expect(record.revision_after).toBe(3);
  });

  test("a bundle that is behind the target vault is refused, not applied", () => {
    writePreference(src, richPreference({ revision: 3 }));
    const bundle = exportBankBundle(src);
    // The target already carries a newer edit of the same rule.
    writePreference(
      dest,
      richPreference({
        revision: 7,
        principle: "the newer principle the target vault already holds",
      }),
      { overwrite: true },
    );

    const result = importBankBundle(dest, bundle, { mode: "skip" });
    expect(result.preferences.restored).toEqual([]);
    expect(result.preferences.failed.length).toBe(1);
    expect(result.preferences.failed[0]!.id).toBe("pref-alpha-rule");
    expect(result.preferences.failed[0]!.reason).toBe(PREFERENCE_RESTORE_FAILURE.revisionConflict);
    // The on-disk record is untouched.
    const kept = readFileSync(preferencePath(dest, "alpha-rule"), "utf8");
    expect(kept).toContain("the newer principle the target vault already holds");
  });

  test("a divergent record at the same revision is refused, not silently overwritten", () => {
    writePreference(src, richPreference({ revision: 5 }));
    const bundle = exportBankBundle(src);
    writePreference(
      dest,
      richPreference({ revision: 5, principle: "a different rule that shares a revision number" }),
      { overwrite: true },
    );

    const result = importBankBundle(dest, bundle, { mode: "skip" });
    expect(result.preferences.failed[0]!.reason).toBe(PREFERENCE_RESTORE_FAILURE.revisionConflict);
    expect(readFileSync(preferencePath(dest, "alpha-rule"), "utf8")).toContain(
      "a different rule that shares a revision number",
    );
  });

  test("a bundle ahead of the target vault moves the preference forward", () => {
    writePreference(
      src,
      richPreference({ revision: 9, principle: "the newer rule from the bank" }),
    );
    const bundle = exportBankBundle(src);
    writePreference(dest, richPreference({ revision: 2 }), { overwrite: true });

    const result = importBankBundle(dest, bundle, { mode: "skip" });
    expect(result.preferences.failed).toEqual([]);
    expect(result.preferences.restored).toContain("pref-alpha-rule");
    const restored = exportBankBundle(dest).preferences[0]!;
    expect(restored.revision).toBe(9);
    expect(restored.principle).toBe("the newer rule from the bank");
  });

  test("the outcome follows the revision, not the order rows appear in", () => {
    writePreference(src, richPreference({ revision: 4, principle: "the older rule of the pair" }));
    const older = exportBankBundle(src).preferences[0]!;
    writePreference(src, richPreference({ revision: 6, principle: "the newer rule of the pair" }), {
      overwrite: true,
    });
    const newer = exportBankBundle(src).preferences[0]!;

    const outcome = (rows: ReadonlyArray<ExportedPreferenceRow>): string => {
      const target = mkdtempSync(join(tmpdir(), "o2b-bundle-rt-order-"));
      try {
        mkdirSync(brainDirs(target).preferences, { recursive: true });
        importBankBundle(target, {
          schema: BANK_BUNDLE_SCHEMA_VERSION,
          graph: { nodes: [] },
          preferences: rows,
        });
        return exportBankBundle(target).preferences[0]!.principle;
      } finally {
        rmSync(target, { recursive: true, force: true });
      }
    };

    expect(outcome([older, newer])).toBe("the newer rule of the pair");
    expect(outcome([newer, older])).toBe("the newer rule of the pair");
  });

  test("a version-1 bundle written before the restore existed still imports", () => {
    writePreference(src, richPreference());
    writeFileSync(join(src, "Notes.md"), "---\ntitle: Notes\n---\nbody\n");
    const bundle = exportBankBundle(src);
    // The shape a pre-restore export produced: no trial window, no revision.
    const legacyRows = bundle.preferences.map((row) => {
      const { unconfirmed_until: _window, revision: _revision, ...rest } = row;
      return rest;
    });
    const legacy = { ...bundle, preferences: legacyRows };

    // The rule is confirmed, so its trial window is inert and derivable
    // from the row's own `confirmed_at`. Refusing it would have discarded
    // recoverable data over a moot field - and a bank bundle IS the backup,
    // so there is no re-export to supply what the projection never carried.
    // The derivation is reported rather than passed off as carried data;
    // `tests/core/brain/portability/legacy-bundle-restore.test.ts` owns the
    // full rule, including the `unconfirmed` row that is still refused and
    // the untrusted default that demotes past-trial rows (t_sec_bank_demote,
    // opted out here so the legacy-window derivation stays the subject).
    const result = importBankBundle(dest, legacy, { mode: "skip", trustedRestore: true });
    expect(result.schema).toBe(BANK_BUNDLE_SCHEMA_VERSION);
    expect(result.graph.created).toContain("Notes.md");
    expect(result.preferences.restored).toEqual(["pref-alpha-rule"]);
    expect(result.preferences.failed).toEqual([]);
    expect(result.preferences.derived.length).toBe(1);
    expect(result.preferences.derived[0]!.field).toBe("unconfirmed_until");
    expect(existsSync(preferencePath(dest, "alpha-rule"))).toBe(true);
    // `revision` is absent-as-zero, which is behind every later write and
    // ahead of nothing - so a legacy row never rewinds the destination.
    expect(readFileSync(preferencePath(dest, "alpha-rule"), "utf8")).toContain(
      "unconfirmed_until:",
    );
  });

  test("a malformed row fails per-entry and never counts as carried-and-restored", () => {
    writePreference(src, richPreference());
    const bundle = exportBankBundle(src);
    const mixed = {
      ...bundle,
      preferences: [{ id: 42 }, ...bundle.preferences, { id: "pref-x", topic: "t" }],
    };
    const result = importBankBundle(dest, mixed, { mode: "skip" });
    expect(result.preferences.carried).toBe(3);
    expect(result.preferences.restored.length).toBe(1);
    expect(result.preferences.failed.length).toBe(2);
    expect(result.preferences.restored.length + result.preferences.failed.length).toBe(
      result.preferences.carried,
    );
    for (const failure of result.preferences.failed) {
      expect(failure.reason).toBe(PREFERENCE_RESTORE_FAILURE.malformedRow);
    }
  });

  test("a preferences section that is not an array is refused, not read as empty", () => {
    const result = importBankBundle(dest, {
      schema: BANK_BUNDLE_SCHEMA_VERSION,
      graph: { nodes: [] },
      preferences: "not-an-array",
    });
    expect(result.preferences.carried).toBe(1);
    expect(result.preferences.restored).toEqual([]);
    expect(result.preferences.failed[0]!.reason).toBe(PREFERENCE_RESTORE_FAILURE.malformedRow);
  });

  test("a bundle with no preferences section reports an empty restore, not a failure", () => {
    const result = importBankBundle(dest, {
      schema: BANK_BUNDLE_SCHEMA_VERSION,
      graph: { nodes: [] },
    });
    expect(result.preferences.carried).toBe(0);
    expect(result.preferences.restored).toEqual([]);
    expect(result.preferences.failed).toEqual([]);
    expect(result.preferences.fieldsNotRestored.length).toBeGreaterThan(0);
  });
});