@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/plan/budget-enforcement.test.mjs

@@ -1,400 +0,0 @@
-/**
- * budget-enforcement.test.mjs — the ceiling, enforced.
- *
- * Covers the three places a breach actually bites:
- *   compile.applyBudgetPosture            the plan-level suspension (125%)
- *   compile.obligationAllowedUnderPosture  the per-tick form the daemon uses
- *   budget-runtime.reconcileBudgetPosture  the I/O around them (drift, band edge)
- *
- * The invariant every one of these tests exists to protect: WE DEGRADE, WE NEVER
- * BRICK. At every band, the inline cadences still run and the seat still answers
- * its inbox.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { promises as fsp } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { compilePlan, applyBudgetPosture, obligationAllowedUnderPosture } from "./compile.mjs";
-import { reconcileBudgetPosture, readPosture } from "./budget-runtime.mjs";
-import { postureForBand } from "../budget-guard.mjs";
-
-// ---------------------------------------------------------------------------
-// fixtures
-// ---------------------------------------------------------------------------
-
-const manifest = () => ({
-  schemaVersion: 1,
-  entries: [
-    { id: "books_reports", plane: "protocol", kind: "method", reachable: true, blastRadius: "internal" },
-    { id: "board_ready", plane: "protocol", kind: "method", reachable: true, blastRadius: "internal" },
-    { id: "messaging_send", plane: "protocol", kind: "method", reachable: true, blastRadius: "external" },
-  ],
-});
-
-/** An adopted, fully-admissible objective — the kind that compiles obligations. */
-function objective(over = {}) {
-  return {
-    id: `obj-${over.key || "a"}`,
-    key: over.key || "a",
-    kind: "OBJECTIVE",
-    state: "active",
-    text: "an adopted objective",
-    memberId: "A016",
-    parentId: null,
-    parentKey: null,
-    charterSectionId: "sec-1",
-    metric: "gross_margin",
-    unit: "pct",
-    direction: "up",
-    baseline: 10,
-    target: 40,
-    value: 12,
-    tolerance: 1,
-    weight: 1,
-    cadence: "weekly",
-    sensor: { source: "method", capability: "books_reports", params: {} },
-    budgetCentsPerPeriod: null,
-    collaborators: [],
-    adoptedById: "HUMAN-1",
-    adoptedAt: "2026-06-01T00:00:00.000Z",
-    ...over,
-  };
-}
-
-function mandate(over = {}) {
-  return {
-    contractVersion: 1,
-    memberId: "A016",
-    objectives: [],
-    proposed: [],
-    budgetCentsPerPeriod: null,
-    seatBudgetCents: null,
-    budgetPeriod: null,
-    budgetSource: "employee.payBasis.meteredBudget",
-    collaborators: [],
-    reactsTo: [],
-    degradations: [],
-    generatedAt: "2026-06-01T00:00:00.000Z",
-    ...over,
-  };
-}
-
-const STANDARD = [
-  { id: "cadence-bus-heartbeat", mode: "inline", interval: 300 },
-  { id: "inbox-processor", mode: "guarded", calendar: { hour: 9 } },
-];
-
-function fundedPlan() {
-  return compilePlan({
-    mandate: mandate({
-      objectives: [objective({ key: "gross-margin", budgetCentsPerPeriod: 60_000 })],
-      seatBudgetCents: 60_000,
-      budgetPeriod: "monthly",
-    }),
-    manifest: manifest(),
-    standardCadences: STANDARD,
-    log: () => {},
-  });
-}
-
-// ---------------------------------------------------------------------------
-// the funded envelope reaches the obligations (the PROOF this all rests on)
-// ---------------------------------------------------------------------------
-
-test("a funded envelope produces per-obligation budgets derived from it", () => {
-  const plan = compilePlan({
-    mandate: mandate({
-      objectives: [
-        objective({ key: "a", budgetCentsPerPeriod: 45_000, weight: 3 }),
-        objective({ key: "b", budgetCentsPerPeriod: 15_000, weight: 1 }),
-      ],
-      seatBudgetCents: 60_000,
-      budgetPeriod: "monthly",
-    }),
-    manifest: manifest(),
-    standardCadences: STANDARD,
-    log: () => {},
-  });
-
-  const funded = plan.obligations.filter((o) => Number.isFinite(o.budget_cents_per_period));
-  assert.ok(funded.length >= 4, "each objective yields a measure SCHEDULE + an OUTCOME, both funded");
-  assert.equal(plan.obligations.find((o) => o.key === "outcome.a").budget_cents_per_period, 45_000);
-  assert.equal(plan.obligations.find((o) => o.key === "outcome.b").budget_cents_per_period, 15_000);
-  // The apportioned shares sum to the envelope — no cents invented, none leaked.
-  const outcomes = plan.obligations.filter((o) => o.kind === "OUTCOME");
-  assert.equal(outcomes.reduce((n, o) => n + o.budget_cents_per_period, 0), 60_000);
-  assert.equal(plan.contract.unmetered, false);
-
-  // And the obligations with NO objective behind them stay honestly unmetered
-  // rather than inheriting a fiction.
-  const standard = plan.obligations.find((o) => o.key === "schedule.inbox-processor");
-  assert.equal(standard.budget_cents_per_period, null);
-});
-
-test("an UNFUNDED seat compiles unmetered and says so — it does not invent 500c", () => {
-  const warnings = [];
-  const plan = compilePlan({
-    mandate: mandate({ objectives: [objective({ key: "a" })] }),
-    manifest: manifest(),
-    standardCadences: STANDARD,
-    log: (_l, m) => warnings.push(m),
-  });
-  assert.equal(plan.contract.unmetered, true);
-  assert.ok(plan.obligations.every((o) => o.budget_cents_per_period === null));
-  assert.ok(warnings.some((w) => /no seat envelope/.test(w) && /NOT enforced/.test(w)));
-});
-
-// ---------------------------------------------------------------------------
-// applyBudgetPosture — the 125% rung
-// ---------------------------------------------------------------------------
-
-test("below 125% nothing is suspended", () => {
-  const plan = fundedPlan();
-  for (const band of [0, 80, 100]) {
-    const r = applyBudgetPosture(plan, postureForBand(band));
-    assert.deepEqual(r.suspended, [], `band ${band} must not suspend obligations`);
-    assert.equal(r.drift.length, 0);
-  }
-});
-
-test("at 125% the objective's obligations suspend — and NOTHING else does", () => {
-  const plan = fundedPlan();
-  const r = applyBudgetPosture(plan, postureForBand(125), { spentUSD: 41, capUSD: 30 });
-
-  assert.ok(r.suspended.includes("outcome.gross-margin"));
-  assert.ok(r.suspended.includes("schedule.measure.gross-margin"),
-    "the measure cadence spends on the same warrant as its OUTCOME");
-
-  // The seat's own life-support is untouched at every band.
-  const heartbeat = r.obligations.find((o) => o.key === "schedule.cadence-bus-heartbeat");
-  assert.equal(heartbeat.status, "active", "an inline cadence costs nothing and must never be suspended");
-  // The trap this asserts against: OUTCOME rows are `offline_safe:true`, so an
-  // exemption keyed on that flag suspends nothing at all.
-  assert.equal(r.obligations.find((o) => o.key === "outcome.gross-margin").offline_safe, true);
-  assert.equal(r.obligations.find((o) => o.key === "outcome.gross-margin").status, "suspended");
-  const inbox = r.obligations.find((o) => o.key === "schedule.inbox-processor");
-  assert.equal(inbox.status, "active", "the seat keeps answering its inbox — Invariant #1");
-  for (const react of r.obligations.filter((o) => o.kind === "REACT")) {
-    assert.equal(react.status, "active", "REACT obligations are how a human reaches this seat");
-  }
-
-  // One drift row per suspended obligation, carrying the evidence.
-  assert.equal(r.drift.length, r.suspended.length);
-  for (const d of r.drift) {
-    assert.equal(d.kind, "budget_breach");
-    assert.equal(d.detail.band, 125);
-    assert.equal(d.detail.spentUSD, 41);
-    assert.equal(d.detail.capUSD, 30);
-  }
-});
-
-test("applyBudgetPosture is idempotent and does not mutate its input", () => {
-  const plan = fundedPlan();
-  const before = JSON.stringify(plan.obligations);
-  const once = applyBudgetPosture(plan, postureForBand(125));
-  const twice = applyBudgetPosture({ obligations: once.obligations }, postureForBand(125));
-  assert.equal(JSON.stringify(plan.obligations), before, "the compiled plan is not mutated");
-  assert.deepEqual(twice.suspended, [], "an already-suspended obligation is not re-suspended, nor re-drifted");
-  assert.equal(twice.drift.length, 0);
-});
-
-// ---------------------------------------------------------------------------
-// obligationAllowedUnderPosture — the per-tick form the daemon uses
-// ---------------------------------------------------------------------------
-
-test("the daemon's per-tick gate agrees with the plan-level transition", () => {
-  const outcomeCadence = { kind: "SCHEDULE", scope: "mandate", objective_id: "obj-a", offline_safe: false, mode: "guarded" };
-  const heartbeat = { kind: "SCHEDULE", scope: "standard", objective_id: null, offline_safe: true, mode: "inline" };
-  const standard = { kind: "SCHEDULE", scope: "standard", objective_id: null, offline_safe: false, mode: "guarded" };
-
-  assert.equal(obligationAllowedUnderPosture(outcomeCadence, postureForBand(100)).allowed, true);
-  assert.equal(obligationAllowedUnderPosture(outcomeCadence, postureForBand(125)).allowed, false);
-  assert.match(obligationAllowedUnderPosture(outcomeCadence, postureForBand(125)).reason, /suspended/);
-
-  // Life support, at the worst band there is.
-  assert.equal(obligationAllowedUnderPosture(heartbeat, postureForBand(150)).allowed, true);
-
-  // >150%: a plain standard cadence is a spawn that is not a human reply.
-  assert.equal(obligationAllowedUnderPosture(standard, postureForBand(125)).allowed, true);
-  assert.equal(obligationAllowedUnderPosture(standard, postureForBand(150)).allowed, false);
-  assert.match(obligationAllowedUnderPosture(standard, postureForBand(150)).reason, /not a direct human reply/);
-});
-
-// ---------------------------------------------------------------------------
-// reconcileBudgetPosture — drift on the band EDGE, plan file untouched
-// ---------------------------------------------------------------------------
-
-async function tmpRoot() {
-  const dir = join(tmpdir(), `budget-runtime-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
-  await fsp.mkdir(join(dir, "state", "plan"), { recursive: true });
-  return dir;
-}
-
-test("reconcile records budget_breach drift once per band edge, not once per tick", async () => {
-  const root = await tmpRoot();
-  try {
-    const plan = fundedPlan();
-    const drift = [];
-    const deps = { plan, appendDrift: (row) => { drift.push(row); return true; }, log: () => {} };
-
-    const first = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(125), status: { spentUSD: 41, capUSD: 30, pct: 137 } }, deps);
-    assert.ok(first.suspended.length >= 2);
-    assert.equal(first.recorded, first.suspended.length);
-    assert.equal(readPosture(root).band, 125, "the acted-on band is persisted");
-
-    const again = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(125), status: {} }, deps);
-    assert.equal(again.recorded, 0, "same band, same tick-after-tick: no new rows");
-    assert.equal(drift.length, first.recorded);
-
-    // Coming back DOWN is an edge too — a human who saw the suspension needs the
-    // clearing edge as well.
-    const down = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(0), status: {} }, deps);
-    assert.equal(down.suspended.length, 0);
-    assert.equal(readPosture(root).band, 0);
-  } finally { await fsp.rm(root, { recursive: true, force: true }); }
-});
-
-test("a breach is mirrored to hq, and the clearing edge resolves it there", async () => {
-  const root = await tmpRoot();
-  try {
-    const plan = fundedPlan();
-    const mirrored = [];
-    const deps = {
-      plan,
-      appendDrift: () => true,
-      log: () => {},
-      mirrorDrift: async (row) => { mirrored.push(row); return { ok: true }; },
-    };
-
-    const up = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(125), status: { spentUSD: 41, capUSD: 30 } }, deps);
-    assert.equal(up.mirrored, up.drift.length);
-    assert.ok(mirrored.every((m) => m.kind === "budget_breach" && !m.resolve));
-
-    // Back under the ceiling: the open rows are RESOLVED at hq, or the org shows
-    // a permanently-breached seat that has in fact recovered.
-    mirrored.length = 0;
-    const down = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(0), status: {} }, deps);
-    assert.equal(down.suspended.length, 0);
-    assert.ok(mirrored.length > 0, "the clearing edge is reported too");
-    assert.ok(mirrored.every((m) => m.resolve === true));
-  } finally { await fsp.rm(root, { recursive: true, force: true }); }
-});
-
-test("an hq that rejects or throws never blocks the LOCAL suspension", async () => {
-  const root = await tmpRoot();
-  try {
-    const plan = fundedPlan();
-    const logged = [];
-    const local = [];
-    const r = await reconcileBudgetPosture(
-      { agentRoot: root, posture: postureForBand(125), status: {} },
-      {
-        plan,
-        appendDrift: (row) => { local.push(row); return true; },
-        log: (l, m) => logged.push(`${l}:${m}`),
-        mirrorDrift: async () => { throw new Error("hq unreachable"); },
-      }
-    );
-    assert.ok(r.suspended.length > 0, "the obligations are still suspended");
-    assert.equal(r.recorded, local.length, "and the local record is complete");
-    assert.equal(r.mirrored, 0);
-    assert.ok(logged.some((l) => /could not mirror/.test(l)), "the mirror failure is named, not swallowed");
-  } finally { await fsp.rm(root, { recursive: true, force: true }); }
-});
-
-test("a seat with no compiled plan reconciles cleanly instead of throwing", async () => {
-  const root = await tmpRoot();
-  try {
-    const logged = [];
-    const r = await reconcileBudgetPosture(
-      { agentRoot: root, posture: postureForBand(150), status: {} },
-      { log: (l, m) => logged.push(`${l}:${m}`) }
-    );
-    assert.equal(r.ok, true);
-    assert.deepEqual(r.suspended, []);
-    assert.match(r.reason, /config\/plan\.yaml is absent/);
-    assert.ok(logged.some((l) => /no plan to suspend/.test(l)), "and it says so rather than passing silently");
-  } finally { await fsp.rm(root, { recursive: true, force: true }); }
-});
-
-// ---------------------------------------------------------------------------
-// BAND 150 MUST NOT SILENCE THE INBOX
-// ---------------------------------------------------------------------------
-
-test("band 150 defers discretionary cadences but NEVER the human lane", () => {
-  // The 150% rung was implemented as `kind !== "REACT"`, and every cadence the
-  // consumer evaluates is a SCHEDULE — so `inbox-processor` and
-  // `messaging-inbound` (the only puller of org DMs and @mentions) were deferred
-  // too. It only looked harmless because both guards default to
-  // `decision:"inline"` and return before the gate; set INBOX_CADENCE_ESCALATE=1
-  // or MESSAGING_INBOUND_ESCALATE=1 — the documented cadence-only mode — and the
-  // seat stopped reading its inbox at a budget breach. That is the bricking
-  // Invariant #1 forbids.
-  const posture = postureForBand(150);
-  assert.equal(posture.refuseNonHumanSpawn, true);
-
-  const inbox = { key: "schedule.inbox-processor", kind: "SCHEDULE", mode: "guarded", human_lane: true, status: "active" };
-  const inbound = { key: "schedule.messaging-inbound", kind: "SCHEDULE", mode: "guarded", human_lane: true, status: "active" };
-  const backlog = { key: "schedule.backlog-executor", kind: "SCHEDULE", mode: "guarded", human_lane: false, status: "active" };
-  const react = { key: "react.task.assigned", kind: "REACT", mode: "escalate", status: "active" };
-
-  assert.equal(obligationAllowedUnderPosture(inbox, posture).allowed, true, "the seat keeps reading its inbox");
-  assert.equal(obligationAllowedUnderPosture(inbound, posture).allowed, true, "and keeps PULLING messages into it");
-  assert.equal(obligationAllowedUnderPosture(react, posture).allowed, true);
-  assert.equal(obligationAllowedUnderPosture(backlog, posture).allowed, false, "discretionary work does defer");
-  assert.match(obligationAllowedUnderPosture(backlog, posture).reason, /not a direct human reply/);
-});
-
-test("the compiler STAMPS the human lane on the plan, so an operator can read it", () => {
-  // Inferring the lane at enforcement time would leave the plan on disk silent
-  // about which obligations a breach may never stop.
-  const plan = compilePlan({
-    mandate: {},
-    manifest: { entries: [] },
-    standardCadences: [
-      { id: "inbox-processor", scope: "standard", mode: "guarded", interval: 300 },
-      { id: "messaging-inbound", scope: "standard", mode: "guarded", interval: 45 },
-      { id: "backlog-executor", scope: "standard", mode: "guarded", interval: 600 },
-      { id: "dynamic-jobs", scope: "standard", mode: "guarded", interval: 60 },
-    ],
-    log: () => {},
-  });
-  const laneOf = (id) => plan.obligations.find((o) => o.key === `schedule.${id}`).human_lane;
-  assert.equal(laneOf("inbox-processor"), true);
-  assert.equal(laneOf("messaging-inbound"), true);
-  assert.equal(laneOf("backlog-executor"), false);
-  assert.equal(laneOf("dynamic-jobs"), false, "the agent's own reminders are not somebody waiting on a reply");
-});
-
-test("STRUCTURAL: the drift return-leg runs on the MONEY clock, not the daily one", async () => {
-  // `reconcileBudgetPosture` had exactly one caller: `guardGoalSteward`, which
-  // `lib/cadences.mjs` schedules at 07:15 DAILY — while the band it reads resets
-  // at UTC midnight. A seat could hit 150% every afternoon for a month and hq
-  // would never see one `budget_breach` drift row, because by the next 07:15 the
-  // band it observed was 0 again. Local enforcement was fine (`governanceGate`
-  // re-reads per tick); it was the RECORD — the thing the person who funds the
-  // seat looks at — that never arrived.
-  const { readFileSync } = await import("node:fs");
-  const { fileURLToPath } = await import("node:url");
-  const root = fileURLToPath(new URL("../../", import.meta.url));
-
-  const consumer = readFileSync(`${root}scripts/daemon/cadence-consumer.mjs`, "utf-8");
-  assert.match(consumer, /reconcileBudgetPosture/, "the consumer reconciles the posture itself");
-
-  // It must live inside the escalation timer (the 5-minute one), not in a
-  // calendar-scheduled handler.
-  const timerAt = consumer.indexOf("const escalateTimer");
-  const reconcileAt = consumer.indexOf("reconcileBudgetPosture", timerAt);
-  const timerEndsAt = consumer.indexOf("}, budgetEscalateMs)", timerAt);
-  assert.ok(timerAt > 0 && reconcileAt > timerAt && reconcileAt < timerEndsAt,
-    "the reconcile is inside the budgetEscalateMs timer");
-  assert.match(consumer, /DEFAULT_BUDGET_ESCALATE_MS = 5 \* 60_000/, "and that timer is 5 minutes");
-
-  // The daily caller stays — it is idempotent and harmless — but it is no longer
-  // the only one.
-  const handlers = readFileSync(`${root}scripts/daemon/cadence-handlers.mjs`, "utf-8");
-  assert.match(handlers, /reconcileBudgetPosture/);
-});