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
30.0 KB
Raw Blame
/**
 * Per-agent / per-session note revert (who-wrote-what, Task D /
 * t_924129c5).
 *
 * The note-write record answers "who wrote that, and what did it say
 * before". This module is the other half: taking it back. It is
 * plan-seal-apply over the `note-write` events, the same shape
 * `src/core/state/migrate.ts` uses for state relocation, because the
 * operator has to be able to READ what a revert is about to do before it
 * does it.
 *
 * ## Refuse on doubt
 *
 * A revert reaches into files other writers share, and there is no
 * three-way merge here by design (`docs/brainstorm/who-wrote-what/
 * design.md`, out of scope). So every target the selected writes touched
 * resolves to exactly one of three things and is REPORTED either way:
 *
 *   - `restore` - put back the before-image of the oldest selected write;
 *   - `delete` - the selected writes brought the note into existence and
 *     nothing wrote it before, so undoing them removes it;
 *   - `refuse` - with a named reason from {@link NOTE_REVERT_REFUSAL}.
 *
 * A refused target is never touched and never dropped from the plan: the
 * digest covers refusals too, so an operator who applies a digest applies
 * the plan they read, including the parts of it that will not run.
 *
 * ## The seal
 *
 * {@link planNoteRevert} returns a `digest` over the selector and the
 * entries - NOT over `planned_at`, so the same vault in the same state
 * plans to the same digest twice and an operator can re-read a plan
 * before applying it. {@link applyNoteRevert} re-plans from scratch and
 * refuses `digest_mismatch` before any byte moves when the vault changed
 * under the operator. That is the whole concurrency story: nothing is
 * locked between the two calls, and the digest is what notices.
 *
 * ## Why the apply is one gated block
 *
 * Every restored and deleted target runs inside one
 * {@link withDestructiveSnapshot} call, so a revert that half-succeeds
 * still has ONE recovery point covering the state before all of it. The
 * removal lives lexically inside the gate's argument list, which is also
 * what the destructive-site census reads.
 */

import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
import { dirname, join } from "node:path";

import { atomicWriteFileSync } from "../../fs-atomic.ts";
import { canonicalJson, sha256Hex } from "../../integrity/digest.ts";
import type { RecoverabilityVerdict } from "../gates/recoverability.ts";
import type { BrainLogParseWarning } from "../log.ts";
import { BRAIN_ROOT_REL, ensureInsideVault, writeImagePath } from "../paths.ts";
import { withDestructiveSnapshot } from "../snapshot-gate.ts";
import { isoSecond } from "../time.ts";
import { BRAIN_SNAPSHOT_REASON } from "../types.ts";
import { assertNoteVaultForWrite } from "../../vault-adapter/index.ts";
import { listNoteWrites, type NoteWriteRecord } from "./write-log.ts";
import {
  NOTE_WRITE_NO_PRIOR,
  NOTE_WRITE_OP,
  recordNoteWrite,
  storeBeforeImage,
  type NoteWriteReceipt,
} from "./write-record.ts";

/** What a plan says will happen to one target. */
export const NOTE_REVERT_ACTION = Object.freeze({
  /** Put the before-image of the oldest selected write back. */
  restore: "restore",
  /** Remove the note the selected writes created. */
  delete: "delete",
  /** Touch nothing, and say why through {@link NOTE_REVERT_REFUSAL}. */
  refuse: "refuse",
} as const);

export type NoteRevertAction = (typeof NOTE_REVERT_ACTION)[keyof typeof NOTE_REVERT_ACTION];

/**
 * Why one target is refused. Closed, and every member is a fact about
 * the vault rather than a failure of this module.
 */
export const NOTE_REVERT_REFUSAL = Object.freeze({
  /**
   * The bytes on disk are not the ones the newest selected write left -
   * somebody wrote the target afterwards, or it is gone when it should
   * be there. Reverting would destroy that unrecorded work.
   */
  drift: "drift",
  /**
   * A write this selector did NOT select sits between the oldest and the
   * newest selected write on this target, in the merged total order
   * (timestamp, shard id, line) the reader already yields. Undoing the
   * outer pair would silently undo the middle one too.
   *
   * Same-second ties are decided by that order too, because line order
   * inside one shard IS append order. Only a tie ACROSS shards is
   * interleaved on doubt: there the merge falls back to the shard id,
   * which is a name and not a clock. See {@link interleaves}.
   */
  interleaved: "interleaved",
  /**
   * The bytes a restore needs are not in the before-image store - pruned
   * by retention, or never written. The hash proves the write happened;
   * only the image can undo it.
   */
  imageMissing: "image-missing",
  /**
   * The current bytes of the target cannot be read at all, so no verdict
   * about drift is possible. "I could not tell" must never resolve to
   * "revert it".
   */
  unrecorded: "unrecorded",
  /**
   * The target already holds exactly what this revert would produce -
   * the selected writes put it back themselves, or a previous revert
   * already ran. Nothing to take back, and saying so is not the same
   * answer as a restore that rewrites identical bytes and logs a write.
   */
  alreadyReverted: "already-reverted",
  /**
   * The recorded target is not a path inside this vault: a corrupt log
   * line, a hand-appended one, a crafted one. Distinct from
   * `unrecorded`, which is a fact about BYTES that could not be read at
   * a path this vault owns; this is a fact about the log, and no revert
   * of such a target could ever be safe.
   */
  targetInvalid: "target-invalid",
} as const);

export type NoteRevertRefusal = (typeof NOTE_REVERT_REFUSAL)[keyof typeof NOTE_REVERT_REFUSAL];

/** Membership list, in declaration order. */
export const NOTE_REVERT_REFUSALS: ReadonlyArray<NoteRevertRefusal> = Object.freeze(
  Object.values(NOTE_REVERT_REFUSAL),
);

/**
 * Why a whole revert call is refused, as opposed to one target of it.
 * Each is thrown as a {@link NoteRevertError} carrying the code, so a CLI
 * or MCP surface reports the reason by name rather than by message text.
 */
export const NOTE_REVERT_ERROR = Object.freeze({
  /** No `agent`, `device` or `path`: a time window alone selects the vault. */
  unboundedSelector: "unbounded_selector",
  /** The sealed plan no longer describes the vault. */
  digestMismatch: "digest_mismatch",
  /** Every entry is a refusal; there is nothing an apply could do. */
  nothingToApply: "nothing_to_apply",
} as const);

export type NoteRevertErrorCode = (typeof NOTE_REVERT_ERROR)[keyof typeof NOTE_REVERT_ERROR];

/** A revert refused as a whole, with the code a caller narrows on. */
export class NoteRevertError extends Error {
  readonly code: NoteRevertErrorCode;
  /** The digest the caller supplied, on a `digest_mismatch` only. */
  readonly expected?: string;
  /** The digest the re-plan produced, on a `digest_mismatch` only. */
  readonly actual?: string;

  constructor(
    code: NoteRevertErrorCode,
    message: string,
    digests?: { readonly expected: string; readonly actual: string },
  ) {
    super(message);
    this.name = "NoteRevertError";
    this.code = code;
    if (digests !== undefined) {
      this.expected = digests.expected;
      this.actual = digests.actual;
    }
  }
}

/**
 * Which recorded writes a revert is about.
 *
 * At least one of `agent`, `device` or `path` is required: a selector
 * that only bounds TIME selects every write every agent on every machine
 * made in a window, which is a rollback of the vault wearing a revert's
 * clothes. `o2b brain rollback` is the verb for that, and it takes a
 * snapshot the operator chose.
 */
export interface NoteRevertSelector {
  /** Exact agent identity that recorded the write. */
  readonly agent?: string;
  /** Exact device id; the empty string is the legacy un-sharded log. */
  readonly device?: string;
  /** Exact vault-relative target path. */
  readonly path?: string;
  /** Inclusive lower bound: an ISO date or an ISO-8601 UTC timestamp. */
  readonly since?: string;
  /** Inclusive upper bound, same two spellings. */
  readonly until?: string;
}

/** What the plan says about one target. */
export interface NoteRevertEntry {
  /** Vault-relative POSIX path of the note. */
  readonly target: string;
  readonly action: NoteRevertAction;
  /** Present exactly when {@link action} is `refuse`. */
  readonly reason?: NoteRevertRefusal;
  /** The selected write ids on this target, oldest first. */
  readonly writes: ReadonlyArray<string>;
  /**
   * sha256 of the bytes on disk now, or {@link NOTE_WRITE_NO_PRIOR} when
   * there is no file, or {@link NOTE_REVERT_HASH_UNREADABLE} when the
   * bytes could not be read at all.
   */
  readonly hash_now: string;
  /**
   * sha256 the target would hold after the revert, or
   * {@link NOTE_WRITE_NO_PRIOR} when the revert removes it.
   */
  readonly hash_to: string;
}

/**
 * What `hash_now` says when the target exists in some form and its bytes
 * cannot be read.
 *
 * A third literal rather than reusing {@link NOTE_WRITE_NO_PRIOR},
 * because "there is no file here" and "there is something here I could
 * not read" are different facts, and reporting the second as the first
 * is exactly the misleading silence the refusal beside it exists to
 * prevent.
 */
export const NOTE_REVERT_HASH_UNREADABLE = "unreadable";

/** A sealed revert plan. */
export interface NoteRevertPlan {
  /** The selector as it was applied, with absent fields omitted. */
  readonly selector: NoteRevertSelector;
  /** One entry per target the selected writes touched, sorted by target. */
  readonly entries: ReadonlyArray<NoteRevertEntry>;
  /** `sha256Hex(canonicalJson({ selector, entries }))`. */
  readonly digest: string;
  /** ISO-8601 UTC second the plan was made. NOT covered by the digest. */
  readonly planned_at: string;
  /**
   * Every parse warning the log days behind this plan reported. A day
   * whose JSONL lost a line is a day whose write history is incomplete,
   * and an operator deciding what to revert has to be told that.
   */
  readonly warnings: ReadonlyArray<BrainLogParseWarning>;
}

/** How one applied target was recorded back into the write ledger. */
export interface NoteRevertRecorded {
  readonly target: string;
  /** The `note-write` id of the revert, or null when it was not recorded. */
  readonly write_id: string | null;
  /** Present exactly when {@link write_id} is null. */
  readonly audit_reason?: string;
}

/** What one apply did. */
/** One target the apply reached and could not complete, and why. */
export interface NoteRevertFailure {
  /** Vault-relative POSIX path of the note. */
  readonly target: string;
  /** The error's own message; a machine code here would be an invention. */
  readonly reason: string;
}

export interface NoteRevertApplyResult {
  /** The recovery point the whole apply ran behind. */
  readonly snapshot: { readonly run_id: string; readonly path: string };
  /** Entries whose bytes moved, in plan order. */
  readonly applied: ReadonlyArray<NoteRevertEntry>;
  /**
   * Entries nothing touched: the plan's own refusals, plus any target
   * whose before-image failed verification at apply time.
   */
  readonly refused: ReadonlyArray<NoteRevertEntry>;
  /** One row per applied target, naming its `revert` write id. */
  readonly recorded: ReadonlyArray<NoteRevertRecorded>;
  /**
   * Entries the apply reached and could not carry out, for a reason no
   * plan could have predicted - an unwritable directory, an I/O error, a
   * target replaced under the apply. A third bucket rather than a
   * refusal, because a refusal is a fact about the vault the plan
   * already knew and this is a failure of this run; and a bucket rather
   * than a throw, because one failing entry must not lose the entries
   * after it, which would then appear in neither `applied` nor
   * `refused`.
   */
  readonly failed: ReadonlyArray<NoteRevertFailure>;
  /**
   * What the recovery point is worth for what this apply reached. A
   * note under `Brain/` and a note outside it are covered differently,
   * and reporting the archive path with no verdict beside it reads as
   * full coverage to every caller.
   */
  readonly recoverability: RecoverabilityVerdict;
}

/** Injected clock, shared by both entry points. */
export interface PlanNoteRevertOptions {
  readonly now?: Date;
  /** Select as a caller below local reach; the safety rules still see every write. */
  readonly withholdsPrivate?: boolean;
}

/** How an apply attributes the `revert` writes it records. */
export interface ApplyNoteRevertOptions extends Omit<PlanNoteRevertOptions, "withholdsPrivate"> {
  /** Caller-asserted identity; defaults to the resolved agent name. */
  readonly agent?: string;
  /** Config file that names the writing agent, threaded to the record. */
  readonly configPath?: string;
}

/** The selector fields that bound a revert to something smaller than the vault. */
const BOUNDING_FIELDS = Object.freeze(["agent", "device", "path"] as const);

/** Prefix that puts a target inside the Brain tree. */
const BRAIN_TREE_PREFIX = `${BRAIN_ROOT_REL}/`;

/** The bytes at a target, or the named reason there are none to hash. */
type CurrentBytes =
  | { readonly kind: "bytes"; readonly bytes: string }
  | { readonly kind: "absent" }
  | { readonly kind: "unreadable" };

/**
 * Read the target as it is now.
 *
 * `ENOENT` is the one error that means "no file here"; every other
 * failure - a directory at the path, a permission wall, an I/O error -
 * is `unreadable`, because a plan that cannot see the bytes cannot judge
 * whether reverting them destroys somebody's work.
 */
function readCurrent(abs: string): CurrentBytes {
  try {
    return { kind: "bytes", bytes: readFileSync(abs, "utf8") };
  } catch (err) {
    return (err as NodeJS.ErrnoException).code === "ENOENT"
      ? { kind: "absent" }
      : { kind: "unreadable" };
  }
}

/** The digest of what is on disk now, in the entry's vocabulary. */
function hashOf(current: CurrentBytes): string {
  if (current.kind === "bytes") return sha256Hex(current.bytes);
  return current.kind === "absent" ? NOTE_WRITE_NO_PRIOR : NOTE_REVERT_HASH_UNREADABLE;
}

/**
 * The digest that seals one plan: the selector with absent fields dropped
 * and the entries, canonically serialised. Exported so a surface that
 * shows only some of a plan's entries can seal exactly what it shows,
 * spelled the same way the full plan is.
 */
export function noteRevertDigest(
  selector: NoteRevertSelector,
  entries: ReadonlyArray<NoteRevertEntry>,
): string {
  return sha256Hex(canonicalJson({ selector: normaliseSelector(selector), entries }));
}

/** The selector with absent fields dropped, so the digest is stable. */
function normaliseSelector(selector: NoteRevertSelector): NoteRevertSelector {
  return {
    ...(selector.agent !== undefined ? { agent: selector.agent } : {}),
    ...(selector.device !== undefined ? { device: selector.device } : {}),
    ...(selector.path !== undefined ? { path: selector.path } : {}),
    ...(selector.since !== undefined ? { since: selector.since } : {}),
    ...(selector.until !== undefined ? { until: selector.until } : {}),
  };
}

/** Refuse a selector that names nobody and nothing. */
function assertBounded(selector: NoteRevertSelector): void {
  if (BOUNDING_FIELDS.some((field) => selector[field] !== undefined)) return;
  throw new NoteRevertError(
    NOTE_REVERT_ERROR.unboundedSelector,
    `a revert selector must name at least one of ${BOUNDING_FIELDS.join(", ")}; a time window ` +
      "alone selects every write by every agent on every device, which is a vault rollback - " +
      "use o2b brain rollback for that",
  );
}

/** One refusal entry, so the four call sites cannot spell it differently. */
function refuse(
  target: string,
  writes: ReadonlyArray<string>,
  reason: NoteRevertRefusal,
  hashNow: string,
  hashTo: string,
): NoteRevertEntry {
  return {
    target,
    action: NOTE_REVERT_ACTION.refuse,
    reason,
    writes,
    hash_now: hashNow,
    hash_to: hashTo,
  };
}

/**
 * Whether the store holds the image a restore needs.
 *
 * `writeImagePath` validates the digest shape, because it reaches this
 * module from a log payload an operator may have hand-edited; a digest
 * it rejects is an image this vault does not have, which is the same
 * answer as a missing file.
 */
function imageAvailable(vault: string, sha256: string): boolean {
  try {
    return existsSync(writeImagePath(vault, sha256));
  } catch {
    return false;
  }
}

/**
 * Whether a write nobody selected sits inside the selected window.
 *
 * The window is measured in the MERGED TOTAL ORDER `listNoteWrites`
 * already yields - `readLogDay` orders by (timestamp, shard id, line),
 * and line order inside one shard IS the order the appends landed - so
 * "between" is a position, not a timestamp comparison. That matters
 * because timestamps are second-precision: three writes in one second
 * are indistinguishable by clock and perfectly ordered by line.
 *
 * The one place the position is NOT evidence is a same-second tie across
 * shards. There the merge falls back to the shard id, which is a name
 * and not a clock: two devices that wrote in the same second could have
 * written in either order, and the order shown is alphabetical. So a
 * non-selected write that shares a second with a selected write is
 * trusted only when it shares that write's SHARD; otherwise it is
 * interleaved, which is the refuse-on-doubt half of the rule.
 *
 * This is deliberately narrower than "any same-second write is
 * interleaved", which is what this rule used to say. That reading
 * refused a create and an update a second apart on one machine - an
 * order the log proves - and an operator whose whole vault lives on one
 * device could never revert anything two writes had touched inside a
 * second.
 */
function interleaves(
  selected: ReadonlyArray<NoteWriteRecord>,
  universe: ReadonlyArray<NoteWriteRecord>,
): boolean {
  const oldest = selected[0]!;
  const newest = selected[selected.length - 1]!;
  const selectedIds = new Set(selected.map((w) => w.write_id));
  const first = universe.findIndex((w) => w.write_id === oldest.write_id);
  const last = universe.findIndex((w) => w.write_id === newest.write_id);

  return universe.some((w, index) => {
    if (selectedIds.has(w.write_id)) return false;
    // Strictly between the two ends in the merged order. A write with a
    // timestamp strictly inside the window lands here too, because the
    // merge sorts on the timestamp first.
    if (index > first && index < last) return true;
    if (w.timestamp < oldest.timestamp || w.timestamp > newest.timestamp) return false;
    // Outside the positional window but inside the same second as one of
    // its ends: trust the position only if the tie is within one shard.
    // A tie against nothing cannot happen (a strictly-interior timestamp
    // is already positionally interior), and if it ever does, doubt wins.
    const tied = selected.filter((s) => s.timestamp === w.timestamp);
    return tied.length === 0 || tied.some((s) => s.device !== w.device);
  });
}

/**
 * Resolve one target, applying the design's rules in the order they are
 * stated: what cannot be judged, then what would destroy unrecorded
 * work, then what would undo somebody else's write, then what is already
 * done, and only then the two actions.
 */
function planTarget(
  vault: string,
  target: string,
  selected: ReadonlyArray<NoteWriteRecord>,
  universe: ReadonlyArray<NoteWriteRecord>,
): NoteRevertEntry {
  const oldest = selected[0]!;
  const newest = selected[selected.length - 1]!;
  const writes = selected.map((w) => w.write_id);
  // The plan is a report over every target the selection touched, so a
  // target this vault would never have written costs that target and
  // not the plan: one crafted log line must not take the verdict on
  // every other note with it.
  let abs: string;
  try {
    abs = ensureInsideVault(join(vault, target), vault);
  } catch {
    return refuse(
      target,
      writes,
      NOTE_REVERT_REFUSAL.targetInvalid,
      NOTE_REVERT_HASH_UNREADABLE,
      oldest.hash_before,
    );
  }
  const current = readCurrent(abs);
  const hashNow = hashOf(current);

  if (current.kind === "unreadable") {
    return refuse(target, writes, NOTE_REVERT_REFUSAL.unrecorded, hashNow, oldest.hash_before);
  }
  if (hashNow !== newest.hash_after) {
    return refuse(target, writes, NOTE_REVERT_REFUSAL.drift, hashNow, oldest.hash_before);
  }

  if (interleaves(selected, universe)) {
    return refuse(target, writes, NOTE_REVERT_REFUSAL.interleaved, hashNow, oldest.hash_before);
  }

  // `delete` applies only when the selected writes brought the note into
  // existence: the oldest one replaced nothing AND nothing on record
  // wrote this target before it. A note created outside the selection is
  // never deleted through this path (design.md, out of scope).
  const createdBySelection =
    oldest.hash_before === NOTE_WRITE_NO_PRIOR &&
    universe.findIndex((w) => w.write_id === oldest.write_id) === 0;
  const hashTo = createdBySelection ? NOTE_WRITE_NO_PRIOR : oldest.hash_before;

  if (hashNow === hashTo) {
    return refuse(target, writes, NOTE_REVERT_REFUSAL.alreadyReverted, hashNow, hashTo);
  }
  if (createdBySelection) {
    return {
      target,
      action: NOTE_REVERT_ACTION.delete,
      writes,
      hash_now: hashNow,
      hash_to: hashTo,
    };
  }
  // A restore to `absent` would be a delete the delete rule declined to
  // authorise - the oldest selected write replaced nothing, but an
  // earlier write of record exists, so this note had a life before the
  // selection. There is no image of nothing to restore, and the store is
  // where the plan says so.
  if (hashTo === NOTE_WRITE_NO_PRIOR || !imageAvailable(vault, hashTo)) {
    return refuse(target, writes, NOTE_REVERT_REFUSAL.imageMissing, hashNow, hashTo);
  }
  return { target, action: NOTE_REVERT_ACTION.restore, writes, hash_now: hashNow, hash_to: hashTo };
}

/**
 * Plan what reverting the selected writes would do, and seal it.
 *
 * Two reads of the ledger rather than one: the SELECTED writes narrow by
 * the whole selector, and the UNIVERSE of writes on the same targets
 * narrows by path alone, because the interleaving and creation rules ask
 * about writes the selector deliberately excluded.
 */
export function planNoteRevert(
  vault: string,
  selector: NoteRevertSelector,
  opts: PlanNoteRevertOptions = {},
): NoteRevertPlan {
  assertBounded(selector);
  const normalised = normaliseSelector(selector);
  // `listNoteWrites` returns newest-first; every rule here reads the
  // history forwards, so both lists are reversed once, here.
  const withholdsPrivate = opts.withholdsPrivate === true;
  const selectedRead = listNoteWrites(vault, { ...normalised, withholdsPrivate });
  // Only the safety rules read the universe: it keeps private writes.
  const universeRead = listNoteWrites(
    vault,
    normalised.path !== undefined ? { path: normalised.path } : {},
  );
  const selected = selectedRead.writes.toReversed();
  const universe = universeRead.writes.toReversed();

  const byTarget = new Map<string, NoteWriteRecord[]>();
  for (const write of selected) {
    const bucket = byTarget.get(write.target);
    if (bucket === undefined) byTarget.set(write.target, [write]);
    else bucket.push(write);
  }

  const entries = [...byTarget.keys()]
    .toSorted((a, b) => a.localeCompare(b))
    .map((target) =>
      planTarget(
        vault,
        target,
        byTarget.get(target)!,
        universe.filter((w) => w.target === target),
      ),
    );

  return {
    selector: normalised,
    entries,
    digest: noteRevertDigest(normalised, entries),
    planned_at: isoSecond(opts.now ?? new Date()),
    warnings: universeRead.warnings,
  };
}

/** The regions this apply reaches, declared from the targets themselves. */
function blastRadiusOf(entries: ReadonlyArray<NoteRevertEntry>): {
  readonly brainTopLevel?: boolean;
  readonly outsideBrainRoot?: boolean;
} {
  const inBrain = entries.some((e) => e.target.startsWith(BRAIN_TREE_PREFIX));
  const outside = entries.some((e) => !e.target.startsWith(BRAIN_TREE_PREFIX));
  return {
    ...(inBrain ? { brainTopLevel: true } : {}),
    ...(outside ? { outsideBrainRoot: true } : {}),
  };
}

/** The recorded row for one applied target, discriminated on the receipt. */
function recordedRow(target: string, receipt: NoteWriteReceipt): NoteRevertRecorded {
  return receipt.write_id === null
    ? { target, write_id: null, audit_reason: receipt.audit_reason }
    : { target, write_id: receipt.write_id };
}

/**
 * Apply a plan the caller has already read, identified by its digest.
 *
 * Order is the contract. The vault-identity guard runs FIRST, so a
 * frozen vault refuses a revert by name before anything is read; then
 * the plan is rebuilt from scratch and compared to the digest, so a
 * vault that moved under the operator is refused before any byte; and
 * only then does the destructive gate take the one recovery point the
 * whole apply runs behind.
 */
export function applyNoteRevert(
  vault: string,
  selector: NoteRevertSelector,
  digest: string,
  opts: ApplyNoteRevertOptions = {},
): NoteRevertApplyResult {
  // Through the vault adapter (design D14 items 8, 13): a vault is
  // required, and the vault identity guard holds.
  assertNoteVaultForWrite(vault, "note revert");
  const plan = planNoteRevert(vault, selector, opts);
  if (plan.digest !== digest) {
    throw new NoteRevertError(
      NOTE_REVERT_ERROR.digestMismatch,
      `this plan no longer describes the vault: the sealed digest was ${digest} and re-planning ` +
        `the same selector now yields ${plan.digest}. Nothing has been touched - plan again and ` +
        "read what changed",
      { expected: digest, actual: plan.digest },
    );
  }

  const actionable = plan.entries.filter((e) => e.action !== NOTE_REVERT_ACTION.refuse);
  if (actionable.length === 0) {
    throw new NoteRevertError(
      NOTE_REVERT_ERROR.nothingToApply,
      `every one of the ${plan.entries.length} target(s) in this plan is refused, so there is ` +
        "nothing to apply; the plan names the reason for each",
    );
  }

  const timestamp = isoSecond(opts.now ?? new Date());
  const applied: NoteRevertEntry[] = [];
  const refused: NoteRevertEntry[] = plan.entries.filter(
    (e) => e.action === NOTE_REVERT_ACTION.refuse,
  );
  const recorded: NoteRevertRecorded[] = [];
  const failed: NoteRevertFailure[] = [];
  const record = (entry: NoteRevertEntry, before: string | null, after: string | null): void => {
    applied.push(entry);
    recorded.push(
      recordedRow(
        entry.target,
        recordNoteWrite(vault, {
          op: NOTE_WRITE_OP.revert,
          target: entry.target,
          before: before === null ? null : { bytes: before },
          after: after === null ? null : { bytes: after },
          timestamp,
          ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
          ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
        }),
      ),
    );
  };

  const gated = withDestructiveSnapshot(
    vault,
    BRAIN_SNAPSHOT_REASON.noteRevert,
    () => {
      for (const entry of actionable) {
        // Per-entry boundary. Every step below can throw on a condition
        // the plan could not see, and the recovery point is already
        // taken - so an escaping throw would abandon every entry after
        // this one inside a half-applied gate, and those entries would
        // appear in neither `applied` nor `refused`. Named in `failed`,
        // the operator reads what did not happen instead of inferring it
        // from what is missing.
        //
        // Inline rather than behind a helper on purpose: the removal
        // below has to stay lexically inside this gate's argument list,
        // which is what the destructive-site census reads.
        try {
          const abs = ensureInsideVault(join(vault, entry.target), vault);
          const current = readCurrent(abs);
          if (entry.action === NOTE_REVERT_ACTION.delete) {
            // The plan proved the bytes are the ones the newest selected
            // write left, so `current` is those bytes; keeping an image
            // of them is what makes this delete itself revertible.
            if (current.kind !== "bytes") {
              refused.push({
                ...entry,
                action: NOTE_REVERT_ACTION.refuse,
                reason: NOTE_REVERT_REFUSAL.unrecorded,
              });
              continue;
            }
            storeBeforeImage(vault, current.bytes);
            unlinkSync(abs);
            record(entry, current.bytes, null);
            continue;
          }
          // A restore verifies the image against the digest the plan
          // sealed BEFORE it writes: restoring bytes that are not the
          // ones recorded is the one failure a revert must never have,
          // and a corrupt or vanished image is the same answer the plan
          // gives.
          const bytes = readImage(vault, entry.hash_to);
          if (bytes === null) {
            refused.push({
              ...entry,
              action: NOTE_REVERT_ACTION.refuse,
              reason: NOTE_REVERT_REFUSAL.imageMissing,
            });
            continue;
          }
          if (current.kind === "bytes") storeBeforeImage(vault, current.bytes);
          mkdirSync(dirname(abs), { recursive: true });
          atomicWriteFileSync(abs, bytes);
          record(entry, current.kind === "bytes" ? current.bytes : null, bytes);
        } catch (err) {
          failed.push({
            target: entry.target,
            reason: err instanceof Error ? err.message : String(err),
          });
        }
      }
    },
    {
      blastRadius: blastRadiusOf(actionable),
      ...(opts.now !== undefined ? { now: opts.now } : {}),
    },
  );

  return {
    snapshot: { run_id: gated.snapshot.runId, path: gated.snapshot.path },
    applied,
    refused,
    failed,
    recorded,
    recoverability: gated.recoverability,
  };
}

/** The image's bytes, or null when it is missing or no longer hashes to its name. */
function readImage(vault: string, sha256: string): string | null {
  try {
    const bytes = readFileSync(writeImagePath(vault, sha256), "utf8");
    return sha256Hex(bytes) === sha256 ? bytes : null;
  } catch {
    return null;
  }
}