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
7.9 KB
Raw Blame
/**
 * Seam 2 - "record what you were derived from, verify on read".
 *
 * Three units of the context-integrity-gates wave need the same
 * mechanism and would otherwise each invent it: a context pack must
 * verify the vault state it was built from (B), an embedding store must
 * verify the model, dimension, and sqlite-vec ABI it was written against
 * (E), and a vault root must verify the identity marker it was
 * bootstrapped with (J).
 *
 * The mechanism is: a caller records a map of opaque string tokens at
 * write time, presents the live tokens at read time, and this module
 * reports which fields drifted. It is deliberately DOMAIN-AGNOSTIC -
 * every field name is supplied by the caller, so nothing here mentions a
 * generation counter, an embedding dimension, or a vault id. A token is
 * an opaque string; this module never parses, orders, or interprets one,
 * and never inspects natural language.
 *
 * ## `null` means "not recorded"
 *
 * A token map is `Record<string, string | null>`. An absent key and an
 * explicit `null` are the SAME condition - the side did not record that
 * field - so a legacy artifact written before a field existed compares
 * as unrecorded rather than as a spurious drift against the empty
 * string. Two unrecorded sides are not a finding. An empty string, by
 * contrast, IS a recorded value and is distinct from `null`.
 *
 * ## The gate decides where refusal begins, and `off` really is off
 *
 * {@link compareStamps} is the pure comparison and always reports what
 * it finds. {@link checkStamp} is the gated form: under
 * {@link GATE_MODE.off} it does not compare at all and returns no
 * evidence, so a caller wired to the gate structurally CANNOT emit a new
 * field, warning, or refusal while the gate is off. That is what makes
 * the byte-identical-when-absent contract mechanical rather than a
 * discipline every consumer has to re-implement. A caller that wants a
 * diagnostic irrespective of the operator's gate calls
 * {@link compareStamps} directly and says so.
 */

/**
 * The three-mode gate. `off` disables the check, `warn` reports drift
 * without refusing, `fail` refuses. Closed by design: every additional
 * mode multiplies the consuming test matrix, and units whose condition
 * is unambiguous are expected to stay binary rather than grow a fourth.
 */
export const GATE_MODE = Object.freeze({
  off: "off",
  warn: "warn",
  fail: "fail",
} as const);

/**
 * Gate-mode union. A consumer switching over it with a `never`-typed
 * `default` arm fails to compile if a mode is ever added.
 */
export type GateMode = (typeof GATE_MODE)[keyof typeof GATE_MODE];

/**
 * The modes in increasing order of strictness. Ordered (not a `Set`) so
 * config-error messages list them the same way every time.
 */
export const GATE_MODES: ReadonlyArray<GateMode> = Object.freeze([
  GATE_MODE.off,
  GATE_MODE.warn,
  GATE_MODE.fail,
]);

/** Narrow an unvalidated config or argument value to a {@link GateMode}. */
export function isGateMode(value: unknown): value is GateMode {
  return typeof value === "string" && (GATE_MODES as ReadonlyArray<string>).includes(value);
}

/**
 * The tokens one side of a comparison recorded. Keys are caller-owned
 * field names; values are opaque strings, or `null` for "this side did
 * not record that field".
 */
export type StampTokens = Readonly<Record<string, string | null>>;

/** One field whose recorded token no longer matches the live one. */
export interface StampMismatch {
  /** The caller-supplied field name that drifted. */
  readonly field: string;
  /** What was recorded when the artifact was derived. */
  readonly expected: string | null;
  /** What is live now. */
  readonly actual: string | null;
}

/** Outcome of a gated comparison. */
export const STAMP_VERDICT = Object.freeze({
  /** Nothing to report: the stamps matched, or the gate is off. */
  pass: "pass",
  /** Drift found; the gate reports it and the caller proceeds. */
  warn: "warn",
  /** Drift found; the gate refuses. */
  fail: "fail",
} as const);

export type StampVerdict = (typeof STAMP_VERDICT)[keyof typeof STAMP_VERDICT];

/** Result of {@link checkStamp}: the verdict plus the evidence behind it. */
export interface StampCheck {
  /** The mode the check ran under, echoed so a report can name it. */
  readonly mode: GateMode;
  readonly verdict: StampVerdict;
  /** Empty whenever the verdict is `pass` - including under `off`. */
  readonly mismatches: ReadonlyArray<StampMismatch>;
}

/** Rendered for a side that recorded nothing, so a gap is never blank. */
const UNRECORDED_MARKER = "<unrecorded>";

/** Runs of any whitespace; collapsed so a rendered mismatch is one line. */
const WHITESPACE_RUN_RE = /\s+/g;

/** An absent key and an explicit `null` are the same condition. */
function tokenOf(tokens: StampTokens, field: string): string | null {
  const value = tokens[field];
  return value === undefined ? null : value;
}

/**
 * Compare two token maps and report every field that drifted.
 *
 * The compared field set is the union of both maps' keys, sorted by code
 * unit so the result is byte-identical across runs, engines, and locales
 * regardless of the order the caller built either map in.
 *
 * This is the ungated form: it always compares and always reports.
 */
export function compareStamps(
  expected: StampTokens,
  actual: StampTokens,
): ReadonlyArray<StampMismatch> {
  const fields = [...new Set([...Object.keys(expected), ...Object.keys(actual)])].toSorted();
  const mismatches: StampMismatch[] = [];
  for (const field of fields) {
    const before = tokenOf(expected, field);
    const now = tokenOf(actual, field);
    if (before === now) continue;
    mismatches.push(Object.freeze({ field, expected: before, actual: now }));
  }
  return Object.freeze(mismatches);
}

/**
 * Compare under an operator-chosen gate.
 *
 * Under {@link GATE_MODE.off} no comparison is performed and no evidence
 * is returned, so a gated caller emits nothing at all - see the module
 * docblock. Otherwise the drift is reported and the mode decides whether
 * the verdict is a warning or a refusal; the caller owns what it does
 * with each.
 *
 * A mode outside the closed vocabulary THROWS. The types stop most of
 * them, but a value crossing a `JSON.parse` or an `as` cast does not
 * meet the compiler, and the previous `mode === fail ? fail : warn`
 * shape resolved every such value to the SOFTEST verdict - an
 * unrecognised token silently becoming a warning is indistinguishable
 * from an operator who asked for one.
 */
export function checkStamp(expected: StampTokens, actual: StampTokens, mode: GateMode): StampCheck {
  if (!isGateMode(mode)) {
    throw new Error(
      `unknown gate mode ${JSON.stringify(mode)}; expected one of ${GATE_MODES.join(", ")}`,
    );
  }
  if (mode === GATE_MODE.off) {
    return Object.freeze({
      mode,
      verdict: STAMP_VERDICT.pass,
      mismatches: Object.freeze([]) as ReadonlyArray<StampMismatch>,
    });
  }
  const mismatches = compareStamps(expected, actual);
  const verdict =
    mismatches.length === 0
      ? STAMP_VERDICT.pass
      : mode === GATE_MODE.fail
        ? STAMP_VERDICT.fail
        : STAMP_VERDICT.warn;
  return Object.freeze({ mode, verdict, mismatches });
}

/**
 * Render one mismatch as a single English line:
 *
 *   `<field>: expected "<recorded>", actual <unrecorded>`
 *
 * Values are quoted so an empty recorded value is visible, and an
 * unrecorded side is named explicitly rather than rendered as a gap.
 * Shared by every consuming unit so three gates cannot grow three
 * spellings of the same refusal.
 */
export function formatStampMismatch(mismatch: StampMismatch): string {
  const field = collapse(mismatch.field);
  return `${field}: expected ${renderToken(mismatch.expected)}, actual ${renderToken(mismatch.actual)}`;
}

function renderToken(value: string | null): string {
  return value === null ? UNRECORDED_MARKER : JSON.stringify(collapse(value));
}

function collapse(value: string): string {
  return value.replace(WHITESPACE_RUN_RE, " ").trim();
}