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
14.0 KB
Raw Blame
/**
 * What backs the vault path - and what this probe refuses to guess.
 *
 * The tempting shape here was a host classifier: local machine vs cloud
 * sandbox vs ephemeral container. Every signal that classifier would read
 * is ONE-WAY. `/.dockerenv` absent is the normal reading inside podman,
 * containerd, LXC and any image that deleted it; `/proc/1/cgroup` on a
 * cgroup v2 unified host is `0::/<path>` for a container and for a plain
 * systemd scope alike; and "containerised" is not "ephemeral" - a
 * bind-mounted volume in a container outlives a laptop's `/tmp`.
 *
 * So this file pins the narrow claim instead: which filesystem backs one
 * resolved path, and an explicit `undetermined` everywhere else. The last
 * describe block is the guard that keeps it narrow - it asserts the module
 * reads no container signal at all, because the failure this whole design
 * avoids is a NEGATIVE container signal being read back as a POSITIVE
 * verdict of durability.
 */

import { describe, expect, test } from "bun:test";
import { readFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import {
  isVaultBackingRemoteness,
  isVaultBackingState,
  isVaultBackingUndeterminedReason,
  probeVaultBacking,
  VAULT_BACKING,
  VAULT_BACKING_REMOTENESS,
  VAULT_BACKING_REMOTENESS_STATES,
  VAULT_BACKING_STATES,
  VAULT_BACKING_UNDETERMINED_REASON,
  VAULT_BACKING_UNDETERMINED_REASONS,
} from "../../src/core/vault-backing.ts";
import { lexSource } from "../helpers/source-lexer.ts";

const EXT4 = 0xef53;
const TMPFS = 0x01021994;
const OVERLAYFS = 0x794c7630;
/** A magic number no released filesystem uses; stands for "not in the table". */
const UNRECOGNISED = 0x0badf00d;
const NFS = 0x6969;
const CIFS = 0xff534d42;
const FUSE = 0x65735546;

function withFsType(type: number) {
  return () => ({ type });
}

describe("the filesystem under the vault path decides the state", () => {
  test("a journalling disk filesystem is durable and names itself", () => {
    const verdict = probeVaultBacking("/vault", { platform: "linux", statfs: withFsType(EXT4) });
    expect(verdict.state).toBe(VAULT_BACKING.durable);
    expect(verdict.filesystem).toBe("ext4");
    expect(verdict.reason).toBeNull();
  });

  test("a memory-backed filesystem is volatile - the one provable loss", () => {
    const verdict = probeVaultBacking("/vault", { platform: "linux", statfs: withFsType(TMPFS) });
    expect(verdict.state).toBe(VAULT_BACKING.volatile);
    expect(verdict.filesystem).toBe("tmpfs");
  });

  test("a container overlay is layered, never durable and never volatile", () => {
    const verdict = probeVaultBacking("/vault", {
      platform: "linux",
      statfs: withFsType(OVERLAYFS),
    });
    expect(verdict.state).toBe(VAULT_BACKING.layered);
    expect(verdict.state).not.toBe(VAULT_BACKING.durable);
    expect(verdict.state).not.toBe(VAULT_BACKING.volatile);
  });
});

describe("the remoteness axis, beside durability", () => {
  test("named network filesystems classify remote without losing durability", () => {
    for (const [magic, name] of [
      [NFS, "nfs"],
      [CIFS, "cifs"],
    ] as const) {
      const verdict = probeVaultBacking("/vault", { platform: "linux", statfs: withFsType(magic) });
      expect(`${name} reads back as ${verdict.filesystem}`).toBe(`${name} reads back as ${name}`);
      expect(verdict.remoteness).toBe(VAULT_BACKING_REMOTENESS.remote);
      // The survival claim is unchanged: the bytes still outlive this
      // process and this reboot. Remoteness is a second axis answering a
      // different question (is this storage shared with other hosts), not
      // a different answer to the first.
      expect(verdict.state).toBe(VAULT_BACKING.durable);
    }
  });

  test("the other Linux network filesystems classify remote too", () => {
    // A modern `mount -t cifs` share reports SMB2_SUPER_MAGIC, not
    // CIFS_SUPER_MAGIC; ceph, afs, the legacy smbfs and 9p (WSL2 drvfs)
    // are cross-host storage in the same sense.
    for (const [magic, name] of [
      [0xfe534d42, "smb2"],
      [0x00c36400, "ceph"],
      [0x5346414f, "afs"],
      [0x6b414653, "afs"],
      [0x517b, "smbfs"],
      [0x01021997, "9p"],
    ] as const) {
      const verdict = probeVaultBacking("/vault", { platform: "linux", statfs: withFsType(magic) });
      expect(`${magic.toString(16)}: ${verdict.filesystem} ${verdict.remoteness}`).toBe(
        `${magic.toString(16)}: ${name} ${VAULT_BACKING_REMOTENESS.remote}`,
      );
      expect(verdict.state).toBe(VAULT_BACKING.durable);
    }
  });

  test("a Windows UNC path is remote without a statfs probe", () => {
    for (const path of [
      "\\\\server\\share\\vault\\.open-second-brain",
      "//server/share/vault",
      "\\\\?\\UNC\\server\\share\\vault",
    ]) {
      const verdict = probeVaultBacking(path, { platform: "win32" });
      expect(`${path}: ${verdict.remoteness}`).toBe(`${path}: ${VAULT_BACKING_REMOTENESS.remote}`);
      expect(verdict.filesystem).toBe("unc-share");
    }
    // A drive path and the extended-length local forms stay unprobed.
    for (const path of ["C:\\vault", "\\\\?\\C:\\vault", "\\\\.\\C:\\vault"]) {
      const verdict = probeVaultBacking(path, { platform: "win32" });
      expect(`${path}: ${verdict.reason}`).toBe(
        `${path}: ${VAULT_BACKING_UNDETERMINED_REASON.probeUnsupported}`,
      );
      expect(verdict.remoteness).toBe(VAULT_BACKING_REMOTENESS.nonRemote);
    }
    // A double slash on Linux is not a share.
    expect(
      probeVaultBacking("//server/share", { platform: "linux", statfs: withFsType(EXT4) })
        .remoteness,
    ).toBe(VAULT_BACKING_REMOTENESS.nonRemote);
  });

  test("fuse stays non-remote, and so does every disk and memory filesystem", () => {
    for (const magic of [FUSE, EXT4, TMPFS, OVERLAYFS]) {
      const verdict = probeVaultBacking("/vault", { platform: "linux", statfs: withFsType(magic) });
      expect(verdict.remoteness).toBe(VAULT_BACKING_REMOTENESS.nonRemote);
    }
  });

  test("probe-unsupported and fs-type-unknown stay silent and non-remote", () => {
    // Non-remote is the ABSENCE of a network finding, not a finding that
    // the storage is local: nothing was read, so nothing is claimed, and
    // a consumer keeps its default behaviour (WAL stays on).
    const unprobed = probeVaultBacking("/vault", { platform: "darwin", statfs: withFsType(NFS) });
    expect(unprobed.state).toBe(VAULT_BACKING.undetermined);
    expect(unprobed.reason).toBe(VAULT_BACKING_UNDETERMINED_REASON.probeUnsupported);
    expect(unprobed.remoteness).toBe(VAULT_BACKING_REMOTENESS.nonRemote);
    const unknown = probeVaultBacking("/vault", {
      platform: "linux",
      statfs: withFsType(UNRECOGNISED),
    });
    expect(unknown.reason).toBe(VAULT_BACKING_UNDETERMINED_REASON.fsTypeUnknown);
    expect(unknown.filesystem).toBeNull();
    expect(unknown.remoteness).toBe(VAULT_BACKING_REMOTENESS.nonRemote);
  });
});

describe("an injected statfs carries its own meaning", () => {
  test("it is honoured without an explicit platform, on any host", () => {
    // The platform veto exists because the DEFAULT statfsSync means
    // something else off Linux. A caller who injects a statfs vouches for
    // what it returns - the index open does exactly that to simulate a
    // network backing - so the injection implies the probeable platform.
    // This is the contract the Windows CI run turned on: there the veto
    // ran first, the injected nfs never applied, and the index opened
    // under WAL with no warning.
    const verdict = probeVaultBacking("/vault", { statfs: withFsType(NFS) });
    expect(verdict.filesystem).toBe("nfs");
    expect(verdict.remoteness).toBe(VAULT_BACKING_REMOTENESS.remote);
    expect(verdict.reason).toBeNull();
  });

  test("an explicitly pinned non-probeable platform still vetoes the injection", () => {
    // The guard on the rule above: an explicit `platform` is the caller
    // speaking about the host, and that word outranks any injection.
    const verdict = probeVaultBacking("/vault", {
      platform: "win32",
      statfs: withFsType(NFS),
    });
    expect(verdict.state).toBe(VAULT_BACKING.undetermined);
    expect(verdict.reason).toBe(VAULT_BACKING_UNDETERMINED_REASON.probeUnsupported);
    expect(verdict.remoteness).toBe(VAULT_BACKING_REMOTENESS.nonRemote);
  });
});

describe("everything the probe cannot establish says so, with a reason", () => {
  test("an unrecognised magic number is undetermined, NOT durable", () => {
    const verdict = probeVaultBacking("/vault", {
      platform: "linux",
      statfs: withFsType(UNRECOGNISED),
    });
    expect(verdict.state).toBe(VAULT_BACKING.undetermined);
    expect(verdict.reason).toBe(VAULT_BACKING_UNDETERMINED_REASON.fsTypeUnknown);
    expect(verdict.filesystem).toBeNull();
    // The number is in the detail so a report names what it did not know.
    expect(verdict.detail).toContain("0xbadf00d");
  });

  test("a platform with no filesystem-type facility is undetermined, NOT durable", () => {
    for (const platform of ["darwin", "win32", "freebsd"]) {
      const verdict = probeVaultBacking("/vault", {
        platform,
        statfs: withFsType(EXT4),
      });
      expect(`${platform}: ${verdict.state}`).toBe(`${platform}: ${VAULT_BACKING.undetermined}`);
      expect(verdict.reason).toBe(VAULT_BACKING_UNDETERMINED_REASON.probeUnsupported);
    }
  });

  test("a path the probe cannot stat is undetermined, NOT durable", () => {
    const verdict = probeVaultBacking("/vault", {
      platform: "linux",
      statfs: () => {
        throw new Error("ENOENT: no such file or directory");
      },
    });
    expect(verdict.state).toBe(VAULT_BACKING.undetermined);
    expect(verdict.reason).toBe(VAULT_BACKING_UNDETERMINED_REASON.pathUnreadable);
    expect(verdict.detail).toContain("ENOENT");
  });

  test("the real host answers something, and never contradicts itself", () => {
    const verdict = probeVaultBacking(resolve(dirname(fileURLToPath(import.meta.url))));
    expect(isVaultBackingState(verdict.state)).toBe(true);
    expect(verdict.state === VAULT_BACKING.undetermined).toBe(verdict.reason !== null);
    expect(verdict.detail.length).toBeGreaterThan(0);
  });
});

describe("the vocabulary is closed and carries the could-not-tell member", () => {
  test("`undetermined` is a member, and no member claims to name a host class", () => {
    expect(VAULT_BACKING_STATES).toContain(VAULT_BACKING.undetermined);
    // No `local`, no `cloud_sandbox`, no `ephemeral`: two of those three are
    // unprovable from any signal this host exposes, and the third is a
    // property of a machine rather than of the path being probed.
    for (const forbidden of ["local", "cloud_sandbox", "ephemeral", "container"]) {
      expect(`${forbidden} is a member: ${isVaultBackingState(forbidden)}`).toBe(
        `${forbidden} is a member: false`,
      );
    }
  });

  test("a reason is never readable back as a state", () => {
    for (const reason of VAULT_BACKING_UNDETERMINED_REASONS) {
      expect(`${reason} is a state: ${isVaultBackingState(reason)}`).toBe(
        `${reason} is a state: false`,
      );
    }
    for (const state of VAULT_BACKING_STATES) {
      expect(`${state} is a reason: ${isVaultBackingUndeterminedReason(state)}`).toBe(
        `${state} is a reason: false`,
      );
    }
  });

  test("the remoteness vocabulary is closed and unreadable as the other axes", () => {
    expect(VAULT_BACKING_REMOTENESS_STATES).toContain(VAULT_BACKING_REMOTENESS.remote);
    expect(VAULT_BACKING_REMOTENESS_STATES).toContain(VAULT_BACKING_REMOTENESS.nonRemote);
    for (const state of VAULT_BACKING_STATES) {
      expect(`${state} is a remoteness: ${isVaultBackingRemoteness(state)}`).toBe(
        `${state} is a remoteness: false`,
      );
    }
    for (const reason of VAULT_BACKING_UNDETERMINED_REASONS) {
      expect(`${reason} is a remoteness: ${isVaultBackingRemoteness(reason)}`).toBe(
        `${reason} is a remoteness: false`,
      );
    }
  });
});

describe("no container signal reaches this verdict", () => {
  const SOURCE = readFileSync(
    join(dirname(fileURLToPath(import.meta.url)), "..", "..", "src", "core", "vault-backing.ts"),
    "utf8",
  );

  /**
   * Comments stripped: the module docblock NAMES every marker below in
   * order to explain why it reads none of them, and a scan that counted
   * the explanation as a use would force the reasoning out of the file.
   */
  // The shared census lexer, not a pair of regexes: the old strip read
  // a `//` inside a string as a comment opener (hence the `[^:]` guard
  // for `https://`, which is one shape of that bug, not all of them).
  // `withoutComments`, because this scan reads STRING literals - a marker
  // path and an import specifier are both strings.
  const CODE = lexSource(SOURCE).withoutComments;

  test("the module never reads a one-way container marker", () => {
    // Naming them, not counting them: every one of these is evidence of a
    // container when PRESENT and evidence of nothing when absent, so a
    // verdict that consulted one would answer `durable` for every modern
    // container that simply does not ship the marker.
    const markers = ["/.dockerenv", "/run/.containerenv", "/proc/1/cgroup", "/proc/1/sched"];
    const found = markers.filter((marker) => CODE.includes(marker));
    expect(found.join("\n")).toBe("");
  });

  test("the only host facility it reaches for is statfs", () => {
    const fsImports = [...CODE.matchAll(/import \{([^}]*)\} from "node:fs"/g)].map((m) =>
      m[1]!.trim(),
    );
    expect(fsImports.join("\n")).toBe("statfsSync");
  });

  test("the verdict is a function of the filesystem alone", () => {
    // Same magic number, two unrelated call sites: nothing about the host
    // can move the answer, which is what makes the absence of a container
    // marker unable to purchase a durability claim.
    const first = probeVaultBacking("/one", {
      platform: "linux",
      statfs: withFsType(UNRECOGNISED),
    });
    const second = probeVaultBacking("/two", {
      platform: "linux",
      statfs: withFsType(UNRECOGNISED),
    });
    expect(first.state).toBe(second.state);
    expect(first.reason).toBe(second.reason);
  });
});