@byollm/relay 0.1.0-alpha.5 → 0.1.0-alpha.51

package/dist/store-contract.js

@@ -0,0 +1,641 @@
+import {
+  routeKey,
+  serviceKey
+} from "./chunk-XLWNHHLS.js";
+
+// src/store-contract.ts
+import { generateKeys, publicIdentityOf } from "@byollm/protocol";
+import { describe, expect, it } from "vitest";
+var CONTRACT_SITE = "site_store";
+var SITE_KEY_ID = "BYOLLM-TEST-SITE-KEY-ID";
+var SITE = CONTRACT_SITE;
+var stub = (id, owner = "alice") => ({
+  id,
+  kind: "llm.generate",
+  owner,
+  site: SITE_KEY_ID,
+  audience: "private",
+  sizeClass: "small",
+  streaming: false,
+  deadlineAt: 41024448e5
+});
+var capability = (model) => ({
+  kind: "llm.generate",
+  service: model,
+  isDefault: true,
+  backendId: "ollama",
+  backendClass: "process",
+  model,
+  offerScope: "private"
+});
+var ENVELOPE = {
+  ciphertext: "AAAA",
+  recipientKeyId: "r",
+  senderKeyId: "s",
+  direction: "payload",
+  deadlineAt: 41024448e5
+};
+var claimArgs = (over = {}) => {
+  const { owners = ["alice"], sites = [SITE], ...rest } = over;
+  return {
+    runnerId: "runner_1",
+    owner: "alice",
+    device: publicIdentityOf(generateKeys(Date.now())),
+    kinds: /* @__PURE__ */ new Set(["llm.generate"]),
+    // Empty by default — `serves` matters only to a job that named a service.
+    // A contract case that exercises selection passes its own.
+    serves: /* @__PURE__ */ new Set(),
+    routes: new Set(
+      sites.flatMap((site) => owners.map((owner) => routeKey(site, owner)))
+    ),
+    max: 10,
+    leaseMs: 6e4,
+    ...rest
+  };
+};
+function describeStoreContract(name, options) {
+  const { make, serialising, writeRawStub } = options;
+  describe(`the routing store \u2014 ${name}`, () => {
+    it("is idempotent by job id", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      await store.claim(claimArgs());
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      expect((await store.job(SITE, "a"))?.state).toBe("awaiting-payload");
+      await done();
+    });
+    it("gives two sites the same id without either seeing the other", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "shared", siteId: SITE, stub: stub("shared") });
+      await store.enqueue({
+        id: "shared",
+        siteId: "site_other",
+        stub: stub("shared", "bob")
+      });
+      expect((await store.job(SITE, "shared"))?.stub.owner).toBe("alice");
+      expect((await store.job("site_other", "shared"))?.stub.owner).toBe("bob");
+      const granted = await store.claim(claimArgs());
+      expect(granted.map((job) => job.id)).toEqual(["shared"]);
+      expect(granted[0]?.owner).toBe("alice");
+      const replay = await store.enqueue({
+        id: "shared",
+        siteId: SITE,
+        stub: stub("shared")
+      });
+      expect(replay).toEqual(await store.job(SITE, "shared"));
+      await done();
+    });
+    it("grants only what the owners set allows", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "mine", siteId: SITE, stub: stub("mine") });
+      await store.enqueue({
+        id: "theirs",
+        siteId: SITE,
+        stub: stub("theirs", "mallory")
+      });
+      const granted = await store.claim(claimArgs());
+      expect(granted.map((job) => job.id)).toEqual(["mine"]);
+      await done();
+    });
+    it("refuses a stale lease and honours the current one", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const [granted] = await store.claim(claimArgs());
+      await store.seal({ jobId: "a", siteId: SITE, envelope: ENVELOPE });
+      expect(
+        await store.takePayload({
+          jobId: "a",
+          runnerId: "runner_1",
+          leaseId: "an-older-grant"
+        })
+      ).toEqual({ refused: "stale-lease" });
+      expect(
+        await store.takePayload({
+          jobId: "a",
+          runnerId: "runner_1",
+          leaseId: granted.lease.id
+        })
+      ).toEqual({ envelope: ENVELOPE });
+      await done();
+    });
+    it("will not answer for one job with another job's lease", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "mine", siteId: SITE, stub: stub("mine") });
+      await store.enqueue({ id: "other", siteId: SITE, stub: stub("other") });
+      const granted = await store.claim(claimArgs());
+      const mine = granted.find((job) => job.id === "mine");
+      const other = granted.find((job) => job.id === "other");
+      await store.seal({ jobId: "other", siteId: SITE, envelope: ENVELOPE });
+      expect(
+        await store.takePayload({
+          jobId: "other",
+          runnerId: "runner_1",
+          leaseId: mine.lease.id
+        })
+      ).toEqual({ refused: "stale-lease" });
+      expect(
+        await store.takePayload({
+          jobId: "other",
+          runnerId: "runner_1",
+          leaseId: other.lease.id
+        })
+      ).toEqual({ envelope: ENVELOPE });
+      await done();
+    });
+    it("renews a grant it still holds, and extends the sweep with it", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const [granted] = await store.claim(claimArgs({ leaseMs: 1e3 }));
+      const renewed = await store.renewLeases({
+        runnerId: "runner_1",
+        leases: [{ jobId: "a", leaseId: granted.lease.id }],
+        leaseMs: 6e4
+      });
+      expect(renewed.lost).toEqual([]);
+      expect(renewed.renewed.map((r) => r.jobId)).toEqual(["a"]);
+      expect(renewed.renewed[0].expiresAt).toBeGreaterThan(
+        granted.lease.expiresAt
+      );
+      expect((await store.job(SITE, "a"))?.claimedBy?.leaseExpiresAt).toBe(
+        renewed.renewed[0].expiresAt
+      );
+      await done();
+    });
+    it("reports a lease the runner no longer holds as lost, and renews nothing", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const [granted] = await store.claim(claimArgs({ leaseMs: 1e3 }));
+      const before = (await store.job(SITE, "a"))?.claimedBy?.leaseExpiresAt;
+      const renewed = await store.renewLeases({
+        runnerId: "runner_1",
+        leases: [{ jobId: "a", leaseId: "a-grant-that-ended" }],
+        leaseMs: 6e4
+      });
+      expect(renewed.renewed).toEqual([]);
+      expect(renewed.lost).toEqual([
+        { jobId: "a", leaseId: "a-grant-that-ended" }
+      ]);
+      expect((await store.job(SITE, "a"))?.claimedBy?.leaseExpiresAt).toBe(
+        before
+      );
+      expect((await store.job(SITE, "a"))?.claimedBy?.leaseId).toBe(
+        granted.lease.id
+      );
+      await done();
+    });
+    it("does not hand out a stub it cannot parse", async () => {
+      const { store, done } = await make();
+      if (!serialising || writeRawStub === void 0) {
+        await done();
+        return;
+      }
+      await store.enqueue({ id: "good", siteId: SITE, stub: stub("good") });
+      await store.enqueue({ id: "old", siteId: SITE, stub: stub("old") });
+      const legacy = { ...stub("old") };
+      delete legacy["site"];
+      await writeRawStub(store, "old", JSON.stringify(legacy));
+      const granted = await store.claim(claimArgs({ max: 10 }));
+      expect(granted.map((job) => job.id)).toEqual(["good"]);
+      expect((await store.job(SITE, "old"))?.state).toBe("queued");
+      await done();
+    });
+    it("honours a self job's audience", async () => {
+      const { store, done } = await make();
+      await store.enqueue({
+        id: "private",
+        siteId: SITE,
+        stub: { ...stub("private", "alice"), audience: "private" }
+      });
+      const granted = await store.claim(
+        claimArgs({ owner: "owner", owners: ["owner", "alice"] })
+      );
+      expect(granted).toEqual([]);
+      expect((await store.job(SITE, "private"))?.state).toBe("queued");
+      await done();
+    });
+    it("still offers that job to its owner's own machine", async () => {
+      const { store, done } = await make();
+      await store.enqueue({
+        id: "private",
+        siteId: SITE,
+        stub: { ...stub("private", "alice"), audience: "private" }
+      });
+      const granted = await store.claim(
+        claimArgs({ owner: "alice", owners: ["alice"] })
+      );
+      expect(granted.map((job) => job.id)).toEqual(["private"]);
+      await done();
+    });
+    it("does not offer a job back to the runner that refused it", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const [granted] = await store.claim(claimArgs());
+      await store.releaseLeases({
+        runnerId: "runner_1",
+        leases: [{ jobId: "a", leaseId: granted.lease.id }],
+        reason: "refused"
+      });
+      expect(await store.claim(claimArgs())).toEqual([]);
+      expect((await store.job(SITE, "a"))?.state).toBe("queued");
+      expect(
+        (await store.claim(claimArgs({ runnerId: "runner_2" }))).map(
+          (j) => j.id
+        )
+      ).toEqual(["a"]);
+      await done();
+    });
+    it("keeps a job claimable by a runner that only went away", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const [granted] = await store.claim(claimArgs());
+      await store.releaseLeases({
+        runnerId: "runner_1",
+        leases: [{ jobId: "a", leaseId: granted.lease.id }],
+        reason: "shutdown"
+      });
+      expect((await store.claim(claimArgs())).map((j) => j.id)).toEqual(["a"]);
+      await done();
+    });
+    it("stops offering a job past its deadline, and drops the ciphertext", async () => {
+      const { store, done } = await make();
+      await store.enqueue({
+        id: "late",
+        siteId: SITE,
+        stub: { ...stub("late"), deadlineAt: Date.now() - 1e3 }
+      });
+      expect(await store.claim(claimArgs())).toEqual([]);
+      expect(await store.job(SITE, "late")).toBeUndefined();
+      await done();
+    });
+    it("names a cancelled job to the device holding it, and offers it to nobody", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      await store.claim(claimArgs());
+      expect(await store.cancel({ jobId: "a", siteId: SITE })).toBe(true);
+      const held = (await store.job(SITE, "a"))?.claimedBy?.leaseId;
+      expect(await store.cancelRequests("runner_1")).toEqual([
+        { jobId: "a", leaseId: held }
+      ]);
+      expect(await store.cancel({ jobId: "a", siteId: "someone_else" })).toBe(
+        false
+      );
+      await done();
+    });
+    it("records a result once", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const [granted] = await store.claim(claimArgs());
+      const first = await store.complete({
+        jobId: "a",
+        runnerId: "runner_1",
+        leaseId: granted.lease.id,
+        envelope: ENVELOPE,
+        disposition: "ok"
+      });
+      const replay = await store.complete({
+        jobId: "a",
+        runnerId: "runner_1",
+        leaseId: granted.lease.id,
+        envelope: { ...ENVELOPE, ciphertext: "different" },
+        disposition: "error"
+      });
+      expect(first).toEqual({ accepted: true, state: "done" });
+      expect(replay).toEqual({
+        accepted: false,
+        duplicate: true,
+        state: "done"
+      });
+      expect((await store.job(SITE, "a"))?.disposition).toBe("ok");
+      await done();
+    });
+    it("answers the device that finished it with `duplicate`", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const [granted] = await store.claim(claimArgs());
+      const first = await store.complete({
+        jobId: "a",
+        runnerId: "runner_1",
+        leaseId: granted.lease.id,
+        envelope: ENVELOPE,
+        disposition: "ok"
+      });
+      expect(first).toEqual({ accepted: true, state: "done" });
+      const replay = await store.complete({
+        jobId: "a",
+        runnerId: "runner_1",
+        leaseId: granted.lease.id,
+        envelope: { ...ENVELOPE, ciphertext: "a-different-result" },
+        disposition: "error"
+      });
+      expect(replay).toEqual({
+        accepted: false,
+        duplicate: true,
+        state: "done"
+      });
+      const stranger = await store.complete({
+        jobId: "a",
+        runnerId: "runner_2",
+        leaseId: granted.lease.id,
+        envelope: ENVELOPE,
+        disposition: "ok"
+      });
+      expect(stranger).toEqual({ refused: "not-holder" });
+      expect((await store.job(SITE, "a"))?.disposition).toBe("ok");
+      await done();
+    });
+    it("refuses a result produced under a grant that ended", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      await store.claim(claimArgs());
+      const late = await store.complete({
+        jobId: "a",
+        runnerId: "runner_1",
+        leaseId: "a-grant-that-ended",
+        envelope: ENVELOPE,
+        disposition: "ok"
+      });
+      expect(late).toEqual({ refused: "stale-lease" });
+      expect((await store.job(SITE, "a"))?.state).toBe("awaiting-payload");
+      expect((await store.job(SITE, "a"))?.result).toBeUndefined();
+      await done();
+    });
+    it("refuses a payload for a job that already finished [V1-6]", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const [granted] = await store.claim(claimArgs());
+      await store.seal({ jobId: "a", siteId: SITE, envelope: ENVELOPE });
+      await store.takePayload({
+        jobId: "a",
+        runnerId: "runner_1",
+        leaseId: granted.lease.id
+      });
+      await store.complete({
+        jobId: "a",
+        runnerId: "runner_1",
+        leaseId: granted.lease.id,
+        envelope: ENVELOPE,
+        disposition: "ok"
+      });
+      const replay = await store.takePayload({
+        jobId: "a",
+        runnerId: "runner_1",
+        leaseId: granted.lease.id
+      });
+      expect(replay).toEqual({ refused: "terminal" });
+      expect((await store.job(SITE, "a"))?.state).toBe("done");
+      await done();
+    });
+    it("tells a runner nothing about another site's job id [V1-8]", async () => {
+      const { store, done } = await make();
+      await store.enqueue({
+        id: "secret",
+        siteId: "site_somebody_else",
+        stub: stub("secret")
+      });
+      await store.enqueue({ id: "mine", siteId: SITE, stub: stub("mine") });
+      const granted = await store.claim(claimArgs());
+      const mine = granted.find((job) => job.id === "mine");
+      const other = await store.takePayload({
+        jobId: "secret",
+        runnerId: "runner_1",
+        leaseId: mine.lease.id
+      });
+      const absent = await store.takePayload({
+        jobId: "no-such-job-anywhere",
+        runnerId: "runner_1",
+        leaseId: mine.lease.id
+      });
+      expect(other).toEqual(absent);
+      expect(other).toEqual({ refused: "not-found" });
+      await done();
+    });
+    it("offers a selected job only to a device advertising that service", async () => {
+      const { store, done } = await make();
+      await store.enqueue({
+        id: "picked",
+        siteId: SITE,
+        stub: { ...stub("picked"), service: "studio" }
+      });
+      const wrong = await store.claim(
+        claimArgs({
+          runnerId: "runner_wrong",
+          serves: /* @__PURE__ */ new Set([serviceKey("llm.generate", "laptop")])
+        })
+      );
+      expect(wrong.map((job) => job.id)).toEqual([]);
+      const right = await store.claim(
+        claimArgs({
+          runnerId: "runner_right",
+          serves: /* @__PURE__ */ new Set([serviceKey("llm.generate", "studio")])
+        })
+      );
+      expect(right.map((job) => job.id)).toEqual(["picked"]);
+      await done();
+    });
+    it("never falls back from a selection to the default", async () => {
+      const { store, done } = await make();
+      await store.enqueue({
+        id: "no-fallback",
+        siteId: SITE,
+        stub: { ...stub("no-fallback"), service: "studio" }
+      });
+      const granted = await store.claim(
+        claimArgs({
+          // Serves the kind by default, advertises no service by that name.
+          kinds: /* @__PURE__ */ new Set(["llm.generate"]),
+          serves: /* @__PURE__ */ new Set()
+        })
+      );
+      expect(granted.map((job) => job.id)).toEqual([]);
+      expect((await store.job(SITE, "no-fallback"))?.state).toBe("queued");
+      await done();
+    });
+    it("sends an unselected job to the default, not to the menu", async () => {
+      const { store, done } = await make();
+      await store.enqueue({
+        id: "unselected",
+        siteId: SITE,
+        stub: stub("unselected")
+      });
+      const nothingDefault = await store.claim(
+        claimArgs({
+          runnerId: "runner_menu",
+          // A menu, and no default for this kind — the withheld state.
+          kinds: /* @__PURE__ */ new Set(),
+          serves: /* @__PURE__ */ new Set([
+            serviceKey("llm.generate", "studio"),
+            serviceKey("llm.generate", "laptop")
+          ])
+        })
+      );
+      expect(nothingDefault.map((job) => job.id)).toEqual([]);
+      const hasDefault = await store.claim(
+        claimArgs({
+          runnerId: "runner_default",
+          kinds: /* @__PURE__ */ new Set(["llm.generate"]),
+          serves: /* @__PURE__ */ new Set([serviceKey("llm.generate", "studio")])
+        })
+      );
+      expect(hasDefault.map((job) => job.id)).toEqual(["unselected"]);
+      await done();
+    });
+    it("keeps the pair together, so two sets cannot multiply", async () => {
+      const { store, done } = await make();
+      await store.enqueue({
+        id: "crossed",
+        siteId: SITE,
+        stub: { ...stub("crossed"), kind: "llm.chat", service: "studio" }
+      });
+      const granted = await store.claim(
+        claimArgs({
+          kinds: /* @__PURE__ */ new Set(["llm.generate", "llm.chat"]),
+          serves: /* @__PURE__ */ new Set([
+            serviceKey("llm.generate", "studio"),
+            serviceKey("llm.chat", "claude")
+          ])
+        })
+      );
+      expect(granted.map((job) => job.id)).toEqual([]);
+      await done();
+    });
+    it("remembers a device, and what it says it can run", async () => {
+      const { store, done } = await make();
+      const device = publicIdentityOf(generateKeys(3e12));
+      await store.seen({
+        runnerId: "runner_1",
+        owner: "alice",
+        device,
+        capabilities: [capability("llama3")],
+        withheld: []
+      });
+      const known = await store.presence("runner_1");
+      expect(known?.owner).toBe("alice");
+      expect(known?.device.identity).toBe(device.identity);
+      expect(known?.capabilities.map((row) => row.model)).toEqual(["llama3"]);
+      await done();
+    });
+    it("replaces the matrix rather than merging it", async () => {
+      const { store, done } = await make();
+      const device = publicIdentityOf(generateKeys(3000000000001));
+      const seen = { runnerId: "runner_2", owner: "alice", device };
+      await store.seen({
+        ...seen,
+        capabilities: [capability("llama3")],
+        withheld: []
+      });
+      await store.seen({
+        ...seen,
+        capabilities: [capability("mistral")],
+        withheld: []
+      });
+      const known = await store.presence("runner_2");
+      expect(known?.capabilities.map((row) => row.model)).toEqual(["mistral"]);
+      await done();
+    });
+    it("keeps an empty matrix, because empty is an answer", async () => {
+      const { store, done } = await make();
+      const device = publicIdentityOf(generateKeys(3000000000002));
+      const seen = { runnerId: "runner_3", owner: "alice", device };
+      await store.seen({
+        ...seen,
+        capabilities: [capability("llama3")],
+        withheld: []
+      });
+      await store.seen({ ...seen, capabilities: [], withheld: [] });
+      expect((await store.presence("runner_3"))?.capabilities).toEqual([]);
+      await done();
+    });
+    it("remembers which kinds are withheld, and drops them when resolved", async () => {
+      const { store, done } = await make();
+      const device = publicIdentityOf(generateKeys(3000000000004));
+      const seen = { runnerId: "runner_withheld", owner: "alice", device };
+      await store.seen({
+        ...seen,
+        capabilities: [],
+        withheld: [
+          {
+            kind: "llm.generate",
+            claimants: [
+              { service: "ollama", offer: "team" },
+              { service: "mlx", offer: "private" }
+            ]
+          }
+        ]
+      });
+      const held = await store.presence("runner_withheld");
+      expect(held?.withheld.map((row) => row.kind)).toEqual(["llm.generate"]);
+      expect(held?.withheld[0]?.claimants.map((c) => c.service)).toEqual([
+        "ollama",
+        "mlx"
+      ]);
+      await store.seen({
+        ...seen,
+        capabilities: [capability("llama3")],
+        withheld: []
+      });
+      expect((await store.presence("runner_withheld"))?.withheld).toEqual([]);
+      await done();
+    });
+    it("stamps presence from its own clock, and moves it on the next beat", async () => {
+      const { store, done } = await make();
+      const device = publicIdentityOf(generateKeys(3000000000003));
+      const seen = { runnerId: "runner_4", owner: "alice", device };
+      const before = await store.now();
+      const first = await store.seen({
+        ...seen,
+        capabilities: [],
+        withheld: []
+      });
+      expect(first.lastSeenAt).toBeGreaterThanOrEqual(before);
+      const later = await store.seen({
+        ...seen,
+        capabilities: [],
+        withheld: []
+      });
+      expect(later.lastSeenAt).toBeGreaterThanOrEqual(first.lastSeenAt);
+      await done();
+    });
+    it("lists everyone it has seen", async () => {
+      const { store, done } = await make();
+      await store.seen({
+        runnerId: "runner_5",
+        owner: "alice",
+        device: publicIdentityOf(generateKeys(3000000000004)),
+        capabilities: [],
+        withheld: []
+      });
+      await store.seen({
+        runnerId: "runner_6",
+        owner: "bob",
+        device: publicIdentityOf(generateKeys(3000000000005)),
+        capabilities: [],
+        withheld: []
+      });
+      const everyone = await store.everyone();
+      const ids = everyone.map((row) => row.runnerId);
+      expect(ids).toContain("runner_5");
+      expect(ids).toContain("runner_6");
+      await done();
+    });
+    it("does not know a runner it has never seen", async () => {
+      const { store, done } = await make();
+      expect(await store.presence("runner_never")).toBeUndefined();
+      await done();
+    });
+    it("stamps deadlines from its own clock", async () => {
+      const { store, done } = await make();
+      await store.enqueue({ id: "a", siteId: SITE, stub: stub("a") });
+      const before = await store.now();
+      const [granted] = await store.claim(claimArgs({ leaseMs: 45e3 }));
+      const after = await store.now();
+      expect(granted.lease.expiresAt).toBeGreaterThanOrEqual(before + 45e3);
+      expect(granted.lease.expiresAt).toBeLessThanOrEqual(after + 45e3);
+      await done();
+    });
+  });
+}
+export {
+  CONTRACT_SITE,
+  describeStoreContract
+};
+//# sourceMappingURL=store-contract.js.map