@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/mandate/refresh.test.mjs

@@ -1,389 +0,0 @@
-/**
- * lib/mandate/refresh.test.mjs — "derived at init from charter/role, refreshed
- * on a cadence", plus the cache and its staleness ladder.
- *
- * The load-bearing rule under test: **an adopted server snapshot always beats a
- * local derivation.** A partitioned agent falls back to what it can derive, but
- * the moment it has once held a real mandate, no local derivation may overwrite
- * it — otherwise a network blip would silently demote adopted objectives to
- * proposed ones and the agent would quietly stop working toward them.
- */
-
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { refreshMandate, fetchSnapshot, GET_METHOD } from "./refresh.mjs";
-import {
-  readCache, writeCache, cachePath, checksumOf, canonical,
-  staleSeconds, stalenessTier, permissionsForTier, adoptedObjectives, TIERS,
-} from "./cache.mjs";
-
-const NOW = Date.parse("2026-08-11T09:00:00.000Z");
-
-function makeRoot() {
-  return mkdtempSync(join(tmpdir(), "mandate-refresh-"));
-}
-function cleanup(root) {
-  try { rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
-}
-
-/**
- * A body in the shape hq ACTUALLY publishes — contract v1, every key the
- * compiler reads present, budgets sourced and apportioned. This fixture used to
- * carry only `{memberId, objectives}`, which is precisely the pre-contract shape
- * that let `budgetCentsPerPeriod` be `undefined` all the way into the compiler.
- * Keep it in sync with hq's `_contract.ts#MANDATE_BODY_KEYS`.
- */
-const BODY = {
-  contractVersion: 1,
-  memberId: "mem_self",
-  objectives: [
-    { key: "revenue", kind: "PILLAR", state: "active", charterSectionId: "cs_1", adoptedById: "mem_boss", budgetCentsPerPeriod: null },
-    {
-      key: "pipeline", kind: "OBJECTIVE", parentKey: "revenue", state: "active",
-      metric: "pipeline_coverage_x", target: 3, direction: "up", cadence: "weekly",
-      sensor: { capability: "crm_list_deals", source: "method" }, adoptedById: "mem_boss",
-      weight: 1, budgetCentsPerPeriod: 25_000,
-    },
-  ],
-  proposed: [],
-  budgetCentsPerPeriod: null,
-  seatBudgetCents: 25_000,
-  budgetPeriod: "monthly",
-  budgetSource: "employee.payBasis.meteredBudget",
-  collaborators: [{ memberId: "mem_boss", role: "REVIEWER", source: "workforceMember.supervisorId" }],
-  reactsTo: [],
-  degradations: [],
-  generatedAt: "2026-08-11T00:00:00.000Z",
-};
-
-/** The shape hq sent BEFORE the contract. Kept to prove it is now caught. */
-const LEGACY_BODY = { memberId: "mem_self", objectives: BODY.objectives, proposed: [], generatedAt: BODY.generatedAt };
-
-const DERIVATION = {
-  charterSections: [{ id: "cs_1", kind: "PILLAR", order: 1, title: "Revenue growth", body: "Own revenue." }],
-  kpiCategories: [{ id: "pipeline", name: "Pipeline coverage", examples: ["pipeline_coverage_x"] }],
-};
-
-// ---------------------------------------------------------------------------
-// Cache primitives
-// ---------------------------------------------------------------------------
-
-test("canonical JSON is key-order independent, so the checksum is stable", () => {
-  assert.equal(canonical({ b: 1, a: 2 }), canonical({ a: 2, b: 1 }));
-  assert.equal(checksumOf({ b: 1, a: 2 }), checksumOf({ a: 2, b: 1 }));
-  assert.notEqual(checksumOf({ a: 1 }), checksumOf({ a: 2 }));
-});
-
-test("a missing cache is null; a CORRUPT cache is reported as corrupt, never as empty", () => {
-  const root = makeRoot();
-  try {
-    assert.equal(readCache(root), null);
-    mkdirSync(join(root, "state", "mandate"), { recursive: true });
-    writeFileSync(cachePath(root), "{not json", "utf-8");
-    const rec = readCache(root);
-    assert.equal(rec.corrupt, true);
-    assert.ok(rec.reason, "a corrupt cache must carry the parse reason — silence is the bug");
-  } finally { cleanup(root); }
-});
-
-test("the staleness ladder degrades on a ramp, not a cliff", () => {
-  const at = (secs) => ({ fetchedAt: new Date(NOW - secs * 1000).toISOString() });
-  assert.equal(stalenessTier(at(3600), NOW), "fresh");
-  assert.equal(stalenessTier(at(TIERS.fresh + 1), NOW), "aging");
-  assert.equal(stalenessTier(at(TIERS.aging + 1), NOW), "stale");
-  assert.equal(stalenessTier(at(TIERS.stale + 1), NOW), "expired");
-  // Never fetched at all is maximally stale, not accidentally fresh.
-  assert.equal(staleSeconds(null, NOW), Infinity);
-  assert.equal(stalenessTier({}, NOW), "expired");
-
-  // The ramp itself: OUTCOME work dies first, REACT last.
-  assert.deepEqual(permissionsForTier("fresh"), { react: "full", schedule: "full", outcome: "full" });
-  assert.equal(permissionsForTier("aging").outcome, "suspended");
-  assert.equal(permissionsForTier("aging").react, "full");
-  assert.equal(permissionsForTier("stale").react, "offline_safe");
-  assert.equal(permissionsForTier("expired").react, "none");
-});
-
-test("adoptedObjectives from the cache carries the WHOLE law, not just the state column", () => {
-  // cache.mjs used to export a second, law-free implementation that filtered on
-  // `state === "active"` alone — so whichever module a caller happened to import
-  // decided whether the anti-Goodhart law applied. It now delegates to
-  // lib/mandate/model.adoptedObjectives. One law, one implementation.
-  const rec = {
-    body: {
-      memberId: "M-OWNER",
-      objectives: [
-        { key: "a", kind: "OBJECTIVE", state: "active", adoptedById: "M-SUPERVISOR" },
-        { key: "b", kind: "OBJECTIVE", state: "proposed", adoptedById: "M-SUPERVISOR" },
-        { key: "c", kind: "OBJECTIVE", state: "active", adoptedById: "M-OWNER" },   // self-adopted
-        { key: "d", kind: "OBJECTIVE", state: "active" },                            // no provenance
-      ],
-    },
-  };
-  assert.deepEqual(adoptedObjectives(rec).map((o) => o.key), ["a"]);
-  assert.deepEqual(adoptedObjectives(null), []);
-});
-
-test("writeCache round-trips and stamps a checksum over the body", () => {
-  const root = makeRoot();
-  try {
-    const rec = writeCache(root, { version: 7, body: BODY, source: "server" });
-    assert.equal(rec.version, 7);
-    assert.equal(rec.checksum, checksumOf(BODY));
-    const back = readCache(root);
-    assert.deepEqual(back.body, BODY);
-    assert.equal(back.source, "server");
-  } finally { cleanup(root); }
-});
-
-// ---------------------------------------------------------------------------
-// fetchSnapshot — every failure mode is a distinct reason
-// ---------------------------------------------------------------------------
-
-test("fetchSnapshot returns the snapshot on an ok frame", async () => {
-  const seen = [];
-  const r = await fetchSnapshot({
-    memberId: "mem_self",
-    callImpl: async (method, params) => {
-      seen.push({ method, params });
-      return { ok: true, result: { version: 4, checksum: "abc", body: BODY } };
-    },
-  });
-  assert.equal(seen[0].method, GET_METHOD);
-  assert.equal(r.ok, true);
-  assert.equal(r.snapshot.version, 4);
-});
-
-test("SERVER UNREACHABLE: a thrown call is a distinct, reportable reason", async () => {
-  const r = await fetchSnapshot({ callImpl: async () => { throw new Error("ECONNREFUSED"); } });
-  assert.equal(r.ok, false);
-  assert.match(r.reason, /^call-threw:/);
-  assert.match(r.reason, /ECONNREFUSED/);
-});
-
-test("a protocol without the mandate family is named exactly, not lumped in with a 404", async () => {
-  const r = await fetchSnapshot({
-    callImpl: async () => ({ ok: false, error: { code: "NOT_FOUND", message: "unknown method mandate.get" } }),
-  });
-  assert.equal(r.reason, "protocol-missing-mandate-family");
-});
-
-test("an ordinary error frame carries its code", async () => {
-  const r = await fetchSnapshot({ callImpl: async () => ({ ok: false, error: { code: "FORBIDDEN" } }) });
-  assert.equal(r.reason, "call-failed:FORBIDDEN");
-});
-
-// ---------------------------------------------------------------------------
-// refreshMandate
-// ---------------------------------------------------------------------------
-
-test("the online path caches the adopted snapshot and reports it changed", async () => {
-  const root = makeRoot();
-  try {
-    const r = await refreshMandate(root, {
-      memberId: "mem_self",
-      now: () => NOW,
-      callImpl: async () => ({ ok: true, result: { version: 4, checksum: checksumOf(BODY), body: BODY } }),
-    });
-    assert.equal(r.ok, true);
-    assert.equal(r.source, "server");
-    assert.equal(r.degraded, false);
-    assert.equal(r.changed, true);
-    assert.equal(r.tier, "fresh");
-    assert.equal(readCache(root).source, "server");
-
-    // A second identical refresh must report NO change, so nothing on disk churns.
-    const again = await refreshMandate(root, {
-      memberId: "mem_self", now: () => NOW,
-      callImpl: async () => ({ ok: true, result: { version: 4, checksum: checksumOf(BODY), body: BODY } }),
-    });
-    assert.equal(again.changed, false);
-  } finally { cleanup(root); }
-});
-
-test("a PRE-CONTRACT snapshot is cached but reported DEGRADED and LOUD", async () => {
-  // The original break: hq sent this exact shape, `refreshMandate` reported
-  // `degraded:false, reason:"fetched the adopted snapshot"`, and the compiler
-  // then invented 500c for every obligation. Adopted objectives still beat
-  // nothing, so it is still cached — but it may never look clean again.
-  const root = makeRoot();
-  const logs = [];
-  try {
-    const r = await refreshMandate(root, {
-      memberId: "mem_self",
-      now: () => NOW,
-      log: (level, msg) => logs.push(`${level}: ${msg}`),
-      callImpl: async () => ({ ok: true, result: { version: 4, checksum: checksumOf(LEGACY_BODY), body: LEGACY_BODY } }),
-    });
-    assert.equal(r.ok, true);
-    assert.equal(r.source, "server");
-    assert.equal(r.degraded, true, "a body the compiler cannot budget from is degraded");
-    assert.equal(r.contract.ok, false);
-    for (const k of ["budgetCentsPerPeriod", "seatBudgetCents", "collaborators", "reactsTo", "contractVersion"]) {
-      assert.ok(r.contract.missing.includes(k), `contract.missing names ${k}`);
-    }
-    assert.match(r.reason, /violates mandate contract v1/);
-    // Still cached — the adopted tree is worth more than nothing.
-    assert.equal(readCache(root).source, "server");
-    assert.ok(logs.some((l) => l.startsWith("error:")), "the violation is logged, not swallowed");
-  } finally { cleanup(root); }
-});
-
-test("SERVER UNREACHABLE, no prior cache: falls back to the local derivation, degraded and LOUD", async () => {
-  const root = makeRoot();
-  try {
-    const logs = [];
-    const r = await refreshMandate(root, {
-      memberId: "mem_self",
-      now: () => NOW,
-      log: (lvl, msg) => logs.push(`${lvl}:${msg}`),
-      callImpl: async () => { throw new Error("ECONNREFUSED"); },
-      derivation: DERIVATION,
-    });
-    assert.equal(r.ok, true);
-    assert.equal(r.source, "local");
-    assert.equal(r.degraded, true, "a local derivation is ALWAYS degraded — it is proposed, not adopted");
-    assert.ok(r.counts.pillars >= 1);
-    assert.ok(logs.some((l) => l.startsWith("warn:")), "the degradation must be logged, never silent");
-
-    // And critically: everything it derived is PROPOSED, so it drives no work.
-    for (const o of readCache(root).body.objectives) assert.equal(o.state, "proposed");
-  } finally { cleanup(root); }
-});
-
-test("SERVER UNREACHABLE with a prior SERVER snapshot: the adopted mandate is KEPT, not overwritten", async () => {
-  const root = makeRoot();
-  try {
-    // The agent once held a real, adopted mandate.
-    writeCache(root, { version: 4, body: BODY, source: "server" });
-
-    const logs = [];
-    const r = await refreshMandate(root, {
-      memberId: "mem_self",
-      now: () => NOW,
-      log: (lvl, msg) => logs.push(`${lvl}:${msg}`),
-      callImpl: async () => { throw new Error("ECONNREFUSED"); },
-      derivation: DERIVATION,
-    });
-
-    assert.equal(r.source, "cache");
-    assert.equal(r.degraded, true);
-    assert.equal(r.changed, false);
-    // The adopted objectives survive the partition intact.
-    const cached = readCache(root);
-    assert.equal(cached.source, "server");
-    assert.deepEqual(cached.body, BODY);
-    assert.equal(cached.body.objectives[1].state, "active");
-    assert.ok(logs.some((l) => /never supersedes adopted/.test(l)));
-  } finally { cleanup(root); }
-});
-
-test("offline:true skips the fetch entirely and derives locally", async () => {
-  const root = makeRoot();
-  try {
-    let called = 0;
-    const r = await refreshMandate(root, {
-      memberId: "mem_self", now: () => NOW, offline: true,
-      callImpl: async () => { called += 1; return { ok: true, result: { body: BODY } }; },
-      derivation: DERIVATION,
-    });
-    assert.equal(called, 0, "offline must not touch the network");
-    assert.equal(r.source, "local");
-    assert.match(r.reason, /offline/);
-  } finally { cleanup(root); }
-});
-
-test("a checksum mismatch is warned about but still cached — the mandate is not lost to a vendoring drift", async () => {
-  const root = makeRoot();
-  try {
-    const logs = [];
-    const r = await refreshMandate(root, {
-      memberId: "mem_self", now: () => NOW,
-      log: (lvl, msg) => logs.push(`${lvl}:${msg}`),
-      callImpl: async () => ({ ok: true, result: { version: 4, checksum: "sha256:not-the-real-one", body: BODY } }),
-    });
-    assert.equal(r.source, "server");
-    assert.ok(logs.some((l) => /checksum mismatch/.test(l)));
-    // The LOCAL checksum is what gets stored, so drift detection stays honest.
-    assert.equal(readCache(root).checksum, checksumOf(BODY));
-  } finally { cleanup(root); }
-});
-
-test("an invalid adopted snapshot is cached but every error is surfaced", async () => {
-  const root = makeRoot();
-  try {
-    const logs = [];
-    const bad = {
-      memberId: "mem_self",
-      objectives: [
-        // Active, measurable, and adopted by its own owner: the Goodhart hole.
-        {
-          key: "self-graded", kind: "OBJECTIVE", state: "active", metric: "m", target: 1,
-          cadence: "weekly", adoptedById: "mem_self",
-        },
-      ],
-    };
-    const r = await refreshMandate(root, {
-      memberId: "mem_self", now: () => NOW,
-      log: (lvl, msg) => logs.push(`${lvl}:${msg}`),
-      callImpl: async () => ({ ok: true, result: { version: 5, body: bad } }),
-    });
-    assert.equal(r.ok, true);
-    assert.equal(r.validation.ok, false);
-    assert.ok(r.validation.errors.some((e) => /self-adopted/.test(e)));
-    assert.ok(logs.some((l) => /invalid/.test(l)), "an invalid snapshot must be logged, not quietly trusted");
-  } finally { cleanup(root); }
-});
-
-test("a corrupt cache does not block a fresh server refresh", async () => {
-  const root = makeRoot();
-  try {
-    mkdirSync(join(root, "state", "mandate"), { recursive: true });
-    writeFileSync(cachePath(root), "}}}garbage", "utf-8");
-    const r = await refreshMandate(root, {
-      memberId: "mem_self", now: () => NOW,
-      callImpl: async () => ({ ok: true, result: { version: 4, body: BODY } }),
-    });
-    assert.equal(r.source, "server");
-    assert.equal(JSON.parse(readFileSync(cachePath(root), "utf-8")).version, 4);
-  } finally { cleanup(root); }
-});
-
-test("REGRESSION — hq's 'nothing adopted' answer must NOT be cached as a server snapshot", async () => {
-  // mandate.get answers an unadopted seat with {version:0, checksum:null,
-  // body:null} BY DESIGN (hq src/server/methods/mandate/get.ts). `body: r.body || r`
-  // read that as a hit and cached the RPC ENVELOPE as the mandate body with
-  // source:"server" — after which "a local derivation never supersedes a server
-  // snapshot" pinned the seat to an empty mandate permanently. Verified live
-  // against os.cohortapp.com.
-  const root = makeRoot();
-  try {
-    const r = await refreshMandate(root, {
-      memberId: "mem_self",
-      now: () => NOW,
-      log: () => {},
-      callImpl: async () => ({
-        ok: true,
-        result: { memberId: "mem_self", version: 0, checksum: null, body: null, publishedAt: null, publishedById: null },
-      }),
-    });
-    assert.notEqual(r.source, "server", "an empty snapshot is an absence, not a fetch");
-    assert.equal(r.source, "local");
-    const cached = JSON.parse(readFileSync(cachePath(root), "utf-8"));
-    assert.equal(cached.source, "local");
-    assert.ok(Array.isArray(cached.body.objectives), "the cached body is a real mandate body, not the RPC envelope");
-    assert.equal(cached.body.publishedAt, undefined, "the envelope's own keys never leaked into the body");
-  } finally { cleanup(root); }
-});
-
-test("fetchSnapshot names the empty-snapshot case distinctly", async () => {
-  const got = await fetchSnapshot({ callImpl: async () => ({ ok: true, result: { version: 0, body: null } }) });
-  assert.equal(got.ok, false);
-  assert.equal(got.reason, "no-adopted-mandate");
-});