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
18.7 KB
Raw Blame
/**
 * Decider envelope and commit validators (recall-quality wave, lane A
 * Task 4): the needs-llm-step envelope builds only when measurable
 * coverage gaps remain, the commit phase refuses malformed shapes,
 * over-limit or oversized sub-queries, unknown evidence ids and
 * replayed round tokens with named typed errors, and an accepted
 * payload drives exactly one further round whose pool grows only by
 * the payload's sub-query pulls.
 */

import { test, expect, beforeEach, afterEach, describe } from "bun:test";

import {
  DECIDER_SUB_QUERIES_MAX,
  DECIDER_SUB_QUERY_LENGTH_MAX,
  DECIDER_STEP_NAME,
  DECIDER_STEP_RESUME_TARGET,
  DeciderStepError,
  buildDeciderStep,
  commitDeciderStep,
  makeRoundToken,
  nonceRoundToken,
  pauseStateDigest,
} from "../../../src/core/search/decider-step.ts";
import type { CoverageReport } from "../../../src/core/search/coverage.ts";
import { NEEDS_LLM_STEP } from "../../../src/core/brain/llm-step.ts";
import { ResponseShapeError } from "../../../src/core/brain/response-shape.ts";
import {
  ResponseCheckError,
  SEMANTIC_VIOLATION_CODES,
} from "../../../src/core/brain/response-checks.ts";
import { Store } from "../../../src/core/search/store.ts";
import { runFtsQueryDetailed } from "../../../src/core/search/fts.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
import {
  runDeciderRound,
  runIterativeRecall,
} from "../../../src/core/search/pipeline/iterative-recall.ts";

/** A measurable, partial coverage with named gaps: the envelope's home case. */
function gappedCoverage(): CoverageReport {
  const term = (t: string, covered: boolean, rare = true) => ({
    term: t,
    df: rare ? 1 : 40,
    idf: rare ? 3.2 : 0.1,
    rare,
    covered,
  });
  return Object.freeze({
    terms: Object.freeze([term("warehouse", true, false), term("chandelier", false)]),
    idfWeightedCoverage: 0.5,
    rareTerms: Object.freeze(["chandelier"]),
    uncoveredRareTerms: Object.freeze(["chandelier"]),
  });
}

/** A complete pool: the envelope must refuse it by name. */
function completeCoverage(): CoverageReport {
  const term = (t: string, covered: boolean, rare = false) => ({
    term: t,
    df: 40,
    idf: 0.1,
    rare,
    covered,
  });
  return Object.freeze({
    terms: Object.freeze([term("warehouse", true), term("rotation", true)]),
    idfWeightedCoverage: 0.95,
    rareTerms: Object.freeze([]),
    uncoveredRareTerms: Object.freeze([]),
  });
}

describe("buildDeciderStep", () => {
  test("builds the needs-llm-step envelope over measurable gaps", () => {
    const poolIds = [3, 7, 11];
    const pause = buildDeciderStep({
      query: "warehouse rotation chandelier",
      round: 3,
      coverage: gappedCoverage(),
      poolIds,
    });
    expect(pause.round).toBe(3);
    expect(pause.llmStep.status).toBe(NEEDS_LLM_STEP);
    expect(pause.llmStep.step).toBe(DECIDER_STEP_NAME);
    expect(pause.llmStep.target_path).toBe(DECIDER_STEP_RESUME_TARGET);
    // The envelope names the gaps and the candidate ids, so the answering
    // agent can select evidence and aim sub-queries without another call.
    expect(pause.llmStep.prompt).toContain("chandelier");
    expect(pause.llmStep.prompt).toContain("3,7,11");
    expect(pause.llmStep.schema_hints.length).toBeGreaterThan(0);
    // The token is opaque and round-stamped.
    expect(pause.token).toBe(makeRoundToken("warehouse rotation chandelier", 3, poolIds));
    expect(pause.token.startsWith("drt-3-")).toBe(true);
  });

  test("refuses a complete pool, an unmeasurable pool and an empty pool by name", () => {
    for (const coverage of [
      completeCoverage(),
      { ...gappedCoverage(), idfWeightedCoverage: null },
    ]) {
      expect(() => buildDeciderStep({ query: "q", round: 2, coverage, poolIds: [1] })).toThrow(
        DeciderStepError,
      );
      try {
        buildDeciderStep({ query: "q", round: 2, coverage, poolIds: [1] });
      } catch (error) {
        expect((error as DeciderStepError).code).toBe("no_gaps");
      }
    }
    expect(() =>
      buildDeciderStep({ query: "q", round: 2, coverage: gappedCoverage(), poolIds: [] }),
    ).toThrow(DeciderStepError);
  });

  test("mints through the registry hook and falls back to the deterministic token", () => {
    const poolIds = [3, 7, 11];
    const mints: Array<{ round: number; pauseDigest: string }> = [];
    const nonceToken = nonceRoundToken(3, "5f1e2d3c4b5a69788796a5b4");
    const pause = buildDeciderStep({
      query: "warehouse rotation chandelier",
      round: 3,
      coverage: gappedCoverage(),
      poolIds,
      mintRoundToken: ({ round, pauseDigest }) => {
        mints.push({ round, pauseDigest });
        return nonceToken;
      },
    });
    // The pause hands out the registry-backed nonce token, and the hook
    // saw the exact pause digest a commit recomputes over this state.
    expect(pause.token).toBe(nonceToken);
    expect(mints).toEqual([
      { round: 3, pauseDigest: pauseStateDigest("warehouse rotation chandelier", 3, poolIds) },
    ]);
    // A mint that could not land (null) falls back to the deterministic
    // digest token, keeping the loop alive without a registry row.
    const fallback = buildDeciderStep({
      query: "warehouse rotation chandelier",
      round: 3,
      coverage: gappedCoverage(),
      poolIds,
      mintRoundToken: () => null,
    });
    expect(fallback.token).toBe(makeRoundToken("warehouse rotation chandelier", 3, poolIds));
    // No hook at all (a commit leg's replay) stays deterministic too.
    const replay = buildDeciderStep({
      query: "warehouse rotation chandelier",
      round: 3,
      coverage: gappedCoverage(),
      poolIds,
    });
    expect(replay.token).toBe(makeRoundToken("warehouse rotation chandelier", 3, poolIds));
  });
});

describe("commitDeciderStep", () => {
  const poolIds = [3, 7, 11];
  const scope = (usedTokens: ReadonlySet<string> = new Set()) => ({
    query: "warehouse rotation chandelier",
    round: 3,
    poolIds,
    usedTokens,
  });
  const token = makeRoundToken("warehouse rotation chandelier", 3, poolIds);
  const payload = { evidence: [3, 7], subQueries: ["chandelier handoff"] };

  test("accepts a well-formed payload and returns the validated commit", () => {
    const commit = commitDeciderStep(token, payload, scope());
    expect(commit.evidenceIds).toEqual([3, 7]);
    expect(commit.subQueries).toEqual(["chandelier handoff"]);
    expect(commit.token).toBe(token);
  });

  test("refuses malformed shapes with the shape error", () => {
    for (const bad of [
      null,
      "nope",
      { evidence: [3] },
      { subQueries: ["q"] },
      { evidence: ["3"], subQueries: ["q"] },
      { evidence: [3], subQueries: ["q"], extra: true },
      { evidence: [3], subQueries: ["  "] },
    ]) {
      expect(() => commitDeciderStep(token, bad, scope())).toThrow(ResponseShapeError);
    }
  });

  test("refuses over-limit and oversized sub-queries with named semantic violations", () => {
    const tooMany = {
      evidence: [3],
      subQueries: Array.from({ length: DECIDER_SUB_QUERIES_MAX + 1 }, (_, i) => `q${i}`),
    };
    try {
      commitDeciderStep(token, tooMany, scope());
      throw new Error("expected a refusal");
    } catch (error) {
      expect(error).toBeInstanceOf(ResponseCheckError);
      const violations = (error as ResponseCheckError).violations;
      expect(violations.some((v) => v.code === SEMANTIC_VIOLATION_CODES.threshold)).toBe(true);
    }
    const oversized = { evidence: [3], subQueries: ["q".repeat(DECIDER_SUB_QUERY_LENGTH_MAX + 1)] };
    expect(() => commitDeciderStep(token, oversized, scope())).toThrow(ResponseCheckError);
    // An empty evidence list or an empty sub-query list breaks the
    // payload's cardinality, not just its shape.
    for (const empty of [
      { evidence: [], subQueries: ["q"] },
      { evidence: [3], subQueries: [] },
    ]) {
      expect(() => commitDeciderStep(token, empty, scope())).toThrow(ResponseCheckError);
    }
    // A sub-query whose words are all punctuation carries no
    // significant terms and can never drive a retrieval pull: the
    // validators refuse it before the round spends anything on it.
    const punctuationOnly = { evidence: [3], subQueries: ["---"] };
    try {
      commitDeciderStep(token, punctuationOnly, scope());
      throw new Error("expected a refusal");
    } catch (error) {
      expect(error).toBeInstanceOf(ResponseCheckError);
      const violations = (error as ResponseCheckError).violations;
      expect(violations.some((v) => v.code === SEMANTIC_VIOLATION_CODES.threshold)).toBe(true);
    }
    // Duplicate sub-queries are a cross-item refusal.
    const duplicate = { evidence: [3], subQueries: ["chandelier", "chandelier"] };
    try {
      commitDeciderStep(token, duplicate, scope());
      throw new Error("expected a refusal");
    } catch (error) {
      expect(error).toBeInstanceOf(ResponseCheckError);
      const violations = (error as ResponseCheckError).violations;
      expect(violations.some((v) => v.code === SEMANTIC_VIOLATION_CODES.crossItem)).toBe(true);
    }
  });

  test("refuses unknown evidence ids by name", () => {
    try {
      commitDeciderStep(token, { evidence: [3, 999999], subQueries: ["q"] }, scope());
      throw new Error("expected a refusal");
    } catch (error) {
      expect(error).toBeInstanceOf(DeciderStepError);
      expect((error as DeciderStepError).code).toBe("unknown_evidence");
      expect((error as DeciderStepError).message).toContain("999999");
    }
  });

  test("refuses duplicate evidence ids and selections longer than the pool", () => {
    // A selection naming one chunk twice pins nothing extra: a cross-item
    // refusal, mirroring the duplicate sub-query rule.
    const duplicate = { evidence: [3, 7, 3], subQueries: ["q"] };
    try {
      commitDeciderStep(token, duplicate, scope());
      throw new Error("expected a refusal");
    } catch (error) {
      expect(error).toBeInstanceOf(ResponseCheckError);
      const violations = (error as ResponseCheckError).violations;
      expect(violations.some((v) => v.code === SEMANTIC_VIOLATION_CODES.crossItem)).toBe(true);
      expect(
        violations.some((v) => v.path === "$.evidence[2]" && v.message.includes("index 0")),
      ).toBe(true);
    }
    // The evidence budget is the pool itself: the scope's pool holds
    // three candidates, so a four-id selection is refused by name before
    // membership is even checked (the ids are distinct so the registered
    // duplicate rule lets the payload through to the context rule).
    const overPool = { evidence: [1, 2, 5, 8], subQueries: ["q"] };
    try {
      commitDeciderStep(token, overPool, scope());
      throw new Error("expected a refusal");
    } catch (error) {
      expect(error).toBeInstanceOf(DeciderStepError);
      expect((error as DeciderStepError).code).toBe("evidence_over_pool");
      expect((error as DeciderStepError).message).toContain("4 id(s)");
    }
  });

  test("refuses a token minted for another state and an already-used token", () => {
    const other = makeRoundToken("warehouse rotation chandelier", 4, poolIds);
    try {
      commitDeciderStep(other, payload, scope());
      throw new Error("expected a refusal");
    } catch (error) {
      expect((error as DeciderStepError).code).toBe("token_mismatch");
    }
    try {
      commitDeciderStep(token, payload, scope(new Set([token])));
      throw new Error("expected a refusal");
    } catch (error) {
      expect((error as DeciderStepError).code).toBe("token_used");
    }
  });

  test("accepts a registry-minted nonce token whose stored digest matches this state", () => {
    // The plan phase minted a nonce token for this exact state: the
    // commit validates the replayed state against the stored digest
    // instead of re-deriving a token.
    const nonceToken = nonceRoundToken(3, "aa1e2d3c4b5a69788796a5b4");
    const stateDigest = pauseStateDigest("warehouse rotation chandelier", 3, poolIds);
    const commit = commitDeciderStep(nonceToken, payload, {
      ...scope(),
      mintedPauseDigest: stateDigest,
    });
    expect(commit.token).toBe(nonceToken);
    expect(commit.evidenceIds).toEqual([3, 7]);
  });

  test("refuses a nonce token whose stored digest names another round or pool", () => {
    const nonceToken = nonceRoundToken(3, "bb1e2d3c4b5a69788796a5b4");
    // The row was minted for a replay that landed elsewhere: genuine
    // divergence, refused by name.
    try {
      commitDeciderStep(nonceToken, payload, {
        ...scope(),
        mintedPauseDigest: pauseStateDigest("warehouse rotation chandelier", 4, poolIds),
      });
      throw new Error("expected a refusal");
    } catch (error) {
      expect((error as DeciderStepError).code).toBe("token_mismatch");
    }
    // And a nonce token with no registry row behind it at all (expired,
    // swept, or never minted) cannot self-validate.
    try {
      commitDeciderStep(nonceToken, payload, scope());
      throw new Error("expected a refusal");
    } catch (error) {
      expect((error as DeciderStepError).code).toBe("token_mismatch");
    }
  });
});

describe("runDeciderRound (accepted payload drives round N+1)", () => {
  /**
   * Six common-term docs pin the IDF floor; 60 uniquely-termed relic docs
   * are recoverable; 20 ghost terms live only in the query, so their IDF
   * mass keeps the coverage below the completeness threshold no matter
   * how many relics the loop recovers - the pool still has measurable
   * gaps after the deterministic budget is spent, which is what mints a
   * pause.
   */
  let vault: string;
  let dbPath: string;
  let cleanup: () => void;

  beforeEach(() => {
    ({ vault, dbPath, cleanup } = createTempVault("decider-step"));
  });
  afterEach(() => cleanup());

  async function seed(): Promise<void> {
    for (let i = 1; i <= 6; i++) {
      writeMd(
        vault,
        `Brain/notes/wh${i}.md`,
        `# WH${i}\n\nWarehouse rotation schedule, bay ${i}.\n`,
      );
    }
    for (let i = 1; i <= 60; i++) {
      const term = `relic${String(i).padStart(2, "0")}`;
      writeMd(vault, `Brain/notes/${term}.md`, `# ${term}\n\n${term} provenance record.\n`);
    }
    await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));
  }

  const GHOSTS = Array.from({ length: 20 }, (_, i) => `wyrm${String(i + 1).padStart(2, "0")}`);
  const wideQuery = () =>
    `warehouse rotation ${Array.from({ length: 60 }, (_, i) => `relic${String(i + 1).padStart(2, "0")}`).join(" ")} ${GHOSTS.join(" ")}`;

  test("the loop pauses with a token when gaps survive the deterministic budget", async () => {
    await seed();
    const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });
    const store = await Store.open(config, { mode: "read", loadVec: false });
    try {
      const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });
      const loop = runIterativeRecall({
        store,
        query: wideQuery(),
        limit: 10,
        pathPrefix: undefined,
        timeRange: null,
        validityWindowFor: () => null,
        keywordHits: base.hits,
        chunkIds: new Set(base.hits.map((h) => h.chunkId)),
        ids: base.hits.map((h) => h.chunkId),
        maxRounds: 1,
        firstRoundNumber: 2,
        isExpired: () => false,
        nowMs: () => 0,
      });
      // Gaps survive the one deterministic round, so the outcome pauses
      // with an envelope and a token instead of pretending completeness.
      expect(loop.stopReason).toBe("round_cap");
      expect(loop.pause).not.toBeNull();
      expect(loop.pause!.round).toBe(3);
      expect(loop.pause!.llmStep.status).toBe(NEEDS_LLM_STEP);
      expect(loop.pause!.token.startsWith("drt-3-")).toBe(true);
      expect(loop.pause!.poolIds.length).toBe(loop.ids.length);
    } finally {
      await store.close();
    }
  });

  test("an accepted payload drives round N+1; the pool grows only by its pulls", async () => {
    await seed();
    const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });
    const store = await Store.open(config, { mode: "read", loadVec: false });
    try {
      const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });
      const input = {
        store,
        query: wideQuery(),
        limit: 10,
        pathPrefix: undefined,
        timeRange: null,
        validityWindowFor: () => null,
        keywordHits: base.hits,
        chunkIds: new Set(base.hits.map((h) => h.chunkId)),
        ids: base.hits.map((h) => h.chunkId),
        maxRounds: 1,
        firstRoundNumber: 2,
        isExpired: () => false,
        nowMs: () => 0,
      };
      const loop = runIterativeRecall(input);
      const pause = loop.pause;
      expect(pause).not.toBeNull();
      const usedTokens = new Set<string>();
      const before = new Set(loop.ids);
      // A decider payload aimed at one specific relic: the pool may grow
      // by exactly the ids that pull recovers, nothing else.
      const after = runDeciderRound({
        ...input,
        keywordHits: loop.keywordHits,
        chunkIds: new Set(loop.ids),
        pause: pause!,
        token: pause!.token,
        payload: {
          evidence: [pause!.poolIds[0]],
          subQueries: ["relic01 relic02 relic60"],
        },
        usedTokens,
        priorRounds: loop.rounds,
      });
      usedTokens.add(after.token);
      expect(after.round.round).toBe(3);
      expect(after.round.author).toBe("decider");
      expect(after.round.subQueries).toEqual(["relic01 relic02 relic60"]);
      expect(after.stopReason).toBe("decider_round");
      expect(after.token).toBe(pause!.token);
      expect(after.rounds).toHaveLength(loop.rounds.length + 1);
      // The pool grew ONLY by the pull: every new id came from the
      // payload's single sub-query and nothing else was fetched.
      const pulled = runFtsQueryDetailed(store, "relic01", {
        expandedTerms: ["relic02", "relic60"],
        limit: 10,
        pathPrefix: null,
      });
      const expectedNew = new Set(
        pulled.hits.map((h) => h.chunkId).filter((id) => !before.has(id)),
      );
      const gained = after.ids.filter((id) => !before.has(id));
      expect(gained.length).toBe(expectedNew.size);
      for (const id of gained) expect(expectedNew.has(id)).toBe(true);
      expect(after.ids.length).toBe(before.size + expectedNew.size);
      // A replayed commit with the same token is refused: single use.
      expect(() =>
        runDeciderRound({
          ...input,
          keywordHits: loop.keywordHits,
          chunkIds: new Set(loop.ids),
          pause: pause!,
          token: pause!.token,
          payload: { evidence: [pause!.poolIds[0]], subQueries: ["relic01"] },
          usedTokens,
          priorRounds: loop.rounds,
        }),
      ).toThrow(DeciderStepError);
    } finally {
      await store.close();
    }
  });
});