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
9.6 KB
Raw Blame
/**
 * Seam 1 - the typed degradation notice channel.
 *
 * Across the read and delivery path this repository swallows failures in
 * bare `catch { continue }` arms and drops frontmatter lines the scanner
 * does not understand. The information is not merely unlogged: the agent
 * cannot tell a genuine miss from a broken mechanism. This module is the
 * one place those sites report to. It records WHAT degraded (`code`),
 * WHERE (`site`), on which artifact (`path`, when one is known), and the
 * concrete observation (`detail`).
 *
 * The channel carries diagnostics only. It never changes control flow: a
 * fail-soft caller emits a notice and continues exactly as before, so
 * conversion of a swallowing call site is behaviour-preserving and only
 * the trace is new.
 *
 * ## The code vocabulary is CLOSED by design
 *
 * `DegradationCode` is a union over a frozen table, not a free string.
 * The failure mode a typed diagnostic channel invites is becoming a
 * dumping ground - every call site inventing its own token until the
 * vocabulary is unreviewable and no consumer can switch on it. Two
 * properties prevent that here:
 *
 *   1. Adding a code is a deliberate edit of this file, reviewed against
 *      the unit that needs it. A caller cannot mint one in passing.
 *   2. A consumer switching over `DegradationCode` with a `never`-typed
 *      `default` arm gets a COMPILE error for an unhandled member, so a
 *      new code cannot silently fall through an existing renderer.
 *
 * Every member below is therefore annotated with the unit that owns it.
 * The seeded set covers exactly the units whose plan entries declare a
 * dependency on this seam (F, C, D, J). Units whose gate is a stamp
 * comparison rather than a swallowed failure (B, E) report through
 * `stamp.ts` instead and add nothing here.
 *
 * Nothing in this module inspects natural language. `detail` is operator
 * -supplied text passed through verbatim; the formatter templates it and
 * normalizes whitespace, and that is the whole of its processing.
 */

/**
 * Closed vocabulary of degradation conditions. Keys are camelCase for
 * call sites; values are the kebab-case tokens that appear in reports,
 * receipts, and MCP payloads.
 */
export const DEGRADATION_CODE = Object.freeze({
  /**
   * Unit F. The frontmatter scanner reached a line it cannot express as
   * a `key: value` pair (or a block-style list continuation) and dropped
   * it. Today this is structurally silent: the field simply never
   * reaches the parsed map.
   */
  frontmatterLineDropped: "frontmatter-line-dropped",
  /**
   * Unit F. A note's frontmatter could not be obtained at all because
   * the read failed. This is the condition behind the bare
   * `catch { continue }` arms on every frontmatter-reading walker.
   */
  frontmatterUnreadable: "frontmatter-unreadable",
  /**
   * Unit F. A vault walk could not descend into or stat an entry, so a
   * subtree is missing from the result. Distinct from
   * `frontmatterUnreadable`: nothing was parsed, an entire branch was
   * skipped.
   */
  vaultWalkEntrySkipped: "vault-walk-entry-skipped",
  /**
   * Unit C. Session continuation declined to link rather than guessing -
   * no candidate, an ambiguous set, or missing evidence. The abstention
   * is the correct outcome; the notice is what makes it visible instead
   * of indistinguishable from "nothing to link".
   */
  sessionLinkAbstained: "session-link-abstained",
  /**
   * Unit D. A lineage observation was not appended (writer-lock
   * contention or a failed read-modify-write) and is recorded as a named
   * gap rather than vanishing.
   */
  lineageObservationDropped: "lineage-observation-dropped",
  /**
   * Unit D. Ledger verification found a sequence gap or a hash-chain
   * break. Reported, never fatal: the read path stays fail-soft.
   */
  lineageChainBroken: "lineage-chain-broken",
  /**
   * Unit J. The resolved vault root carries no identity marker. An
   * absent marker cannot distinguish an old vault from a wrong root, so
   * this warns rather than refusing.
   */
  vaultMarkerAbsent: "vault-marker-absent",
  /**
   * Unit J. The resolved vault root carries a marker that does not match
   * the expected identity. Unambiguous, and therefore a refusal at the
   * write path rather than a warning.
   */
  vaultMarkerMismatch: "vault-marker-mismatch",
  /**
   * Task C. An operator froze this vault, so the content lane refuses
   * every write until the marker is removed. Unlike the two above this is
   * an INTENDED state rather than a defect: the notice exists so the
   * refusal names when the freeze was set, who set it, why, and the one
   * command that lifts it.
   */
  vaultFrozen: "vault-frozen",
  /**
   * Task E. A shard of the Brain log does not link up: a line's hash does
   * not recompute, its `prev` does not name the line before it, or a line
   * carries no chain fields where the chain had already started. Distinct
   * from {@link DEGRADATION_CODE.lineageChainBroken} because it names a
   * different file with a different chain shape - one shard per device
   * per day rather than one ledger - and an operator holding the finding
   * has to know which of the two to open.
   *
   * Report-only, exactly like its lineage sibling: the log's read path
   * never consults the chain, so a broken shard still yields every event
   * it holds.
   */
  logChainBroken: "log-chain-broken",
} as const);

/**
 * The closed union. A consumer that switches over this type with a
 * `never`-typed `default` arm fails to compile when a member is added
 * without a corresponding arm - which is the point of the closure.
 */
export type DegradationCode = (typeof DEGRADATION_CODE)[keyof typeof DEGRADATION_CODE];

/**
 * One named degradation. `path` is present only when the condition is
 * attributable to a concrete file or directory; the key is OMITTED (not
 * set to `undefined`) when it is not, so a serialized notice from a
 * path-less site carries no empty field.
 */
export interface DegradationNotice {
  /** What degraded, from the closed vocabulary. */
  readonly code: DegradationCode;
  /** Where it was observed - a function, verb, or subsystem name. */
  readonly site: string;
  /** The artifact it happened to, when one is known. */
  readonly path?: string;
  /** The concrete observation, in English, passed through verbatim. */
  readonly detail: string;
}

/** Construction input for {@link degradationNotice}. */
export interface DegradationNoticeInput {
  readonly code: DegradationCode;
  readonly site: string;
  readonly path?: string;
  readonly detail: string;
}

/**
 * A notice was constructed that could not name its own condition. This
 * throws rather than returning a placeholder record: a diagnostic
 * channel that emits blank diagnostics reproduces exactly the silent
 * failure it exists to remove.
 */
export class DegradationNoticeError extends Error {
  /** The offending field (`site`, `detail`, or `path`). */
  readonly field: string;

  constructor(field: string, message: string) {
    super(`degradation notice: ${field}: ${message}`);
    this.name = "DegradationNoticeError";
    this.field = field;
  }
}

/** Runs of any whitespace, including the newlines a single line cannot carry. */
const WHITESPACE_RUN_RE = /\s+/g;

/** Rendered in place of a path only when one is known - see `formatDegradationNotice`. */
const PATH_OPEN = " (";
const PATH_CLOSE = ")";

function requireNonBlank(field: string, value: string): string {
  if (value.trim().length === 0) {
    throw new DegradationNoticeError(field, "must be a non-blank string");
  }
  return value;
}

/**
 * Build one frozen {@link DegradationNotice}, rejecting an input that
 * cannot name its condition. Use this at sites that RETURN a notice;
 * sites that accumulate into a collector should use
 * {@link emitDegradationNotice}.
 */
export function degradationNotice(input: DegradationNoticeInput): DegradationNotice {
  const site = requireNonBlank("site", input.site);
  const detail = requireNonBlank("detail", input.detail);
  // `path` is optional, so absence is legal - but a present-and-blank
  // path is a caller bug that would render as an empty `()` suffix.
  const path = input.path === undefined ? undefined : requireNonBlank("path", input.path);
  return Object.freeze({
    code: input.code,
    site,
    ...(path !== undefined ? { path } : {}),
    detail,
  });
}

/**
 * Build a notice and append it to `sink`, returning the same record.
 * This is the emit form used by the report types that already exist
 * (`IndexStats`, the doctor's `uncertain` list, MCP response fields):
 * the caller keeps one array and never repeats the push.
 *
 * A malformed input throws before anything is appended, so a sink never
 * holds a notice that cannot name its condition.
 */
export function emitDegradationNotice(
  sink: DegradationNotice[],
  input: DegradationNoticeInput,
): DegradationNotice {
  const notice = degradationNotice(input);
  sink.push(notice);
  return notice;
}

/**
 * Render a notice as exactly ONE English line:
 *
 *   `<code> at <site>: <detail>`
 *   `<code> at <site> (<path>): <detail>`
 *
 * Whitespace runs inside `site`, `path`, and `detail` collapse to single
 * spaces so a multi-line error message cannot break the one-line
 * contract that log, receipt, and doctor renderers depend on.
 */
export function formatDegradationNotice(notice: DegradationNotice): string {
  const site = collapse(notice.site);
  const detail = collapse(notice.detail);
  const where =
    notice.path === undefined ? "" : `${PATH_OPEN}${collapse(notice.path)}${PATH_CLOSE}`;
  return `${notice.code} at ${site}${where}: ${detail}`;
}

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