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
/**
 * The capacity gate decision (`evaluateCapacityGate`).
 *
 * Claims pinned here:
 *
 *   1. The decision is computed from a FRESH `measureStorageUsage` call
 *      at decision time, never from the stored aggregate: mutating the
 *      vault between `sampleStorageUsage` and the decision changes the
 *      answer, in both directions.
 *   2. An unbounded store never skips and never measures; an
 *      unmeasurable store never skips and names the refused surfaces.
 *   3. Only the critical tier skips; warn and ok run, with the tier and
 *      reading attached either way.
 *   4. The gate reads its bounds through the resolved `storage:` config,
 *      so an operator cap is the only thing that can close it.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { appendFileSync, chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { brainConfigPath } from "../../../src/core/brain/paths.ts";
import {
  STORAGE_FORECAST_TIER,
  sampleStorageUsage,
} from "../../../src/core/brain/storage/forecast.ts";
import { evaluateCapacityGate } from "../../../src/core/brain/storage/gate.ts";
import { measureStorageUsage } from "../../../src/core/brain/storage/usage.ts";
import { resolveStorage } from "../../../src/core/brain/policy.ts";
import { loadBrainConfig } from "../../../src/core/brain/policy.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-storage-gate-"));
  bootstrapBrain(vault, {});
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

/** Append a storage block to the bootstrapped config. */
function configureCap(capBytes: number): void {
  appendFileSync(brainConfigPath(vault), `\nstorage:\n  cap_bytes: ${capBytes}\n`);
}

function resolvedCap(): number | null {
  return resolveStorage(loadBrainConfig(vault)).cap_bytes;
}

function writePages(name: string, totalBytes: number): void {
  mkdirSync(join(vault, "Brain", "sources"), { recursive: true });
  writeFileSync(join(vault, "Brain", "sources", name), "x".repeat(totalBytes), "utf8");
}

describe("evaluateCapacityGate", () => {
  test("an unbounded store runs without measuring", () => {
    const decision = evaluateCapacityGate(vault, { capBytes: resolvedCap() });
    expect(decision.decision).toBe("run");
    expect(decision.tier).toBe(STORAGE_FORECAST_TIER.unbounded);
    // No cap, no reading: the measurement was never taken.
    expect(decision.reading).toBeUndefined();
  });

  test("a bounded store far below the cap runs with its reading attached", () => {
    configureCap(10_000_000);
    writePages("AA-small.md", 100);
    const decision = evaluateCapacityGate(vault, { capBytes: resolvedCap() });
    expect(decision.decision).toBe("run");
    expect(decision.tier).toBe(STORAGE_FORECAST_TIER.ok);
    expect(decision.reading).toBeDefined();
    expect(decision.reading!.measuredBytes).toBe(measureStorageUsage(vault).totalBytes);
    expect(decision.reading!.percentUsed).toBeLessThan(1);
  });

  test("a store past the critical percent skips", () => {
    configureCap(1000);
    writePages("AA-big.md", 5000);
    const decision = evaluateCapacityGate(vault, { capBytes: resolvedCap() });
    expect(decision.decision).toBe("skip");
    expect(decision.tier).toBe(STORAGE_FORECAST_TIER.critical);
    expect(decision.reading!.percentUsed).toBeGreaterThan(95);
  });

  test("only the critical tier skips; the warn band runs", () => {
    // The bootstrapped skeleton lands inside the warn band of a 30 KB
    // cap: past 80 percent, short of 95.
    configureCap(30_000);
    const decision = evaluateCapacityGate(vault, { capBytes: resolvedCap() });
    expect(decision.tier).toBe(STORAGE_FORECAST_TIER.warn);
    expect(decision.decision).toBe("run");
  });

  test("the decision re-measures: the stored aggregate never decides", () => {
    // The bootstrapped skeleton sits near 30 KB, so 100 KB keeps the
    // base vault below every band while a grown page blows past it.
    const CAP = 100_000;
    configureCap(CAP);
    // Sample the small vault, then push it past the cap: the decision
    // must reflect the fresh bytes, not the sampled aggregate.
    sampleStorageUsage(vault, { runId: "before" });
    writePages("AA-grown.md", 150_000);
    const after = evaluateCapacityGate(vault, { capBytes: resolvedCap() });
    expect(after.decision).toBe("skip");
    expect(after.tier).toBe(STORAGE_FORECAST_TIER.critical);

    // And the other direction: a sampled-heavy vault that has been
    // emptied runs again.
    const heavy = mkdtempSync(join(tmpdir(), "o2b-storage-gate-heavy-"));
    try {
      bootstrapBrain(heavy, {});
      appendFileSync(brainConfigPath(heavy), `\nstorage:\n  cap_bytes: ${CAP}\n`);
      mkdirSync(join(heavy, "Brain", "sources"), { recursive: true });
      writeFileSync(join(heavy, "Brain", "sources", "AA-big.md"), "x".repeat(150_000), "utf8");
      sampleStorageUsage(heavy, { runId: "heavy" });
      rmSync(join(heavy, "Brain", "sources", "AA-big.md"));
      const emptied = evaluateCapacityGate(heavy, { capBytes: CAP });
      expect(emptied.decision).toBe("run");
    } finally {
      rmSync(heavy, { recursive: true, force: true });
    }
  });

  test.skipIf(CHMOD_CANNOT_DENY)(
    "an unmeasurable store never skips and names the refused surface",
    () => {
      configureCap(1000);
      mkdirSync(join(vault, "Brain", ".artifacts"), { recursive: true });
      chmodSync(join(vault, "Brain", ".artifacts"), 0o000);
      try {
        const decision = evaluateCapacityGate(vault, { capBytes: resolvedCap() });
        expect(decision.decision).toBe("run");
        expect(decision.tier).toBe(STORAGE_FORECAST_TIER.unmeasurable);
        expect(decision.reason).toContain("artifacts");
        // A refusal carries no percent: there is no number to attach.
        expect(decision.reading).toBeUndefined();
      } finally {
        chmodSync(join(vault, "Brain", ".artifacts"), 0o755);
      }
    },
  );

  test("threshold overrides move the skip line", () => {
    configureCap(1_000_000);
    writePages("AA-small.md", 100);
    const run = evaluateCapacityGate(vault, { capBytes: resolvedCap() });
    expect(run.decision).toBe("run");
    const skipped = evaluateCapacityGate(vault, {
      capBytes: resolvedCap(),
      criticalPercent: 1,
    });
    expect(skipped.decision).toBe("skip");
    expect(skipped.tier).toBe(STORAGE_FORECAST_TIER.critical);
  });

  test("a pausePercent passed in closes the gate one band before the refuse line", () => {
    // The bootstrapped skeleton sits in the warn band of a 30 KB cap.
    // Without a pause line the gate RUNS there (the interactive wall's
    // posture, pinned above); the lane hands its pause_percent in, and
    // the same reading then skips - background work backs off before
    // the wall, interactive ingest still works.
    configureCap(30_000);
    const decision = evaluateCapacityGate(vault, {
      capBytes: resolvedCap(),
      pausePercent: 80,
    });
    expect(decision.tier).toBe(STORAGE_FORECAST_TIER.warn);
    expect(decision.decision).toBe("skip");
    // The line rides the decision, so a report can show how far the
    // vault was from the pause.
    expect(decision.pausePercent).toBe(80);
  });

  test("a pausePercent below the tier line pauses an ok vault", () => {
    configureCap(1_000_000);
    writePages("AA-small.md", 100);
    const decision = evaluateCapacityGate(vault, {
      capBytes: resolvedCap(),
      pausePercent: 1,
    });
    expect(decision.tier).toBe(STORAGE_FORECAST_TIER.ok);
    expect(decision.decision).toBe("skip");
  });

  test("a pausePercent above the measured percent leaves the gate open", () => {
    configureCap(10_000_000);
    const decision = evaluateCapacityGate(vault, {
      capBytes: resolvedCap(),
      pausePercent: 50,
    });
    expect(decision.decision).toBe("run");
    expect(decision.pausePercent).toBe(50);
  });
});