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
28.2 KB
Raw Blame
/**
 * Score-aware tail trim for delivered evidence (t_cb6a5558).
 *
 * The trim runs after the unified tier/budget walk, only when the caller
 * opted in via `tailTrim` AND a query is present to score against. It
 * keeps the pack's top delivered items, keeps any tail item whose
 * query-term COVERAGE - the fraction of the query's tokens the item
 * carries - is at least TAIL_TRIM_KEEP_FRACTION of the top delivered
 * item's (it restates the question's terms), drops the rest whole with
 * `"tail-trim"` skips, and offers the freed budget back to
 * `over-budget` candidates in priority order.
 *
 * Claims pinned here:
 *   1. An absent option, an explicit false, a flag-on pack without a
 *      query, and a flag-on pack with a tokenless query are all
 *      byte-identical to the legacy pack.
 *   2. The trim keeps top-3 head items immune: a head item below the
 *      bar survives while an equal-scoring tail item is dropped.
 *   3. The restatement keep-rule scores query-term coverage, so a long
 *      body carrying every query term is kept whatever its length, and
 *      the rule fires exactly at the fraction: a tail item at 0.8
 *      coverage is kept.
 *   4. Dropped tail items become whole `"tail-trim"` skip entries and
 *      the telemetry gap `tail_trim`; the report counters and the
 *      receipt/telemetry budget metadata carry the trim only when it ran.
 *   5. The rescue re-admits `over-budget` candidates in priority order
 *      within `maxTokens`, retracts their `over-budget` skips, and never
 *      reorders or drops the synthesized attention item.
 *   6. The trim scores coverage in every mode - ranked included - never
 *      the ranked comparator's jaccard, whose union grows with the
 *      page's own length.
 *   7. The `packingPolicy` branch is untouched: a named policy never
 *      produces the trim report.
 */

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

import { packContext } from "../../../src/core/brain/context-pack.ts";
import { listAttentionFlows } from "../../../src/core/brain/attention-flows.ts";
import { listContextReceipts } from "../../../src/core/brain/context-receipts.ts";
import { RECALL_CHANNEL, listRecallTelemetry } from "../../../src/core/brain/recall-telemetry.ts";

let vault: string;

/** Five tokens, so the ranked-mode jaccard fractions land on controllable values. */
const QUERY = "alpha beta gamma delta epsilon";

/**
 * Four tokens, so a page that fuses the query's last term into a
 * longer token (`delta-off`) passes the substring filter while its
 * coverage - 3 of 4 terms, 0.75 - lands below the 0.8 bar. (With five
 * query terms the same trick misses one term and scores exactly 0.8,
 * which the inclusive bar keeps.)
 */
const PARTIAL_QUERY = "alpha beta gamma delta";

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-pack-tail-trim-"));
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
});

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

function writePref(
  slug: string,
  fields: { principle: string; created_at: string; body?: string },
): void {
  const lines = [
    "---",
    `id: pref-${slug}`,
    "topic: a b",
    `principle: ${fields.principle}`,
    "tier: core",
    `created_at: ${fields.created_at}`,
    "---",
    "",
    fields.body ?? "",
  ];
  writeFileSync(join(vault, "Brain", "preferences", `pref-${slug}.md`), lines.join("\n"));
}

/**
 * Five pages whose `topic` tokenises to nothing and whose principle
 * carries the query verbatim, so substring mode keeps every page and
 * recency alone decides the delivery order. Every page covers all five
 * query terms - coverage 1.0 each - so the trim has nothing to drop
 * here; the flag-off byte-identity pins use it, and the trim-active
 * tests use {@link writePartialTailVault}, whose pages separate.
 */
function writeRestatementVault(): void {
  writePref("a", { principle: QUERY, created_at: "2026-05-05T00:00:00Z" });
  writePref("b", { principle: QUERY, created_at: "2026-05-04T00:00:00Z", body: "zeta" });
  writePref("c", {
    principle: QUERY,
    created_at: "2026-05-03T00:00:00Z",
    body: "zeta eta theta",
  });
  writePref("d", { principle: QUERY, created_at: "2026-05-02T00:00:00Z", body: "zeta" });
  writePref("e", {
    principle: QUERY,
    created_at: "2026-05-01T00:00:00Z",
    body: "zeta eta theta iota kappa lambda mu nu",
  });
}

/**
 * Five pages in recency order whose trim scores separate under
 * query-term coverage ({@link PARTIAL_QUERY}): a, b and c restate the
 * query verbatim; d restates it just as fully and carries a LONG body
 * that repeats every query term - coverage 1.0, where the jaccard
 * kernel the ranked comparator uses scores it 1/3 because the union
 * grows with the page's own vocabulary (the M1 defect: the trim kept
 * the short ones, not the restating ones); e passes the substring
 * filter only by fusing the query's last term into a longer token
 * (`delta-off`), so it covers 3 of the 4 query terms - 0.75, below
 * the bar.
 */
function writePartialTailVault(): void {
  writePref("a", { principle: PARTIAL_QUERY, created_at: "2026-05-05T00:00:00Z" });
  writePref("b", { principle: PARTIAL_QUERY, created_at: "2026-05-04T00:00:00Z", body: "zeta" });
  writePref("c", {
    principle: PARTIAL_QUERY,
    created_at: "2026-05-03T00:00:00Z",
    body: "zeta eta theta",
  });
  writePref("d", {
    principle: PARTIAL_QUERY,
    created_at: "2026-05-02T00:00:00Z",
    body: "zeta eta theta iota kappa lambda mu nu alpha beta gamma delta",
  });
  writePref("e", {
    principle: "alpha beta gamma delta-off",
    created_at: "2026-05-01T00:00:00Z",
    body: "omega",
  });
}

describe("packContext tailTrim byte identity", () => {
  test("an absent option and an explicit false are byte-identical", () => {
    writeRestatementVault();
    const absent = packContext(vault, { maxTokens: 10_000, query: QUERY });
    const off = packContext(vault, { maxTokens: 10_000, query: QUERY, tailTrim: false });
    expect(off.tailTrim).toBeUndefined();
    expect(JSON.stringify(off)).toBe(JSON.stringify(absent));
    // Nothing was trimmed: all five pages delivered in recency order.
    expect(absent.items.map((i) => i.id)).toEqual([
      "pref-a",
      "pref-b",
      "pref-c",
      "pref-d",
      "pref-e",
    ]);
    expect(absent.skipped).toEqual([]);
  });

  test("the flag on without a query is byte-identical - there is nothing to score against", () => {
    writeRestatementVault();
    const baseline = packContext(vault, { maxTokens: 10_000 });
    const noQuery = packContext(vault, { maxTokens: 10_000, tailTrim: true });
    expect(noQuery.tailTrim).toBeUndefined();
    expect(JSON.stringify(noQuery)).toBe(JSON.stringify(baseline));
  });

  test("the flag on with a tokenless query is byte-identical", () => {
    writeRestatementVault();
    // Ranked mode: no substring filter to trip, so the only difference a
    // tokenless query could make is the trim - and a query that
    // tokenises to nothing scores every candidate 0, cannot
    // discriminate, and must not run.
    const baseline = packContext(vault, { maxTokens: 10_000, query: "   ", queryMode: "ranked" });
    const tokenless = packContext(vault, {
      maxTokens: 10_000,
      query: "   ",
      queryMode: "ranked",
      tailTrim: true,
    });
    expect(tokenless.tailTrim).toBeUndefined();
    expect(JSON.stringify(tokenless)).toBe(JSON.stringify(baseline));
  });
});

describe("packContext tailTrim trim and keep rules", () => {
  test("substring mode: a tail item that restates every query term is kept whatever its length", () => {
    writePartialTailVault();
    const r = packContext(vault, { maxTokens: 10_000, query: PARTIAL_QUERY, tailTrim: true });
    // Head (3) immune: pref-a, pref-b, pref-c. The tail keeps pref-d -
    // coverage 1.0, every query term present even though the body is
    // the longest of the set - at the 0.8 bar, and drops pref-e (3 of
    // 4 terms, 0.75) whole. Under the jaccard kernel this trim ran
    // backwards: d's own vocabulary scored it 1/3 while the short,
    // partial e scored 3/5 and survived - the trim kept the short
    // ones, not the restating ones.
    expect(r.items.map((i) => i.id)).toEqual(["pref-a", "pref-b", "pref-c", "pref-d"]);
    const drop = r.skipped.find((s) => s.reason === "tail-trim");
    expect(drop).toEqual({ id: "pref-e", tokens: expect.any(Number), reason: "tail-trim" });
    expect(drop!.tokens).toBeGreaterThan(0);
    expect(r.tailTrim).toEqual({
      dropped: 1,
      keptByQueryTerms: 1,
      rescued: 0,
      tokensSaved: drop!.tokens,
    });
    // The freed budget is visible in the recomputed spend.
    expect(r.tokensUsed).toBe(r.items.reduce((sum, item) => sum + item.tokens, 0));
  });

  test("ranked mode: head immunity beats the bar - an equal-scoring tail item drops", () => {
    // pref-pa covers every query term (1.0); pb/pc/pd cover three of
    // the five (0.6 each). Ranked order: pa, then the three ties by
    // recency. The head keeps pb and pc even though both sit below the
    // 0.8 bar; pd, the equal-scoring tail item, is dropped - position,
    // not score, shields the head.
    writePref("pa", { principle: QUERY, created_at: "2026-05-04T00:00:00Z" });
    writePref("pb", { principle: "alpha beta gamma", created_at: "2026-05-03T00:00:00Z" });
    writePref("pc", { principle: "alpha beta gamma", created_at: "2026-05-02T00:00:00Z" });
    writePref("pd", { principle: "alpha beta gamma", created_at: "2026-05-01T00:00:00Z" });
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: QUERY,
      queryMode: "ranked",
      tailTrim: true,
    });
    expect(r.items.map((i) => i.id)).toEqual(["pref-pa", "pref-pb", "pref-pc"]);
    expect(r.skipped.map((s) => ({ id: s.id, reason: s.reason }))).toEqual([
      { id: "pref-pd", reason: "tail-trim" },
    ]);
    expect(r.tailTrim).toEqual({
      dropped: 1,
      keptByQueryTerms: 0,
      rescued: 0,
      tokensSaved: r.skipped[0]!.tokens,
    });
  });

  test("ranked mode: a long body carrying every query term is kept though the comparator ranked it last", () => {
    // The M1 case in the mode with no substring filter: pref-long
    // covers all five query terms inside a long body - coverage 1.0 -
    // but its own vocabulary drags the comparator's jaccard to 5/15,
    // ranking it last of four. The trim's keep rule scores coverage:
    // the long page stays, where the jaccard kernel dropped it.
    writePref("top", { principle: QUERY, created_at: "2026-05-04T00:00:00Z" });
    writePref("mid1", { principle: QUERY, created_at: "2026-05-03T00:00:00Z", body: "zeta" });
    writePref("mid2", { principle: QUERY, created_at: "2026-05-02T00:00:00Z", body: "zeta eta" });
    writePref("long", {
      principle: QUERY,
      created_at: "2026-05-01T00:00:00Z",
      body: "zeta eta theta iota kappa lambda mu nu xi omicron alpha beta gamma delta epsilon",
    });
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: QUERY,
      queryMode: "ranked",
      tailTrim: true,
    });
    expect(r.items.map((i) => i.id)).toEqual(["pref-top", "pref-mid1", "pref-mid2", "pref-long"]);
    expect(r.skipped).toEqual([]);
    expect(r.tailTrim).toEqual({ dropped: 0, keptByQueryTerms: 1, rescued: 0, tokensSaved: 0 });
  });

  test("ranked mode scores coverage, not the comparator: a tail item exactly at the fraction is kept", () => {
    // Coverage: p1 1.0 (the principle carries the whole query), p2 0.8
    // (four of five terms; the body adds none), p3 0.8, p4 0.8 (its
    // body's `delta` is the fifth term's own token), p5 0. The ranked
    // COMPARATOR still scores jaccard: p1 1.0, p3 0.8, p4 0.8, p2 2/3
    // (its extra body token inflates the union), p5 0 - so the
    // delivery order is p1, p3, p4, p2, p5 and p2 sits in the tail.
    // The trim scores coverage: p2's 0.8 is AT the bar and is kept
    // although its comparator score would have dropped it; p5 drops
    // whole.
    writePref("p1", { principle: QUERY, created_at: "2026-05-05T00:00:00Z" });
    writePref("p2", {
      principle: "alpha beta gamma delta",
      created_at: "2026-05-04T00:00:00Z",
      body: "zeta",
    });
    writePref("p3", { principle: "alpha beta gamma delta", created_at: "2026-05-03T00:00:00Z" });
    writePref("p4", {
      principle: "alpha beta gamma",
      created_at: "2026-05-02T00:00:00Z",
      body: "delta",
    });
    writePref("p5", {
      principle: "unrelated words about caching systems",
      created_at: "2026-05-01T00:00:00Z",
    });
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: QUERY,
      queryMode: "ranked",
      tailTrim: true,
    });
    expect(r.items.map((i) => i.id)).toEqual(["pref-p1", "pref-p3", "pref-p4", "pref-p2"]);
    expect(r.skipped.map((s) => ({ id: s.id, reason: s.reason }))).toEqual([
      { id: "pref-p5", reason: "tail-trim" },
    ]);
    expect(r.tailTrim).toEqual({
      dropped: 1,
      keptByQueryTerms: 1,
      rescued: 0,
      tokensSaved: r.skipped[0]!.tokens,
    });
  });

  test("ranked mode, a real-token query matching nothing: the zero bar keeps every delivered item", () => {
    // The query tokenises (so the trim runs - a tokenless query never
    // would) but shares no token with any page: every score is 0, the top
    // delivered score is 0, and the keep bar is 0 with it. Nothing was
    // dropped, so nothing is rescued and nothing is saved; the tail items
    // sit exactly AT the bar (0 >= 0) and are kept - a query that cannot
    // discriminate must not trim the pack it also could not rank.
    writePref("z1", {
      principle: "unrelated words about caching systems",
      created_at: "2026-05-05T00:00:00Z",
    });
    writePref("z2", {
      principle: "unrelated words about caching systems",
      created_at: "2026-05-04T00:00:00Z",
      body: "zeta",
    });
    writePref("z3", {
      principle: "unrelated words about caching systems",
      created_at: "2026-05-03T00:00:00Z",
      body: "zeta eta theta",
    });
    writePref("z4", {
      principle: "unrelated words about caching systems",
      created_at: "2026-05-02T00:00:00Z",
      body: "zeta",
    });
    writePref("z5", {
      principle: "unrelated words about caching systems",
      created_at: "2026-05-01T00:00:00Z",
      body: "zeta eta theta iota kappa lambda mu nu",
    });
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "omega sigma tau",
      queryMode: "ranked",
      tailTrim: true,
    });
    // All scores 0: the ranked order falls through to recency, and the
    // whole delivered set survives the trim whole.
    expect(r.items.map((i) => i.id)).toEqual([
      "pref-z1",
      "pref-z2",
      "pref-z3",
      "pref-z4",
      "pref-z5",
    ]);
    expect(r.skipped).toEqual([]);
    expect(r.tailTrim).toEqual({ dropped: 0, keptByQueryTerms: 2, rescued: 0, tokensSaved: 0 });
  });

  test("a trim that ran but had no tail still reports, with zero counters", () => {
    writePref("s1", { principle: QUERY, created_at: "2026-05-03T00:00:00Z" });
    writePref("s2", { principle: QUERY, created_at: "2026-05-02T00:00:00Z", body: "zeta" });
    writePref("s3", { principle: QUERY, created_at: "2026-05-01T00:00:00Z", body: "zeta" });
    const r = packContext(vault, { maxTokens: 10_000, query: QUERY, tailTrim: true });
    expect(r.items.map((i) => i.id)).toEqual(["pref-s1", "pref-s2", "pref-s3"]);
    expect(r.tailTrim).toEqual({ dropped: 0, keptByQueryTerms: 0, rescued: 0, tokensSaved: 0 });
  });
});

describe("packContext tailTrim counters under the char ceiling and the freed budget", () => {
  test("the char ceiling cutting kept-tail items recounts the trim report", () => {
    // Ranked order (the comparator still scores jaccard): p1 (1.0),
    // p2 (0.8), p3 (5/7), p5 and p6 (2/3 each), p4 (3/7). The walk
    // (maxTokens 8) delivers all six. Coverage: p1 1.0, p2 0.8, p3
    // 1.0, p5 0.8, p6 0.8, p4 0.6 - the trim keeps the head p1-p3
    // immune, keeps p5 and p6 at the bar and drops p4 whole, freeing
    // its 2 tokens with no over-budget candidate to rescue.
    writePref("p1", { principle: QUERY, created_at: "2026-05-06T00:00:00Z" });
    writePref("p2", {
      principle: "alpha beta gamma delta",
      created_at: "2026-05-05T00:00:00Z",
    });
    writePref("p3", { principle: QUERY, created_at: "2026-05-04T00:00:00Z", body: "x1 x2" });
    writePref("p4", {
      principle: "alpha beta gamma",
      created_at: "2026-05-03T00:00:00Z",
      body: "z1 z2",
    });
    writePref("p5", {
      principle: "alpha beta gamma delta",
      created_at: "2026-05-02T00:00:00Z",
      body: "q1",
    });
    writePref("p6", {
      principle: "alpha beta gamma delta",
      created_at: "2026-05-01T00:00:00Z",
      body: "q2",
    });
    // The uncapped pack: p4 dropped whole (freed 2), p5 and p6 kept at
    // the tail - where the char ceiling later cuts from.
    const uncapped = packContext(vault, {
      maxTokens: 8,
      query: QUERY,
      queryMode: "ranked",
      tailTrim: true,
    });
    expect(uncapped.items.map((i) => i.id)).toEqual([
      "pref-p1",
      "pref-p2",
      "pref-p3",
      "pref-p5",
      "pref-p6",
    ]);
    expect(uncapped.tailTrim).toEqual({
      dropped: 1,
      keptByQueryTerms: 2,
      rescued: 0,
      tokensSaved: expect.any(Number),
    });
    const headChars = uncapped.items.slice(0, 3).reduce((sum, item) => sum + item.body.length, 0);
    const drop = uncapped.skipped.find((skip) => skip.reason === "tail-trim")!;

    // A char budget that keeps exactly the head: both kept-tail items
    // are cut from the emitted set, and the report must describe what
    // actually shipped - nothing the trim kept by query terms
    // survived.
    const r = packContext(vault, {
      maxTokens: 8,
      query: QUERY,
      queryMode: "ranked",
      tailTrim: true,
      maxTotalChars: headChars,
    });
    expect(r.items.map((i) => i.id)).toEqual(["pref-p1", "pref-p2", "pref-p3"]);
    expect(r.skipped.map((s) => ({ id: s.id, reason: s.reason }))).toEqual([
      { id: "pref-p4", reason: "tail-trim" },
      { id: "pref-p5", reason: "over-char-budget" },
      { id: "pref-p6", reason: "over-char-budget" },
    ]);
    expect(r.tailTrim).toEqual({
      dropped: 1,
      keptByQueryTerms: 0,
      rescued: 0,
      tokensSaved: drop.tokens,
    });
  });

  test("the rescue spends the freed budget, never the walk's leftover slack", () => {
    // q1..q3 are the immune head; q4's principle fuses the query's
    // last term into a longer token, so it passes the substring filter
    // while covering 3 of the 4 query terms (0.75 < 0.8) and drops
    // whole (the freed budget); q5 and q6 cover every term and clear
    // the rescue bar. The walk cap leaves q5 and q6 over-budget with
    // one token of slack, and the two rescued together would re-spend
    // MORE than the trim freed - the freed budget is the rescue's
    // whole allowance, so only q5 fits and tokensSaved never goes
    // negative.
    const stem = "alpha beta gamma delta";
    writePref("q1", { principle: stem, created_at: "2026-05-06T00:00:00Z", body: "aaa" });
    writePref("q2", { principle: stem, created_at: "2026-05-05T00:00:00Z", body: "aaa" });
    writePref("q3", { principle: stem, created_at: "2026-05-04T00:00:00Z", body: "aaa" });
    writePref("q4", {
      principle: `${stem}-miss`,
      created_at: "2026-05-03T00:00:00Z",
      body: "aaa bbb ccc",
    });
    writePref("q5", { principle: stem, created_at: "2026-05-02T00:00:00Z", body: "aaa bbb" });
    writePref("q6", { principle: stem, created_at: "2026-05-01T00:00:00Z", body: "aaa bbb" });
    const probe = packContext(vault, { maxTokens: 10_000, query: stem, tailTrim: false });
    const tokens = new Map(probe.items.map((item) => [item.id, item.tokens]));
    const freed = tokens.get("pref-q4")!;
    const candidate = tokens.get("pref-q5")!;
    expect(freed).toBe(3);
    expect(candidate).toBe(2);
    // q1..q4 deliver; q5 goes over the cap by exactly its last token.
    const delivered = probe.items.slice(0, 4).reduce((sum, item) => sum + item.tokens, 0);
    const maxTokens = delivered + candidate - 1;

    const r = packContext(vault, { maxTokens, query: stem, tailTrim: true });
    expect(r.items.map((i) => i.id)).toEqual(["pref-q1", "pref-q2", "pref-q3", "pref-q5"]);
    expect(r.skipped.map((s) => ({ id: s.id, reason: s.reason }))).toEqual([
      { id: "pref-q6", reason: "over-budget" },
      { id: "pref-q4", reason: "tail-trim" },
    ]);
    expect(r.tailTrim).toEqual({
      dropped: 1,
      keptByQueryTerms: 0,
      rescued: 1,
      tokensSaved: freed - candidate,
    });
    expect(r.tokensUsed).toBeLessThanOrEqual(maxTokens);
  });
});

describe("packContext tailTrim rescue", () => {
  test("freed budget is offered to over-budget candidates in priority order within maxTokens", () => {
    // Substring mode keeps every page whose principle carries the
    // query and recency decides the walk order. p4's principle fuses
    // the query's last term into a longer token, so it passes the
    // substring filter while covering 3 of the 4 query terms (0.75 <
    // 0.8). Tokens: p1 0, p2 3, p3 3, p4 2, p5 1, p6 1. maxTokens 8:
    // the walk delivers p1-p4 (used 8) and reports p5 and p6
    // over-budget. The trim drops p4 whole, freeing 2 tokens; the
    // rescue then re-admits p5 (1.0 >= 0.8) and p6 (1.0 >= 0.8) in
    // walk order.
    const stem = "alpha beta gamma delta";
    writePref("p1", { principle: stem, created_at: "2026-05-06T00:00:00Z" });
    writePref("p2", { principle: stem, created_at: "2026-05-05T00:00:00Z", body: "x1 x2 x3 x4" });
    writePref("p3", { principle: stem, created_at: "2026-05-04T00:00:00Z", body: "y1 y2 y3 y4" });
    writePref("p4", {
      principle: `${stem}-partial`,
      created_at: "2026-05-03T00:00:00Z",
      body: "z1 z2",
    });
    writePref("p5", { principle: stem, created_at: "2026-05-02T00:00:00Z", body: "z1" });
    writePref("p6", { principle: stem, created_at: "2026-05-01T00:00:00Z", body: "z1" });
    const r = packContext(vault, { maxTokens: 8, query: stem, tailTrim: true });
    // p4 dropped whole, p5 and p6 rescued at the tail in priority order.
    expect(r.items.map((i) => i.id)).toEqual([
      "pref-p1",
      "pref-p2",
      "pref-p3",
      "pref-p5",
      "pref-p6",
    ]);
    expect(r.skipped).toEqual([{ id: "pref-p4", tokens: expect.any(Number), reason: "tail-trim" }]);
    expect(r.tailTrim).toEqual({ dropped: 1, keptByQueryTerms: 0, rescued: 2, tokensSaved: 0 });
    expect(r.tokensUsed).toBeLessThanOrEqual(8);
  });

  test("an over-budget candidate below the restatement bar keeps its over-budget skip", () => {
    const stem = "alpha beta gamma delta";
    writePref("p1", { principle: stem, created_at: "2026-05-05T00:00:00Z" });
    writePref("p2", { principle: stem, created_at: "2026-05-04T00:00:00Z", body: "x1 x2 x3 x4" });
    writePref("p3", { principle: stem, created_at: "2026-05-03T00:00:00Z", body: "y1 y2 y3 y4" });
    // p4's fused last term covers 3 of the 4 query terms (0.75 < 0.8):
    // delivered, in the tail, and dropped whole - the freed budget.
    writePref("p4", {
      principle: `${stem}-partial`,
      created_at: "2026-05-02T00:00:00Z",
      body: "z1 z2",
    });
    // p5 is older, over-budget at the walk, and below the bar: the
    // rescue must not re-admit it even though it would fit.
    writePref("p5", {
      principle: `${stem}-partial`,
      created_at: "2026-05-01T00:00:00Z",
      body: "z1 z2",
    });
    const r = packContext(vault, { maxTokens: 8, query: stem, tailTrim: true });
    expect(r.items.map((i) => i.id)).toEqual(["pref-p1", "pref-p2", "pref-p3"]);
    // Skips keep walk order (p5 went over-budget first); the trim's
    // whole-item drop appends after.
    expect(r.skipped.map((s) => ({ id: s.id, reason: s.reason }))).toEqual([
      { id: "pref-p5", reason: "over-budget" },
      { id: "pref-p4", reason: "tail-trim" },
    ]);
    expect(r.tailTrim).toEqual({
      dropped: 1,
      keptByQueryTerms: 0,
      rescued: 0,
      tokensSaved: r.skipped[1]!.tokens,
    });
  });

  test("the rescue never touches the synthesized attention item", () => {
    writePartialTailVault();
    listAttentionFlows(vault); // bootstraps the default flow fixtures
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: PARTIAL_QUERY,
      tailTrim: true,
      attentionFlowIds: ["open-loops"],
    });
    // The attention block sits at the head, inside the immune keep
    // count, and stays first after the trim. The tail past the head
    // keeps pref-c and pref-d - both cover every query term, d's long
    // body included - and drops pref-e (0.75) whole.
    expect(r.items[0]!.id).toBe("attention-flows");
    expect(r.items.map((i) => i.id)).toEqual([
      "attention-flows",
      "pref-a",
      "pref-b",
      "pref-c",
      "pref-d",
    ]);
    expect(r.skipped.filter((s) => s.id === "attention-flows")).toEqual([]);
    expect(r.skipped.map((s) => s.id)).toEqual(["pref-e"]);
    expect(r.tailTrim).toEqual({
      dropped: 1,
      keptByQueryTerms: 2,
      rescued: 0,
      tokensSaved: expect.any(Number),
    });
  });
});

describe("packContext tailTrim telemetry and receipts", () => {
  test("the trim counters ride the receipt budget and the telemetry metadata, and the gap surfaces", () => {
    writePartialTailVault();
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: PARTIAL_QUERY,
      tailTrim: true,
      receipt: { trigger: "context_pack", host: "tail-trim-test" },
      telemetry: { host: "tail-trim-test", channel: RECALL_CHANNEL.cli },
    });
    expect(r.tailTrim).toBeDefined();
    const telemetryRecords = listRecallTelemetry(vault, { mode: "context_pack" });
    expect(telemetryRecords).toHaveLength(1);
    const metadata = telemetryRecords[0]!.payload["metadata"] as Record<string, unknown>;
    expect(metadata["tail_trim_dropped"]).toBe(1);
    expect(metadata["tail_trim_kept_by_query_terms"]).toBe(1);
    expect(metadata["tail_trim_rescued"]).toBe(0);
    expect(metadata["tail_trim_tokens_saved"]).toBe(r.tailTrim!.tokensSaved);
    expect(telemetryRecords[0]!.payload["gaps"]).toContain("tail_trim");
    const receiptRecords = listContextReceipts(vault);
    expect(receiptRecords).toHaveLength(1);
    const budget = receiptRecords[0]!.payload["budget"] as Record<string, unknown>;
    expect(budget["tail_trim_dropped"]).toBe(1);
    expect(budget["tail_trim_kept_by_query_terms"]).toBe(1);
    expect(budget["tail_trim_rescued"]).toBe(0);
    expect(budget["tail_trim_tokens_saved"]).toBe(r.tailTrim!.tokensSaved);
  });

  test("an untrimmed pack carries no trim counters and no tail_trim gap", () => {
    writeRestatementVault();
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: QUERY,
      receipt: { trigger: "context_pack", host: "tail-trim-test" },
      telemetry: { host: "tail-trim-test", channel: RECALL_CHANNEL.cli },
    });
    expect(r.tailTrim).toBeUndefined();
    const telemetryRecords = listRecallTelemetry(vault, { mode: "context_pack" });
    expect(telemetryRecords).toHaveLength(1);
    const metadata = telemetryRecords[0]!.payload["metadata"] as Record<string, unknown>;
    expect("tail_trim_dropped" in metadata).toBe(false);
    expect("tail_trim_tokens_saved" in metadata).toBe(false);
    expect(telemetryRecords[0]!.payload["gaps"]).not.toContain("tail_trim");
    const receiptRecords = listContextReceipts(vault);
    expect(receiptRecords).toHaveLength(1);
    const budget = receiptRecords[0]!.payload["budget"] as Record<string, unknown>;
    expect("tail_trim_dropped" in budget).toBe(false);
  });
});

describe("packContext tailTrim scope", () => {
  test("the packingPolicy branch never produces the trim report", () => {
    writePref("a", { principle: QUERY, created_at: "2026-05-02T00:00:00Z" });
    writeFileSync(
      join(vault, "Brain", "retired", "retired-old.md"),
      [
        "---",
        "id: retired-old",
        "topic: a b",
        `principle: ${QUERY}`,
        "tier: core",
        "created_at: 2026-05-01T00:00:00Z",
        "---",
        "",
        "zeta",
      ].join("\n"),
    );
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: QUERY,
      tailTrim: true,
      packingPolicy: "facts_first",
    });
    expect(r.packing).toBeDefined();
    expect(r.tailTrim).toBeUndefined();
  });
});