@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/examples/kitchen-sink/src/cli.ts

@@ -1,15 +1,24 @@
-import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node";
+import {
+  NodeHttpClient,
+  NodeRuntime,
+  NodeServices,
+} from "@effect/platform-node";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { Config, Effect, flow, Option } from "effect";
 import { Command } from "effect/cli";
 import { HttpClient, HttpClientRequest } from "effect/http";
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
 import { Http } from "./Api.js";
 
+const unchanged = (request: HttpClientRequest.HttpClientRequest) => request;
+
 // Entrypoint: `node --import tsx examples/kitchen-sink/src/cli.ts list-issues`.
 // The members' CLI: a command per action of the binding, a flag per input field, each calling
 // the server over HTTP. It imports the binding alone and runs nothing locally: the server
-// authenticates and authorizes, as for any client.
+// authenticates and authorizes, as for any client. The binding's event adds `tracker watch
+// issue.changed --status open`, printing each change of the member's workspace as a line of
+// JSON as it happens; `--cursor` resumes from the last one's.
 const tracker = ActionCli.remote(Http, {
   name: "tracker",
   // Each command's options, keyed by its action's name and typed by that action.
@@ -18,10 +27,13 @@ const tracker = ActionCli.remote(Http, {
     // the JSON back). Its help says so: the action's description, which HTTP and MCP keep, says
     // what the JSON holds.
     listIssues: {
-      description: "List your workspace's issues, newest first, one line each: id, status, title.",
+      description:
+        "List your workspace's issues, newest first, one line each: id, status, title.",
       aliases: { limit: "n", status: "s" },
       render: ({ issues }) =>
-        issues.map(({ id, status, title }) => `${id}  ${status}  ${title}`).join("\n"),
+        issues
+          .map(({ id, status, title }) => `${id}  ${status}  ${title}`)
+          .join("\n"),
     },
     // `tracker get-issue ACME-1`: the id is an argument, not a flag.
     getIssue: {
@@ -37,6 +49,12 @@ const tracker = ActionCli.remote(Http, {
     createIssue: { stdin: "body" },
     commentOnIssue: { name: "comment", positional: ["id"], stdin: "text" },
     closeIssue: { name: "close", positional: ["id"] },
+    // An action answering a stream: `render` takes each issue, printed as it arrives, one line
+    // each; `--json` prints each as a line of JSON instead, so `tracker export-issues --json >
+    // issues.jsonl` writes JSON Lines.
+    exportIssues: {
+      render: ({ id, status, title }) => `${id}  ${status}  ${title}`,
+    },
     // `render` receives the decoded success, the image's bytes a `Uint8Array`.
     getAttachment: {
       positional: ["id"],
@@ -49,14 +67,12 @@ const tracker = ActionCli.remote(Http, {
   // a workspace its 403.
   client: Effect.gen(function* () {
     const baseUrl = yield* Config.String("TRACKER_URL").pipe(
-      Config.withDefault("http://127.0.0.1:3000"),
+      Config.withDefault("http://127.0.0.1:3000")
     );
 
     const token = yield* Config.option(Config.Redacted("TRACKER_TOKEN"));
     const workspace = yield* Config.option(Config.String("TRACKER_WORKSPACE"));
 
-    const unchanged = (request: HttpClientRequest.HttpClientRequest) => request;
-
     return yield* ActionHttp.client(Http, {
       baseUrl,
       transformClient: HttpClient.mapRequest(
@@ -68,8 +84,8 @@ const tracker = ActionCli.remote(Http, {
           Option.match(workspace, {
             onNone: () => unchanged,
             onSome: (slug) => HttpClientRequest.setHeader("x-workspace", slug),
-          }),
-        ),
+          })
+        )
       ),
     });
   }),
@@ -78,5 +94,5 @@ const tracker = ActionCli.remote(Http, {
 Command.run(tracker, { version: "1.0.0" }).pipe(
   Effect.provide([NodeHttpClient.layerUndici, NodeServices.layer]),
   ActionCli.logToStderr,
-  NodeRuntime.runMain,
+  NodeRuntime.runMain()
 );

package/examples/kitchen-sink/src/config.ts

@@ -5,7 +5,7 @@ import { Config } from "effect";
 
 /** Where callers reach the public port: the OAuth resource, and a Host the server answers to. */
 export const publicUrl = Config.String("PUBLIC_URL").pipe(
-  Config.withDefault("http://localhost:3000"),
+  Config.withDefault("http://localhost:3000")
 );
 
 /**

package/examples/kitchen-sink/src/identity/Identity.ts

@@ -1,7 +1,7 @@
-import { Context, Schema } from "effect";
-import { HttpApiSecurity } from "effect/http-api";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Context, Schema } from "effect";
+import { HttpApiSecurity } from "effect/http-api";
 
 export const scopes = { read: "issues:read", write: "issues:write" } as const;
 
@@ -19,21 +19,27 @@ export interface Member {
  * provides it per request, and a local host (stdio, the assistant, a test) provides it itself.
  */
 export class CurrentMember extends Context.Service<CurrentMember, Member>()(
-  "tracker/CurrentMember",
+  "tracker/CurrentMember"
 ) {}
 
 // What a verifier may fail with besides a refusal: the issuer it checks tokens with is down.
 // It is not the caller's fault, so it is no 401: signing in again cannot help.
-export class IssuerUnavailable extends Schema.TaggedError<IssuerUnavailable>()(
+export class IssuerUnavailable extends Schema.TaggedError<
+  IssuerUnavailable,
+  { readonly brand: unique symbol }
+>()(
   "IssuerUnavailable",
   { retryAfterSeconds: Schema.Finite },
-  { httpApiStatus: 503 },
+  { httpApiStatus: 503 }
 ) {}
 
 // How an API client, the CLI and an MCP client prove they are CurrentMember: a bearer token,
-// the default scheme.
+// the default scheme. `principal` names one subscriber, for what MCP and HTTP hold between its
+// requests, such as its webhook subscriptions: a member of two workspaces is two subscribers,
+// so it names the workspace too, encoded so no two pairs spell one principal.
 export const Login = Authentication.make("tracker.Login", CurrentMember, {
   error: IssuerUnavailable,
+  principal: (member) => JSON.stringify([member.workspace, member.id]),
 });
 
 // How the web app proves the same identity: the session cookie its sign-in page set. It is
@@ -46,16 +52,24 @@ export const Session = Authentication.make("tracker.Session", CurrentMember, {
 // What the API's request quota answers with. It is the bindings' error, not an action's:
 // middleware sends it on any action's route, before its input is decoded. Only HTTP and RPC
 // have that middleware.
-export class QuotaExceeded extends Schema.TaggedError<QuotaExceeded>()(
+export class QuotaExceeded extends Schema.TaggedError<
+  QuotaExceeded,
+  { readonly brand: unique symbol }
+>()(
   "QuotaExceeded",
   { retryAfterSeconds: Schema.Finite },
-  { httpApiStatus: 429 },
+  { httpApiStatus: 429 }
 ) {}
 
 // An action without input: its client method takes no argument, its command no flag.
 export const WhoAmI = Action.make("whoAmI", {
-  description: "Show who the credential identifies, in which workspace, with which scopes.",
-  success: { id: Schema.String, workspace: Schema.String, scopes: Schema.Array(Scope) },
+  description:
+    "Show who the credential identifies, in which workspace, with which scopes.",
+  success: {
+    id: Schema.String,
+    workspace: Schema.String,
+    scopes: Schema.Array(Scope),
+  },
   readOnly: true,
   caller: CurrentMember,
 });

package/examples/kitchen-sink/src/identity/authenticate.ts

@@ -1,11 +1,14 @@
-import { Array, Effect, Option, type Redacted } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Array, Effect, Option } from "effect";
+import type { Redacted } from "effect";
+
 import { publicUrl } from "../config.js";
 import { WorkspaceRegistry } from "../workspaces/registry.js";
 import { Tenant } from "../workspaces/tenant.js";
 import { Directory } from "./directory.js";
-import { Login, type Member, scopes, Session } from "./Identity.js";
+import { Login, scopes, Session } from "./Identity.js";
+import type { Member } from "./Identity.js";
 
 // What both verifiers check once a credential has named a member: an operator may have
 // suspended the workspace. Checked here, it holds on every remote surface.
@@ -15,12 +18,16 @@ const inService = Effect.gen(function* () {
   return Effect.fn("inService")(function* (member: Member) {
     const suspended = yield* registry.get(member.workspace).pipe(
       Effect.map((workspace) => workspace.suspended),
-      Effect.orElseSucceed(() => true),
+      Effect.orElseSucceed(() => true)
     );
 
     // No scopes named: signing in again grants nothing, so this is a plain 403, never a
     // challenge sending an OAuth client back to its authorization server.
-    if (suspended) return yield* new Action.Forbidden({ message: "This workspace is suspended." });
+    if (suspended) {
+      return yield* new Action.Forbidden({
+        message: "This workspace is suspended.",
+      });
+    }
 
     return member;
   });
@@ -38,7 +45,7 @@ const protectedResource = Effect.map(
       scopesSupported: [scopes.read, scopes.write],
       scopesRequired: [scopes.read],
       resourceName: "Tracker",
-    }) satisfies Authentication.ProtectedResource,
+    }) satisfies Authentication.ProtectedResource
 );
 
 // Server only: `Login`'s provider. The Effect is a builder, as `Action.implement` takes one:
@@ -50,24 +57,25 @@ export const authenticateBearer = Authentication.layer(
     const directory = yield* Directory;
     const admit = yield* inService;
 
-    return (token: Redacted.Redacted<string>) =>
+    return (token: Redacted.Redacted) =>
       Effect.gen(function* () {
         const memberships = yield* directory.ofToken(token);
 
         const member = Option.flatMap(yield* Tenant, (slug) =>
-          Array.findFirst(memberships, ({ workspace }) => workspace === slug),
+          Array.findFirst(memberships, ({ workspace }) => workspace === slug)
         );
 
         if (Option.isNone(member)) {
           return yield* new Action.Forbidden({
-            message: "Name a workspace you belong to in the X-Workspace header.",
+            message:
+              "Name a workspace you belong to in the X-Workspace header.",
           });
         }
 
         return yield* admit(member.value);
       });
   }),
-  { protectedResource },
+  { protectedResource }
 );
 
 // `Session`'s provider: the same identity from another credential. Its verifier receives what
@@ -79,7 +87,7 @@ export const authenticateSession = Authentication.layer(
     const directory = yield* Directory;
     const admit = yield* inService;
 
-    return (session: Redacted.Redacted<string>) =>
+    return (session: Redacted.Redacted) =>
       Effect.flatMap(directory.ofSession(session), admit);
-  }),
+  })
 );

package/examples/kitchen-sink/src/identity/authorize.ts

@@ -1,5 +1,7 @@
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
 import { CurrentMember, scopes } from "./Identity.js";
 
 // The members' rule, read from each contract: a read needs the read scope, anything else the
@@ -7,11 +9,19 @@ import { CurrentMember, scopes } from "./Identity.js";
 // them runs it before the handler: HTTP, MCP, RPC, stdio, the assistant's tools and a test alike.
 // For a bearer token, naming the missing scope turns the 403 into the challenge an OAuth client
 // re-authorizes on.
-export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
-  const scope = action.readOnly ? scopes.read : scopes.write;
+export const authorize = Effect.fn("authorize")(function* (
+  contract: Action.Any | Event.Any
+) {
+  // A subscription to an event reads, as a `readOnly` action does.
+  const scope =
+    Event.isEvent(contract) || contract.readOnly ? scopes.read : scopes.write;
+
   const member = yield* CurrentMember;
 
   if (!member.scopes.includes(scope)) {
-    return yield* new Action.Forbidden({ message: `Requires ${scope}.`, scopes: [scope] });
+    return yield* new Action.Forbidden({
+      message: `Requires ${scope}.`,
+      scopes: [scope],
+    });
   }
 });

package/examples/kitchen-sink/src/identity/directory.ts

@@ -1,5 +1,6 @@
-import { Context, Effect, Layer, Redacted } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Context, Effect, Layer, Redacted } from "effect";
+
 import type { IssuerUnavailable, Member } from "./Identity.js";
 import { members } from "./members.js";
 
@@ -12,11 +13,14 @@ export class Directory extends Context.Service<
   {
     /** Every membership of the account an access token was issued to. */
     readonly ofToken: (
-      token: Redacted.Redacted<string>,
-    ) => Effect.Effect<ReadonlyArray<Member>, Action.Unauthenticated | IssuerUnavailable>;
+      token: Redacted.Redacted
+    ) => Effect.Effect<
+      readonly Member[],
+      Action.Unauthenticated | IssuerUnavailable
+    >;
     /** The member a web session was opened for: a session belongs to one workspace. */
     readonly ofSession: (
-      session: Redacted.Redacted<string>,
+      session: Redacted.Redacted
     ) => Effect.Effect<Member, Action.Unauthenticated>;
   }
 >()("tracker/Directory") {
@@ -25,7 +29,7 @@ export class Directory extends Context.Service<
   // its audience included, failing with `IssuerUnavailable` when it cannot reach its keys, and
   // reads sessions from their store.
   static readonly layerDemo = Layer.sync(Directory, () => {
-    const accounts = new Map<string, ReadonlyArray<Member>>([
+    const accounts = new Map<string, readonly Member[]>([
       ["ada", [members.ada, members.adaAtGlobex]],
       ["linus", [members.linus]],
       ["kay", [members.kay]],
@@ -41,11 +45,16 @@ export class Directory extends Context.Service<
     return Directory.of({
       ofToken: (token) =>
         Effect.fromNullishOr(accounts.get(Redacted.value(token))).pipe(
-          Effect.mapError(() => new Action.Unauthenticated({ message: "Unknown demo token." })),
+          Effect.mapError(
+            () => new Action.Unauthenticated({ message: "Unknown demo token." })
+          )
         ),
       ofSession: (session) =>
         Effect.fromNullishOr(sessions.get(Redacted.value(session))).pipe(
-          Effect.mapError(() => new Action.Unauthenticated({ message: "Unknown demo session." })),
+          Effect.mapError(
+            () =>
+              new Action.Unauthenticated({ message: "Unknown demo session." })
+          )
         ),
     });
   });

package/examples/kitchen-sink/src/identity/handlers.ts

@@ -1,4 +1,5 @@
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+
 import { CurrentMember, WhoAmI } from "./Identity.js";
 
 // `Action.allowAll`: verification is the whole policy here. Any authenticated member may ask

package/examples/kitchen-sink/src/identity/members.ts

@@ -1,4 +1,5 @@
-import { type Member, scopes } from "./Identity.js";
+import { scopes } from "./Identity.js";
+import type { Member } from "./Identity.js";
 
 // DEMO ONLY: the people of the demo, each a member of one workspace. A real application has no
 // such table: its directory reads a member from a signed token or a stored session. A local
@@ -9,5 +10,9 @@ export const members = {
   linus: { id: "linus", workspace: "acme", scopes: [scopes.read] },
   // Invited to acme, granted nothing yet.
   kay: { id: "kay", workspace: "acme", scopes: [] },
-  grace: { id: "grace", workspace: "globex", scopes: [scopes.read, scopes.write] },
+  grace: {
+    id: "grace",
+    workspace: "globex",
+    scopes: [scopes.read, scopes.write],
+  },
 } as const satisfies Readonly<Record<string, Member>>;

package/examples/kitchen-sink/src/identity/quota.ts

@@ -2,6 +2,7 @@ import { Duration, Effect, Layer } from "effect";
 import { HttpApiMiddleware } from "effect/http-api";
 import { RateLimiter } from "effect/persistence";
 import { RpcMiddleware } from "effect/rpc";
+
 import { CurrentMember, QuotaExceeded } from "./Identity.js";
 
 // The API's request quota: 60 requests a minute per member. It is a surface's own middleware,
@@ -10,24 +11,22 @@ import { CurrentMember, QuotaExceeded } from "./Identity.js";
 // caller. HTTP and RPC each have their native middleware; an MCP endpoint takes none.
 
 /** Listed in `ActionHttp.layer`'s `middleware`. It fails only with an error the binding declares. */
-export class HttpQuota extends HttpApiMiddleware.Service<HttpQuota, { requires: CurrentMember }>()(
-  "tracker/HttpQuota",
-  { error: QuotaExceeded },
-) {}
+export class HttpQuota extends HttpApiMiddleware.Service<
+  HttpQuota,
+  { requires: CurrentMember }
+>()("tracker/HttpQuota", { error: QuotaExceeded }) {}
 
 /** Listed in `ActionRpc.layer`'s `middleware`: the same quota, counted per message. */
-export class RpcQuota extends RpcMiddleware.Service<RpcQuota, { requires: CurrentMember }>()(
-  "tracker/RpcQuota",
-  { error: QuotaExceeded },
-) {}
+export class RpcQuota extends RpcMiddleware.Service<
+  RpcQuota,
+  { requires: CurrentMember }
+>()("tracker/RpcQuota", { error: QuotaExceeded }) {}
 
 // What both middleware do before a call. Each middleware's layer builds this for itself, so it
 // runs twice; the count is one all the same, because both yield the one `RateLimiter` the
 // entrypoint provides and spend under the same key.
-const spend = Effect.gen(function* () {
-  const limiter = yield* RateLimiter.RateLimiter;
-
-  return Effect.gen(function* () {
+const spend = Effect.map(RateLimiter.RateLimiter, (limiter) =>
+  Effect.gen(function* () {
     const member = yield* CurrentMember;
 
     yield* limiter
@@ -42,21 +41,25 @@ const spend = Effect.gen(function* () {
           "RateLimiterError",
           "RateLimitExceeded",
           ({ retryAfter }) =>
-            Effect.fail(new QuotaExceeded({ retryAfterSeconds: Duration.toSeconds(retryAfter) })),
+            Effect.fail(
+              new QuotaExceeded({
+                retryAfterSeconds: Duration.toSeconds(retryAfter),
+              })
+            ),
           // Any other reason is the limiter's store failing: a defect, never the caller's.
-          Effect.die,
-        ),
+          Effect.die
+        )
       );
-  });
-});
+  })
+);
 
 export const quota = Layer.merge(
   Layer.effect(
     HttpQuota,
-    Effect.map(spend, (spent) => (route) => Effect.andThen(spent, route)),
+    Effect.map(spend, (spent) => (route) => Effect.andThen(spent, route))
   ),
   Layer.effect(
     RpcQuota,
-    Effect.map(spend, (spent) => (rpc) => Effect.andThen(spent, rpc)),
-  ),
+    Effect.map(spend, (spent) => (rpc) => Effect.andThen(spent, rpc))
+  )
 );

package/examples/kitchen-sink/src/issues/Issues.ts

@@ -1,10 +1,15 @@
-import { Effect, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect, Schema } from "effect";
+
 import { CurrentMember } from "../identity/Identity.js";
 
 export const Status = Schema.Literals(["open", "closed"]);
 
-export const Comment = Schema.Struct({ author: Schema.String, text: Schema.String });
+export const Comment = Schema.Struct({
+  author: Schema.String,
+  text: Schema.String,
+});
 
 export const Issue = Schema.Struct({
   id: Schema.String,
@@ -19,16 +24,18 @@ export type Issue = typeof Issue.Type;
 
 // A declared error is part of the contract: every client decodes it as this class, and its
 // status is what HTTP answers with. Without `httpApiStatus` it would be a 422.
-export class IssueNotFound extends Schema.TaggedError<IssueNotFound>()(
-  "IssueNotFound",
-  { id: Schema.String },
-  { httpApiStatus: 404 },
-) {}
+export class IssueNotFound extends Schema.TaggedError<
+  IssueNotFound,
+  { readonly brand: unique symbol }
+>()("IssueNotFound", { id: Schema.String }, { httpApiStatus: 404 }) {}
 
-export class RateLimited extends Schema.TaggedError<RateLimited>()(
+export class RateLimited extends Schema.TaggedError<
+  RateLimited,
+  { readonly brand: unique symbol }
+>()(
   "RateLimited",
   { retryAfterSeconds: Schema.Finite },
-  { httpApiStatus: 429 },
+  { httpApiStatus: 429 }
 ) {}
 
 // A shared error list: what any write to an existing issue may fail with. Each such action
@@ -51,20 +58,23 @@ const change = {
 const Text = Schema.String.check(Schema.isMinLength(1));
 
 export const ListIssues = Action.make("listIssues", {
-  description: "List your workspace's issues, newest first, without bodies or comments.",
+  description:
+    "List your workspace's issues, newest first, without bodies or comments.",
   input: {
     // Optional: left out, issues of every status are listed.
     status: Schema.optional(Status),
     // Defaulted: left out, the handler receives 20. A field description is also the help text
     // of its CLI flag and the description in the tool's schema.
-    limit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 })).pipe(
+    limit: Schema.Int.check(
+      Schema.isBetween({ minimum: 1, maximum: 100 })
+    ).pipe(
       Schema.annotate({ description: "How many issues to list, at most 100." }),
-      Schema.withDecodingDefaultKey(Effect.succeed(20)),
+      Schema.withDecodingDefaultKey(Effect.succeed(20))
     ),
   },
   success: {
     issues: Schema.Array(
-      Schema.Struct({ id: Schema.String, title: Schema.String, status: Status }),
+      Schema.Struct({ id: Schema.String, title: Schema.String, status: Status })
     ),
   },
   readOnly: true,
@@ -82,7 +92,11 @@ export const GetIssue = Action.make("getIssue", {
 
 export const CreateIssue = Action.make("createIssue", {
   description: "File an issue in your workspace.",
-  input: { title: Text, body: Schema.String, assignee: Schema.optional(Schema.String) },
+  input: {
+    title: Text,
+    body: Schema.String,
+    assignee: Schema.optional(Schema.String),
+  },
   success: Issue,
   error: RateLimited,
   readOnly: false,
@@ -108,4 +122,66 @@ export const CloseIssue = Action.make("closeIssue", {
   mcp: { ...change.mcp, idempotentHint: true },
 });
 
-export const Issues = [ListIssues, GetIssue, CreateIssue, CommentOnIssue, CloseIssue] as const;
+export const Issues = [
+  ListIssues,
+  GetIssue,
+  CreateIssue,
+  CommentOnIssue,
+  CloseIssue,
+] as const;
+
+// An action answering a stream: its handler returns a `Stream` of issues, and every client's
+// call returns one, each issue read as the server sends it. It reports how far it is, too.
+// `Issues` leaves it out, so MCP's `Tools` and the assistant's tools do: a tool answers one
+// result, so it would collect the whole export before answering, every issue at once in a
+// model's context. HTTP, RPC and the CLI serve it.
+export const ExportIssues = Action.make("exportIssues", {
+  description:
+    "Stream every issue of your workspace, oldest first, with bodies and comments.",
+  input: {
+    status: Schema.optional(Status).annotate({
+      description: "Only issues of this status.",
+    }),
+  },
+  success: Action.Stream(Issue),
+  progress: {
+    exported: Schema.Finite.annotate({
+      description: "How many issues were sent.",
+    }),
+    total: Schema.Finite.annotate({
+      description: "How many the export holds.",
+    }),
+  },
+  // An export is costly, so it is limited too: refused before its first issue, a 429.
+  error: RateLimited,
+  readOnly: true,
+  caller: CurrentMember,
+});
+
+/** What changed about an issue, as `issue.changed` carries it. */
+export const IssueChange = Schema.Struct({
+  workspace: Schema.String,
+  id: Schema.String,
+  title: Schema.String,
+  status: Status,
+  change: Schema.Literals(["filed", "commented", "closed"]),
+  // The comment a change added; a subscriber asking `comments: false` receives none.
+  comment: Schema.optional(Comment),
+});
+
+// An event type: what a subscription takes, what each occurrence carries, and who may
+// subscribe. `input` both filters the occurrences, by `status`, and shapes them, by `comments`.
+export const IssueChanged = Event.make("issue.changed", {
+  description: "An issue in your workspace was filed, commented on or closed.",
+  input: {
+    status: Schema.optional(Status).annotate({
+      description: "Only issues now of this status.",
+    }),
+    comments: Schema.optional(Schema.Boolean).annotate({
+      description:
+        "Whether a change carries the comment it added; omitted, it does.",
+    }),
+  },
+  payload: IssueChange,
+  caller: CurrentMember,
+});

package/examples/kitchen-sink/src/issues/assistant.ts

@@ -1,5 +1,6 @@
-import { LanguageModel } from "effect/ai";
 import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import { LanguageModel } from "effect/ai";
+
 import { issues } from "./handlers.js";
 import { CloseIssue, CommentOnIssue, GetIssue, ListIssues } from "./Issues.js";
 
@@ -20,4 +21,5 @@ export const { toolkit, layer } = ActionToolkit.make(issues, {
 
 // One turn of the assistant. The caller provides the model, and the member it acts for around
 // the whole turn: `authorize` and the handlers read that one caller.
-export const triage = (prompt: string) => LanguageModel.generateText({ prompt, toolkit });
+export const triage = (prompt: string) =>
+  LanguageModel.generateText({ prompt, toolkit });

package/examples/kitchen-sink/src/issues/events.ts

@@ -0,0 +1,46 @@
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect, Stream, Struct } from "effect";
+
+import { authorize } from "../identity/authorize.js";
+import { CurrentMember } from "../identity/Identity.js";
+import { IssueChanged } from "./Issues.js";
+import { IssueStore } from "./store.js";
+
+// A log source fed by a stream: the store pushes every change, of every workspace, and the
+// library consumes the stream once, from startup, keeping what it produced lately for
+// subscribers resuming from a cursor. `key`, `match` and `transform` run per subscriber, as the
+// subscriber.
+export const issueEvents = Event.implement(
+  IssueChanged,
+  Effect.gen(function* () {
+    const store = yield* IssueStore;
+
+    return {
+      log: {
+        // No `eventId`: the library gives each change one, kept on every replay. An id of the
+        // store's would have to stay unique across restarts, as a subscriber drops a repeated
+        // one. Each change is keyed by its workspace, which reaches that workspace's
+        // subscribers alone.
+        emit: Stream.map(store.changes, (data) => ({
+          data,
+          key: data.workspace,
+        })),
+        // One log holds every workspace's changes: a subscriber resuming within an hour, and
+        // within the last thousand changes of all workspaces, misses nothing; one resuming
+        // later receives a gap first, then what is kept. A busy workspace shortens a quiet
+        // one's hour.
+        maxAge: "1 hour",
+        maxEvents: 1000,
+      },
+      // Tenant isolation, as the store's methods hold it for the actions: a member follows
+      // their own workspace's key. It is never `undefined`, which would follow every key.
+      key: () => Effect.map(CurrentMember, (member) => member.workspace),
+      match: ({ status }, change) =>
+        status === undefined || change.status === status,
+      transform: ({ comments }, change) =>
+        comments === false ? Struct.omit(change, ["comment"]) : change,
+    };
+  }),
+  // The members' rule, as for the actions: a subscription needs the read scope.
+  { authorize }
+);