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
6.2 KB
Raw Blame
/**
 * The checkpoint substrate two resume lanes share.
 *
 * `ingest/checkpoint.ts` shipped first and owned all of this privately: the
 * opt-out env var, the id validation, the location under the machine-artifact
 * directory, the read that REFUSES an unknown `schema_version` instead of
 * silently resetting, and the write that takes the sync lock, asserts vault
 * identity and lands atomically. The sessions lane now needs the same
 * discipline for a different payload - a turn boundary rather than a set of
 * completed paths - and the honest way to give it that is to extract what the
 * two share rather than copy a second, drifting version of it.
 *
 * What is shared is the MECHANISM; what is not is the record. Each lane keeps
 * its own schema, its own serializer, and its own no-op rule, because those
 * are the parts that differ: the ingest checkpoint no-ops when the completed
 * SET is unchanged, and the sessions checkpoint when the serialized bytes are.
 *
 * Why an unknown `schema_version` is a hard error in both lanes: a resume
 * point that cannot be read is not "no resume point". Treating it as one
 * would present completed work as pending, which for the sessions lane means
 * re-hashing every turn a previous run already finished - the exact cost this
 * substrate exists to avoid.
 *
 * Language-agnostic: keys are hex ids and paths; no natural-language content
 * is inspected.
 */

import { existsSync, readFileSync, rmSync } from "node:fs";

import { atomicWriteFileSync } from "../fs-atomic.ts";
import { DERIVED_STORE_DIR } from "./path-constants.ts";
import { acquireLockSyncWithRetry, ingestLockRemedy, type LockHandle } from "./sync-lockfile.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { machineStatePath } from "../state/machine-state.ts";

/**
 * Env var that, when truthy, disables checkpoint reads and writes in EVERY
 * lane. One spelling on purpose: an operator who has turned resumability off
 * for a deterministic run means it for the whole process, and a second var
 * would be a second thing to remember and a second thing to forget.
 */
export const NO_CHECKPOINT_ENV = "OSB_INGEST_NO_CHECKPOINT";

/** Shape of a checkpoint id: a lowercase hex digest prefix. */
const CHECKPOINT_ID_RE = /^[0-9a-f]{6,64}$/;

/**
 * Whether checkpointing is active. Off only when {@link NO_CHECKPOINT_ENV}
 * holds a truthy value; the empty string, `0`, and `false` are all treated as
 * unset so an accidentally-exported empty var does not silently disable
 * resumability.
 */
export function checkpointingEnabled(): boolean {
  const raw = process.env[NO_CHECKPOINT_ENV];
  if (raw === undefined) return true;
  const v = raw.trim().toLowerCase();
  return v === "" || v === "0" || v === "false";
}

/**
 * Refuse an id that is not a hex digest, naming the lane. The id becomes a
 * filename, so a caller-supplied `../outside` has to fail here rather
 * than reach `join`.
 */
export function assertCheckpointId(label: string, id: string): void {
  if (!CHECKPOINT_ID_RE.test(id)) {
    throw new Error(`invalid ${label} id (expected lowercase hex): ${JSON.stringify(id)}`);
  }
}

/** Absolute path of one checkpoint file inside a lane's own directory. */
export function checkpointFilePath(vault: string, dir: string, label: string, id: string): string {
  assertCheckpointId(label, id);
  return machineStatePath(vault, DERIVED_STORE_DIR, dir, `${id}.json`);
}

/**
 * Read one checkpoint file as a plain object. Returns `null` when the file
 * does not exist. Throws - naming `label` and the path - when the bytes are
 * not JSON, are not an object, or carry a `schema_version` this build does
 * not understand. Never a silent reset.
 */
export function readCheckpointObject(
  path: string,
  label: string,
  schemaVersion: number,
): Record<string, unknown> | null {
  if (!existsSync(path)) return null;
  let parsed: unknown;
  try {
    parsed = JSON.parse(readFileSync(path, "utf8"));
  } catch (e) {
    throw new Error(`${label} is corrupted JSON: ${path}`, { cause: e });
  }
  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
    throw new Error(`${label} is not an object: ${path}`);
  }
  const obj = parsed as Record<string, unknown>;
  if (obj["schema_version"] !== schemaVersion) {
    throw new Error(
      `${label} schema_version ${String(obj["schema_version"])} not supported (expected ${schemaVersion}): ${path}`,
    );
  }
  return obj;
}

/**
 * Write one checkpoint file behind the vault-identity guard, atomically, and
 * only when the bytes differ from what is already there. Returns `true` when
 * a write happened, `false` on the byte-identical no-op - which is what keeps
 * a re-recorded boundary from touching the file's mtime.
 */
export function writeCheckpointObject(vault: string, path: string, body: string): boolean {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  if (existsSync(path) && readFileSync(path, "utf8") === body) return false;
  atomicWriteFileSync(path, body);
  return true;
}

/**
 * Remove one checkpoint file. Returns `true` when a file was removed, `false`
 * when there was none. Absence is the terminal state for a resume point: a
 * lane with no checkpoint starts from the beginning, which is the same thing
 * a checkpoint rewritten to empty would have to mean.
 */
export function removeCheckpointFile(vault: string, path: string): boolean {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  if (!existsSync(path)) return false;
  rmSync(path);
  return true;
}

/**
 * Run `fn` with the sync lock held on a checkpoint file.
 *
 * The read, the merge and the write of a checkpoint are ONE critical section.
 * A plan's items - and a machine's session logs - are dispatched to parallel
 * workers, so two of them finishing at once would otherwise each write back
 * the state they read, and the later write would erase the earlier progress:
 * done work silently turned back into pending work on the next resume.
 */
export function withCheckpointLock<T>(path: string, fn: () => T): T {
  const handle: LockHandle = acquireLockSyncWithRetry(path, undefined, {
    remedy: ingestLockRemedy,
  });
  try {
    return fn();
  } finally {
    handle.release();
  }
}