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
8.0 KB
Raw Blame
/**
 * A path one of the doctor's own sweeps could not read.
 *
 * The sweeps that walk the store by hand each used to swallow a failed
 * read in a bare `catch` and return. That produces no findings, and no
 * findings is what every surface renders as a clean bill of health - so
 * the operator was told the vault was fine exactly where the doctor had
 * been unable to look. This module is the one place that answer is
 * replaced: the read still fails soft, and the branch is named in the
 * `uncertain` stream instead of vanishing.
 *
 * One distinction is drawn here rather than at each call site, because
 * getting it wrong in either direction is a defect. A path that is
 * ABSENT was never a subtree to sweep - the common case is a vault whose
 * optional directory has not been created, and it stays as quiet as it
 * always was. Every other failure - a permission denial, a file standing
 * where a directory was expected, an I/O error - is a subtree that
 * exists and was not read, which is precisely what uncertainty means.
 *
 * That reading of `ENOENT` holds only where absence was POSSIBLE, which
 * is why every read here declares where its path came from. At a sweep's
 * own root, absence is the ordinary case. A path the walk DISCOVERED
 * existed a moment earlier, when its parent listed it, so an `ENOENT` on
 * it is a race - something removed the entry under the walk - and a
 * subtree that was skipped like any other.
 *
 * The code is `vault-walk-entry-skipped` from the closed
 * {@link DEGRADATION_CODE} vocabulary, which already names this exact
 * condition for the shared vault walker. It is SPELLED here rather than
 * referenced through the constant so the doctor's exit census can read
 * the doctor's own code population out of its source; the two cannot
 * drift, because {@link degradationNotice} takes the closed union and a
 * spelling the vocabulary does not hold fails the build.
 */

import { readdirSync, readFileSync, type Dirent } from "node:fs";

import { degradationNotice, type DegradationNotice } from "../../integrity/degradation.ts";
import type { DoctorIssue } from "../types.ts";
import type { DoctorUncertainEntry } from "./report.ts";
import { pushUncertain } from "./uncertain-stream.ts";

/** See the module docblock: spelled, and pinned to the vocabulary by its type. */
const VAULT_WALK_ENTRY_SKIPPED_CODE = "vault-walk-entry-skipped";

/**
 * What a sweep reports under, and what it consequently cannot claim.
 *
 * `consequence` is written by the sweep because only the sweep knows
 * which question went unanswered: the operator reads it directly under
 * `[UNSURE]`, and "a directory could not be read" on its own does not
 * say what was therefore left unverified.
 */
export interface SweptPath {
  /** Subsystem name recorded on the notice, e.g. `brain.doctor.symlinkEscape`. */
  readonly site: string;
  /** What this sweep can no longer claim, as one clause. */
  readonly consequence: string;
  /** The doctor's uncertainty stream for the running pass. */
  readonly uncertain: DoctorUncertainEntry[];
}

/**
 * Where the path a read failed on came from, which is what decides
 * whether `ENOENT` means "nothing was ever here" or "it went away under
 * the walk". See the module docblock.
 */
export const SWEEP_ORIGIN = Object.freeze({
  root: "root",
  discovered: "discovered",
} as const);

export type SweepOrigin = (typeof SWEEP_ORIGIN)[keyof typeof SWEEP_ORIGIN];

/** `errno` values meaning nothing is there - not a failure to verify. */
const ABSENT_ERRNO: ReadonlySet<string> = new Set(["ENOENT"]);

/**
 * List `dir`, or report why it could not be listed and return `null`.
 * The caller's control flow is unchanged: `null` means "skip this
 * subtree", exactly as the bare `catch { return; }` it replaces did.
 */
export function readSweptDir(dir: string, swept: SweptPath, origin: SweepOrigin): Dirent[] | null {
  try {
    return readdirSync(dir, { withFileTypes: true });
  } catch (err) {
    return reportSweptFailure(dir, "directory listing failed", err, swept, origin);
  }
}

/** Read `path` as UTF-8, or report why it could not be read. */
export function readSweptFile(path: string, swept: SweptPath, origin: SweepOrigin): string | null {
  try {
    return readFileSync(path, "utf8");
  } catch (err) {
    return reportSweptFailure(path, "file read failed", err, swept, origin);
  }
}

/**
 * Report a read this module did not itself perform - a listing behind a
 * shared helper, a discovery pass that throws its own error - under the
 * same code and the same absent/failed split. `action` names what was
 * attempted; the errno text and the sweep's consequence are appended.
 *
 * Always returns `null` so a caller can `return reportSweptFailure(...)`
 * from the branch that skips the subtree.
 */
export function reportSweptFailure(
  path: string,
  action: string,
  err: unknown,
  swept: SweptPath,
  origin: SweepOrigin,
): null {
  if (origin === SWEEP_ORIGIN.root && isAbsent(err)) return null;
  reportSweptSkip(path, `${action}: ${describe(err)}`, swept);
  return null;
}

/**
 * Report a path the sweep declined to read for a reason that is not an
 * error - an entry that is neither a regular file nor a directory, so
 * neither branch of the walk consumes it. Skipping it silently is the
 * same false clean bill of health as swallowing a failed read.
 *
 * Returns the composed sentence, for the one caller that must carry the
 * same statement on a warning as well; the walks ignore it.
 */
export function reportSweptSkip(path: string, detail: string, swept: SweptPath): string {
  const notice = degradationNotice({
    code: VAULT_WALK_ENTRY_SKIPPED_CODE,
    site: swept.site,
    path,
    detail,
  });
  return pushUncertain(
    swept.uncertain,
    {
      code: notice.code,
      ...(notice.path !== undefined ? { path: notice.path } : {}),
      message: notice.detail,
    },
    swept.consequence,
  );
}

/**
 * The same condition as a reportable issue, for a path whose failure
 * stops a whole pass rather than one subtree. Built here so the code is
 * written down once, beside the vocabulary member it is pinned to.
 */
export function sweptPathWarning(path: string, message: string): DoctorIssue {
  return { severity: "warning", code: VAULT_WALK_ENTRY_SKIPPED_CODE, path, message };
}

/**
 * Fold notices a shared walker collected into the same stream, under the
 * same consequence. Used where the sweep does not perform the read
 * itself and the walker reports through the degradation channel.
 */
export function forwardSweepNotices(
  notices: ReadonlyArray<DegradationNotice>,
  swept: SweptPath,
): void {
  for (const notice of notices) {
    pushUncertain(
      swept.uncertain,
      {
        code: notice.code,
        ...(notice.path !== undefined ? { path: notice.path } : {}),
        message: notice.detail,
      },
      swept.consequence,
    );
  }
}

/**
 * Why a path could not be reached, or `null` when the failure means it
 * is not there at all.
 *
 * The same split {@link readSweptDir} applies, exposed for the one
 * caller that must act on the answer rather than report it: the pass
 * entry point, which reports an ABSENT Brain layer as an un-initialized
 * vault and must never say that about one it merely could not read.
 */
export function sweptFailureReason(err: unknown): string | null {
  return isAbsent(err) ? null : describe(err);
}

/**
 * The path an `errno` failure names, or `fallback` when it names none.
 * A shared builder reports the exact directory it stumbled on inside the
 * error, and that is a better answer than the root the caller handed it.
 */
export function sweptFailurePath(err: unknown, fallback: string): string {
  if (typeof err !== "object" || err === null) return fallback;
  const path = (err as { path?: unknown }).path;
  return typeof path === "string" && path.length > 0 ? path : fallback;
}

function isAbsent(err: unknown): boolean {
  if (typeof err !== "object" || err === null) return false;
  const code = (err as { code?: unknown }).code;
  return typeof code === "string" && ABSENT_ERRNO.has(code);
}

function describe(err: unknown): string {
  return err instanceof Error ? err.message : String(err);
}