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
22.1 KB
Raw Blame
/**
 * The declared recovery story of every destructive site under
 * `src/core/brain/` that does not route through the snapshot gate (R1b).
 *
 * `snapshot-gate.ts` promises that no destructive brain mutation runs
 * without a recovery point on disk first, and it is reached by two
 * modules. That is not a bug in the gate; it is what happens to any
 * mechanism that has to be called by hand. Fixing the call sites fixes
 * the call sites. What makes the NEXT unprotected removal impossible to
 * add silently is this file plus
 * `tests/core/architecture/destructive-site-census.test.ts`: the census
 * sweeps the tree for removal calls and requires each site it finds to
 * be routed through the gate or to appear below.
 *
 * ## What an entry is
 *
 * Facts, not conclusions. Each entry states the calls the site makes,
 * what those calls put at risk (in the regions a snapshot archive is
 * defined over), and whether anything archived them first. The verdict
 * is DERIVED from those facts by the same pure classifier the gate uses,
 * so the registry and the gate cannot come to different conclusions
 * about the same shape of risk.
 *
 * The `reason` is what the facts alone do not say: for most of these
 * sites it is the argument that the removal is safe by CONSTRUCTION -
 * the destination landed and was re-confirmed before the source went, or
 * the removed file's whole content was its existence, or a producer will
 * emit it again on the next run. Those are real recovery stories; they
 * are just not archives.
 *
 * ## What this module is not
 *
 * It imports nothing but the verdict vocabularies. A registry that must
 * know about the modules it names is exactly where an import cycle
 * appears, and a cycle here would be paid for by every module in the
 * tree - so the sites are named by PATH, as strings, and the census is
 * what proves those strings still resolve to real files.
 */

import {
  classifyRecoverability,
  type RecoverabilityFacts,
  type RecoverabilityVerdict,
} from "./gates/recoverability.ts";

/**
 * The calls that put existing bytes beyond reach: removal and
 * displacement, in both the sync and the promise spelling. An atomic
 * overwrite is deliberately absent - see the census header for the
 * measurement behind that narrowing.
 */
export const REMOVAL_CALLS: ReadonlyArray<string> = Object.freeze([
  // `node:fs`
  "rmSync",
  "unlinkSync",
  "renameSync",
  "rmdirSync",
  // `node:fs/promises` twins. Nothing in `src/core/brain/` imports them
  // today; they are here so the FIRST one is reported rather than
  // admitted. The import gate in the census is what keeps a local helper
  // named `rm` or `rename` from being miscounted as one of these.
  "rm",
  "unlink",
  "rename",
  "rmdir",
]);

/**
 * What the census records when a module reaches an fs namespace through
 * a COMPUTED member - `fs[call](path)`. Which call that is is a runtime
 * fact, so the site is reported under this token rather than resolved to
 * a name the census would be guessing at.
 *
 * Not a `node:fs` name, and deliberately unspellable as one: a site that
 * needs it has to declare it, and the declaration is where the module
 * says which calls that expression can actually reach.
 */
export const FS_UNRESOLVED_CALL = "fs[]";

/**
 * Shortest reason the census accepts. Set where a real argument fits and
 * a placeholder does not: "cleanup" and "not needed" are both under it.
 */
export const DESTRUCTIVE_SITE_MIN_REASON_LENGTH = 60;

/** One site's declaration. */
export interface DestructiveSiteDeclaration {
  /** The removal calls this module makes directly, sorted. */
  readonly calls: ReadonlyArray<string>;
  /** What is at risk, and whether anything archived it first. */
  readonly recovery: RecoverabilityFacts;
  /** What the facts alone do not say. Never empty, never shared. */
  readonly reason: string;
}

/** No archive behind it, and the bytes are inside the Brain tree. */
const UNARCHIVED_BRAIN: RecoverabilityFacts = Object.freeze({
  recoveryPoint: false,
  blastRadius: Object.freeze({ brainTopLevel: true }),
});

/** No archive behind it, and the bytes are outside the Brain tree. */
const UNARCHIVED_OUTSIDE: RecoverabilityFacts = Object.freeze({
  recoveryPoint: false,
  blastRadius: Object.freeze({ outsideBrainRoot: true }),
});

/**
 * No archive behind it, and the bytes are in an entry no archive has
 * ever contained: `Brain/.snapshots` or `Brain/.artifacts`.
 */
const UNARCHIVED_EXCLUDED: RecoverabilityFacts = Object.freeze({
  recoveryPoint: false,
  blastRadius: Object.freeze({ snapshotExcludedEntries: true }),
});

/**
 * No archive behind it, and no bytes reachable at all: the call removes
 * a directory entry that is empty by construction the moment it runs.
 */
const EMPTY_SHELL_ONLY: RecoverabilityFacts = Object.freeze({
  recoveryPoint: false,
  blastRadius: Object.freeze({}),
});

/**
 * Every destructive site under `src/core/brain/` that is not routed
 * through the destructive gate, with the argument for why the removal
 * is accounted for anyway.
 *
 * Paths are repo-relative and POSIX-separated, matching the census's own
 * enumeration.
 */
export const DESTRUCTIVE_SITES: Readonly<Record<string, DestructiveSiteDeclaration>> =
  Object.freeze({
    // --- Moves whose destination is proved before the source goes -------
    // (`src/core/brain/pending.ts` stopped being a site when the
    // multi-lane queue moved the engine into `pending/pending-lanes.ts`
    // and the module became a pure delegation surface.)
    "src/core/brain/pending/pending-lanes.ts": {
      calls: ["unlinkSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "the multi-lane queue's apply and reject, generalized from the A3 applier: " +
        "apply exclusive-creates the decoded publish target and throws on an occupied " +
        "name BEFORE the staged copy is unlinked, so the document exists twice at that " +
        "instant and never zero times; reject writes the retire-shaped render through " +
        "`writeFrontmatterAtomic` and refuses an occupied retired name before the " +
        "staged copy goes, preserving every original field beside the retire stamps.",
    },
    "src/core/brain/preference.ts": {
      calls: ["unlinkSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "the retire re-renders into `retired/` through `writeFrontmatterAtomic` and " +
        "then re-confirms the destination with `existsSync`, throwing if it is absent, " +
        "before unlinking. Worth naming precisely: it RE-RENDERS rather than copies, so " +
        "the record survives and the original prose does not.",
    },
    "src/core/brain/signal-retire.ts": {
      calls: ["unlinkSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "the signal twin of the preference retire - shared-writer write, existence " +
        "re-confirmed with a throw on absence, then the source unlinked - and the one " +
        "of the pair that copies rather than re-renders, so no prose is lost.",
    },

    // --- Archival moves: the bytes change location, not existence -------
    "src/core/brain/capture/capture-note.ts": {
      calls: ["renameSync", "rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "moves a staged capture into `processed/`. The `rmSync` is the source half of " +
        "the cross-device fallback and runs only after `atomicWriteText` has written " +
        "the archived copy from bytes already read into memory.",
    },
    "src/core/brain/dream-apply.ts": {
      calls: ["renameSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "moves each consumed signal from `inbox/` into its processed location. It runs " +
        "inside the dream pass, whose pre-run archive covers the whole Brain tree - " +
        "coverage this entry cannot claim itself, because the archive belongs to the " +
        "caller and this module is reachable from tests without one.",
    },
    "src/core/brain/intentions.ts": {
      calls: ["renameSync", "rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "archives an active intention into `history/` under a name a collision loop has " +
        "already proved free, so an existing history entry can never be renamed over. " +
        "The `rmSync` is the cross-device fallback's source half.",
    },
    "src/core/brain/recompile.ts": {
      calls: ["renameSync", "rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "moves an orphaned GENERATED page into the cleanup directory under a suffixed " +
        "free name. The page is reproducible from its inputs by definition, and the " +
        "move is what lets an operator see what was orphaned rather than guess. Across " +
        "volumes the move is a copy, then the source's removal.",
    },

    // --- Files whose whole content is their existence --------------------
    "src/core/brain/exact-state.ts": {
      calls: ["rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "clears one aspect's exact-state file. Absence IS the cleared state, so the " +
        "removal is the state transition rather than a loss of one.",
    },
    "src/core/brain/skill-accept-journal.ts": {
      calls: ["rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "clears a skill accept journal and its prior-content copy, device-local repair " +
        "markers whose absence is the state 'no accept outstanding'; the transaction they " +
        "recorded is resolved before they go.",
    },
    "src/core/brain/checkpoint-store.ts": {
      calls: ["rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "clears one checkpoint - an ingest plan's or a session import's - once that run " +
        "reached its terminal state. A checkpoint exists to let an interrupted run resume; " +
        "after the run is done there is nothing it could resume into.",
    },
    "src/core/brain/lineage/identity.ts": {
      calls: ["unlinkSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "clears a worktree identity marker and prunes the oldest past a fixed retain " +
        "count, expired and undatable first. A marker carries no content beyond the " +
        "fact that a worktree was seen, and the next run re-creates the live ones.",
    },
    "src/core/brain/git/ingest.ts": {
      calls: ["rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "clears the git-ingest `state.json` watermark on a rescan that found no head, " +
        "so the next run starts as an initial walk instead of inheriting a marker that " +
        "points at a commit the repository no longer has.",
    },

    // --- Regenerable derivations -----------------------------------------
    "src/core/brain/truth/store.ts": {
      calls: ["rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "removes a claim-event shard only when compaction has filtered every line out " +
        "of it, so the file removed is provably empty of surviving events at the moment " +
        "it goes.",
    },

    // --- Bootstrap: a tree that did not exist a moment ago ---------------
    "src/core/brain/init.ts": {
      calls: ["renameSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "re-dates the starter bundle's own log filenames immediately after copying them " +
        "into a destination the pre-check already proved empty. This is also the path " +
        "that CREATES the tree, so it cannot be gated on anything the tree is about to " +
        "contain.",
    },

    // --- The archive machinery itself ------------------------------------
    "src/core/brain/snapshot.ts": {
      calls: ["renameSync", "rmSync", "unlinkSync"],
      recovery: UNARCHIVED_EXCLUDED,
      reason:
        "the module that MAKES recovery points: it prunes archives past the retention " +
        "count, removes a partial store archive whose snapshot was refused, and swaps a " +
        "decompressed database into place. Gating any of it on taking a snapshot would " +
        "be circular, so `pruneSnapshots` carries a floor and a named refusal instead " +
        "and `restoreSnapshot` takes a manual recovery point of the tree it discards.",
    },

    // --- Concurrency primitives ------------------------------------------
    "src/core/brain/sync-lockfile.ts": {
      calls: ["unlinkSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "the lock release and the process-exit sweep that releases any lock still held, " +
        "each only while the lock file is still the one its holder created, and " +
        "`removeStaleLockSync`, which removes an abandoned lock for the one contender whose " +
        "exclusive takeover claim on that file won (the lineage gap-sidecar trim lock and " +
        "the hook-state scope locks break theirs through it). A lock file's meaning comes " +
        "entirely from its exclusive creation; removing one grants access rather than " +
        "destroying anything.",
    },

    // --- Rewrites through a temp file ------------------------------------
    "src/core/brain/freeze.ts": {
      calls: ["unlinkSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "removes the freeze marker, whose whole content was its existence: the file carries " +
        "no memory, `o2b brain freeze` writes an identical one in a single command, and the " +
        "`unfreeze` log event records who lifted the freeze plus what the marker said before " +
        "it went. Archiving it would preserve a fact the log already holds.",
    },

    "src/core/brain/maintenance/journal.ts": {
      calls: ["renameSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "the tmp-plus-rename half of the journal cap sweep, which runs only while the " +
        "maintenance lease is held. The rename is what makes the trim atomic - a reader " +
        "sees either the full journal or the capped one, never a torn file.",
    },
    "src/core/brain/secrets/store.ts": {
      calls: ["renameSync", "rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "the tmp-plus-rename half of a hand-rolled atomic write that must land at mode " +
        "0600, which no shared writer expresses. The store holds encrypted secrets and " +
        "is deliberately outside every snapshot archive, so its safety comes from the " +
        "atomicity of the swap and not from a recovery point. The rmSync removes only " +
        "this process's own staging copy of the vault-secrets adoption, whose source " +
        "stays in the vault untouched.",
    },
    "src/core/brain/secrets/envelope.ts": {
      calls: ["renameSync", "unlinkSync"],
      recovery: UNARCHIVED_OUTSIDE,
      reason:
        "wraps the plaintext keyfile into a passphrase-verified envelope through a " +
        "tmp-plus-rename swap that lands at mode 0600, and the unlink is only the tmp " +
        "whose wrap failed, so the displaced bytes are the keyfile the envelope just " +
        "replaced and the wrapping passphrase re-derives the key it protects - a lost " +
        "passphrase is the documented, permanent loss. The custody state sits outside " +
        "every snapshot archive by design.",
    },
    "src/core/brain/secrets/token-store.ts": {
      calls: ["renameSync"],
      recovery: UNARCHIVED_OUTSIDE,
      reason:
        "the tmp-plus-rename half of the per-agent MCP token store's write, which must " +
        "land at mode 0600 at creation, so no shared writer serves it. The store is " +
        "hash-at-rest by design: the bytes a rotation displaces are the previous hash " +
        "and non-secret prefix, never a credential, and overwriting them is the rotate " +
        "or revoke doing its job. Custody state sits outside every snapshot archive.",
    },

    // --- Two-phase accept with a journalled rollback ---------------------
    "src/core/brain/skill-proposals.ts": {
      calls: ["rmdirSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "the pending, accepted and materialised pages are removed through the lane " +
        "page store (task 2.10 WP6), after the accepted copy landed and the journal " +
        "recorded the commit phase, and only when the journal recorded that neither " +
        "existed beforehand. The `rmdirSync` finishes that rollback for a `mature_page` " +
        "accept, which creates a directory to hold its SKILL.md: `rmdirSync` refuses a " +
        "non-empty directory, so only the empty shell this sequence made is removed. " +
        "A `scored_rewrite` accept OVERWRITES an incumbent, so when the journal " +
        "recorded that the artifact DID exist and carries a prior-content copy, the " +
        "same rollback restores the incumbent bytes through `atomicWriteFileSync` " +
        "instead of removing anything; a missing copy is a named refusal that keeps " +
        "the journal on disk, because silently leaving the candidate body on an " +
        "incumbent's path is the one outcome worse than the crash being recovered " +
        "from.",
    },

    // --- Repair under an explicit apply ----------------------------------
    "src/core/brain/watchdog.ts": {
      calls: ["rmSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "under `--remediate` without `--dry-run` only: removes a non-directory " +
        "occupying a path the Brain tree requires to be a directory, immediately before " +
        "creating it. The plan naming that file is returned on every dry run, so the " +
        "operator sees the exact removal before authorising it.",
    },

    // --- Reached from the gate, but not lexically inside it --------------
    "src/core/brain/source-cleanup.ts": {
      calls: ["rmSync"],
      recovery: Object.freeze({
        recoveryPoint: true,
        blastRadius: Object.freeze({ brainTopLevel: true, outsideBrainRoot: true }),
      }),
      reason:
        "`removeFile` is reached only from `runDeletion`, which `deleteBySource` hands to " +
        "`withDestructiveSnapshot` BY NAME - so the archive exists before any removal, but the " +
        "census sees a helper rather than a gated block and this entry is that claim written " +
        "down. The one ungated call of `runDeletion` is the no-work branch, where the derived, " +
        "originals and manifest lists are all empty and the loops remove nothing. Recovery is " +
        "PARTIAL rather than covered because `--include-originals` removes the imported file " +
        "outside `Brain/`, which no archive has ever held.",
    },
    "src/core/brain/anticipatory-prune.ts": {
      calls: ["unlinkSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "prunes the anticipatory context cache under `Brain/.state/anticipatory/` by file age " +
        "and a hard count cap, never the entry the calling refresh just wrote. Every entry is " +
        "a derived context pack rebuilt from the vault it sits in, so removing one costs one " +
        "recomputation on the next refresh or read and loses no content.",
    },
    "src/core/brain/notes/write-record.ts": {
      calls: ["unlinkSync"],
      recovery: UNARCHIVED_BRAIN,
      reason:
        "prunes before-images past a retention window measured from each file's own mtime, " +
        "and an image whose age cannot be measured at all is kept rather than removed. Every " +
        "image is a COPY of note content that still exists somewhere the snapshot region " +
        "archives - either on disk as the note's current body or inside an earlier archive - " +
        "so removing one loses no content; it only narrows how far back a revert can reach, " +
        "and a revert that cannot reach its before-image refuses that target by name rather " +
        "than discovering the absence silently.",
    },
    "src/core/brain/notes/lifecycle.ts": {
      calls: ["renameSync", "unlinkSync"],
      recovery: UNARCHIVED_OUTSIDE,
      reason:
        "the note MOVE, which is a relink and not a copy: `linkSync` attaches the inode to the " +
        "destination name and the name is re-confirmed on disk before the source name is " +
        "dropped, so the bytes are reachable under two names at that instant and under one at " +
        "every other. The case-only rename cannot use that order - unlinking the source would " +
        "remove the destination with it - so it stages a third private name for the same inode " +
        "first. A note lives outside `Brain/` by construction, which is why no archive covers " +
        "it and why the DELETE arm of the same module is behind the gate instead - including " +
        "the `--delete-linked` cascade, whose extra unlinks all sit inside that one gate call " +
        "and whose Brain-resident half the archive therefore does hold.",
    },

    "src/core/brain/notes/folder-lifecycle.ts": {
      calls: ["rmdirSync", "unlinkSync"],
      recovery: EMPTY_SHELL_ONLY,
      reason:
        "prunes the moved folder's own emptied directories after every file of the move set " +
        "has relocated: `rmdirSync` refuses a non-empty directory, so a folder whose " +
        "subtree still holds a failed file - or any file this surface does not address - " +
        "keeps it, which is exactly where the report says the bytes are. The one " +
        "`unlinkSync` drops a destination name a mid-set fault linked after the source " +
        "name's own drop had already failed: the source name still holds that inode, so " +
        "the bytes outlive the removal and the failure report's kept-path claim stays " +
        "true. No file bytes are ever reached: both removals take names, never bytes.",
    },

    // --- Outside the vault entirely --------------------------------------
    "src/core/brain/portability/pointer.ts": {
      calls: ["rmSync"],
      recovery: UNARCHIVED_OUTSIDE,
      reason:
        "the project-side pointer NAMING a vault lives outside that vault - " +
        "`assertNotInsideVault` enforces it - so no archive could ever have covered it, " +
        "and its whole content is one path an operator can write again.",
    },
  });

/**
 * The verdict for one declared site, or `null` when the path carries no
 * declaration (which for a real path means it routes through the gate).
 *
 * Derived rather than stored, so a registry entry cannot claim a state
 * its own facts do not support.
 */
export function destructiveSiteRecoverability(path: string): RecoverabilityVerdict | null {
  const entry = DESTRUCTIVE_SITES[path];
  return entry === undefined ? null : classifyRecoverability(entry.recovery);
}