@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/goals/gaps.test.mjs

@@ -0,0 +1,284 @@
+/**
+ * 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");
+});