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
17.4 KB
Raw Blame
/**
 * What filesystem backs the resolved vault path.
 *
 * This module exists because of what it refuses to answer. The question it
 * was asked was "is this machine local, a cloud sandbox, or an ephemeral
 * container", and no signal a host exposes can settle it:
 *
 *   - `/.dockerenv` is written by Docker and by nothing else. Absent is
 *     the normal reading under podman, containerd/CRI-O, LXC,
 *     systemd-nspawn, and any image that removed it.
 *   - `/proc/1/cgroup` carried the classic heuristic on cgroup v1. On a
 *     cgroup v2 unified host - what a current kernel gives you - the line
 *     is `0::/<path>` inside a container and inside a plain systemd scope
 *     alike, so the heuristic is dead rather than weakened.
 *   - "cloud sandbox" has no signal that separates it from "container",
 *     and "container" is not "ephemeral": a bind-mounted volume inside a
 *     container outlives a laptop's `/tmp`.
 *
 * Every one of those signals is ONE-WAY. A positive is decent evidence of
 * containerisation; a negative is evidence of nothing at all. A classifier
 * built on them would answer "local, therefore durable" on exactly the
 * hosts where the answer matters most, which is a confident wrong answer
 * in place of an honest missing one.
 *
 * What CAN be established is narrower and is the claim an ownership
 * statement actually makes: which filesystem backs ONE path. A vault on
 * `tmpfs` is provably gone at reboot. A vault on an overlay is very likely
 * gone at container exit, and is at least not a plain disk. A vault on
 * ext4/xfs/btrfs/zfs is backed by storage that survives the process.
 * Everything else - an unrecognised magic number, a path that will not
 * stat, a platform with no such facility at all - is
 * {@link VAULT_BACKING.undetermined}, with a reason from a SEPARATE
 * vocabulary so a guard can never read a reason back as a verdict.
 *
 * Beside survival the probe answers one more axis, REMOTENESS: whether the
 * backing is a NAMED network filesystem. It is narrow by the same
 * discipline. Only the named network filesystems (nfs, cifs/smb2/smbfs,
 * ceph, afs, 9p) and, on Windows, a UNC path classify remote, because
 * those are the backings whose storage is provably shared with another host and whose
 * locking semantics SQLite's WAL journal mode depends on and does not
 * get. Fuse stays non-remote: what backs a fuse mount is unknowable from
 * its type, and failing safe there would warn every user-space mount.
 * Everything the probe could not read - unknown type, unreadable path,
 * platform without statfs - is {@link VAULT_BACKING_REMOTENESS.nonRemote}
 * and SILENT: the absence of a network finding is never rendered as a
 * finding that the storage is local.
 *
 * The DEFAULT probe is Linux-only by construction. `statfs(2)`'s `f_type`
 * is a Linux filesystem magic number; the same field on macOS and the BSDs
 * means something else, so a call that relies on the default `statfsSync`
 * answers `probe_unsupported` on every other platform rather than being
 * handed a number to misread. That veto guards the default facility's
 * meaning, not the probe itself: an explicitly injected `statfs` carries
 * its own meaning - the caller vouches for what it returns - so an
 * injection implies the probeable platform unless the caller pins
 * `platform` explicitly.
 *
 * Pure and injectable: the platform and the `statfs` call are parameters,
 * so every state below is reachable in a unit test on any host.
 */

import { statfsSync } from "node:fs";

// ----- The verdict vocabulary ----------------------------------------------

/**
 * What the filesystem under a path says about the path's survival.
 *
 * Deliberately absent: any member meaning "local machine", "cloud
 * sandbox" or "ephemeral". See the module docblock - no signal separates
 * them, and naming one would be the guess this design exists to refuse.
 */
export const VAULT_BACKING = Object.freeze({
  /** Backed by storage that survives the process and a reboot. */
  durable: "durable",
  /** Proved memory-backed: the contents are gone at reboot. */
  volatile: "volatile",
  /** Proved container-overlay-backed: survival past container exit unknown. */
  layered: "layered",
  /** No verdict was reached; {@link VaultBackingVerdict.reason} says why. */
  undetermined: "undetermined",
} as const);

/** Closed union over {@link VAULT_BACKING}. */
export type VaultBackingState = (typeof VAULT_BACKING)[keyof typeof VAULT_BACKING];

/** Membership list, in order from most durable to least known. */
export const VAULT_BACKING_STATES: ReadonlyArray<VaultBackingState> = Object.freeze([
  VAULT_BACKING.durable,
  VAULT_BACKING.layered,
  VAULT_BACKING.volatile,
  VAULT_BACKING.undetermined,
]);

/** Narrow a string read back off disk or across a tool boundary. */
export function isVaultBackingState(value: unknown): value is VaultBackingState {
  return (
    typeof value === "string" && (VAULT_BACKING_STATES as ReadonlyArray<string>).includes(value)
  );
}

/**
 * Why the probe reached no verdict.
 *
 * A separate vocabulary rather than three more members on the one above,
 * because a reason is not a verdict: folding them together lets a guard
 * accept `path_unreadable` everywhere a state is expected, and lets a
 * renderer print a cause where a conclusion belongs.
 */
export const VAULT_BACKING_UNDETERMINED_REASON = Object.freeze({
  /** The platform exposes no filesystem-type facility this build can read. */
  probeUnsupported: "probe_unsupported",
  /** The path could not be stat'd at all. */
  pathUnreadable: "path_unreadable",
  /** A filesystem magic number this build does not recognise. */
  fsTypeUnknown: "fs_type_unknown",
} as const);

/** Closed union over {@link VAULT_BACKING_UNDETERMINED_REASON}. */
export type VaultBackingUndeterminedReason =
  (typeof VAULT_BACKING_UNDETERMINED_REASON)[keyof typeof VAULT_BACKING_UNDETERMINED_REASON];

/** Membership list for {@link VAULT_BACKING_UNDETERMINED_REASON}. */
export const VAULT_BACKING_UNDETERMINED_REASONS: ReadonlyArray<VaultBackingUndeterminedReason> =
  Object.freeze([
    VAULT_BACKING_UNDETERMINED_REASON.probeUnsupported,
    VAULT_BACKING_UNDETERMINED_REASON.pathUnreadable,
    VAULT_BACKING_UNDETERMINED_REASON.fsTypeUnknown,
  ]);

/** Narrow a string read back off disk or across a tool boundary. */
export function isVaultBackingUndeterminedReason(
  value: unknown,
): value is VaultBackingUndeterminedReason {
  return (
    typeof value === "string" &&
    (VAULT_BACKING_UNDETERMINED_REASONS as ReadonlyArray<string>).includes(value)
  );
}

// ----- The second axis: remoteness ------------------------------------------

/**
 * Whether the filesystem under a path is a NAMED network filesystem.
 *
 * A second axis beside {@link VAULT_BACKING}, not a new member on it.
 * Durability answers "do the bytes survive this process and this reboot"
 * - on nfs and cifs they do, which is why both stay `durable`. Remoteness
 * answers "is this storage shared with another host", which is the
 * question a consumer of cross-host-unsafe machinery (SQLite's WAL
 * journal mode and its shared-memory index) needs and which no durability
 * verdict can answer.
 *
 * Two members, and `nonRemote` is the one that earns the vocabulary: it
 * is deliberately NOT named `local`, because unknown and probe-unsupported
 * backings answer non-remote too, and "we found no network filesystem" is
 * not evidence that the storage is local.
 */
export const VAULT_BACKING_REMOTENESS = Object.freeze({
  /** Backed by a named network filesystem (nfs, cifs). */
  remote: "remote",
  /** No network filesystem was identified. Not a claim that the storage is local. */
  nonRemote: "non_remote",
} as const);

/** Closed union over {@link VAULT_BACKING_REMOTENESS}. */
export type VaultBackingRemoteness =
  (typeof VAULT_BACKING_REMOTENESS)[keyof typeof VAULT_BACKING_REMOTENESS];

/** Membership list for {@link VAULT_BACKING_REMOTENESS}. */
export const VAULT_BACKING_REMOTENESS_STATES: ReadonlyArray<VaultBackingRemoteness> = Object.freeze(
  [VAULT_BACKING_REMOTENESS.remote, VAULT_BACKING_REMOTENESS.nonRemote],
);

/** Narrow a string read back off disk or across a tool boundary. */
export function isVaultBackingRemoteness(value: unknown): value is VaultBackingRemoteness {
  return (
    typeof value === "string" &&
    (VAULT_BACKING_REMOTENESS_STATES as ReadonlyArray<string>).includes(value)
  );
}

// ----- The probe ------------------------------------------------------------

/**
 * One answer. `filesystem` and `reason` are exclusive by construction: a
 * verdict names the filesystem it read, an `undetermined` names why it
 * read none, and neither ever carries both.
 */
export interface VaultBackingVerdict {
  readonly state: VaultBackingState;
  /** Recognised filesystem name, or `null` when the state is undetermined. */
  readonly filesystem: string | null;
  /** Why no verdict was reached, or `null` when one was. */
  readonly reason: VaultBackingUndeterminedReason | null;
  /**
   * The second axis: whether the identified filesystem is a named network
   * one. `nonRemote` whenever no filesystem was identified at all - the
   * absence of a network finding, never a claim of local storage.
   */
  readonly remoteness: VaultBackingRemoteness;
  /** One line naming what was probed and what came back. */
  readonly detail: string;
}

/** The `statfs` facility, injectable so every branch is testable. */
export type StatfsProbe = (path: string) => { readonly type: number | bigint };

export interface VaultBackingOptions {
  /**
   * Defaults to `process.platform` - or to the one probeable platform when
   * `statfs` is injected, since an injected probe carries its own meaning
   * wherever it runs. An explicit value always wins.
   */
  readonly platform?: string;
  /** Defaults to `node:fs`'s `statfsSync`. */
  readonly statfs?: StatfsProbe;
}

/** The one platform whose `statfs` `f_type` is the magic number below. */
const PROBEABLE_PLATFORM = "linux";

/**
 * Linux filesystem magic numbers, each mapped to the state and remoteness
 * they prove.
 *
 * Only filesystems whose durability follows FROM THE TYPE are listed. A
 * type that is not here is `fs_type_unknown` rather than assumed durable -
 * the same polarity `declaredInputWindowTokens` uses for an unlisted
 * model, and for the same reason: reporting a pass for a condition nobody
 * measured is the misleading silence this release removes.
 *
 * Network filesystems are listed as durable deliberately. The vault living
 * on someone else's server is an availability question, not a survival
 * one: the bytes outlive this process and this reboot, which is the whole
 * claim the state makes. Sharing that server with other hosts is a
 * DIFFERENT question, answered by the second axis: the network filesystems carry
 * `remote` because their storage is provably cross-host and their locking
 * semantics are the ones SQLite's WAL journal mode cannot rely on. Fuse
 * carries `nonRemote` deliberately too: what backs a fuse mount is
 * unknowable from the type, and failing safe there would put the warning
 * on every user-space mount rather than on the network ones.
 */
const FS_MAGIC: ReadonlyMap<
  number,
  {
    readonly name: string;
    readonly state: VaultBackingState;
    readonly remote: VaultBackingRemoteness;
  }
> = new Map([
  // Memory-backed: provably lost at reboot.
  [
    0x01021994,
    { name: "tmpfs", state: VAULT_BACKING.volatile, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  [
    0x858458f6,
    { name: "ramfs", state: VAULT_BACKING.volatile, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  // Union mount: a container's root by default, survival unknown.
  [
    0x794c7630,
    { name: "overlayfs", state: VAULT_BACKING.layered, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  [
    0xaad7aaea,
    { name: "aufs", state: VAULT_BACKING.layered, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  // Storage that outlives the process and a reboot.
  [
    0xef53,
    { name: "ext4", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  [
    0x9123683e,
    { name: "btrfs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  [
    0x58465342,
    { name: "xfs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  [
    0x2fc12fc1,
    { name: "zfs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  [
    0xf2f52010,
    { name: "f2fs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  // Cross-host storage: durable AND remote, the two axes independently.
  [0x6969, { name: "nfs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.remote }],
  [
    0xff534d42,
    { name: "cifs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.remote },
  ],
  // What a modern `mount -t cifs` (SMB2/SMB3) share reports.
  [
    0xfe534d42,
    { name: "smb2", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.remote },
  ],
  [
    0x517b,
    { name: "smbfs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.remote },
  ],
  [
    0x00c36400,
    { name: "ceph", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.remote },
  ],
  // AFS_SUPER_MAGIC and kAFS's AFS_FS_MAGIC.
  [
    0x5346414f,
    { name: "afs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.remote },
  ],
  [
    0x6b414653,
    { name: "afs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.remote },
  ],
  // 9p/v9fs, which also backs WSL2's drvfs mounts of the Windows drives.
  [
    0x01021997,
    { name: "9p", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.remote },
  ],
  // Backing unknowable from the type; non-remote rather than every
  // user-space mount being warned about.
  [
    0x65735546,
    { name: "fuse", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  [
    0x4d44,
    { name: "vfat", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
  [
    0x52654973,
    { name: "reiserfs", state: VAULT_BACKING.durable, remote: VAULT_BACKING_REMOTENESS.nonRemote },
  ],
]);

function hex(type: number): string {
  return `0x${type.toString(16)}`;
}

function undetermined(reason: VaultBackingUndeterminedReason, detail: string): VaultBackingVerdict {
  return {
    state: VAULT_BACKING.undetermined,
    filesystem: null,
    reason,
    // Silent: nothing was read, so no remoteness finding is claimed.
    remoteness: VAULT_BACKING_REMOTENESS.nonRemote,
    detail,
  };
}

/** The platform whose UNC paths name a network share by their spelling. */
const WINDOWS_PLATFORM = "win32";

/**
 * A Windows UNC path: `\\server\share\...`, `//server/share/...` or the
 * extended-length `\\?\UNC\server\share\...`. The local
 * extended-length and device forms (`\\?\C:\...`, `\\.\C:\...`) are
 * not shares.
 */
function isUncPath(path: string): boolean {
  if (/^[\\/]{2}\?[\\/]UNC[\\/][^\\/]+[\\/][^\\/]+/i.test(path)) return true;
  return /^[\\/]{2}(?![?.][\\/])[^\\/]+[\\/][^\\/]+/.test(path);
}

/**
 * Probe the filesystem backing `path`.
 *
 * Never throws: a path that will not stat is a verdict, not a fault - this
 * runs beside an ownership statement whose whole point is that it stays
 * honest on hosts it cannot measure.
 */
export function probeVaultBacking(
  path: string,
  opts: VaultBackingOptions = {},
): VaultBackingVerdict {
  // The veto below guards the DEFAULT facility's meaning, not the probe
  // itself: `statfsSync`'s f_type is a Linux magic number only on Linux, so
  // a call that relies on it answers probe_unsupported elsewhere rather than
  // being handed a number to misread. An injected statfs carries its own
  // meaning - the caller vouches for what it returns - so an injection
  // implies the probeable platform unless the caller pins `platform`.
  const platform =
    opts.platform ?? (opts.statfs !== undefined ? PROBEABLE_PLATFORM : process.platform);
  // Windows exposes no filesystem-type facility this build reads, but a
  // UNC path names a network share by its spelling alone: the one cheap,
  // certain remoteness signal there. Every other Windows path, and every
  // path on macOS (no stable `f_type`, no `f_fstypename` in Node), stays
  // probe_unsupported.
  if (platform === WINDOWS_PLATFORM && isUncPath(path)) {
    return {
      state: VAULT_BACKING.durable,
      filesystem: "unc-share",
      reason: null,
      remoteness: VAULT_BACKING_REMOTENESS.remote,
      detail: `${path} is a UNC path, which names a network share`,
    };
  }
  if (platform !== PROBEABLE_PLATFORM) {
    return undetermined(
      VAULT_BACKING_UNDETERMINED_REASON.probeUnsupported,
      `the filesystem backing ${path} was not probed: statfs f_type is a ${PROBEABLE_PLATFORM} ` +
        `magic number and this host is ${platform}`,
    );
  }
  const statfs = opts.statfs ?? statfsSync;
  let type: number;
  try {
    type = Number(statfs(path).type);
  } catch (err) {
    return undetermined(
      VAULT_BACKING_UNDETERMINED_REASON.pathUnreadable,
      `the filesystem backing ${path} could not be read: ${
        err instanceof Error ? err.message : String(err)
      }`,
    );
  }
  const known = FS_MAGIC.get(type);
  if (known === undefined) {
    return undetermined(
      VAULT_BACKING_UNDETERMINED_REASON.fsTypeUnknown,
      `${path} is backed by filesystem type ${hex(type)}, which this build does not recognise`,
    );
  }
  return {
    state: known.state,
    filesystem: known.name,
    reason: null,
    remoteness: known.remote,
    detail: `${path} is backed by ${known.name} (${hex(type)})`,
  };
}