switchroom 0.14.60 → 0.14.62

package/telegram-plugin/tests/obligation-determinism.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from "vitest";
+import { ObligationLedger, type Obligation } from "../gateway/obligation-ledger.js";
+import {
+  loadObligations,
+  persistObligations,
+  type ObligationStoreFsSeam,
+} from "../gateway/obligation-store.js";
+
+/**
+ * REGRESSION GUARD — not the proof.
+ *
+ * The actual determinism argument is closed-form and lives WITH the code: the
+ * ledger is a finite FSM with a total transition function and a strictly-
+ * decreasing measure μ = (REPRESENT_MAX - representCount) + (ESCALATE_MAX -
+ * escalateAttempts) ⇒ every OPEN reaches a terminal (see the proof comment on
+ * obligationSweep in gateway.ts and the ledger methods in obligation-ledger.ts).
+ * A total state-machine proof also found — and a fix closed — the one liveness
+ * hole this kind of SAMPLING test structurally cannot reach: a hung escalation
+ * send leaking the in-flight flag (now bounded by withDeadline; guarded by
+ * with-deadline.test.ts). The lesson stands: a random-schedule test only
+ * exercises the behaviours its model encodes; it is evidence, never the proof.
+ *
+ * What this file still earns its keep doing: drive the REAL ObligationLedger +
+ * REAL durable snapshot store over many random {model-behaviour × timing ×
+ * restart} schedules to catch a regression that breaks the FSM invariant
+ * (no silent drop, no double-ask of an answered message, bounded termination).
+ * It models the lifecycle SYNCHRONOUSLY (open at receipt; close at turn_end on a
+ * delivered answer; bounded represent→escalate; restart = hydrate from snapshot)
+ * — so it does NOT and cannot cover async/coupling liveness (hung send, gate
+ * never opening, drain wedging); those are proven/bounded in the code, not here.
+ * The coalesced PARTIAL-ANSWER residual is also out of model — the one honest
+ * hard limit (a turn-keyed ledger can't see "answered half" without parsing the
+ * model's prose), mitigated by coalescing policy, not the ledger.
+ */
+
+// Mirrors the gateway constants under test.
+const MAX_REPRESENTS = 2;
+const ESCALATE_MAX = 3;
+
+// Deterministic PRNG (mulberry32) so any failure reproduces from its seed.
+function rng(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function memStore(): { fs: ObligationStoreFsSeam } {
+  const files = new Map<string, string>();
+  return {
+    fs: {
+      readFileSync: (p) => {
+        if (!files.has(p)) throw new Error(`ENOENT ${p}`);
+        return files.get(p)!;
+      },
+      writeFileSync: (p, d) => files.set(p, d),
+      renameSync: (a, b) => {
+        if (!files.has(a)) throw new Error(`ENOENT ${a}`);
+        files.set(b, files.get(a)!);
+        files.delete(a);
+      },
+      existsSync: (p) => files.has(p),
+    },
+  };
+}
+
+type Terminal = "answered" | "escalation-delivered" | "escalation-give-up";
+
+interface Msg {
+  id: string;
+  /** Real numeric Telegram message id (the gateway only opens an obligation
+   *  when deriveTurnId is non-null, i.e. messageId > 0 — so the durable row
+   *  always carries a valid number). */
+  msgId: number;
+  /** Turn attempt index (0 = original, 1 = 1st re-present, 2 = 2nd) at which
+   *  the model delivers a final answer. >MAX_REPRESENTS ⇒ never answered ⇒ escalates. */
+  answerOnAttempt: number;
+  /** How many escalation SEND attempts fail before one succeeds. ≥ESCALATE_MAX
+   *  ⇒ permanently undeliverable ⇒ bounded give-up. */
+  escalateFailsFor: number;
+}
+
+interface Sim {
+  terminals: Map<string, Terminal>;
+  steps: number;
+}
+
+function runSchedule(msgs: Msg[], seed: number): Sim {
+  const PATH = "/state/agent/telegram/obligations.json";
+  const store = memStore();
+  let ledger = new ObligationLedger(MAX_REPRESENTS, {
+    onChange: (snap) => persistObligations(PATH, store.fs, snap),
+  });
+  const r = rng(seed);
+
+  const pending = [...msgs]; // not yet received
+  const byId = new Map(msgs.map((m) => [m.id, m]));
+  const turnsHad = new Map<string, number>(); // total turns delivered to each obligation
+  const terminals = new Map<string, Terminal>();
+  const received = new Set<string>();
+
+  const close = (id: string, why: Terminal) => {
+    ledger.close(id);
+    terminals.set(id, why);
+  };
+
+  // Run one turn for an obligation; close if the model answers on this attempt.
+  const deliverTurn = (id: string) => {
+    const had = (turnsHad.get(id) ?? 0);
+    const attemptIndex = had; // 0-based
+    turnsHad.set(id, had + 1);
+    if (byId.get(id)!.answerOnAttempt === attemptIndex) close(id, "answered");
+  };
+
+  const ESC_IN_FLIGHT = new Set<string>(); // mirrors the gateway's concurrency guard (no-op in a sync model)
+
+  let steps = 0;
+  const CAP = 10_000; // generous; a real infinite loop blows past this and fails
+  while (steps < CAP) {
+    steps++;
+    const open = ledger.hasOpen();
+    // Receive a fresh inbound (interleave: maybe receive while something is open,
+    // exercising multi-open). Always receive if nothing is open and work remains.
+    if (pending.length > 0 && (!open || r() < 0.5)) {
+      const m = pending.shift()!;
+      received.add(m.id);
+      // OPEN at receipt — keyed origin id; idempotent.
+      ledger.openIfAbsent({
+        originTurnId: m.id,
+        chatId: "-100123",
+        threadId: 3,
+        messageId: m.msgId,
+        text: `msg ${m.id}`,
+        openedAt: 1000 + steps,
+      });
+      deliverTurn(m.id); // original turn (attempt 0)
+    } else if (open) {
+      const decision = ledger.decideAtIdle();
+      const o = decision.obligation as Obligation;
+      // INVARIANT (no double-ask): a terminated obligation must never resurface.
+      expect(terminals.has(o.originTurnId)).toBe(false);
+      if (decision.action === "represent") {
+        ledger.markRepresented(o.originTurnId);
+        deliverTurn(o.originTurnId); // the re-present turn
+      } else if (decision.action === "escalate") {
+        if (ESC_IN_FLIGHT.has(o.originTurnId)) continue;
+        const attempt = ledger.markEscalateAttempt(o.originTurnId);
+        const willSucceed = byId.get(o.originTurnId)!.escalateFailsFor < attempt;
+        if (willSucceed) {
+          close(o.originTurnId, "escalation-delivered");
+        } else if (attempt >= ESCALATE_MAX) {
+          close(o.originTurnId, "escalation-give-up");
+        }
+        // else: transient failure — stays OPEN, retried next sweep.
+      }
+    } else {
+      break; // idle: nothing pending, nothing open → done
+    }
+
+    // Random restart: the durable snapshot is the only thing that survives.
+    // A fresh ledger hydrated from disk must resume exactly where we left off.
+    if (r() < 0.15) {
+      ledger = new ObligationLedger(MAX_REPRESENTS, {
+        onChange: (snap) => persistObligations(PATH, store.fs, snap),
+      });
+      ledger.hydrate(loadObligations(PATH, store.fs));
+    }
+  }
+
+  return { terminals, steps };
+}
+
+function pick<T>(arr: T[], r: () => number): T {
+  return arr[Math.floor(r() * arr.length)];
+}
+
+describe("obligation determinism — every inbound reaches a terminal, no silent loss, no double-ask", () => {
+  it("holds across 3000 random {model-behavior × timing × restart} schedules", () => {
+    const ANSWER = [0, 1, 2, 3, 99]; // 0..2 = answered via ladder; 3/99 = never → escalate
+    const ESCFAIL = [0, 1, 2, 3, 5]; // 0 = first send ok; ≥3 = permanently undeliverable
+    for (let seed = 1; seed <= 3000; seed++) {
+      const r = rng(seed * 7919);
+      const n = 1 + Math.floor(r() * 5); // 1..5 messages
+      const msgs: Msg[] = [];
+      for (let i = 0; i < n; i++) {
+        const msgId = seed * 100 + i; // real positive integer id
+        msgs.push({
+          id: `c:3#${msgId}`,
+          msgId,
+          answerOnAttempt: pick(ANSWER, r),
+          escalateFailsFor: pick(ESCFAIL, r),
+        });
+      }
+      const { terminals, steps } = runSchedule(msgs, seed * 104729);
+
+      // 1. TERMINATION: the engine settled well within the cap (no infinite loop).
+      expect(steps).toBeLessThan(10_000);
+
+      // 2. NO SILENT LOSS: every message received reached a terminal.
+      for (const m of msgs) {
+        const t = terminals.get(m.id);
+        expect(t, `seed=${seed} msg=${m.id} answer=${m.answerOnAttempt} escFail=${m.escalateFailsFor}`).toBeDefined();
+
+        // 3. CORRECT TERMINAL per behaviour:
+        if (m.answerOnAttempt <= MAX_REPRESENTS) {
+          // answerable within the represent ladder → answered (never escalated early)
+          expect(t).toBe("answered");
+        } else if (m.escalateFailsFor < ESCALATE_MAX) {
+          // never answered, escalation eventually lands
+          expect(t).toBe("escalation-delivered");
+        } else {
+          // never answered, escalation permanently undeliverable → bounded give-up
+          expect(t).toBe("escalation-give-up");
+        }
+      }
+    }
+  });
+
+  it("a delivered-but-unanswered obligation survives a restart and is escalated, not lost", () => {
+    // Deterministic single case: model NEVER answers, escalation succeeds first try,
+    // with a restart forced mid-life via a seed that triggers the 0.15 branch.
+    const { terminals } = runSchedule(
+      [{ id: "c:3#715", msgId: 715, answerOnAttempt: 99, escalateFailsFor: 0 }],
+      42,
+    );
+    expect(terminals.get("c:3#715")).toBe("escalation-delivered");
+  });
+
+  it("escalation that is permanently undeliverable is bounded (give-up), never an infinite loop", () => {
+    const { terminals, steps } = runSchedule(
+      [{ id: "c:3#900", msgId: 900, answerOnAttempt: 99, escalateFailsFor: 99 }],
+      7,
+    );
+    expect(terminals.get("c:3#900")).toBe("escalation-give-up");
+    expect(steps).toBeLessThan(10_000);
+  });
+});

package/telegram-plugin/tests/obligation-ledger.test.ts

@@ -165,3 +165,72 @@ describe("buildObligationRepresentInbound", () => {
     expect(obligationEscalationText(ob)).toMatch(/re-?send/i);
   });
 });
+
+describe("ObligationLedger — durability hooks + escalate-attempt counter", () => {
+  function input(id: string, openedAt: number, text = "do the thing") {
+    return { originTurnId: id, chatId: "-100123", threadId: 3, messageId: Number(id.split("#").pop() ?? 0), text, openedAt };
+  }
+
+  it("fires onChange after every mutation with the full open snapshot", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    L.openIfAbsent(input("c:3#1", 1000)); // open
+    L.openIfAbsent(input("c:3#2", 1001)); // open
+    L.markRepresented("c:3#1"); // represent
+    L.markEscalateAttempt("c:3#1"); // escalate-attempt
+    L.close("c:3#1"); // close
+    // open, open, represent, escalate-attempt, close = 5 mutations.
+    expect(snapshots.length).toBe(5);
+    expect(snapshots[1].map((o) => o.originTurnId).sort()).toEqual(["c:3#1", "c:3#2"]);
+    // last snapshot reflects the close.
+    expect(snapshots[4].map((o) => o.originTurnId)).toEqual(["c:3#2"]);
+  });
+
+  it("does NOT fire onChange for an idempotent (already-open) openIfAbsent", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    expect(L.openIfAbsent(input("c:3#1", 1000))).toBe(true);
+    expect(L.openIfAbsent(input("c:3#1", 9999))).toBe(false); // dup
+    expect(snapshots.length).toBe(1);
+  });
+
+  it("does NOT fire onChange for a close of an unknown id", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    expect(L.close("nope")).toBe(false);
+    expect(snapshots.length).toBe(0);
+  });
+
+  it("markEscalateAttempt increments per call and persists", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    L.openIfAbsent(input("c:3#1", 1000));
+    expect(L.markEscalateAttempt("c:3#1")).toBe(1);
+    expect(L.markEscalateAttempt("c:3#1")).toBe(2);
+    expect(L.list()[0].escalateAttempts).toBe(2);
+    expect(L.markEscalateAttempt("missing")).toBe(0);
+  });
+
+  it("hydrate restores the open set WITH counters and does not fire onChange", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    L.hydrate([
+      { originTurnId: "c:3#715", chatId: "-100123", threadId: 3, messageId: 715, text: "x", openedAt: 1000, representCount: 2, escalateAttempts: 1 },
+    ]);
+    expect(snapshots.length).toBe(0); // hydrate is restoration, not a mutation
+    expect(L.isOpen("c:3#715")).toBe(true);
+    expect(L.list()[0].representCount).toBe(2);
+    expect(L.list()[0].escalateAttempts).toBe(1);
+    // a represented obligation at/over max decides 'escalate', preserving count across restart
+    expect(L.decideAtIdle().action).toBe("escalate");
+  });
+
+  it("hydrate skips malformed rows", () => {
+    const L = new ObligationLedger();
+    L.hydrate([
+      { originTurnId: "c:3#1", chatId: "-100123", messageId: 1, text: "x", openedAt: 1000, representCount: 0 },
+      { originTurnId: "", chatId: "x", messageId: 0, text: "", openedAt: 0, representCount: 0 } as Obligation,
+    ]);
+    expect(L.size()).toBe(1);
+  });
+});

package/telegram-plugin/tests/obligation-store.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import {
+  loadObligations,
+  persistObligations,
+  type ObligationStoreFsSeam,
+} from "../gateway/obligation-store.js";
+import type { Obligation } from "../gateway/obligation-ledger.js";
+
+/** In-memory fs seam with an atomic rename, so the store's tmp→rename
+ *  crash-safety contract is exercised without touching the real disk. */
+function memFs(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed));
+  const calls: string[] = [];
+  const fs: ObligationStoreFsSeam = {
+    readFileSync: (p) => {
+      if (!files.has(p)) throw new Error(`ENOENT ${p}`);
+      return files.get(p)!;
+    },
+    writeFileSync: (p, d) => {
+      calls.push(`write:${p}`);
+      files.set(p, d);
+    },
+    renameSync: (a, b) => {
+      calls.push(`rename:${a}->${b}`);
+      if (!files.has(a)) throw new Error(`ENOENT ${a}`);
+      files.set(b, files.get(a)!);
+      files.delete(a);
+    },
+    existsSync: (p) => files.has(p),
+  };
+  return { fs, files, calls };
+}
+
+const PATH = "/state/agent/telegram/obligations.json";
+
+function ob(id: string, over: Partial<Obligation> = {}): Obligation {
+  return {
+    originTurnId: id,
+    chatId: "-100123",
+    threadId: 3,
+    messageId: Number(id.split("#").pop() ?? 1),
+    text: "do the thing",
+    openedAt: 1000,
+    representCount: 0,
+    ...over,
+  };
+}
+
+describe("obligation-store", () => {
+  it("round-trips the open set, preserving representCount + escalateAttempts", () => {
+    const { fs } = memFs();
+    const snap: Obligation[] = [
+      ob("c:3#715", { representCount: 2, escalateAttempts: 1 }),
+      ob("c:5#900", { representCount: 0, openedAt: 2000 }),
+    ];
+    persistObligations(PATH, fs, snap);
+    const loaded = loadObligations(PATH, fs);
+    expect(loaded).toEqual(snap);
+    expect(loaded[0].escalateAttempts).toBe(1);
+    expect(loaded[0].representCount).toBe(2);
+  });
+
+  it("persists atomically: writes a sibling .tmp then renames over the path", () => {
+    const { fs, calls, files } = memFs();
+    persistObligations(PATH, fs, [ob("c:3#1")]);
+    expect(calls).toEqual([`write:${PATH}.tmp`, `rename:${PATH}.tmp->${PATH}`]);
+    // The tmp is gone (renamed); only the real path remains.
+    expect(files.has(PATH)).toBe(true);
+    expect(files.has(`${PATH}.tmp`)).toBe(false);
+  });
+
+  it("returns [] for a missing file", () => {
+    const { fs } = memFs();
+    expect(loadObligations(PATH, fs)).toEqual([]);
+  });
+
+  it("returns [] for a torn / non-JSON file (crash mid-write tolerance)", () => {
+    const { fs } = memFs({ [PATH]: '{"v":1,"obligations":[{"originTurnId":"c:3#7' });
+    expect(loadObligations(PATH, fs)).toEqual([]);
+  });
+
+  it("returns [] for a wrong-version or wrong-shape envelope", () => {
+    const a = memFs({ [PATH]: JSON.stringify({ v: 2, obligations: [ob("c:3#1")] }) });
+    expect(loadObligations(PATH, a.fs)).toEqual([]);
+    const b = memFs({ [PATH]: JSON.stringify({ v: 1, obligations: "nope" }) });
+    expect(loadObligations(PATH, b.fs)).toEqual([]);
+  });
+
+  it("filters out malformed rows but keeps valid ones", () => {
+    const raw = JSON.stringify({
+      v: 1,
+      obligations: [
+        ob("c:3#715"),
+        { originTurnId: "", chatId: "x" }, // empty id → dropped
+        { nope: true }, // missing fields → dropped
+        ob("c:5#900", { openedAt: 2000 }),
+      ],
+    });
+    const { fs } = memFs({ [PATH]: raw });
+    const loaded = loadObligations(PATH, fs);
+    expect(loaded.map((o) => o.originTurnId)).toEqual(["c:3#715", "c:5#900"]);
+  });
+
+  it("never throws on a write failure — degrades to in-memory (logs)", () => {
+    const logs: string[] = [];
+    const fs: ObligationStoreFsSeam = {
+      readFileSync: () => "",
+      writeFileSync: () => {
+        throw new Error("EROFS read-only fs");
+      },
+      renameSync: () => {},
+      existsSync: () => false,
+    };
+    expect(() => persistObligations(PATH, fs, [ob("c:3#1")], (l) => logs.push(l))).not.toThrow();
+    expect(logs.join("")).toContain("persist FAILED");
+  });
+});

package/telegram-plugin/tests/with-deadline.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { withDeadline } from "../gateway/with-deadline.js";
+
+const tick = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("withDeadline — bounds the obligation escalation send so a hang can't leak the in-flight flag", () => {
+  it("resolves with the inner value when the promise settles before the deadline", async () => {
+    await expect(withDeadline(Promise.resolve("ok"), 1000, "timed out")).resolves.toBe("ok");
+  });
+
+  it("rejects with the inner error when the promise rejects before the deadline", async () => {
+    await expect(withDeadline(Promise.reject(new Error("boom")), 1000, "timed out")).rejects.toThrow(
+      "boom",
+    );
+  });
+
+  it("rejects with the timeout message when the promise NEVER settles (the hang case)", async () => {
+    // The whole point: a promise that never resolves/rejects (a stalled send)
+    // must still settle the chain so the caller's .finally clears the in-flight flag.
+    const neverSettles = new Promise<string>(() => {});
+    await expect(withDeadline(neverSettles, 20, "obligation escalation send timed out")).rejects.toThrow(
+      "obligation escalation send timed out",
+    );
+  });
+
+  it("the .finally chained after it ALWAYS runs even when the inner promise hangs", async () => {
+    // This mirrors the gateway's obligationEscalateInFlight clear: it lives in a
+    // .finally on withDeadline(...), and must fire within the deadline regardless.
+    let flagCleared = false;
+    await withDeadline(new Promise<void>(() => {}), 20, "timed out")
+      .catch(() => {})
+      .finally(() => {
+        flagCleared = true;
+      });
+    expect(flagCleared).toBe(true);
+  });
+
+  it("a hung-then-late-rejecting inner promise does not produce an unhandled rejection", async () => {
+    const seen: unknown[] = [];
+    const onUnhandled = (reason: unknown) => seen.push(reason);
+    process.on("unhandledRejection", onUnhandled);
+    try {
+      const lateReject = new Promise<void>((_, reject) => {
+        setTimeout(() => reject(new Error("late-zombie-rejection")), 30);
+      });
+      // withDeadline rejects at 10ms; the inner promise rejects later at 30ms.
+      await withDeadline(lateReject, 10, "timed out").catch(() => {});
+      await tick(60); // let the late rejection fire
+    } finally {
+      process.off("unhandledRejection", onUnhandled);
+    }
+    expect(seen.some((r) => r instanceof Error && r.message === "late-zombie-rejection")).toBe(false);
+  });
+
+  it("clears its timer on a fast settle (no dangling work keeps the loop alive)", async () => {
+    // Sanity: a fast resolve settles immediately, not after the deadline.
+    const start = Date.now();
+    await withDeadline(Promise.resolve(1), 5000, "timed out");
+    expect(Date.now() - start).toBeLessThan(500);
+  });
+});