@cohortapp/agent-sdk 2.16.0 → 2.17.0

package/.env.example

@@ -226,6 +226,9 @@ GREPTILE_API_KEY=
 # Flags that control system behaviour. These are not secrets.
 #
 
-# Enable session context compiler for optimised daemon prompts
-# Set to 1 to pre-compile context before each Claude Code session (recommended)
+# The session context compiler: pre-compile context before each Claude Code
+# session. ON BY DEFAULT in code as well as here — the two used to disagree
+# (code read `=== "1"`, this file shipped `=1`), so which of two materially
+# different context paths ran depended on whether the operator had copied this
+# file. Set to 0 only to fall back to the legacy path in a hurry.
 DAEMON_CONTEXT_COMPILER=1

package/docs/guides/poller-daemon-setup.md

@@ -279,7 +279,10 @@ Pre-compiles session context to reduce prompt size:
 
 - Reads recent interactions, queue state, and active items
 - Compresses context to fit within token limits
-- Enabled via `DAEMON_CONTEXT_COMPILER=1` in `.env`
+- **On by default.** Set `DAEMON_CONTEXT_COMPILER=0` in `.env` to fall back to
+  the legacy per-prompt history path. The code used to default this OFF while
+  `.env.example` shipped `=1`, so which path ran depended on whether the
+  operator had copied the example env; both now agree.
 
 ---
 

package/lib/context/budget.mjs

@@ -0,0 +1,327 @@
+/**
+ * lib/context/budget.mjs — the declared token budget for an inbound prompt.
+ *
+ * Every bound in this repo up to now has been a row count or a `.slice(n)` char
+ * clamp (design §5.4, R8). Both are proxies: a row count cannot tell a one-word
+ * turn from a pasted stack trace, and a char clamp spends the allowance on
+ * whichever section happens to be assembled first. So the prompt that reaches
+ * the model is whatever the assembly order happened to produce, and the parts
+ * that fall off do so SILENTLY — the model reads a thread with a hole in it and
+ * cannot tell the hole from a conversation that never happened.
+ *
+ * This module states the budget instead of discovering it:
+ *
+ *   1. a budget PER TIER (§5.1) — an Answer gets 6k input tokens, Work 12k,
+ *      Plan 20k. Context rot is measured: accuracy falls with input length well
+ *      before the window limit, so a bigger prompt is not a better one.
+ *   2. sections filled in PRIORITY order ({@link SECTION_ORDER}) — the trigger
+ *      is the thing being answered and is never dropped whole; the backlog is
+ *      the first thing to go.
+ *   3. every drop VISIBLE — `… 14 earlier turns not shown`, in the prompt, where
+ *      the model reads it. A section that did not fit at all still leaves a line
+ *      saying so.
+ *
+ * PURE. No clock, no env, no fs, no network: tokens are estimated from
+ * character length at {@link CHARS_PER_TOKEN}, the same ratio
+ * `context-compiler.mjs` already uses, so the two agree. A caller that has a
+ * real tokeniser passes `estimate` and this module uses it instead.
+ *
+ * Char clamps stay where they are as a second belt — this is the first one.
+ *
+ * @module lib/context/budget
+ */
+
+"use strict";
+
+/** Characters per token. The estimate `scripts/daemon/context-compiler.mjs` uses. */
+export const CHARS_PER_TOKEN = 4;
+
+/**
+ * Input-token budget per reply tier (design §5.4). A tier is the ack/effort
+ * tier from `lib/assurance/tier.mjs` — answer | work | plan.
+ */
+export const TIER_BUDGETS = Object.freeze({
+  answer: 6000,
+  work: 12000,
+  plan: 20000,
+});
+
+/**
+ * FILL priority. Earlier wins the budget; later is dropped first.
+ *
+ *   trigger  the message being answered — without it there is nothing to answer
+ *   thread   the conversation it sits in
+ *   entity   the anchored artifact: the task card, the doc body, the decision
+ *   digest   the distilled record of this thread
+ *   memory   recalled facts from elsewhere
+ *   backlog  what else is open — useful, never load-bearing
+ */
+export const FILL_PRIORITY = Object.freeze([
+  "trigger",
+  "thread",
+  "entity",
+  "digest",
+  "memory",
+  "backlog",
+]);
+
+/**
+ * RENDER order — a DIFFERENT question, and conflating the two costs the cache.
+ *
+ * Fill priority asks "who wins the budget"; the trigger wins it, because a
+ * prompt without the message being answered is not a smaller prompt but a
+ * broken one. Render order asks "what byte comes first", and design §4 is
+ * explicit about the consequence: "any byte change before a breakpoint
+ * invalidates everything after it". Rendering the trigger first — the ONE
+ * section that is different on every single inbound — gives the block a
+ * zero-length stable prefix, so WP-4's `cache_control` breakpoint would sit
+ * after volatile content and every read would be a silent miss. Prompt caching
+ * is the highest-ROI latency lever in the research pass; this is what it needs.
+ *
+ * So: stable first, volatile last, trigger last of all. `thread` sits second to
+ * last because it is append-only and rendered oldest-first, which makes its own
+ * prefix stable between turns even as it grows.
+ */
+export const RENDER_ORDER = Object.freeze([
+  "entity",
+  "digest",
+  "backlog",
+  "memory",
+  "thread",
+  "trigger",
+]);
+
+/**
+ * @deprecated Read {@link FILL_PRIORITY} or {@link RENDER_ORDER} by name — the
+ * whole point of the split is that "the section order" is two different orders.
+ * Kept as an alias so an existing importer does not silently get the wrong one.
+ */
+export const SECTION_ORDER = FILL_PRIORITY;
+
+/** Sections that must render SOMETHING rather than be dropped whole. */
+const NEVER_DROPPED_WHOLE = new Set(["trigger"]);
+
+/** A blank-safe string. */
+function s(v) {
+  return v == null ? "" : String(v);
+}
+
+/** The declared budget for a tier; an unknown tier takes the middle one. */
+export function budgetFor(tier) {
+  const key = s(tier).toLowerCase();
+  return Object.prototype.hasOwnProperty.call(TIER_BUDGETS, key) ? TIER_BUDGETS[key] : TIER_BUDGETS.work;
+}
+
+/** Estimated tokens for a string, rounded up so a partial token still costs one. */
+export function estimateTokens(text, charsPerToken = CHARS_PER_TOKEN) {
+  const t = s(text);
+  if (!t) return 0;
+  const per = Number.isFinite(charsPerToken) && charsPerToken > 0 ? charsPerToken : CHARS_PER_TOKEN;
+  return Math.ceil(t.length / per);
+}
+
+/** Where a section sorts in a declared order; unknown names sort last, stably. */
+function rankIn(order, name) {
+  const i = order.indexOf(name);
+  return i === -1 ? order.length : i;
+}
+
+/** `1 earlier turn` / `14 earlier turns` — the count is the point, so it leads. */
+function turnNote(n) {
+  return `… ${n} earlier turn${n === 1 ? "" : "s"} not shown`;
+}
+
+/** `… 1,204 characters not shown`. */
+function charNote(n) {
+  return `… ${n.toLocaleString("en-US")} character${n === 1 ? "" : "s"} not shown`;
+}
+
+/**
+ * @typedef {Object} SectionInput
+ * @property {string} name             one of {@link SECTION_ORDER}, or any name (sorts last)
+ * @property {string} [title]          heading rendered above the body
+ * @property {string} [text]           a whole-text section
+ * @property {string[]} [turns]        a turn-structured section, OLDEST FIRST
+ */
+
+/**
+ * @typedef {Object} FittedSection
+ * @property {string} name
+ * @property {boolean} included        false == dropped whole (still rendered as a note)
+ * @property {string} text             what was kept, drop note included
+ * @property {number} keptTurns
+ * @property {number} droppedTurns
+ * @property {number} droppedChars
+ * @property {number} tokens
+ */
+
+/**
+ * Fit the sections into the tier's budget.
+ *
+ * Turn-structured sections spend the budget from the NEWEST turn backwards —
+ * the turns nearest the message being answered are the ones that explain it
+ * (the same rule `lib/org/inbound/hydrate.mjs#renderThread` follows, and for the
+ * same reason: clipping the joined string keeps the oldest turns and drops the
+ * newest, which is the exact inverse of what context is for).
+ *
+ * NEVER THROWS. A malformed section is skipped; a missing budget takes the
+ * tier's. The prompt path must not be able to fail on its own budgeting.
+ *
+ * @param {Object} o
+ * @param {SectionInput[]} o.sections
+ * @param {string} [o.tier]                    answer | work | plan
+ * @param {number} [o.budgetTokens]            override the tier's budget
+ * @param {number} [o.charsPerToken]
+ * @param {(text:string)=>number} [o.estimate] a real tokeniser, when the caller has one
+ * @returns {{tier:string, budgetTokens:number, usedTokens:number,
+ *           sections:FittedSection[], drops:Array<object>, text:string}}
+ */
+export function fitSections(o = {}) {
+  const tier = s(o.tier).toLowerCase() || "work";
+  const budgetTokens = Number.isFinite(o.budgetTokens) && o.budgetTokens > 0
+    ? Math.floor(o.budgetTokens)
+    : budgetFor(tier);
+  const charsPerToken = Number.isFinite(o.charsPerToken) && o.charsPerToken > 0 ? o.charsPerToken : CHARS_PER_TOKEN;
+  const tokensOf = typeof o.estimate === "function" ? o.estimate : (t) => estimateTokens(t, charsPerToken);
+
+  const input = (Array.isArray(o.sections) ? o.sections : [])
+    .map((sec, i) => ({ sec, i }))
+    .filter(({ sec }) => sec && typeof sec === "object" && s(sec.name))
+    .sort((a, b) => rankIn(FILL_PRIORITY, s(a.sec.name)) - rankIn(FILL_PRIORITY, s(b.sec.name)) || a.i - b.i);
+
+  const out = [];
+  const drops = [];
+  let used = 0;
+
+  for (const { sec } of input) {
+    const name = s(sec.name);
+    const title = s(sec.title);
+    const headCost = title ? tokensOf(`${title}\n`) : 0;
+    const room = budgetTokens - used - headCost;
+
+    const fitted = Array.isArray(sec.turns)
+      ? fitTurns(sec.turns, room, tokensOf)
+      : fitText(s(sec.text), room, tokensOf, charsPerToken);
+
+    // A section with no content at all is simply absent — there is nothing to
+    // report the loss of, and a note about an empty section is noise.
+    if (fitted.empty) continue;
+
+    if (!fitted.body && !NEVER_DROPPED_WHOLE.has(name)) {
+      // Dropped whole. It still shows: an absence the reader cannot see is the
+      // failure this module exists to prevent.
+      const note = `… ${name} not shown`;
+      const cost = tokensOf(note);
+      if (used + cost <= budgetTokens) {
+        out.push({ name, included: false, text: note, keptTurns: 0, droppedTurns: fitted.droppedTurns, droppedChars: fitted.droppedChars, tokens: cost });
+        used += cost;
+      } else {
+        out.push({ name, included: false, text: "", keptTurns: 0, droppedTurns: fitted.droppedTurns, droppedChars: fitted.droppedChars, tokens: 0 });
+      }
+      drops.push({ section: name, turns: fitted.droppedTurns, chars: fitted.droppedChars, note });
+      continue;
+    }
+
+    // The trigger is the thing being answered: it always renders something,
+    // even when the budget cannot pay for it. A prompt with no trigger is not a
+    // smaller prompt, it is a broken one.
+    let body = fitted.body;
+    if (!body && NEVER_DROPPED_WHOLE.has(name)) {
+      const minChars = Math.max(1, Math.floor(Math.max(room, 1) * charsPerToken));
+      const whole = Array.isArray(sec.turns) ? sec.turns.filter(Boolean).map(s).join("\n") : s(sec.text);
+      body = whole.slice(0, minChars);
+      const lost = whole.length - body.length;
+      if (lost > 0) {
+        body += `\n${charNote(lost)}`;
+        drops.push({ section: name, turns: 0, chars: lost, note: charNote(lost) });
+      }
+    } else if (fitted.droppedTurns > 0) {
+      drops.push({ section: name, turns: fitted.droppedTurns, chars: 0, note: turnNote(fitted.droppedTurns) });
+    } else if (fitted.droppedChars > 0) {
+      drops.push({ section: name, turns: 0, chars: fitted.droppedChars, note: charNote(fitted.droppedChars) });
+    }
+
+    const text = title ? `${title}\n${body}` : body;
+    const cost = tokensOf(text);
+    out.push({
+      name,
+      included: true,
+      text,
+      keptTurns: fitted.keptTurns,
+      droppedTurns: fitted.droppedTurns,
+      droppedChars: fitted.droppedChars,
+      tokens: cost,
+    });
+    used += cost;
+  }
+
+  // Filled in priority order, RENDERED in cache order. The two are separate
+  // arrays for the reason RENDER_ORDER states, and this is the only place the
+  // difference is applied.
+  const rendered = out
+    .map((sec, i) => ({ sec, i }))
+    .sort((a, b) => rankIn(RENDER_ORDER, a.sec.name) - rankIn(RENDER_ORDER, b.sec.name) || a.i - b.i)
+    .map(({ sec }) => sec);
+
+  return {
+    tier,
+    budgetTokens,
+    usedTokens: used,
+    sections: rendered,
+    drops,
+    text: rendered.map((sec) => sec.text).filter(Boolean).join("\n\n"),
+  };
+}
+
+/** Keep the newest turns that fit; report the rest as a visible note. */
+function fitTurns(turns, room, tokensOf) {
+  const rows = (Array.isArray(turns) ? turns : []).filter((t) => s(t).trim()).map((t) => s(t));
+  if (rows.length === 0) return { empty: true, body: "", keptTurns: 0, droppedTurns: 0, droppedChars: 0 };
+  if (room <= 0) return { empty: false, body: "", keptTurns: 0, droppedTurns: rows.length, droppedChars: 0 };
+
+  const kept = [];
+  let used = 0;
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const cost = tokensOf(rows[i]) + (kept.length ? 1 : 0);
+    // The note itself has to fit, or the drop would be the silent kind.
+    const reserve = i > 0 ? tokensOf(turnNote(i)) + 1 : 0;
+    if (used + cost + reserve > room) break;
+    kept.unshift(rows[i]);
+    used += cost;
+  }
+  const dropped = rows.length - kept.length;
+  if (kept.length === 0) return { empty: false, body: "", keptTurns: 0, droppedTurns: dropped, droppedChars: 0 };
+  const body = dropped > 0 ? [turnNote(dropped), ...kept].join("\n") : kept.join("\n");
+  return { empty: false, body, keptTurns: kept.length, droppedTurns: dropped, droppedChars: 0 };
+}
+
+/** Keep the head that fits; report the tail as a visible note. */
+function fitText(text, room, tokensOf, charsPerToken) {
+  const t = s(text).trim();
+  if (!t) return { empty: true, body: "", keptTurns: 0, droppedTurns: 0, droppedChars: 0 };
+  if (room <= 0) return { empty: false, body: "", keptTurns: 0, droppedTurns: 0, droppedChars: t.length };
+  if (tokensOf(t) <= room) return { empty: false, body: t, keptTurns: 1, droppedTurns: 0, droppedChars: 0 };
+
+  // Reserve room for the note, then take the largest head that still fits.
+  let chars = Math.max(0, Math.floor(room * charsPerToken));
+  let head = t.slice(0, chars);
+  let note = charNote(t.length - head.length);
+  while (head.length > 0 && tokensOf(`${head}\n${note}`) > room) {
+    chars = Math.floor(chars * 0.8);
+    head = t.slice(0, chars);
+    note = charNote(t.length - head.length);
+  }
+  if (!head) return { empty: false, body: "", keptTurns: 0, droppedTurns: 0, droppedChars: t.length };
+  return { empty: false, body: `${head}\n${note}`, keptTurns: 1, droppedTurns: 0, droppedChars: t.length - head.length };
+}
+
+export default {
+  TIER_BUDGETS,
+  FILL_PRIORITY,
+  RENDER_ORDER,
+  SECTION_ORDER,
+  CHARS_PER_TOKEN,
+  budgetFor,
+  estimateTokens,
+  fitSections,
+};

package/lib/context/budget.test.mjs

@@ -0,0 +1,252 @@
+/**
+ * budget.test.mjs — the declared token budget (spec §5.4, SDK half).
+ *
+ * Three properties are under test throughout:
+ *   1. the budget is DECLARED per tier, not discovered by a char clamp;
+ *   2. sections are filled in PRIORITY order, so the trigger survives a budget
+ *      that the backlog cannot, and RENDERED in cache order, which is a
+ *      different order for a different reason; and
+ *   3. every drop is VISIBLE in the rendered text. A silent drop is the bug —
+ *      the reader cannot tell an absent turn from a turn that never happened.
+ *
+ * Run: node --test lib/context/budget.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  TIER_BUDGETS,
+  SECTION_ORDER,
+  FILL_PRIORITY,
+  RENDER_ORDER,
+  CHARS_PER_TOKEN,
+  budgetFor,
+  estimateTokens,
+  fitSections,
+} from "./budget.mjs";
+
+const turns = (n, text = "x".repeat(40)) => Array.from({ length: n }, (_, i) => `s${i}: ${text}`);
+
+// ---------------------------------------------------------------------------
+// the declared budget
+// ---------------------------------------------------------------------------
+
+test("each tier declares its own budget, and the table is frozen", () => {
+  assert.equal(TIER_BUDGETS.answer, 6000);
+  assert.equal(TIER_BUDGETS.work, 12000);
+  assert.equal(TIER_BUDGETS.plan, 20000);
+  assert.equal(Object.isFrozen(TIER_BUDGETS), true);
+});
+
+test("an unknown tier takes the WORK budget rather than an unbounded one", () => {
+  assert.equal(budgetFor("plan"), 20000);
+  assert.equal(budgetFor("nonsense"), TIER_BUDGETS.work);
+  assert.equal(budgetFor(undefined), TIER_BUDGETS.work);
+});
+
+test("estimateTokens is the declared chars-per-token ratio, rounded up", () => {
+  assert.equal(estimateTokens(""), 0);
+  assert.equal(estimateTokens("a".repeat(CHARS_PER_TOKEN)), 1);
+  assert.equal(estimateTokens("a".repeat(CHARS_PER_TOKEN + 1)), 2);
+  assert.equal(estimateTokens(null), 0);
+});
+
+// ---------------------------------------------------------------------------
+// fitting
+// ---------------------------------------------------------------------------
+
+test("everything that fits is kept, verbatim, with no drop notes", () => {
+  const out = fitSections({
+    tier: "plan",
+    sections: [
+      { name: "trigger", text: "fix the invoice total" },
+      { name: "thread", turns: turns(3) },
+    ],
+  });
+  assert.equal(out.drops.length, 0);
+  assert.match(out.text, /fix the invoice total/);
+  assert.doesNotMatch(out.text, /not shown/);
+  assert.ok(out.usedTokens <= out.budgetTokens);
+});
+
+test("an overflowing thread keeps the NEWEST turns and says how many it dropped", () => {
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 60, // ~240 chars
+    sections: [
+      { name: "trigger", text: "which one?" },
+      { name: "thread", turns: turns(20, "y".repeat(60)) },
+    ],
+  });
+  const thread = out.sections.find((s) => s.name === "thread");
+  assert.ok(thread.keptTurns > 0, "at least one turn survives");
+  assert.ok(thread.droppedTurns > 0, "the rest were dropped");
+  assert.equal(thread.keptTurns + thread.droppedTurns, 20);
+  // The newest turn is the one nearest the message being answered.
+  assert.match(out.text, /s19:/);
+  assert.doesNotMatch(out.text, /s0:/);
+  assert.match(out.text, new RegExp(`… ${thread.droppedTurns} earlier turns not shown`));
+});
+
+test("the drop note is singular for exactly one dropped turn", () => {
+  // Two turns, and room for the newest one plus its drop note but not for both.
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 60,
+    sections: [{ name: "thread", turns: [`s0: ${"a".repeat(200)}`, `s1: ${"b".repeat(200)}`] }],
+  });
+  const thread = out.sections.find((s) => s.name === "thread");
+  assert.equal(thread.keptTurns, 1);
+  assert.equal(thread.droppedTurns, 1);
+  assert.match(out.text, /… 1 earlier turn not shown/);
+  assert.doesNotMatch(out.text, /earlier turns not shown/);
+});
+
+test("sections fill in priority order — the trigger outranks the backlog", () => {
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 12,
+    sections: [
+      { name: "backlog", turns: turns(6, "b".repeat(80)) },
+      { name: "trigger", text: "the one question that matters" },
+    ],
+  });
+  assert.match(out.text, /the one question that matters/);
+  const backlog = out.sections.find((s) => s.name === "backlog");
+  assert.equal(backlog.included, false);
+});
+
+test("a section dropped WHOLE is still visible — never silently absent", () => {
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 20,
+    sections: [
+      { name: "trigger", text: "t".repeat(60) },
+      { name: "memory", turns: turns(4, "m".repeat(100)) },
+    ],
+  });
+  const memory = out.sections.find((s) => s.name === "memory");
+  assert.equal(memory.included, false);
+  assert.match(out.text, /… memory not shown/);
+  assert.equal(out.drops.some((d) => d.section === "memory"), true);
+});
+
+test("a long text section is clipped and says how many characters went", () => {
+  const body = "z".repeat(4000);
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 100,
+    sections: [{ name: "entity", title: "Document", text: body }],
+  });
+  const entity = out.sections.find((s) => s.name === "entity");
+  assert.ok(entity.droppedChars > 0);
+  assert.match(out.text, /characters not shown/);
+  assert.ok(out.usedTokens <= out.budgetTokens);
+});
+
+test("the trigger is never dropped whole — it is the thing being answered", () => {
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 5,
+    sections: [{ name: "trigger", text: "q".repeat(2000) }],
+  });
+  const trigger = out.sections.find((s) => s.name === "trigger");
+  assert.equal(trigger.included, true);
+  assert.ok(trigger.text.length > 0);
+});
+
+test("rendered order is CACHE order — stable first, the trigger last", () => {
+  // Fill priority and render order are two different questions. The trigger
+  // WINS the budget (it is the thing being answered) and RENDERS last (it is
+  // the only section that changes on every inbound). A block that opened with
+  // the trigger would have a zero-length stable prefix, so WP-4's cache_control
+  // breakpoint would sit after volatile content and every cache read would miss
+  // silently — design §4, "any byte change before a breakpoint invalidates
+  // everything after it".
+  const out = fitSections({
+    tier: "plan",
+    sections: [
+      { name: "memory", turns: ["m: one"] },
+      { name: "trigger", text: "the ask" },
+      { name: "thread", turns: ["t: two"] },
+      { name: "entity", text: "the card" },
+    ],
+  });
+  assert.deepEqual(out.sections.map((s) => s.name), ["entity", "memory", "thread", "trigger"]);
+  assert.ok(out.text.indexOf("the card") < out.text.indexOf("m: one"));
+  assert.ok(out.text.indexOf("m: one") < out.text.indexOf("t: two"));
+  assert.ok(out.text.indexOf("t: two") < out.text.indexOf("the ask"));
+  assert.ok(out.text.endsWith("the ask"), "the volatile section is the tail, so everything before it can be cached");
+});
+
+test("FILL priority still decides who is dropped — the trigger wins the budget", () => {
+  // Same four sections, a budget only one of them fits. Render order must not
+  // become a fill order by accident: `entity` renders first but `trigger` is
+  // what survives.
+  const out = fitSections({
+    budgetTokens: 8,
+    sections: [
+      { name: "entity", text: "E".repeat(400) },
+      { name: "backlog", text: "B".repeat(400) },
+      { name: "trigger", text: "the ask itself" },
+    ],
+  });
+  const byName = Object.fromEntries(out.sections.map((s) => [s.name, s]));
+  assert.equal(byName.trigger.included, true, "the trigger is filled first, whatever it renders after");
+  assert.equal(byName.trigger.droppedChars, 0, "…and it is filled WHOLE");
+  assert.match(out.text, /the ask itself/);
+  assert.equal(byName.backlog.included, false, "the last section in fill priority is the first to go");
+  assert.ok(byName.entity.droppedChars > 0, "and the higher-priority one is only trimmed");
+  assert.equal(out.text.endsWith("the ask itself"), true, "render order is unchanged by who was dropped");
+});
+
+test("FILL_PRIORITY and RENDER_ORDER name the same sections, and are not the same array", () => {
+  assert.deepEqual([...FILL_PRIORITY].sort(), [...RENDER_ORDER].sort(),
+    "a section that can be filled must be renderable, and vice versa");
+  assert.notDeepEqual([...FILL_PRIORITY], [...RENDER_ORDER]);
+  assert.equal(FILL_PRIORITY[0], "trigger", "the trigger wins the budget");
+  assert.equal(RENDER_ORDER[RENDER_ORDER.length - 1], "trigger", "…and renders last, so the prefix is cacheable");
+});
+
+test("an unknown section name sorts after every declared one, keeping its order", () => {
+  const out = fitSections({
+    tier: "plan",
+    sections: [
+      { name: "weather", text: "w" },
+      { name: "trigger", text: "t" },
+      { name: "tides", text: "d" },
+    ],
+  });
+  assert.deepEqual(out.sections.map((s) => s.name), ["trigger", "weather", "tides"]);
+  assert.equal(SECTION_ORDER.includes("trigger"), true);
+  assert.equal(SECTION_ORDER.includes("weather"), false);
+});
+
+// ---------------------------------------------------------------------------
+// purity
+// ---------------------------------------------------------------------------
+
+test("pure: same input, same output, and the caller's arrays are untouched", () => {
+  const input = { tier: "work", sections: [{ name: "thread", turns: turns(50) }] };
+  const before = JSON.stringify(input);
+  const a = fitSections(input);
+  const b = fitSections(input);
+  assert.deepEqual(a, b);
+  assert.equal(JSON.stringify(input), before, "fitSections mutated its argument");
+});
+
+test("no sections is an empty block, not a throw", () => {
+  const out = fitSections({ tier: "answer", sections: [] });
+  assert.equal(out.text, "");
+  assert.equal(out.usedTokens, 0);
+  assert.deepEqual(out.drops, []);
+});
+
+test("a malformed section is ignored rather than taking the prompt down", () => {
+  const out = fitSections({ tier: "answer", sections: [null, { text: "no name" }, { name: "trigger", text: "ok" }] });
+  assert.equal(out.sections.length, 1);
+  assert.match(out.text, /ok/);
+});