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
9.1 KB
Raw Blame
/**
 * Blob creation (design D1, D2): where the temp file goes, the exclusive
 * create, and the fallback for filesystems without hard links.
 */
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  existsSync,
  linkSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  renameSync,
  writeFileSync,
} from "node:fs";
import { basename, dirname, join } from "node:path";

import { sha256Hex } from "../../../src/core/integrity/digest.ts";
import { NO_LINK_CODES, readBlob, writeBlob } from "../../../src/core/store/blobs.ts";
import { appendRecord } from "../../../src/core/store/appender.ts";
import { BLOB_TEMP_PREFIX, STORE_LINE_CAP_BYTES } from "../../../src/core/store/constants.ts";
import { blobPath, partitionDir } from "../../../src/core/store/store-paths.ts";
import { makeTempStore, type TempStore } from "./fixtures/temp-store.ts";

/** Every file under `dir`, relative, `/`-separated. */
function walk(dir: string, prefix = ""): string[] {
  if (!existsSync(dir)) return [];
  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
    entry.isDirectory()
      ? walk(join(dir, entry.name), `${prefix}${entry.name}/`)
      : [`${prefix}${entry.name}`],
  );
}

/** A link call that behaves like a FAT or exFAT volume. */
function noHardLinks(): never {
  throw Object.assign(new Error("operation not permitted, link"), { code: "EPERM" });
}

/** A link call that fails for a reason unrelated to hard-link support. */
function diskFull(): never {
  throw Object.assign(new Error("no space left"), { code: "ENOSPC" });
}

describe("writeBlob", () => {
  let tmp: TempStore;
  let partition: string;
  beforeEach(() => {
    tmp = makeTempStore("osb-store-blob-");
    partition = partitionDir(tmp.open("dev-a").root, "shared");
  });
  afterEach(() => tmp.cleanup());

  test("with a device-local temp dir on the same filesystem, nothing temporary touches blobs/", () => {
    const tempDir = join(tmp.parent, "state", "dev-a", "tmp");
    const text = JSON.stringify({ note: "hello" });
    const sources: string[] = [];
    const written = writeBlob(partition, text, {
      tempDir,
      link: (from, to) => {
        sources.push(from);
        linkSync(from, to);
      },
    });
    expect(written.created).toBe(true);
    expect(sources.length).toBe(1);
    expect(dirname(sources[0]!)).toBe(tempDir);
    expect(walk(join(partition, "blobs"))).toEqual([`${written.sha.slice(0, 2)}/${written.sha}`]);
    expect(walk(tempDir)).toEqual([]);
    expect(readBlob(partition, written.sha)).toEqual({ status: "ok", text });
  });

  test("with no usable device-local dir the temp file is dot-prefixed beside the blob", () => {
    const sources: string[] = [];
    const written = writeBlob(partition, JSON.stringify({ note: "beside" }), {
      link: (from, to) => {
        sources.push(from);
        linkSync(from, to);
      },
    });
    expect(dirname(sources[0]!)).toBe(dirname(written.path));
    expect(basename(sources[0]!).startsWith(BLOB_TEMP_PREFIX)).toBe(true);
    expect(existsSync(sources[0]!)).toBe(false);
  });

  test("an unusable device-local dir falls back to a dot-prefixed temp beside the blob", () => {
    const fileNotDir = join(tmp.parent, "not-a-dir");
    writeFileSync(fileNotDir, "");
    const sources: string[] = [];
    const written = writeBlob(partition, JSON.stringify({ note: "fallback" }), {
      tempDir: join(fileNotDir, "tmp"),
      link: (from, to) => {
        sources.push(from);
        linkSync(from, to);
      },
    });
    expect(dirname(sources[0]!)).toBe(dirname(written.path));
    expect(basename(sources[0]!).startsWith(BLOB_TEMP_PREFIX)).toBe(true);
    expect(walk(join(partition, "blobs"))).toEqual([`${written.sha.slice(0, 2)}/${written.sha}`]);
  });

  const noLinkCodes = ["EPERM", "ENOTSUP", "EOPNOTSUPP", "ENOSYS", "EXDEV", "EMLINK"];

  test("the codes below are every code that means the filesystem has no hard links", () => {
    expect([...NO_LINK_CODES].toSorted()).toEqual(noLinkCodes.toSorted());
  });

  test.each(noLinkCodes)(
    "a link refused with %s falls back to an exclusive create of the final name",
    (code) => {
      const text = JSON.stringify({ note: `no link ${code}` });
      const written = writeBlob(partition, text, {
        link: () => {
          throw Object.assign(new Error(`link refused: ${code}`), { code });
        },
      });
      expect(written.created).toBe(true);
      expect(readBlob(partition, written.sha)).toEqual({ status: "ok", text });
      expect(walk(join(partition, "blobs"))).toEqual([`${written.sha.slice(0, 2)}/${written.sha}`]);
    },
  );

  test("without hard links the final name is created exclusively and reads back verified", () => {
    const text = JSON.stringify({ note: "fat volume" });
    const written = writeBlob(partition, text, { link: noHardLinks });
    expect(written.created).toBe(true);
    expect(readBlob(partition, written.sha)).toEqual({ status: "ok", text });
    // No temp file is left behind anywhere in the blob tree.
    expect(walk(join(partition, "blobs"))).toEqual([`${written.sha.slice(0, 2)}/${written.sha}`]);
  });

  test("without hard links a second write of the same body is a verified no-op", () => {
    const text = JSON.stringify({ note: "twice" });
    writeBlob(partition, text, { link: noHardLinks });
    const again = writeBlob(partition, text, { link: noHardLinks });
    expect(again.created).toBe(false);
    expect(readBlob(partition, again.sha)).toEqual({ status: "ok", text });
  });

  test("a taken name holding a torn write is repaired to the content its name promises", () => {
    const text = JSON.stringify({ note: "repair me" });
    const sha = sha256Hex(text);
    const path = blobPath(partition, sha);
    // A crash halfway through a direct create left the first half on disk.
    mkdirSync(dirname(path), { recursive: true });
    writeFileSync(path, text.slice(0, 5));
    expect(readBlob(partition, sha).status).toBe("mismatch");
    const written = writeBlob(partition, text, { link: noHardLinks });
    expect(written.created).toBe(false);
    expect(readFileSync(path, "utf8")).toBe(text);
    // The repair goes through a temp file renamed over the blob; none is left behind.
    expect(walk(join(partition, "blobs"))).toEqual([`${sha.slice(0, 2)}/${sha}`]);
  });

  /** A torn first half of `text` at its blob name, as a crash during a direct create leaves it. */
  function tornBlob(text: string): string {
    const path = blobPath(partition, sha256Hex(text));
    mkdirSync(dirname(path), { recursive: true });
    writeFileSync(path, text.slice(0, 5));
    return path;
  }

  test("a repair writes its temp file in the device-local dir, not in blobs/", () => {
    const text = JSON.stringify({ note: "repair locally" });
    tornBlob(text);
    const tempDir = join(tmp.parent, "state", "dev-a", "tmp");
    const sources: string[] = [];
    writeBlob(partition, text, {
      tempDir,
      link: noHardLinks,
      rename: (from, to) => {
        sources.push(from);
        renameSync(from, to);
      },
    });
    expect(sources.map((s) => dirname(s))).toEqual([tempDir]);
  });

  test("a repair refused because the writer still holds the blob open waits for that writer", () => {
    const text = JSON.stringify({ note: "slow writer" });
    const path = tornBlob(text);
    const written = writeBlob(partition, text, {
      link: noHardLinks,
      rename: () => {
        // The slow writer finishes while the rename is refused.
        writeFileSync(path, text);
        throw Object.assign(new Error("resource busy or locked, rename"), { code: "EBUSY" });
      },
    });
    expect(written.created).toBe(false);
    expect(readBlob(partition, written.sha)).toEqual({ status: "ok", text });
    expect(walk(join(partition, "blobs"))).toEqual([`${written.sha.slice(0, 2)}/${written.sha}`]);
  });

  test("a refused repair of a blob that never completes still fails", () => {
    const text = JSON.stringify({ note: "never completes" });
    tornBlob(text);
    expect(() =>
      writeBlob(partition, text, {
        link: noHardLinks,
        rename: () => {
          throw Object.assign(new Error("operation not permitted, rename"), { code: "EPERM" });
        },
      }),
    ).toThrow("operation not permitted");
  });

  test("a link failure that is not about hard-link support propagates and leaves no temp file", () => {
    expect(() => writeBlob(partition, "{}", { link: diskFull })).toThrow("no space left");
    expect(walk(join(partition, "blobs"))).toEqual([]);
  });
});

describe("appendRecord spills through the device-local temp dir", () => {
  let tmp: TempStore;
  beforeEach(() => {
    tmp = makeTempStore("osb-store-blob-append-");
  });
  afterEach(() => tmp.cleanup());

  test("a spilled body leaves only the blob in blobs/", () => {
    const store = tmp.open("dev-a");
    const result = appendRecord(store, {
      partition: "shared",
      stream: "events",
      kind: "note",
      agent: "tester",
      body: { text: "x".repeat(STORE_LINE_CAP_BYTES * 2) },
    });
    expect(result.spilled).toBe(true);
    const sha = result.record.sum;
    expect(walk(join(tmp.root, "shared", "blobs"))).toEqual([`${sha.slice(0, 2)}/${sha}`]);
  });
});