agent-yes 1.287.0 → 1.288.0

package/ts/callbackCore.bun.spec.ts

@@ -0,0 +1,139 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, it } from "bun:test";
+import {
+  MAX_EXPIRES_MS,
+  buildSnippet,
+  frameVisitorMessage,
+  mintCapability,
+  parseExpires,
+  verifyCapability,
+} from "./callbackCore.ts";
+
+const SECRET = "test-secret";
+const NOW = 1_784_700_000_000;
+
+describe("parseExpires", () => {
+  it("parses minutes/hours/days/weeks", () => {
+    expect(parseExpires("30m")).toBe(30 * 60_000);
+    expect(parseExpires("12h")).toBe(12 * 3_600_000);
+    expect(parseExpires("7d")).toBe(7 * 24 * 3_600_000);
+    expect(parseExpires("2w")).toBe(14 * 24 * 3_600_000);
+    expect(parseExpires(" 1d ")).toBe(24 * 3_600_000);
+  });
+
+  it("rejects everything that is not an explicit finite duration", () => {
+    for (const bad of ["", "7", "d", "never", "0d", "-1d", "1y", "1.5d", "7 d"]) {
+      expect(() => parseExpires(bad), bad).toThrow();
+    }
+  });
+
+  it("caps at 365d — no effectively-immortal capabilities", () => {
+    expect(parseExpires("365d")).toBe(MAX_EXPIRES_MS);
+    expect(() => parseExpires("366d")).toThrow(/365d/);
+    expect(() => parseExpires("53w")).toThrow(/365d/);
+  });
+});
+
+describe("mint / verify", () => {
+  const payload = { id: "ab12cd34", agent: "4d65a096e983", exp: NOW + 3_600_000 };
+
+  it("round-trips a valid capability", () => {
+    const cap = mintCapability(SECRET, payload);
+    expect(cap).toMatch(/^cb1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/);
+    const v = verifyCapability(SECRET, cap, NOW);
+    expect(v).toEqual({ ok: true, payload });
+  });
+
+  it("fails hard after expiry (410 path)", () => {
+    const cap = mintCapability(SECRET, payload);
+    expect(verifyCapability(SECRET, cap, payload.exp)).toEqual({ ok: false, reason: "expired" });
+    expect(verifyCapability(SECRET, cap, payload.exp + 1)).toEqual({
+      ok: false,
+      reason: "expired",
+    });
+  });
+
+  it("rejects a tampered payload as badsig — retargeting is impossible", () => {
+    const cap = mintCapability(SECRET, payload);
+    const [pre, , sig] = cap.split(".");
+    const forged = Buffer.from(
+      JSON.stringify({ ...payload, agent: "other-agent-id", exp: NOW + 999_999_999 }),
+    ).toString("base64url");
+    expect(verifyCapability(SECRET, `${pre}.${forged}.${sig}`, NOW)).toEqual({
+      ok: false,
+      reason: "badsig",
+    });
+  });
+
+  it("rejects a capability minted with a different secret", () => {
+    const cap = mintCapability("other-secret", payload);
+    expect(verifyCapability(SECRET, cap, NOW)).toEqual({ ok: false, reason: "badsig" });
+  });
+
+  it("rejects malformed tokens without throwing", () => {
+    for (const bad of ["", "cb1", "cb1.x", "cb2.a.b", "nope.a.b", "cb1..", "cb1.!!.??"]) {
+      const v = verifyCapability(SECRET, bad, NOW);
+      expect(v.ok, bad).toBe(false);
+    }
+  });
+
+  it("rejects a signed payload with missing fields as malformed", () => {
+    // Sign a structurally wrong payload with the REAL secret: signature passes,
+    // shape check must still refuse it.
+    const raw = Buffer.from(JSON.stringify({ id: "x" })).toString("base64url");
+    const sig = createHmac("sha256", SECRET).update(`cb1.${raw}`).digest().toString("base64url");
+    expect(verifyCapability(SECRET, `cb1.${raw}.${sig}`, NOW)).toEqual({
+      ok: false,
+      reason: "malformed",
+    });
+  });
+});
+
+describe("frameVisitorMessage", () => {
+  it("wraps the message in an untrusted frame carrying the capability id", () => {
+    const framed = frameVisitorMessage("ab12", "hello agent");
+    expect(framed).toContain("<ay-callback ab12");
+    expect(framed).toContain("untrusted visitor message");
+    expect(framed).toContain("hello agent");
+    expect(framed).toContain("</ay-callback ab12>");
+  });
+
+  it("strips control characters so a visitor cannot inject escapes or Enter", () => {
+    const framed = frameVisitorMessage("ab12", "a\u001b[31mred\u0000\rb");
+    expect(framed).toContain("a[31mredb");
+    // eslint-disable-next-line no-control-regex
+    expect(framed).not.toMatch(/[\u0000-\u0008\u000b-\u001f\u007f]/);
+  });
+
+  it("keeps newlines and tabs (multi-line messages stay readable)", () => {
+    const framed = frameVisitorMessage("ab12", "line1\nline2\tend");
+    expect(framed).toContain("line1\nline2\tend");
+  });
+});
+
+describe("buildSnippet", () => {
+  const cap = mintCapability(SECRET, { id: "ab12", agent: "deadbeef1234", exp: NOW + 1000 });
+
+  it("targets <base>/cb/<cap> and is fully self-contained", () => {
+    const s = buildSnippet({ base: "https://x1.agent-yes.com/", cap });
+    expect(s).toContain(`"https://x1.agent-yes.com/cb/${cap}"`);
+    expect(s).toMatch(/^<script>/);
+    expect(s).toMatch(/<\/script>$/);
+    // No external loads: everything inline, only the endpoint is fetched.
+    expect(s).not.toContain("src=");
+    expect(s).not.toContain("import ");
+  });
+
+  it("handles the expired (410) and rate-limited (429) states explicitly", () => {
+    const s = buildSnippet({ base: "http://127.0.0.1:4680", cap });
+    expect(s).toContain("410");
+    expect(s).toContain("expired");
+    expect(s).toContain("429");
+  });
+
+  it("sanitizes the title against markup injection", () => {
+    const s = buildSnippet({ base: "http://h", cap, title: `<img onerror="x">"'&` });
+    expect(s).not.toContain("<img");
+    expect(s).toContain('var TITLE = "img onerror=x"');
+  });
+});

package/ts/channels/hlc.bun.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "bun:test";
+import { compareHlc, formatHlc, hlcSend, parseHlc } from "./hlc.ts";
+
+describe("hlc", () => {
+  it("round-trips format/parse", () => {
+    const s = formatHlc(1_700_000_000_000, 3, "node7");
+    expect(parseHlc(s)).toEqual({ ms: 1_700_000_000_000, ctr: 3, node: "node7" });
+  });
+
+  it("is lexicographically sortable in HLC order", () => {
+    const a = formatHlc(1000, 0, "z"); // earlier ms
+    const b = formatHlc(1000, 1, "a"); // same ms, higher ctr
+    const c = formatHlc(2000, 0, "a"); // later ms
+    expect([c, a, b].sort()).toEqual([a, b, c]);
+    expect(compareHlc(a, b)).toBeLessThan(0);
+    expect(compareHlc(c, a)).toBeGreaterThan(0);
+    expect(compareHlc(a, a)).toBe(0);
+  });
+
+  it("advances the ms and resets the counter when wall clock moves forward", () => {
+    const prev = formatHlc(1000, 5, "n1");
+    expect(parseHlc(hlcSend(prev, 2000, "n1"))).toMatchObject({ ms: 2000, ctr: 0 });
+  });
+
+  it("keeps ms and bumps the counter when wall clock has not advanced", () => {
+    const prev = formatHlc(5000, 2, "n1");
+    // physNow behind the max we've seen (clock skew / same ms) → monotonic via ctr
+    expect(parseHlc(hlcSend(prev, 4000, "n1"))).toMatchObject({ ms: 5000, ctr: 3 });
+    expect(parseHlc(hlcSend(prev, 5000, "n1"))).toMatchObject({ ms: 5000, ctr: 3 });
+  });
+
+  it("is strictly monotonic across repeated sends seeded from the running max", () => {
+    let max: string | null = null;
+    const out: string[] = [];
+    for (let i = 0; i < 100; i++) {
+      // simulate a clock that sometimes stalls
+      const now = 1000 + (i % 3 === 0 ? 0 : i);
+      max = hlcSend(max, now, "n");
+      out.push(max);
+    }
+    for (let i = 1; i < out.length; i++) expect(compareHlc(out[i - 1]!, out[i]!)).toBeLessThan(0);
+  });
+
+  it("starts from zero with no prior max", () => {
+    expect(parseHlc(hlcSend(null, 42, "n"))).toEqual({ ms: 42, ctr: 0, node: "n" });
+  });
+
+  it("rejects malformed and out-of-range values", () => {
+    expect(() => parseHlc("nope")).toThrow();
+    expect(() => parseHlc("1.2")).toThrow(); // too few fields
+    expect(() => formatHlc(-1, 0, "n")).toThrow();
+    expect(() => formatHlc(0, -1, "n")).toThrow();
+    expect(() => formatHlc(10 ** 15, 0, "n")).toThrow(); // ms overflow
+    expect(() => formatHlc(0, 10 ** 6, "n")).toThrow(); // ctr overflow
+  });
+});

package/ts/channels/link.bun.spec.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "bun:test";
+import {
+  deriveChannelId,
+  deriveRoom,
+  formatChannelLink,
+  formatChannelWebLink,
+  isChannelLink,
+  parseChannelLink,
+  secretFromTopic,
+} from "./link.ts";
+
+const S = "a".repeat(64); // a valid 64-hex secret
+
+describe("channel identity derivation", () => {
+  it("derives a stable, topic-blind channelId and room from the secret", async () => {
+    const [id1, id2] = await Promise.all([deriveChannelId(S), deriveChannelId(S)]);
+    expect(id1).toBe(id2);
+    expect(id1).toMatch(/^[0-9a-f]{16}$/);
+    const room = await deriveRoom(S);
+    expect(room).toMatch(/^c[0-9a-f]{12}$/); // matches the signaling room grammar
+    // different secret → different identity
+    expect(await deriveChannelId("b".repeat(64))).not.toBe(id1);
+  });
+
+  it("rejects a non-hex secret before hashing", async () => {
+    await expect(deriveChannelId("not-hex")).rejects.toThrow();
+  });
+
+  it("derives a deterministic, valid secret from a topic (same URL → same channel)", async () => {
+    const url = "https://example.com/docs/page";
+    const [a, b] = await Promise.all([secretFromTopic(url), secretFromTopic(url)]);
+    expect(a).toBe(b); // deterministic
+    expect(a).toMatch(/^[0-9a-f]{64}$/); // a valid S
+    // usable as a real secret end-to-end
+    await expect(deriveChannelId(a)).resolves.toMatch(/^[0-9a-f]{16}$/);
+    // distinct topics (incl. a differing hash) yield distinct channels
+    expect(await secretFromTopic(url + "#section")).not.toBe(a);
+    expect(await secretFromTopic("https://example.com/other")).not.toBe(a);
+  });
+});
+
+describe("channel invite links", () => {
+  const link = { sighost: "s.agent-yes.com", room: "cabc123", s: S };
+
+  it("round-trips the ay:// form", () => {
+    const str = formatChannelLink(link);
+    expect(str).toBe(`ay://ch/s.agent-yes.com/cabc123#e1.${S}`);
+    expect(parseChannelLink(str)).toEqual(link);
+    expect(isChannelLink(str)).toBe(true);
+  });
+
+  it("round-trips the browser https form, defaulting the sighost", () => {
+    const web = formatChannelWebLink(link);
+    expect(web).toBe(`https://agent-yes.com/w/#ch=cabc123:e1.${S}`);
+    expect(parseChannelLink(web)).toEqual(link);
+    // a non-default sighost is carried explicitly
+    const custom = { ...link, sighost: "sig.example.com" };
+    expect(parseChannelLink(formatChannelWebLink(custom))).toEqual(custom);
+  });
+
+  it("returns null for non-links and throws on a malformed secret slot", () => {
+    expect(parseChannelLink("just a topic name")).toBeNull();
+    expect(isChannelLink("topic")).toBe(false);
+    // http url without the #ch= fragment is not a channel link
+    expect(isChannelLink("https://example.com/page")).toBe(false);
+    expect(parseChannelLink("https://example.com/page")).toBeNull();
+    // https channel form missing the room:secret separator → null
+    expect(parseChannelLink("https://x/w/#ch=noseparator")).toBeNull();
+    expect(() => parseChannelLink("ay://ch/host/room#e1.short")).toThrow();
+    expect(() => parseChannelLink("https://x/w/#ch=room:e1.short")).toThrow();
+  });
+});

package/ts/channels/op.bun.spec.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "bun:test";
+import { isValidOp, makeOp, opId } from "./op.ts";
+
+const base = { author: "a1", name: "alice", role: "human" as const, hlc: "h1" };
+
+describe("op", () => {
+  it("derives a stable id from author + hlc", () => {
+    expect(opId("a1", "h1")).toBe("a1@h1");
+    expect(makeOp({ ...base, kind: "msg", body: "hi" }).id).toBe("a1@h1");
+  });
+
+  it("drops empty optional fields", () => {
+    const op = makeOp({ ...base, kind: "msg", body: "hi" });
+    expect(op).not.toHaveProperty("ref");
+    const del = makeOp({ ...base, kind: "delete", ref: "a1@h0" });
+    expect(del).not.toHaveProperty("body");
+    expect(del.ref).toBe("a1@h0");
+  });
+
+  it("keeps an empty-string body (a cleared edit) but not undefined", () => {
+    expect(makeOp({ ...base, kind: "edit", body: "", ref: "x" }).body).toBe("");
+  });
+
+  it("validates a well-formed op", () => {
+    expect(isValidOp(makeOp({ ...base, kind: "msg", body: "hi" }))).toBe(true);
+    expect(isValidOp(makeOp({ ...base, kind: "reaction", body: "👍", ref: "x" }))).toBe(true);
+  });
+
+  it("validates control ops (cmd/stream) only with a payload body", () => {
+    expect(isValidOp(makeOp({ ...base, kind: "cmd", body: '{"action":"highlight"}' }))).toBe(true);
+    expect(isValidOp(makeOp({ ...base, kind: "stream", body: "delta" }))).toBe(true);
+    // cmd/stream without a body are rejected (fail-closed)
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "cmd", name: "x" })).toBe(false);
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "stream", name: "x" })).toBe(false);
+  });
+
+  it("rejects malformed ops (fail-closed)", () => {
+    expect(isValidOp(null)).toBe(false);
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "nope", name: "x" })).toBe(false);
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "msg", name: "x", role: "robot" })).toBe(false);
+    // id must equal author@hlc
+    expect(isValidOp({ ...base, id: "forged", kind: "msg", name: "x" })).toBe(false);
+    // amendments must carry a ref
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "edit", name: "x", body: "z" })).toBe(false);
+    // wrong field types
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "msg", name: 5 })).toBe(false);
+    expect(
+      isValidOp({
+        author: "a1",
+        hlc: "h1",
+        id: "a1@h1",
+        kind: "msg",
+        name: "x",
+        role: "human",
+        body: 1,
+      }),
+    ).toBe(false);
+    // ref of the wrong type
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "edit", name: "x", body: "z", ref: 9 })).toBe(
+      false,
+    );
+    // sig of the wrong type is rejected; a string sig is accepted
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "msg", name: "x", sig: 1 })).toBe(false);
+    expect(
+      isValidOp({ ...base, id: "a1@h1", kind: "msg", name: "x", body: "hi", sig: "deadbeef" }),
+    ).toBe(true);
+    // reaction/delete without a ref also fail-closed
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "reaction", name: "x", body: "👍" })).toBe(
+      false,
+    );
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "delete", name: "x" })).toBe(false);
+    // missing/blank required fields
+    expect(isValidOp({ ...base, id: "a1@h1", kind: "msg", name: "x", author: "" })).toBe(false);
+    expect(
+      isValidOp({ id: "@h1", kind: "msg", name: "x", role: "human", author: "", hlc: "h1" }),
+    ).toBe(false);
+  });
+});

package/ts/channels/store.browser.bun.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "bun:test";
+import { formatHlc } from "./hlc.ts";
+import { makeOp, type Op } from "./op.ts";
+import { LocalStorageStore } from "./store.browser.ts";
+
+// Minimal in-memory Storage stand-in (the parts LocalStorageStore uses).
+function memStorage(): Storage {
+  const m = new Map<string, string>();
+  return {
+    getItem: (k) => m.get(k) ?? null,
+    setItem: (k, v) => void m.set(k, v),
+    removeItem: (k) => void m.delete(k),
+    clear: () => m.clear(),
+    key: (i) => [...m.keys()][i] ?? null,
+    get length() {
+      return m.size;
+    },
+  } as Storage;
+}
+
+function op(author: string, ms: number, body: string): Op {
+  return makeOp({
+    author,
+    name: author,
+    role: "human",
+    hlc: formatHlc(ms, 0, author),
+    kind: "msg",
+    body,
+  });
+}
+
+describe("LocalStorageStore", () => {
+  it("returns [] for an empty channel", async () => {
+    const s = new LocalStorageStore("c1", memStorage());
+    expect(await s.all()).toEqual([]);
+  });
+
+  it("appends, dedups, and reads back sorted (same CRDT as the jsonl backend)", async () => {
+    const store = memStorage();
+    const s = new LocalStorageStore("c1", store);
+    const added = await s.append([op("b", 2, "two"), op("a", 1, "one")]);
+    expect(added).toHaveLength(2);
+    expect((await s.all()).map((o) => o.body)).toEqual(["one", "two"]);
+    // re-append an existing op → nothing new; a second reader converges identically
+    expect(await s.append([op("a", 1, "one")])).toEqual([]);
+    expect((await new LocalStorageStore("c1", store).all()).map((o) => o.body)).toEqual([
+      "one",
+      "two",
+    ]);
+  });
+
+  it("tolerates corrupt storage + drops invalid ops", async () => {
+    const store = memStorage();
+    store.setItem("ay29ch:c1", "not json");
+    const s = new LocalStorageStore("c1", store);
+    expect(await s.all()).toEqual([]);
+    // @ts-expect-error deliberately malformed
+    expect(await s.append([{ id: "x", kind: "msg" }])).toEqual([]);
+  });
+});

package/ts/channels/store.bun.spec.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "bun:test";
+import { formatHlc } from "./hlc.ts";
+import { makeOp, type Op, type Role } from "./op.ts";
+import { haveVector, maxHlc, mergeOps, opsMissing, renderThread, sortOps } from "./store.ts";
+
+// Build an op with an explicit (ms, ctr) HLC for deterministic ordering.
+function op(
+  author: string,
+  ms: number,
+  kind: Op["kind"],
+  body?: string,
+  ref?: string,
+  role: Role = "human",
+): Op {
+  return makeOp({ author, name: author, role, hlc: formatHlc(ms, 0, author), kind, body, ref });
+}
+
+describe("mergeOps", () => {
+  const a = op("a", 1, "msg", "one");
+  const b = op("b", 2, "msg", "two");
+  const c = op("c", 3, "msg", "three");
+
+  it("is a union deduped by id", () => {
+    const { merged, added } = mergeOps([a], [a, b]);
+    expect(merged.map((o) => o.id)).toEqual([a.id, b.id]);
+    expect(added.map((o) => o.id)).toEqual([b.id]); // only genuinely new
+  });
+
+  it("is commutative and idempotent (convergence)", () => {
+    const x = mergeOps(mergeOps([], [a, b]).merged, [c]).merged;
+    const y = mergeOps(mergeOps([], [c, b]).merged, [a]).merged;
+    expect(x.map((o) => o.id)).toEqual(y.map((o) => o.id));
+    // merging again adds nothing
+    expect(mergeOps(x, [a, b, c]).added).toEqual([]);
+  });
+
+  it("reports the running max HLC", () => {
+    expect(maxHlc([])).toBeNull();
+    expect(maxHlc([a, c, b])).toBe(c.hlc);
+  });
+
+  it("sorts by HLC then id", () => {
+    expect(sortOps([c, a, b]).map((o) => o.id)).toEqual([a.id, b.id, c.id]);
+  });
+
+  it("breaks a same-HLC tie deterministically by id", () => {
+    // two authors that collide on (ms, ctr) — the id (author@hlc) decides order
+    const x = makeOp({
+      author: "z",
+      name: "z",
+      role: "human",
+      hlc: formatHlc(9, 0, "z"),
+      kind: "msg",
+      body: "x",
+    });
+    const y = makeOp({
+      author: "a",
+      name: "a",
+      role: "human",
+      hlc: formatHlc(9, 0, "a"),
+      kind: "msg",
+      body: "y",
+    });
+    expect(sortOps([x, y]).map((o) => o.author)).toEqual(["a", "z"]);
+    expect(sortOps([y, x]).map((o) => o.author)).toEqual(["a", "z"]);
+  });
+});
+
+describe("renderThread", () => {
+  it("renders base messages in HLC order", () => {
+    const msgs = renderThread([op("b", 2, "msg", "two"), op("a", 1, "msg", "one")]);
+    expect(msgs.map((m) => m.text)).toEqual(["one", "two"]);
+  });
+
+  it("applies the latest edit (last-writer-wins)", () => {
+    const m = op("a", 1, "msg", "orig");
+    const e1 = op("a", 2, "edit", "v2", m.id);
+    const e2 = op("a", 3, "edit", "v3", m.id);
+    const [r] = renderThread([m, e2, e1]);
+    expect(r!.text).toBe("v3");
+    expect(r!.amendedHlc).toBe(e2.hlc);
+  });
+
+  it("hides a deleted message, and an edit after a delete revives it", () => {
+    const m = op("a", 1, "msg", "hi");
+    expect(renderThread([m, op("a", 2, "delete", undefined, m.id)])[0]!).toMatchObject({
+      deleted: true,
+      text: "",
+    });
+    // delete then a newer edit → revived
+    const revived = renderThread([
+      m,
+      op("a", 2, "delete", undefined, m.id),
+      op("a", 3, "edit", "back", m.id),
+    ])[0]!;
+    expect(revived).toMatchObject({ deleted: false, text: "back" });
+  });
+
+  it("groups reactions by emoji into distinct authors", () => {
+    const m = op("a", 1, "msg", "hi");
+    const r = renderThread([
+      m,
+      op("b", 2, "reaction", "👍", m.id),
+      op("c", 3, "reaction", "👍", m.id),
+      op("b", 4, "reaction", "👍", m.id), // duplicate author → deduped
+      op("b", 5, "reaction", "🎉", m.id),
+    ])[0]!;
+    expect(r.reactions).toEqual([
+      { emoji: "👍", by: ["b", "c"] },
+      { emoji: "🎉", by: ["b"] },
+    ]);
+  });
+
+  it("ignores amendments whose target op is absent", () => {
+    expect(renderThread([op("a", 2, "edit", "x", "missing@id")])).toEqual([]);
+  });
+
+  it("ignores a reaction with an empty body", () => {
+    const m = op("a", 1, "msg", "hi");
+    const [r] = renderThread([m, op("b", 2, "reaction", "", m.id)]);
+    expect(r!.reactions).toEqual([]);
+  });
+});
+
+describe("anti-entropy sync", () => {
+  const local = [op("a", 1, "msg", "a1"), op("a", 2, "msg", "a2"), op("b", 5, "msg", "b1")];
+
+  it("summarizes what a replica holds per author", () => {
+    expect(haveVector(local)).toEqual({ a: formatHlc(2, 0, "a"), b: formatHlc(5, 0, "b") });
+    // keeps the max even when an older op for an author appears after a newer one
+    const outOfOrder = [op("a", 2, "msg", "a2"), op("a", 1, "msg", "a1")];
+    expect(haveVector(outOfOrder)).toEqual({ a: formatHlc(2, 0, "a") });
+  });
+
+  it("computes exactly the ops a peer is missing", () => {
+    // peer has a up to ms=1 and nothing from b
+    const remoteHave = { a: formatHlc(1, 0, "a") };
+    const missing = opsMissing(local, remoteHave);
+    expect(missing.map((o) => o.body)).toEqual(["a2", "b1"]);
+  });
+
+  it("sends nothing when the peer is already caught up", () => {
+    expect(opsMissing(local, haveVector(local))).toEqual([]);
+  });
+});

package/ts/channels/store.node.bun.spec.ts

@@ -0,0 +1,76 @@
+import { appendFile, mkdtemp, mkdir, rm } from "fs/promises";
+import os from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { formatHlc } from "./hlc.ts";
+import { makeOp, type Op } from "./op.ts";
+import { appendOps, channelFilePath, readOps } from "./store.node.ts";
+
+function op(author: string, ms: number, body: string): Op {
+  return makeOp({
+    author,
+    name: author,
+    role: "human",
+    hlc: formatHlc(ms, 0, author),
+    kind: "msg",
+    body,
+  });
+}
+
+describe("store.node jsonl backend", () => {
+  let cwd: string;
+  const CH = "abc123";
+
+  beforeEach(async () => {
+    cwd = await mkdtemp(path.join(os.tmpdir(), "ay-ch-"));
+  });
+  afterEach(async () => {
+    await rm(cwd, { recursive: true, force: true });
+  });
+
+  it("colocates the replica under <cwd>/.agent-yes", () => {
+    expect(channelFilePath("/x", CH)).toBe(path.join("/x", ".agent-yes", "ch-abc123.jsonl"));
+  });
+
+  it("returns [] for a channel with no file yet", async () => {
+    expect(await readOps(cwd, CH)).toEqual([]);
+  });
+
+  it("appends and reads back, sorted by HLC", async () => {
+    const added = await appendOps(cwd, CH, [op("b", 2, "two"), op("a", 1, "one")]);
+    expect(added).toHaveLength(2);
+    expect((await readOps(cwd, CH)).map((o) => o.body)).toEqual(["one", "two"]);
+  });
+
+  it("dedups already-stored ops on append (idempotent replica)", async () => {
+    const first = op("a", 1, "one");
+    await appendOps(cwd, CH, [first]);
+    const added = await appendOps(cwd, CH, [first, op("a", 2, "two")]);
+    expect(added.map((o) => o.body)).toEqual(["two"]); // only the new one
+    expect(await readOps(cwd, CH)).toHaveLength(2);
+  });
+
+  it("drops invalid ops instead of storing them", async () => {
+    // @ts-expect-error deliberately malformed
+    const added = await appendOps(cwd, CH, [{ id: "x", kind: "msg" }]);
+    expect(added).toEqual([]);
+    expect(await readOps(cwd, CH)).toEqual([]);
+  });
+
+  it("skips corrupt/partial lines when reading", async () => {
+    const good = op("a", 1, "one");
+    await appendOps(cwd, CH, [good]);
+    // simulate a torn write: a half-line + a non-op JSON line
+    await appendFile(channelFilePath(cwd, CH), `{"not":"an op"}\n{oops not json\n\n`);
+    const ops = await readOps(cwd, CH);
+    expect(ops.map((o) => o.body)).toEqual(["one"]);
+  });
+
+  it("returns [] when the ops list is entirely invalid", async () => {
+    // appendOps with an empty list is a no-op
+    expect(await appendOps(cwd, CH, [])).toEqual([]);
+    // reading a fresh channel dir that exists but has no file
+    await mkdir(path.join(cwd, ".agent-yes"), { recursive: true });
+    expect(await readOps(cwd, "never-written")).toEqual([]);
+  });
+});