@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/goals/gaps.test.mjs

@@ -1,284 +0,0 @@
-/**
- * lib/goals/gaps.test.mjs — the read-only bridge between measured KPI series
- * and the daemon's backlog ranking, plus the gap-weighted ranking itself.
- *
- * The invariant that matters most: **an agent with no mandate, a stale mandate,
- * or no measurements must rank its backlog EXACTLY as it does today.** The gap
- * term can promote goal-linked work; it must never silently reorder a fleet's
- * seeded backlog because a cache went missing.
- */
-
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { readLatestGaps } from "./gaps.mjs";
-import {
-  scoreQueueItem, rankBacklog, resolveBacklogWeights,
-  DEFAULT_BACKLOG_WEIGHTS, PRIORITY_ORDER, parseQueueItems,
-} from "../backlog.mjs";
-
-const NOW = Date.parse("2026-08-11T09:00:00.000Z");
-const SELF = "mem_self";
-
-function record(over = {}) {
-  return {
-    version: 3,
-    source: "server",
-    fetchedAt: new Date(NOW - 3600_000).toISOString(),
-    body: {
-      memberId: SELF,
-      objectives: [
-        { key: "revenue", kind: "PILLAR", state: "active", charterSectionId: "cs_1", adoptedById: "mem_boss" },
-        {
-          key: "pipeline", kind: "OBJECTIVE", parentKey: "revenue", state: "active",
-          metric: "pipeline_coverage_x", target: 4, direction: "up", tolerance: 0, cadence: "weekly",
-          sensor: { capability: "crm_list_deals", source: "method" }, adoptedById: "mem_boss",
-        },
-      ],
-    },
-    ...over,
-  };
-}
-
-/** An injected series reader: objectiveKey → rows. */
-function seriesFrom(map) {
-  return (_root, key) => map[key] || [];
-}
-
-// ---------------------------------------------------------------------------
-// readLatestGaps
-// ---------------------------------------------------------------------------
-
-test("a measured, missed objective yields a normalized gap", () => {
-  const gaps = readLatestGaps("/tmp", {
-    cacheRecord: record(),
-    now: () => NOW,
-    readSeries: seriesFrom({
-      pipeline: [{ value: 1, window: "2026-W33", at: new Date(NOW - 3600_000).toISOString(), source: "method" }],
-    }),
-  });
-  assert.ok(gaps.pipeline);
-  assert.equal(gaps.pipeline.value, 1);
-  assert.equal(gaps.pipeline.target, 4);
-  assert.equal(gaps.pipeline.gap, 3);
-  assert.equal(gaps.pipeline.normalizedGap, 0.75);
-});
-
-test("NO MANDATE: an empty map, logged at info — the ranking degrades, it does not break", () => {
-  const logs = [];
-  const gaps = readLatestGaps("/tmp", { cacheRecord: null, now: () => NOW, log: (l, m) => logs.push(`${l}:${m}`) });
-  assert.deepEqual(gaps, {});
-  assert.ok(logs.some((l) => /no mandate cache/.test(l)), "the degradation must be visible");
-});
-
-test("CORRUPT MANDATE: an empty map, logged at WARN", () => {
-  const logs = [];
-  const gaps = readLatestGaps("/tmp", {
-    cacheRecord: { corrupt: true, reason: "bad json", body: {} },
-    now: () => NOW, log: (l, m) => logs.push(`${l}:${m}`),
-  });
-  assert.deepEqual(gaps, {});
-  assert.ok(logs.some((l) => l.startsWith("warn:") && /corrupt/.test(l)));
-});
-
-test("EXPIRED MANDATE (>7d): stops steering dispatch entirely", () => {
-  const logs = [];
-  const gaps = readLatestGaps("/tmp", {
-    cacheRecord: record({ fetchedAt: new Date(NOW - 8 * 24 * 3600 * 1000).toISOString() }),
-    now: () => NOW,
-    log: (l, m) => logs.push(`${l}:${m}`),
-    readSeries: seriesFrom({ pipeline: [{ value: 1, at: new Date(NOW).toISOString(), source: "method" }] }),
-  });
-  assert.deepEqual(gaps, {}, "ranking on a week-old target is worse than not ranking");
-  assert.ok(logs.some((l) => /expired/.test(l)));
-});
-
-test("PROPOSED objectives never influence dispatch order", () => {
-  const rec = record();
-  rec.body.objectives[1].state = "proposed";
-  const gaps = readLatestGaps("/tmp", {
-    cacheRecord: rec, now: () => NOW,
-    readSeries: seriesFrom({ pipeline: [{ value: 1, at: new Date(NOW).toISOString(), source: "method" }] }),
-  });
-  assert.deepEqual(gaps, {});
-});
-
-test("a SELF-ADOPTED objective cannot float its own backlog", () => {
-  const rec = record();
-  rec.body.objectives[1].adoptedById = SELF;
-  const gaps = readLatestGaps("/tmp", {
-    cacheRecord: rec, now: () => NOW,
-    readSeries: seriesFrom({ pipeline: [{ value: 1, at: new Date(NOW).toISOString(), source: "method" }] }),
-  });
-  assert.deepEqual(gaps, {}, "a seat that grades itself must not also get dispatch priority for it");
-});
-
-test("a STALE SENSOR contributes zero urgency, not stale urgency", () => {
-  const gaps = readLatestGaps("/tmp", {
-    cacheRecord: record(), now: () => NOW,
-    readSeries: seriesFrom({
-      // Three weeks old against a weekly cadence.
-      pipeline: [{ value: 1, at: new Date(NOW - 21 * 24 * 3600 * 1000).toISOString(), source: "method" }],
-    }),
-  });
-  assert.equal(gaps.pipeline.stale, true);
-  assert.equal(gaps.pipeline.normalizedGap, 0);
-});
-
-test("a series reader that throws is contained per objective", () => {
-  const logs = [];
-  const gaps = readLatestGaps("/tmp", {
-    cacheRecord: record(), now: () => NOW,
-    log: (l, m) => logs.push(`${l}:${m}`),
-    readSeries: () => { throw new Error("disk gone"); },
-  });
-  assert.deepEqual(gaps, {});
-  assert.ok(logs.some((l) => /could not compute the gap/.test(l)));
-});
-
-// ---------------------------------------------------------------------------
-// Weights
-// ---------------------------------------------------------------------------
-
-test("charter rewardWeights override the defaults, per key, ignoring junk", () => {
-  assert.deepEqual(resolveBacklogWeights(null), DEFAULT_BACKLOG_WEIGHTS);
-  assert.deepEqual(resolveBacklogWeights({ rewardWeights: { gap: 3 } }), { priority: 1, gap: 3, age: 0.25 });
-  // Junk must not poison the ranking.
-  assert.deepEqual(
-    resolveBacklogWeights({ rewardWeights: { gap: "lots", priority: -5, age: NaN } }),
-    DEFAULT_BACKLOG_WEIGHTS
-  );
-  assert.deepEqual(resolveBacklogWeights({ reward_weights: { age: 0 } }).age, 0);
-});
-
-// ---------------------------------------------------------------------------
-// Scoring + ranking
-// ---------------------------------------------------------------------------
-
-test("with no gaps at all, ranking reproduces today's flat priority order exactly", () => {
-  const items = [
-    { title: "n", priority: "normal" },
-    { title: "c", priority: "critical" },
-    { title: "l", priority: "low" },
-    { title: "h", priority: "high" },
-  ];
-  const ranked = rankBacklog(items, { now: NOW });
-  assert.deepEqual(ranked.map((r) => r.title), ["c", "h", "n", "l"]);
-
-  // …which is precisely the legacy sort.
-  const legacy = [...items].sort((a, b) => (PRIORITY_ORDER[a.priority] ?? 3) - (PRIORITY_ORDER[b.priority] ?? 3));
-  assert.deepEqual(ranked.map((r) => r.title), legacy.map((r) => r.title));
-});
-
-test("a badly-missed objective promotes its work above an equal-priority peer", () => {
-  const items = [
-    { title: "unlinked", priority: "normal" },
-    { title: "goal-linked", priority: "normal", advances: ["pipeline"], expected_delta: 1 },
-  ];
-  const gapsByObjective = { pipeline: { normalizedGap: 0.75 } };
-  const ranked = rankBacklog(items, { gapsByObjective, now: NOW });
-  assert.equal(ranked[0].title, "goal-linked");
-  assert.ok(ranked[0]._scoreParts.gapTerm > 0);
-  assert.equal(ranked[1]._scoreParts.gapTerm, 0);
-});
-
-test("an unmeasured objective manufactures NO urgency", () => {
-  const items = [
-    { title: "critical-unlinked", priority: "critical" },
-    { title: "linked-but-unmeasured", priority: "low", advances: ["pipeline"], expected_delta: 1 },
-  ];
-  // The objective exists but has never been measured.
-  const ranked = rankBacklog(items, { gapsByObjective: { pipeline: { normalizedGap: 0 } }, now: NOW });
-  assert.equal(ranked[0].title, "critical-unlinked");
-});
-
-test("a claimed delta with no measured gap, or a gap with no claimed delta, scores zero", () => {
-  const noDelta = scoreQueueItem({ priority: "normal", advances: ["pipeline"] }, { gapsByObjective: { pipeline: { normalizedGap: 0.9 } } });
-  assert.equal(noDelta.gapTerm, 0, "a gap with no expected delta is not evidence this item helps");
-  const noGap = scoreQueueItem({ priority: "normal", advances: ["pipeline"], expected_delta: 1 }, { gapsByObjective: {} });
-  assert.equal(noGap.gapTerm, 0);
-});
-
-test("the gap term cannot outrank a whole priority level on its own", () => {
-  // Worst possible gap and a full claimed delta.
-  const linked = scoreQueueItem(
-    { priority: "normal", advances: ["pipeline"], expected_delta: 99 },
-    { gapsByObjective: { pipeline: { normalizedGap: 99 } }, weights: DEFAULT_BACKLOG_WEIGHTS }
-  );
-  const critical = scoreQueueItem({ priority: "critical" }, { weights: DEFAULT_BACKLOG_WEIGHTS });
-  // normal(1) + gap(≤1) == 2 < critical(3). A KPI gap escalates work; it does
-  // not let the agent redefine what "critical" means.
-  assert.ok(linked.score <= critical.score, `${linked.score} must not exceed critical ${critical.score}`);
-});
-
-test("the age penalty stops a permanently-lagging KPI starving everything else", () => {
-  const gapsByObjective = { pipeline: { normalizedGap: 0.5 } };
-  const fresh = scoreQueueItem(
-    { priority: "normal", advances: ["pipeline"], expected_delta: 1, created: new Date(NOW).toISOString() },
-    { gapsByObjective, now: NOW }
-  );
-  const old = scoreQueueItem(
-    { priority: "normal", advances: ["pipeline"], expected_delta: 1, created: "2026-01-01" },
-    { gapsByObjective, now: NOW }
-  );
-  assert.ok(old.agePenalty > fresh.agePenalty);
-  assert.ok(old.score < fresh.score);
-  // …but bounded, so it can never invert a whole priority level either.
-  assert.ok(old.agePenalty <= 2 * DEFAULT_BACKLOG_WEIGHTS.age);
-});
-
-test("ranking is stable and total — equal scores keep their input order", () => {
-  const items = [
-    { title: "a", priority: "normal" },
-    { title: "b", priority: "normal" },
-    { title: "c", priority: "normal" },
-  ];
-  assert.deepEqual(rankBacklog(items, { now: NOW }).map((r) => r.title), ["a", "b", "c"]);
-  // And it is a pure function of its inputs.
-  assert.deepEqual(rankBacklog(items, { now: NOW }), rankBacklog(items, { now: NOW }));
-});
-
-test("rankBacklog never mutates its input", () => {
-  const items = [{ title: "a", priority: "low" }, { title: "b", priority: "critical" }];
-  const copy = JSON.parse(JSON.stringify(items));
-  rankBacklog(items, { now: NOW });
-  assert.deepEqual(items, copy);
-});
-
-test("junk in, no crash out", () => {
-  assert.deepEqual(rankBacklog(null), []);
-  assert.deepEqual(rankBacklog(undefined, {}), []);
-  const s = scoreQueueItem({}, {});
-  assert.ok(Number.isFinite(s.score));
-  const weird = scoreQueueItem({ priority: "nonsense", advances: "not-an-array" }, {});
-  assert.ok(Number.isFinite(weird.score));
-});
-
-test("end to end: a rendered goals.yaml parses and ranks by its measured gap", () => {
-  const yaml = [
-    "queue: goals",
-    "items:",
-    '  - id: seeded-1',
-    '    title: "Seeded archetype work"',
-    "    status: open",
-    "    priority: normal",
-    '    next_action: "Do the seeded thing"',
-    "    created: 2026-08-11",
-    '  - id: goal-1',
-    '    title: "Close the pipeline gap"',
-    "    status: open",
-    "    priority: normal",
-    '    next_action: "Book calls"',
-    "    advances: [pipeline]",
-    "    expected_delta: 1.5",
-    "    obligation_key: outcome.pipeline",
-    "    disposition: SELF",
-    "    created: 2026-08-11",
-  ].join("\n");
-  const parsed = parseQueueItems(yaml, "goals.yaml");
-  assert.equal(parsed.length, 2);
-  const ranked = rankBacklog(parsed, { gapsByObjective: { pipeline: { normalizedGap: 0.75 } }, now: NOW });
-  assert.equal(ranked[0].id, "goal-1", "the measured gap must win between equal priorities");
-});