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
10.6 KB
Raw Blame
/**
 * The `storage:` block - the operator-configured capacity policy the
 * storage lifecycle reads: the byte cap, the two percent thresholds and
 * the two day horizons.
 *
 * One reason to change: what an operator may bound about their vault's
 * storage. Absent `cap_bytes` is the DEFAULT and means unbounded: no cap
 * by default means nothing pauses and nothing refuses, exactly as an
 * unconfigured maintenance window leaves the lane always open. A cap
 * only ever comes from an explicit operator decision recorded in this
 * file - the one file no tool call can rewrite.
 *
 * Out-of-range values are hard errors, following the policy stated in
 * `../field-checks.ts`: a knob that silently clamped would be
 * indistinguishable from the operator never having set it, and for a
 * gate that refuses writes the operator would believe a bound is in
 * force that is not - or believe it is not, while it is.
 *
 * The four thresholds default to the forecast's module constants
 * (`../../storage/forecast.ts`), imported rather than restated, so the
 * resolver and the forecast cannot disagree about what a default is.
 */

import type { BrainConfig, BrainStorageConfig, ResolvedBrainStorageConfig } from "../../types.ts";
import {
  STORAGE_CRITICAL_DAYS_DEFAULT,
  STORAGE_CRITICAL_PERCENT_DEFAULT,
  STORAGE_WARN_DAYS_DEFAULT,
  STORAGE_WARN_PERCENT_DEFAULT,
} from "../../storage/forecast.ts";
import { readBoundedInt } from "../field-checks.ts";
import { BrainConfigError } from "../errors.ts";
import { openBlock, warnUnknownKeys, type BlockParseContext } from "../key-index.ts";

const BLOCK = "storage";

/**
 * A cap must be a positive whole number of bytes. Zero would put every
 * vault past its cap the moment the block is written - not a cap but a
 * way to refuse everything, and the way to do that is a cap the operator
 * chose on purpose.
 */
export const STORAGE_CAP_BYTES_MIN = 1;

/** Percents are bounded to the open-at-zero, closed-at-100 range. */
export const STORAGE_PERCENT_MIN = 1;
export const STORAGE_PERCENT_MAX = 100;

/** Day horizons are positive whole days. */
export const STORAGE_DAYS_MIN = 1;

const KNOWN_KEYS = [
  "cap_bytes",
  "warn_percent",
  "critical_percent",
  "pause_percent",
  "warn_days",
  "critical_days",
] as const;

/**
 * Defaults for an absent block. `cap_bytes` is `null` rather than a
 * number: the capacity gate has no neutral default, because any number
 * would start refusing writes on vaults whose operator never asked for a
 * gate - the same shape as the unconfigured maintenance pressure gate.
 */
export const BRAIN_STORAGE_DEFAULTS: ResolvedBrainStorageConfig = Object.freeze({
  cap_bytes: null,
  warn_percent: STORAGE_WARN_PERCENT_DEFAULT,
  critical_percent: STORAGE_CRITICAL_PERCENT_DEFAULT,
  pause_percent: STORAGE_WARN_PERCENT_DEFAULT,
  warn_days: STORAGE_WARN_DAYS_DEFAULT,
  critical_days: STORAGE_CRITICAL_DAYS_DEFAULT,
}) as ResolvedBrainStorageConfig;

/**
 * Merge a parsed `storage` block (or `undefined`) with the defaults.
 *
 * An absent `pause_percent` follows the block's warn band - the lane
 * pauses where the forecast warns unless the operator names the pause
 * line themselves.
 */
export function resolveStorage(cfg: BrainConfig): ResolvedBrainStorageConfig {
  const s = cfg.storage;
  if (s === undefined) return BRAIN_STORAGE_DEFAULTS;
  const warnPercent = s.warn_percent ?? BRAIN_STORAGE_DEFAULTS.warn_percent;
  return {
    cap_bytes: s.cap_bytes ?? BRAIN_STORAGE_DEFAULTS.cap_bytes,
    warn_percent: warnPercent,
    critical_percent: s.critical_percent ?? BRAIN_STORAGE_DEFAULTS.critical_percent,
    pause_percent: s.pause_percent ?? warnPercent,
    warn_days: s.warn_days ?? BRAIN_STORAGE_DEFAULTS.warn_days,
    critical_days: s.critical_days ?? BRAIN_STORAGE_DEFAULTS.critical_days,
  };
}

/**
 * Shape:
 *   storage:
 *     cap_bytes: 1073741824   # positive integer bytes; absent = unbounded
 *     warn_percent: 80        # integer in [1, 100]; must be < critical_percent
 *     critical_percent: 95    # integer in [1, 100]; must be > warn_percent
 *     pause_percent: 80       # integer in [1, 100]; must be < critical_percent
 *                             # and defaults to the warn band
 *     warn_days: 30           # positive integer; must be > critical_days
 *     critical_days: 7        # positive integer; must be < warn_days
 */
export function parseStorageBlock(ctx: BlockParseContext): BrainStorageConfig | undefined {
  const map = openBlock(ctx, BLOCK);
  if (map === undefined) return undefined;

  const capBytes = readCapBytes(map, ctx);
  const warnPercent = readBoundedInt(
    map,
    "warn_percent",
    STORAGE_PERCENT_MIN,
    STORAGE_PERCENT_MAX,
    "storage.warn_percent",
    ctx.source,
  );
  const criticalPercent = readBoundedInt(
    map,
    "critical_percent",
    STORAGE_PERCENT_MIN,
    STORAGE_PERCENT_MAX,
    "storage.critical_percent",
    ctx.source,
  );
  const pausePercent = readBoundedInt(
    map,
    "pause_percent",
    STORAGE_PERCENT_MIN,
    STORAGE_PERCENT_MAX,
    "storage.pause_percent",
    ctx.source,
  );
  assertCriticalAboveWarn(warnPercent, criticalPercent, ctx);
  assertPauseBelowCritical(pausePercent, criticalPercent, ctx);
  const warnDays = readBoundedInt(
    map,
    "warn_days",
    STORAGE_DAYS_MIN,
    Number.MAX_SAFE_INTEGER,
    "storage.warn_days",
    ctx.source,
  );
  const criticalDays = readBoundedInt(
    map,
    "critical_days",
    STORAGE_DAYS_MIN,
    Number.MAX_SAFE_INTEGER,
    "storage.critical_days",
    ctx.source,
  );
  assertCriticalNearerThanWarn(warnDays, criticalDays, ctx);

  warnUnknownKeys(ctx, map, KNOWN_KEYS, BLOCK);
  return {
    ...(capBytes !== undefined ? { cap_bytes: capBytes } : {}),
    ...(warnPercent !== undefined ? { warn_percent: warnPercent } : {}),
    ...(criticalPercent !== undefined ? { critical_percent: criticalPercent } : {}),
    ...(pausePercent !== undefined ? { pause_percent: pausePercent } : {}),
    ...(warnDays !== undefined ? { warn_days: warnDays } : {}),
    ...(criticalDays !== undefined ? { critical_days: criticalDays } : {}),
  };
}

/**
 * Read `cap_bytes`, also accepting an explicit `null` as "no cap" - the
 * template shows the key commented out, and an operator who uncomments
 * it with `null` is spelling the default intent, not a typo.
 */
function readCapBytes(
  map: Readonly<Record<string, unknown>>,
  ctx: BlockParseContext,
): number | undefined {
  if (!("cap_bytes" in map)) return undefined;
  const v = map["cap_bytes"];
  if (v === null) return undefined;
  if (typeof v !== "number" || !Number.isInteger(v) || v < STORAGE_CAP_BYTES_MIN) {
    throw new BrainConfigError(
      `must be a positive integer number of bytes; got ${JSON.stringify(v)}`,
      "storage.cap_bytes",
      ctx.source,
    );
  }
  return v;
}

/**
 * The critical percent band must begin ABOVE the warn band. Compared at
 * parse time, pair-wise over whichever of the two are present, each
 * against the default the other would resolve to - so `warn_percent: 95`
 * alone errors exactly as `critical_percent: 95` spelled beside an
 * 80-percent warn would. The error names the key(s) actually at fault:
 * the lone set key whose value broke the pair against the other's
 * default, or the pair when both were spelled and either could yield.
 */
function assertCriticalAboveWarn(
  warnPercent: number | undefined,
  criticalPercent: number | undefined,
  ctx: BlockParseContext,
): void {
  const warn = warnPercent ?? BRAIN_STORAGE_DEFAULTS.warn_percent;
  const critical = criticalPercent ?? BRAIN_STORAGE_DEFAULTS.critical_percent;
  if (criticalPercent !== undefined || warnPercent !== undefined) {
    if (critical <= warn) {
      const [field, message] =
        warnPercent !== undefined && criticalPercent !== undefined
          ? [
              "storage.warn_percent, storage.critical_percent",
              `the critical band must begin above the warn band: critical_percent (${critical}) must be greater than warn_percent (${warn})`,
            ]
          : warnPercent !== undefined
            ? [
                "storage.warn_percent",
                `must be smaller than critical_percent (${critical}); got ${warn}`,
              ]
            : [
                "storage.critical_percent",
                `must be greater than warn_percent (${warn}); got ${critical}`,
              ];
      throw new BrainConfigError(message, field, ctx.source);
    }
  }
}

/**
 * The pause line must sit strictly BELOW the critical band, whether
 * critical is spelled in the block or at its default: a pause at or past
 * the refuse line could never pause anything - the ingest wall fires
 * first at critical - so the knob would sit configured and dead. Only an
 * explicitly set `pause_percent` is checked: an absent one defaults to
 * the warn band, and warn-below-critical is already the existing pair
 * check's contract, so a default-inferred pause can never violate this
 * without that check firing first.
 */
function assertPauseBelowCritical(
  pausePercent: number | undefined,
  criticalPercent: number | undefined,
  ctx: BlockParseContext,
): void {
  if (pausePercent === undefined) return;
  const critical = criticalPercent ?? BRAIN_STORAGE_DEFAULTS.critical_percent;
  if (pausePercent < critical) return;
  throw new BrainConfigError(
    `must be smaller than critical_percent (${critical}); the pause line governs background ` +
      `work and interactive ingest is already refused at the critical band - got ${pausePercent}`,
    "storage.pause_percent",
    ctx.source,
  );
}

/**
 * The critical day horizon must be NEARER than the warn horizon, same
 * rule, and the error names the key(s) actually at fault the same way.
 */
function assertCriticalNearerThanWarn(
  warnDays: number | undefined,
  criticalDays: number | undefined,
  ctx: BlockParseContext,
): void {
  const warn = warnDays ?? BRAIN_STORAGE_DEFAULTS.warn_days;
  const critical = criticalDays ?? BRAIN_STORAGE_DEFAULTS.critical_days;
  if (criticalDays !== undefined || warnDays !== undefined) {
    if (critical >= warn) {
      const [field, message] =
        warnDays !== undefined && criticalDays !== undefined
          ? [
              "storage.warn_days, storage.critical_days",
              `the critical horizon must be nearer than the warn horizon: critical_days (${critical}) must be smaller than warn_days (${warn})`,
            ]
          : warnDays !== undefined
            ? ["storage.warn_days", `must be greater than critical_days (${critical}); got ${warn}`]
            : [
                "storage.critical_days",
                `must be smaller than warn_days (${warn}); got ${critical}`,
              ];
      throw new BrainConfigError(message, field, ctx.source);
    }
  }
}