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
/**
 * Overwrite-only exact-state lane (t_b0c9d0a3).
 *
 * Operational "current value" state - the deploy target, the active branch,
 * the current sprint - accumulates badly in a free-form scratchpad: an old
 * value stays in the text and can resurface through semantic recall. This
 * lane stores that state STRUCTURALLY, keyed by aspect: each write to an
 * aspect overwrites its canonical value entirely, with no history and no
 * versioned copies. One file per aspect at `Brain/state/<aspect>.md`.
 *
 * The lane is excluded from the search index by the index-admission
 * predicate ({@link ../vault-scope/index-admission.ts}) and from retrieval
 * by the staleness barrier ({@link ../search/result-filters.ts}), so a
 * superseded value can never leak back through FTS/vector/graph recall.
 *
 * Language-agnostic: the aspect is an opaque slug; nothing here inspects the
 * natural-language content of the value.
 *
 * Once this machine is store-only (design D14, task 2.10) the lane lives in
 * the brain store, as the migration imports it: one `lane-entry` record per
 * write in lane {@link EXACT_STATE_LANE}, keyed by the aspect, and a
 * `lane-entry-remove` tombstone per clear. The entry fold gives the current
 * value; nothing under `Brain/state/` is written or read.
 */

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

import { atomicWriteFileSync } from "../fs-atomic.ts";
import { sanitiseTextField } from "../redactor.ts";
import { STORE_PARTITIONS } from "../store/constants.ts";
import { foldLaneEntries, laneEntryRecord, laneEntryRemoveRecord } from "../store/lane-records.ts";
import type { DualWriteRecord } from "../store/dual-write.ts";
import { protectionStore, StoreUnavailableError } from "../store/read/protection-store.ts";
import { readStreamRecords } from "../store/read/stream-read.ts";
import { rowNamesPrivatePage } from "../store/reference-privacy.ts";
import { isStoreOnly } from "../store/store-only.ts";
import type { StoreInspection } from "../store/store-open.ts";
import { routeWrite } from "../store/store-write.ts";
import { parseFrontmatterText } from "../vault.ts";
import { brainStateDir, exactStatePath, validateSlug } from "./paths.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";

/** Frontmatter `kind` marking a page as an exact-state lane artifact. */
export const EXACT_STATE_KIND = "exact-state";

/** The store lane of exact-state entries, as the migration names it (`surface-map.ts`). */
export const EXACT_STATE_LANE = "exact-state";

/** Hard ceiling on a single aspect's value. Mirrors the pinned-context budget. */
export const MAX_EXACT_STATE_VALUE_LEN = 20_000;

export type ExactStateErrorCode = "budget_exceeded" | "invalid_aspect";

/** Typed failure so callers surface a structured error instead of opaque prose. */
export class ExactStateError extends Error {
  readonly code: ExactStateErrorCode;
  readonly details: Readonly<Record<string, unknown>>;

  constructor(
    code: ExactStateErrorCode,
    message: string,
    details: Readonly<Record<string, unknown>> = {},
  ) {
    super(message);
    this.name = "ExactStateError";
    this.code = code;
    this.details = details;
  }
}

export interface ExactStateEntry {
  /** The aspect slug this entry is keyed by. */
  readonly aspect: string;
  /** The canonical value (the latest overwrite). */
  readonly value: string;
  /** Absolute path of the aspect's lane file; empty for an entry held in the store. */
  readonly path: string;
  /** ISO-8601 instant of the last write. */
  readonly updatedAt: string;
}

function normaliseValue(value: unknown): string {
  return sanitiseTextField(value, { maxLen: Number.POSITIVE_INFINITY }).trim();
}

/**
 * Validate an aspect slug, converting the generic slug-guard `Error` into a
 * typed {@link ExactStateError} so an invalid aspect surfaces as a handleable
 * operational failure instead of crashing a caller that only catches
 * `ExactStateError`.
 */
function validateAspect(aspect: string): string {
  try {
    return validateSlug(aspect);
  } catch (exc) {
    throw new ExactStateError("invalid_aspect", (exc as Error).message, { aspect });
  }
}

function renderPage(aspect: string, value: string, updatedAt: string): string {
  // Fixed, machine-safe frontmatter fields (slug aspect, ISO instant,
  // constant kind) - no user text reaches the YAML, so no quoting hazard.
  return `---\nkind: ${EXACT_STATE_KIND}\naspect: ${aspect}\nupdated_at: ${updatedAt}\n---\n\n${value}\n`;
}

/**
 * Write (overwrite) an aspect's canonical value. Returns the stored entry.
 * Over-budget input is rejected with {@link ExactStateError} BEFORE any
 * write - never silently truncated. An invalid aspect slug is rejected with
 * {@link ExactStateError} (`invalid_aspect`).
 */
export function writeExactState(
  vault: string,
  aspect: string,
  value: unknown,
  now: number = Date.now(),
): ExactStateEntry {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  const slug = validateAspect(aspect);
  const normalised = normaliseValue(value);
  if (normalised.length > MAX_EXACT_STATE_VALUE_LEN) {
    throw new ExactStateError(
      "budget_exceeded",
      `exact-state value of ${normalised.length} chars exceeds the ${MAX_EXACT_STATE_VALUE_LEN} budget`,
      { aspect: slug, length: normalised.length, budget: MAX_EXACT_STATE_VALUE_LEN },
    );
  }
  const updatedAt = new Date(now).toISOString();
  const replacesPrivate = replacesPrivateAspect(vault, slug);
  const routed = routeWrite({
    legacy: () => {
      const path = exactStatePath(vault, slug);
      atomicWriteFileSync(path, renderPage(slug, normalised, updatedAt));
      return path;
    },
    // One verdict over the whole caller input, the aspect and its value,
    // raised by the entry it replaces: a private aspect stays private. A
    // shared aspect the new value raises to private gets a shared
    // tombstone first (content-free, dropped when the value stays shared),
    // so a machine that holds only shared stops reading the old value.
    store: () => {
      const live = storeEntries().get(slug);
      return [
        ...(live !== undefined && !live.livePrivate ? [replacedSharedTombstone(slug)] : []),
        laneEntryRecord({
          lane: EXACT_STATE_LANE,
          entry: slug,
          fields: { kind: EXACT_STATE_KIND, aspect: slug, updated_at: updatedAt },
          text: normalised,
          authority: "agent",
          private:
            replacesPrivate || rowNamesPrivatePage(vault, { aspect: slug, value: normalised }),
        }),
      ];
    },
    context: { vault },
  });
  const path = routed.mode === "legacy" ? routed.value : "";
  return Object.freeze({ aspect: slug, value: normalised, path, updatedAt });
}

/** The shared tombstone of a shared aspect a private value replaces (`Located`). */
function replacedSharedTombstone(slug: string): DualWriteRecord {
  return {
    ...laneEntryRemoveRecord({
      lane: EXACT_STATE_LANE,
      entry: slug,
      authority: "agent",
      private: false,
    }),
    located: { partition: "shared", content: false, onlyIfApart: true },
  };
}

/**
 * Whether a write of `slug` replaces a private aspect (design D14, one
 * verdict per operation, fail closed): on a store-only machine the live
 * entry lives in `private`; on an unswitched one the value on the page
 * names a private page, as the write that stored it judged. A private
 * aspect never becomes shared by an overwrite, so while a store shard
 * cannot be seen the aspect counts as private.
 */
function replacesPrivateAspect(vault: string, slug: string): boolean {
  if (isStoreOnly({ vault })) {
    const read = readStoreAspects();
    return read.incomplete || read.entries.get(slug)?.livePrivate === true;
  }
  if (!existsSync(exactStatePath(vault, slug))) return false;
  try {
    const current = readExactState(vault, slug);
    return rowNamesPrivatePage(vault, { aspect: slug, value: current?.value ?? "" });
  } catch {
    return true;
  }
}

/** An exact-state entry the store holds, with the partitions its records sit in. */
interface StoreEntry extends ExactStateEntry {
  /** Whether a record of its history is private. */
  readonly private: boolean;
  /** Whether a record of its history is shared. */
  readonly shared: boolean;
  /** Whether its live record is in `private`. */
  readonly livePrivate: boolean;
}

/** Every exact-state entry the store holds, keyed by aspect. */
function storeEntries(): Map<string, StoreEntry> {
  return readStoreAspects().entries;
}

/**
 * The store's exact-state entries, and whether an `events` shard of a
 * held partition could not be read or is gone since this machine read it
 * (`incomplete`): an aspect's private records may be in it.
 */
function readStoreAspects(): { entries: Map<string, StoreEntry>; incomplete: boolean } {
  const out = new Map<string, StoreEntry>();
  let store: StoreInspection | null;
  try {
    store = protectionStore(undefined, { needShared: true });
  } catch (err) {
    if (!(err instanceof StoreUnavailableError)) throw err;
    // A switched machine whose store cannot be opened sees no aspect.
    return { entries: out, incomplete: true };
  }
  if (store === null) return { entries: out, incomplete: false };
  const privateIds = new Set<string>();
  let incomplete = false;
  const records = STORE_PARTITIONS.filter((p) => store.partitions.has(p)).flatMap((partition) => {
    const read = readStreamRecords(store.root, partition, { stream: "events" });
    if (read.unreadable.length > 0) incomplete = true;
    if (partition === "private") for (const r of read.records) privateIds.add(r.id);
    return read.records;
  });
  for (const state of foldLaneEntries(records).entries.values()) {
    const value = state.value;
    if (value === null || value.lane !== EXACT_STATE_LANE) continue;
    const updated = value.fields["updated_at"];
    out.set(
      value.entry,
      Object.freeze({
        aspect: value.entry,
        value: value.text.trim(),
        path: "",
        updatedAt: typeof updated === "string" ? updated : "",
        private: state.history.some((h) => privateIds.has(h.record.id)),
        shared: state.history.some((h) => !privateIds.has(h.record.id)),
        livePrivate: privateIds.has(state.winner),
      }),
    );
  }
  return { entries: out, incomplete };
}

/** Read an aspect's canonical value, or null when it was never written. */
export function readExactState(vault: string, aspect: string): ExactStateEntry | null {
  const slug = validateAspect(aspect);
  if (isStoreOnly({ vault })) {
    const entry = storeEntries().get(slug);
    if (entry === undefined) return null;
    const { private: _private, livePrivate: _live, ...rest } = entry;
    return Object.freeze(rest);
  }
  const path = exactStatePath(vault, slug);
  // Read directly rather than existsSync-then-read: a concurrent delete
  // between the check and the read would otherwise surface as an unhandled
  // ENOENT. Treat "not found" as null; propagate any other read error.
  try {
    return parseEntry(slug, path, readFileSync(path, "utf8"));
  } catch (exc) {
    if ((exc as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw exc;
  }
}

/** Every aspect in the lane, sorted by aspect slug ascending. */
export function listExactState(vault: string): ExactStateEntry[] {
  if (isStoreOnly({ vault })) {
    return [...storeEntries().values()]
      .map(({ private: _private, shared: _shared, ...rest }) => Object.freeze(rest))
      .toSorted((a, b) => (a.aspect < b.aspect ? -1 : a.aspect > b.aspect ? 1 : 0));
  }
  const dir = brainStateDir(vault);
  let names: string[];
  try {
    names = readdirSync(dir);
  } catch {
    return [];
  }
  const out: ExactStateEntry[] = [];
  for (const name of names) {
    if (!name.endsWith(".md")) continue;
    const aspect = name.slice(0, -3);
    try {
      const entry = readExactState(vault, aspect);
      if (entry !== null) out.push(entry);
    } catch {
      // A malformed aspect filename is not a valid lane entry; skip it.
    }
  }
  out.sort((a, b) => (a.aspect < b.aspect ? -1 : a.aspect > b.aspect ? 1 : 0));
  return out;
}

/** Remove an aspect. Returns whether it existed before the call. */
export function clearExactState(vault: string, aspect: string): boolean {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  const slug = validateAspect(aspect);
  if (isStoreOnly({ vault })) {
    const held = storeEntries().get(slug);
    if (held === undefined) return false;
    routeWrite({
      legacy: () => undefined,
      store: () =>
        laneEntryRemoveRecord({
          lane: EXACT_STATE_LANE,
          entry: slug,
          authority: "agent",
          // A tombstone names only the lane and the aspect slug. It goes to
          // shared whenever a shared record of the aspect exists, so a
          // machine without private clears the value it still shows;
          // otherwise it stays in private with the entry.
          private: held.private && !held.shared,
        }),
      context: { vault },
    });
    return true;
  }
  const path = exactStatePath(vault, slug);
  if (!existsSync(path)) return false;
  // Judged from the value being cleared, as the write judged it; an
  // unreadable page counts as private.
  let isPrivate = true;
  try {
    const current = readExactState(vault, slug);
    isPrivate = rowNamesPrivatePage(vault, { aspect: slug, value: current?.value ?? "" });
  } catch {
    // fail closed
  }
  // The dual write records the tombstone, so the store's fold forgets the
  // aspect too and a later switch cannot bring the cleared value back.
  routeWrite({
    legacy: () => rmSync(path, { force: true }),
    store: () =>
      laneEntryRemoveRecord({
        lane: EXACT_STATE_LANE,
        entry: slug,
        authority: "agent",
        private: isPrivate,
      }),
    context: { vault },
  });
  return true;
}

function parseEntry(aspect: string, path: string, raw: string): ExactStateEntry {
  const [meta, body] = parseFrontmatterText(raw);
  const updatedAt = typeof meta["updated_at"] === "string" ? meta["updated_at"] : "";
  return Object.freeze({ aspect, value: body.trim(), path, updatedAt });
}