@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/examples/assistant/test/tasks/tasks.test.ts

@@ -1,16 +1,19 @@
 import { describe, expect, it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
-import { CurrentCaller, type Member, type Operator } from "../../src/identity/Identity.js";
+import { Effect, Layer } from "effect";
+
+import { CurrentCaller } from "../../src/identity/Identity.js";
+import type { Member, Operator } from "../../src/identity/Identity.js";
 import { members } from "../../src/identity/members.js";
 import { Permissions } from "../../src/identity/permissions.js";
 import { tasks } from "../../src/tasks/handlers.js";
-import { TaskNotFound } from "../../src/tasks/Tasks.js";
 import { TaskStore } from "../../src/tasks/store.js";
+import { TaskNotFound } from "../../src/tasks/Tasks.js";
 
 // What the implementation does, with no model and no command line: `Action.client` runs the
 // same decoding, `authorize` and handler every surface runs. Each call names its caller.
-const as = (caller: Member | Operator) => Effect.provideService(CurrentCaller, caller);
+const as = (caller: Member | Operator) =>
+  Effect.provideService(CurrentCaller, caller);
 
 const operator: Operator = { kind: "operator", id: "root" };
 
@@ -22,52 +25,77 @@ describe("tasks, in process", () => {
     Effect.gen(function* () {
       const client = yield* Action.client(tasks);
 
-      yield* client.addTask({ title: "Book the venue", assignee: "ada" }).pipe(as(members.ada));
-      yield* client.addTask({ title: "Send invitations", assignee: "grace" }).pipe(as(operator));
+      yield* client
+        .addTask({ title: "Book the venue", assignee: "ada" })
+        .pipe(as(members.ada));
+      yield* client
+        .addTask({ title: "Send invitations", assignee: "grace" })
+        .pipe(as(operator));
 
-      const { tasks: listed } = yield* client.listTasks().pipe(as(members.grace));
+      const { tasks: listed } = yield* client
+        .listTasks()
+        .pipe(as(members.grace));
 
-      expect(listed.map(({ id, addedBy }) => [id, addedBy])).toEqual([
+      expect(listed.map(({ id, addedBy }) => [id, addedBy])).toStrictEqual([
         ["1", "ada"],
         ["2", "root"],
       ]);
-      expect(yield* client.listTasks({ assignee: "grace" }).pipe(as(members.grace))).toMatchObject({
+      expect(
+        yield* client.listTasks({ assignee: "grace" }).pipe(as(members.grace))
+      ).toMatchObject({
         tasks: [{ title: "Send invitations" }],
       });
-    }).pipe(Effect.provide(services)),
+    }).pipe(Effect.provide(services))
   );
 
-  it.effect("refuses a write from a member the store grants reading alone", () =>
-    Effect.gen(function* () {
-      const client = yield* Action.client(tasks);
-      const add = client.addTask({ title: "Order lunch", assignee: "guest" });
+  it.effect(
+    "refuses a write from a member the store grants reading alone",
+    () =>
+      Effect.gen(function* () {
+        const client = yield* Action.client(tasks);
+        const add = client.addTask({ title: "Order lunch", assignee: "guest" });
 
-      const refusal = yield* Effect.flip(add.pipe(as(members.guest)));
+        const refusal = yield* Effect.flip(add.pipe(as(members.guest)));
 
-      expect(refusal).toBeInstanceOf(Action.Forbidden);
-      expect(refusal.message).toBe("Requires tasks:write.");
-      expect(yield* client.listTasks().pipe(as(members.guest))).toEqual({ tasks: [] });
-    }).pipe(Effect.provide(services)),
+        expect(refusal).toBeInstanceOf(Action.Forbidden);
+        expect(refusal.message).toBe("Requires tasks:write.");
+        expect(yield* client.listTasks().pipe(as(members.guest))).toStrictEqual(
+          {
+            tasks: [],
+          }
+        );
+      }).pipe(Effect.provide(services))
   );
 
-  it.effect("admits the operator, whom the permission store does not know", () =>
-    Effect.gen(function* () {
-      const client = yield* Action.client(tasks);
-      const add = client.addTask({ title: "Rotate the keys", assignee: "ada" });
-      const { id } = yield* add.pipe(as(operator));
+  it.effect(
+    "admits the operator, whom the permission store does not know",
+    () =>
+      Effect.gen(function* () {
+        const client = yield* Action.client(tasks);
+
+        const add = client.addTask({
+          title: "Rotate the keys",
+          assignee: "ada",
+        });
 
-      expect(yield* client.completeTask({ id }).pipe(as(operator))).toMatchObject({ done: true });
-    }).pipe(Effect.provide(services)),
+        const { id } = yield* add.pipe(as(operator));
+
+        expect(
+          yield* client.completeTask({ id }).pipe(as(operator))
+        ).toMatchObject({ done: true });
+      }).pipe(Effect.provide(services))
   );
 
-  it.effect("fails with the declared error for a task that does not exist", () =>
-    Effect.gen(function* () {
-      const client = yield* Action.client(tasks);
-      const annotate = client.annotateTask({ id: "9", notes: "Urgent." });
+  it.effect(
+    "fails with the declared error for a task that does not exist",
+    () =>
+      Effect.gen(function* () {
+        const client = yield* Action.client(tasks);
+        const annotate = client.annotateTask({ id: "9", notes: "Urgent." });
 
-      expect(yield* Effect.flip(annotate.pipe(as(members.ada)))).toEqual(
-        new TaskNotFound({ id: "9" }),
-      );
-    }).pipe(Effect.provide(services)),
+        expect(
+          yield* Effect.flip(annotate.pipe(as(members.ada)))
+        ).toStrictEqual(new TaskNotFound({ id: "9" }));
+      }).pipe(Effect.provide(services))
   );
 });

package/examples/assistant/test/toolkit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "@effect/vitest";
 import { Effect, Layer, Stream } from "effect";
 import { Chat, LanguageModel } from "effect/ai";
+
 import type { Member } from "../src/identity/Identity.js";
 import { members } from "../src/identity/members.js";
 import { Permissions } from "../src/identity/permissions.js";
@@ -11,21 +12,43 @@ import { actingFor, layer, toolkit } from "../src/toolkit.js";
 // What the toolkit adds to the implementations: a caller per call, and a model's approvals.
 // The handlers run in this process, on a store in memory the tests can read too.
 const tools = layer.pipe(
-  Layer.provideMerge(Layer.mergeAll(TaskStore.layerMemory, Permissions.layerMemory)),
+  Layer.provideMerge(
+    Layer.mergeAll(TaskStore.layerMemory, Permissions.layerMemory)
+  )
 );
 
 // A model's call of `addTask`, as a provider sends it.
 const adding = (id: string, assignee: string) =>
-  ({ type: "tool-call", id, name: "addTask", params: { title: "Order lunch", assignee } }) as const;
+  ({
+    type: "tool-call",
+    id,
+    name: "addTask",
+    params: { title: "Order lunch", assignee },
+  }) as const;
 
 // Which calls of a turn ran, and which wait for a person.
-const outcome = (response: LanguageModel.GenerateTextResponse<typeof toolkit.tools, "opaque">) => ({
+const outcome = (
+  response: LanguageModel.GenerateTextResponse<typeof toolkit.tools, "opaque">
+) => ({
   ran: response.toolResults.map(({ id }) => id),
   waiting: response.content.flatMap((part) =>
-    part.type === "tool-approval-request" ? [part.toolCallId] : [],
+    part.type === "tool-approval-request" ? [part.toolCallId] : []
   ),
 });
 
+// The model answers each member with the same two calls.
+const plan = (member: Member) =>
+  LanguageModel.generateText({
+    prompt: "Plan the launch.",
+    toolkit,
+  }).pipe(
+    actingFor(member),
+    Effect.map(outcome),
+    Effect.provide(
+      scripted([adding("for ada", "ada"), adding("for grace", "grace")])
+    )
+  );
+
 describe("the toolkit", () => {
   it.effect("runs each call as the member provided around it", () =>
     Effect.gen(function* () {
@@ -33,9 +56,10 @@ describe("the toolkit", () => {
 
       // A call by hand, with the JSON arguments a model sends. The member goes around the whole
       // call, the collecting of its results included.
-      const add = handle("addTask", { title: "Order lunch", assignee: "guest" }).pipe(
-        Effect.flatMap(Stream.runCollect),
-      );
+      const add = handle("addTask", {
+        title: "Order lunch",
+        assignee: "guest",
+      }).pipe(Effect.flatMap(Stream.runCollect));
 
       // A refusal is not raised: it is a result the model reads, as a declared error is.
       expect(yield* add.pipe(actingFor(members.guest))).toMatchObject([
@@ -44,77 +68,82 @@ describe("the toolkit", () => {
       expect(yield* add.pipe(actingFor(members.ada))).toMatchObject([
         { isFailure: false, result: { id: "1", addedBy: "ada" } },
       ]);
-    }).pipe(Effect.provide(tools)),
+    }).pipe(Effect.provide(tools))
   );
 
-  it.effect("asks for approval before a model adds to a list that is not its caller's", () =>
-    Effect.gen(function* () {
-      // The model answers each member with the same two calls.
-      const plan = (member: Member) =>
-        LanguageModel.generateText({ prompt: "Plan the launch.", toolkit }).pipe(
-          actingFor(member),
-          Effect.map(outcome),
-          Effect.provide(scripted([adding("for ada", "ada"), adding("for grace", "grace")])),
-        );
-
-      expect(yield* plan(members.ada)).toEqual({ ran: ["for ada"], waiting: ["for grace"] });
-      expect(yield* plan(members.grace)).toEqual({ ran: ["for grace"], waiting: ["for ada"] });
-
-      // A call that waits has not run.
-      const store = yield* TaskStore;
-
-      expect((yield* store.list(undefined)).map(({ addedBy }) => addedBy)).toEqual([
-        "ada",
-        "grace",
-      ]);
-    }).pipe(Effect.provide(tools)),
+  it.effect(
+    "asks for approval before a model adds to a list that is not its caller's",
+    () =>
+      Effect.gen(function* () {
+        expect(yield* plan(members.ada)).toStrictEqual({
+          ran: ["for ada"],
+          waiting: ["for grace"],
+        });
+        expect(yield* plan(members.grace)).toStrictEqual({
+          ran: ["for grace"],
+          waiting: ["for ada"],
+        });
+
+        // A call that waits has not run.
+        const store = yield* TaskStore;
+
+        expect(
+          (yield* store.list(undefined)).map(({ addedBy }) => addedBy)
+        ).toStrictEqual(["ada", "grace"]);
+      }).pipe(Effect.provide(tools))
   );
 
-  it.effect("authorizes an approved call too: approval lets no one do what they may not", () =>
-    Effect.gen(function* () {
-      // The `Chat` keeps the request in its history, which the answer is matched against.
-      const chat = yield* Chat.empty;
-
-      const asked = yield* chat
-        .generateText({ prompt: "Add lunch to Ada's list.", toolkit })
-        .pipe(actingFor(members.guest));
-
-      expect(outcome(asked)).toEqual({ ran: [], waiting: ["for ada"] });
-
-      // The approved call runs in the turn that carries the answer, as that turn's caller.
-      const answered = yield* chat
-        .generateText({
-          prompt: [
-            {
-              role: "tool",
-              content: asked.content.flatMap((part) =>
-                part.type === "tool-approval-request"
-                  ? [
-                      {
-                        type: "tool-approval-response",
-                        approvalId: part.approvalId,
-                        approved: true,
-                      },
-                    ]
-                  : [],
-              ),
-            },
-          ],
-          toolkit,
-        })
-        .pipe(actingFor(members.guest));
-
-      expect(answered.toolResults).toMatchObject([
-        {
-          id: "for ada",
-          isFailure: true,
-          result: { message: "Requires tasks:write." },
-        },
-      ]);
-
-      const store = yield* TaskStore;
-
-      expect(yield* store.list(undefined)).toEqual([]);
-    }).pipe(Effect.provide(scripted([adding("for ada", "ada")])), Effect.provide(tools)),
+  it.effect(
+    "authorizes an approved call too: approval lets no one do what they may not",
+    () =>
+      Effect.gen(function* () {
+        // The `Chat` keeps the request in its history, which the answer is matched against.
+        const chat = yield* Chat.empty;
+
+        const asked = yield* chat
+          .generateText({ prompt: "Add lunch to Ada's list.", toolkit })
+          .pipe(actingFor(members.guest));
+
+        expect(outcome(asked)).toStrictEqual({ ran: [], waiting: ["for ada"] });
+
+        // The approved call runs in the turn that carries the answer, as that turn's caller.
+        const answered = yield* chat
+          .generateText({
+            prompt: [
+              {
+                role: "tool",
+                content: asked.content.flatMap((part) =>
+                  part.type === "tool-approval-request"
+                    ? [
+                        {
+                          type: "tool-approval-response",
+                          approvalId: part.approvalId,
+                          approved: true,
+                        },
+                      ]
+                    : []
+                ),
+              },
+            ],
+            toolkit,
+          })
+          .pipe(actingFor(members.guest));
+
+        expect(answered.toolResults).toMatchObject([
+          {
+            id: "for ada",
+            isFailure: true,
+            result: { message: "Requires tasks:write." },
+          },
+        ]);
+
+        const store = yield* TaskStore;
+
+        expect(yield* store.list(undefined)).toStrictEqual([]);
+      }).pipe(
+        Effect.provide(
+          scripted([adding("for ada", "ada")]).pipe(Layer.provideMerge(tools))
+        )
+      )
   );
 });

package/examples/build-events/README.md

@@ -0,0 +1,83 @@
+# build-events
+
+A CI service whose events are watched by its members: `build.finished`, read from a store that can be asked what finished since a cursor, and `deploy.requested`, published by the action that requests a deploy, with no store to ask. Each member sees only the pipelines they may. It serves both, with the actions that cause them, as an MCP endpoint, as HTTP routes and as Effect RPC, delivers them by webhook, keeping its subscriptions past a restart, and watches them in process, over each surface, and from a command line. A second service, the notifier, watches failed builds by webhook. Two actions answer more than one value: `startBuild` reports progress as it runs, and `tailLog` answers a stream of a build's log lines.
+
+## Run it
+
+From the repository root, after `vp install`:
+
+```sh
+node --import tsx examples/build-events/src/server.ts
+BUILDS_TOKEN=grace node --import tsx examples/build-events/src/cli.ts watch build.finished
+BUILDS_TOKEN=grace PUBLIC_URL=https://<a tunnel to port 3001> node --import tsx examples/build-events/src/notifier.ts
+vp test examples/build-events
+```
+
+## Layout
+
+```text
+src/
+├── identity/
+│   ├── Identity.ts    contract: CurrentMember and the Login descriptor, with its principal and schema
+│   ├── members.ts     the demo members
+│   └── verifier.ts    Login's verifier: a token is a member's name
+├── builds/
+│   ├── Builds.ts      contract: the build schema, finishBuild, startBuild, tailLog and build.finished
+│   ├── store.ts       BuildStore: finished builds read by cursor, its epoch, and its Layer
+│   ├── handlers.ts    Action.implement: finishBuild, and startBuild reporting progress, each notifying build.finished
+│   ├── log.ts         Action.implement: tailLog, answering a stream of log lines
+│   └── events.ts      Event.implement: build.finished, a check source
+├── deploys/
+│   ├── Deploys.ts     contract: the deploy schema, requestDeploy and deploy.requested
+│   ├── approvers.ts   Approvers: who stands by to approve deploys, and its Layer
+│   ├── handlers.ts    Action.implement: requestDeploy, publishing deploy.requested
+│   └── events.ts      Event.implement: deploy.requested, a log source with a subscription hook
+├── Api.ts             the HTTP binding: the actions' routes and the events' routes
+├── Rpc.ts             the RPC binding: the actions' rpcs and the events' stream rpcs
+├── routes.ts          the MCP endpoint, the HTTP routes and the rpcs, from one list of implementations, and webhook delivery
+├── server.ts          entrypoint: the stores, the events announced, a body limit, webhook delivery's client, resolver and store, and Node's HTTP server
+├── commands.ts        ActionCli.remote: a command per action, and `watch` per event type
+├── cli.ts             entrypoint: the commands, calling the server over HTTP
+├── notifier/
+│   ├── Notices.ts     the failed builds the notifier was told of, and its Layer
+│   └── routes.ts      the notifier: its receiver, and its watch by webhook reading from it
+└── notifier.ts        entrypoint of the notifier, a second service
+test/
+├── support/           as: the caller of a call or subscription; inMemory: what the routes need, in memory
+├── builds/            watching build.finished in process, a progress report and a log's stream
+├── deploys/           watching deploy.requested in process
+├── routes.test.ts     watching both over MCP, streamed and polled, in memory
+├── http.test.ts       watching both over HTTP, as SSE and as JSON pages, in memory
+├── rpc.test.ts        watching over Effect RPC, in memory
+├── webhooks.test.ts   subscribing a callback, and the signed POSTs it receives, in memory
+├── notifier.test.ts   the notifier told of failed builds by webhook, both services in memory
+└── commands.test.ts   `watch build.finished` printing lines of JSON, in memory
+```
+
+## Where to look
+
+| To see | Read |
+| --- | --- |
+| An event type beside the actions of its domain | `src/builds/Builds.ts` |
+| A check source, its cursor the store's own | `src/builds/events.ts` |
+| A cursor that tells a restart apart, as `truncated` | `src/builds/store.ts` |
+| An action reporting progress as it runs | `src/builds/handlers.ts` |
+| An action answering a stream | `src/builds/log.ts` |
+| What a member may see, checked in the data access | `src/builds/store.ts` |
+| A log source, and each subscriber's `match` | `src/deploys/events.ts` |
+| Publishing to a log source from an action | `src/deploys/handlers.ts` |
+| Waking a check source's subscribers after a write | `src/builds/handlers.ts` |
+| Something set up upstream while a subscription lasts | `src/deploys/events.ts` |
+| Watching events in process, with an action causing them | `test/builds/events.test.ts` |
+| Serving events over MCP, and what it needs of `Login` | `src/routes.ts` |
+| Watching over MCP, by stream and by poll | `test/routes.test.ts` |
+| Binding events to HTTP routes beside the actions | `src/Api.ts` |
+| Watching over HTTP, by SSE and by JSON pages | `test/http.test.ts` |
+| Serving events as stream rpcs, and their serialization | `src/routes.ts` |
+| Watching over RPC | `test/rpc.test.ts` |
+| Watching from a command line, as lines of JSON | `src/commands.ts` |
+| Delivering events by webhook, and what it needs | `src/routes.ts`, `src/server.ts` |
+| Keeping webhook subscriptions past a restart | `src/server.ts`, `src/identity/Identity.ts` |
+| Subscribing a callback, and checking each signature | `test/webhooks.test.ts` |
+| Watching by webhook from a second service | `src/notifier/routes.ts` |
+| Two services in memory, each calling the other | `test/notifier.test.ts` |

package/examples/build-events/src/Api.ts

@@ -0,0 +1,27 @@
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
+import {
+  BuildFinished,
+  FinishBuild,
+  PipelineStatus,
+  StartBuild,
+  TailLog,
+} from "./builds/Builds.js";
+import { DeployRequested, RequestDeploy } from "./deploys/Deploys.js";
+import { Login } from "./identity/Identity.js";
+
+// The HTTP binding: each action at `POST /api/<name>`, and each event at
+// `POST /api/events/<name>`, which answers a page of JSON, or, asked for `text/event-stream`,
+// holds a stream open. It imports no server code, so a client imports it with the contracts.
+export const Http = ActionHttp.make(
+  [
+    FinishBuild,
+    StartBuild,
+    TailLog,
+    BuildFinished,
+    PipelineStatus,
+    RequestDeploy,
+    DeployRequested,
+  ],
+  { authentication: Login }
+);

package/examples/build-events/src/Rpc.ts

@@ -0,0 +1,26 @@
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+
+import {
+  BuildFinished,
+  FinishBuild,
+  PipelineStatus,
+  StartBuild,
+  TailLog,
+} from "./builds/Builds.js";
+import { DeployRequested, RequestDeploy } from "./deploys/Deploys.js";
+import { Login } from "./identity/Identity.js";
+
+// The RPC binding: each action an rpc named after it, and each event a stream rpc named after
+// it, which pushes each occurrence as the server reads it. Plain data, as the HTTP binding is.
+export const Rpc = ActionRpc.make(
+  [
+    FinishBuild,
+    StartBuild,
+    TailLog,
+    BuildFinished,
+    PipelineStatus,
+    RequestDeploy,
+    DeployRequested,
+  ],
+  { authentication: Login }
+);

package/examples/build-events/src/builds/Builds.ts

@@ -0,0 +1,108 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Schema } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+
+const Pipeline = Schema.String.annotate({
+  description: "A pipeline's name, such as api.",
+});
+
+const Status = Schema.Literals(["passed", "failed"]).annotate({
+  description: "How the build ended.",
+});
+
+export const Build = Schema.Struct({
+  id: Schema.String,
+  pipeline: Pipeline,
+  status: Status,
+});
+
+export type Build = typeof Build.Type;
+
+// DEMO ONLY: a CI runner reports finished builds; here a member does, so the example can
+// cause the event it watches.
+export const FinishBuild = Action.make("finishBuild", {
+  description: "Record that a build of a pipeline finished.",
+  input: { pipeline: Pipeline, status: Status },
+  success: Build,
+  readOnly: false,
+  caller: CurrentMember,
+});
+
+// A build run here, which reports each step as it starts, before it answers how the build ended.
+// A caller reads the steps only if it asks, with `onProgress`; each surface carries them its
+// own way. They are a snapshot to show: a caller falling behind misses some, never the answer.
+// What a caller must see every time is the answer, or `build.finished`, which this build causes.
+export const StartBuild = Action.make("startBuild", {
+  description:
+    "Run a build of a pipeline, reporting each step, and record how it ended.",
+  input: { pipeline: Pipeline },
+  success: Build,
+  progress: {
+    step: Schema.String.annotate({
+      description: "The step that started, such as test.",
+    }),
+    done: Schema.Finite.annotate({
+      description: "How many steps finished before it.",
+    }),
+    total: Schema.Finite.annotate({
+      description: "How many steps the build has.",
+    }),
+  },
+  readOnly: false,
+  caller: CurrentMember,
+});
+
+// A build this member may not see is not found, as one that never ran: its id tells nothing.
+export class BuildNotFound extends Schema.TaggedError<
+  BuildNotFound,
+  { readonly brand: unique symbol }
+>()("BuildNotFound", { buildId: Schema.String }, { httpApiStatus: 404 }) {}
+
+// An action answering a stream: its handler returns a `Stream` of lines, and every client's
+// call returns one, each line arriving as the server sends it. HTTP, RPC and a command carry a
+// stream; an MCP tool answers one result, the lines collected once the stream ends, so the MCP
+// endpoint in `routes.ts` leaves it out rather than put a whole log in a model's context.
+export const TailLog = Action.make("tailLog", {
+  description: "Stream a build's log, line by line.",
+  input: {
+    buildId: Schema.String.annotate({
+      description: "The build's id, such as build-1.",
+    }),
+  },
+  success: Action.Stream({ line: Schema.String }),
+  error: BuildNotFound,
+  readOnly: true,
+  caller: CurrentMember,
+});
+
+// An event type: what a subscription takes, what each occurrence carries, and who may
+// subscribe. Like an action's contract, it imports no server code.
+export const BuildFinished = Event.make("build.finished", {
+  description: "A build of a pipeline you may see finished.",
+  input: {
+    pipeline: Schema.optional(Pipeline).annotate({
+      description: "Only this pipeline's builds.",
+    }),
+    status: Schema.optional(Status).annotate({
+      description: "Only builds that ended so.",
+    }),
+  },
+  payload: Build,
+  caller: CurrentMember,
+});
+
+// An event whose occurrence is the whole value: how a pipeline's last build ended, `null` before
+// its first. A subscriber is sent it as it is, then again each time a build of it finishes.
+export const PipelineStatus = Event.make("pipeline.status", {
+  description:
+    "How a pipeline's last build ended: first as it is, then each time one finishes.",
+  input: { pipeline: Pipeline },
+  payload: {
+    status: Schema.NullOr(Status).annotate({
+      description: "How it ended; null before any did.",
+    }),
+  },
+  caller: CurrentMember,
+});

package/examples/build-events/src/builds/events.ts

@@ -0,0 +1,54 @@
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { BuildFinished } from "./Builds.js";
+import { BuildStore } from "./store.js";
+
+// A check source: one function answers "what finished since this cursor?" for every
+// subscriber, whether it polls or holds a stream open, on every surface. The builder runs once,
+// at startup; the check runs per subscriber, as that subscriber.
+export const buildEvents = Event.implement(
+  BuildFinished,
+  Effect.gen(function* () {
+    const store = yield* BuildStore;
+
+    return {
+      check: ({ pipeline, status }, cursor) =>
+        Effect.gen(function* () {
+          const member = yield* CurrentMember;
+
+          // A first subscription asks with `null`: the store answers the current position, so
+          // the subscriber starts from now.
+          const page = yield* store.finishedSince(
+            member.pipelines,
+            cursor,
+            100
+          );
+
+          return {
+            cursor: page.cursor,
+            hasMore: page.hasMore,
+            // A cursor the store cannot resume from: the subscriber is sent a gap first.
+            truncated: page.truncated,
+            events: page.builds
+              .filter(
+                (build) => pipeline === undefined || build.pipeline === pipeline
+              )
+              .filter(
+                (build) => status === undefined || build.status === status
+              )
+              // The store's own id, within its epoch: a subscriber that sees a build twice,
+              // after a reconnect, drops the second, and never drops a build of a restarted store
+              // as one it saw before.
+              .map((build) => ({
+                eventId: `${page.epoch}/${build.id}`,
+                data: build,
+              })),
+          };
+        }),
+    };
+  }),
+  // Every member may watch; which builds each sees is the store's check, by pipeline.
+  { authorize: Event.allowAll }
+);