@gjermundgaraba/effect-actions-cloudflare 0.21.0 → 0.23.0

package/dist/subscriptions.mjs

@@ -2,7 +2,6 @@ import { deleted } from "./batches.mjs";
 import { RequestId, closeQuietly, groupTag, socketIdOf } from "./frames.mjs";
 import { Effect, Function, Match, Option, Predicate, Schema } from "effect";
 // src/durable/subscriptions.ts
-/** Where an object keeps its sockets' event subscriptions. */
 const keptPrefix = "effect-actions/subscription/";
 const Request = Schema.TaggedStruct("Request", {
 	id: RequestId,
@@ -11,33 +10,27 @@ const Request = Schema.TaggedStruct("Request", {
 });
 const requestOf = Schema.decodeUnknownOption(Request);
 const payloadOf = Schema.decodeUnknownOption(Schema.Json);
+const resumeFailedCode = 1e3;
 const unresumable = "This server could not resume this socket's subscriptions: connect again";
 const suffixOf = (socket, id) => `${socket}#${Predicate.isNumber(id) ? "n" : "s"}${id}`;
 const socketOf = (suffix) => Number(suffix.slice(0, suffix.indexOf("#")));
-/**
-* The event subscriptions of the sockets one `layerWebSocket` path accepted, kept in storage:
-* `keeper` stores each request as `ActionRpc.layer` admits it, `sent` stores the payload that
-* resumes it with each chunk sent and forgets it at its exit, `closed` forgets a socket's, and
-* `resumed` writes each kept one whose socket of this path is still open to the server again,
-* from there.
-*/
 const makeSubscriptions = (state, path) => {
 	const { storage } = state;
 	const group = groupTag(path);
 	const requests = `${keptPrefix}request/${path}#`;
 	const payloads = `${keptPrefix}payload/${path}#`;
 	const keysOf = (suffix) => [`${requests}${suffix}`, `${payloads}${suffix}`];
-	const live = /* @__PURE__ */ new Map();
+	const liveSubscriptionsMirror = /* @__PURE__ */ new Map();
 	const listed = (prefix) => Effect.map(Effect.promise(async () => await storage.list({ prefix })), (found) => [...found].map(([key, value]) => [key.slice(prefix.length), value]));
 	const closed = (socket) => Effect.suspend(() => {
-		const owned = [...live.keys()].filter((suffix) => socketOf(suffix) === socket);
-		for (const suffix of owned) live.delete(suffix);
+		const owned = [...liveSubscriptionsMirror.keys()].filter((suffix) => socketOf(suffix) === socket);
+		for (const suffix of owned) liveSubscriptionsMirror.delete(suffix);
 		return deleted(storage, owned.flatMap(keysOf));
 	});
 	const keeper = { keep: ({ clientId, requestId, tag, payload, headers, resumeFrom }) => Effect.suspend(() => {
 		const suffix = suffixOf(clientId, requestId);
-		const resuming = live.has(suffix);
-		live.set(suffix, resumeFrom);
+		const resuming = liveSubscriptionsMirror.has(suffix);
+		liveSubscriptionsMirror.set(suffix, resumeFrom);
 		if (resuming) return Effect.void;
 		return Effect.promise(async () => {
 			await storage.put({
@@ -51,23 +44,18 @@ const makeSubscriptions = (state, path) => {
 		});
 	}) };
 	const moved = (suffix, values) => Effect.suspend(() => {
-		const payload = live.get(suffix)?.(values);
+		const payload = liveSubscriptionsMirror.get(suffix)?.(values);
 		return payload === void 0 ? Effect.void : Effect.promise(async () => {
 			await storage.put(`${payloads}${suffix}`, payload);
 		});
 	});
 	const sent = (socket, response) => Match.value(response).pipe(Match.tag("Defect", () => closed(socket)), Match.tag("Chunk", ({ requestId, values }) => moved(suffixOf(socket, requestId), values)), Match.tag("Exit", ({ requestId }) => Effect.suspend(() => {
 		const suffix = suffixOf(socket, requestId);
-		return live.delete(suffix) ? Effect.promise(async () => await storage.delete(keysOf(suffix))) : Effect.void;
+		return liveSubscriptionsMirror.delete(suffix) ? Effect.promise(async () => await storage.delete(keysOf(suffix))) : Effect.void;
 	})), Match.orElse(() => Effect.void));
 	const unresumed = (socket) => Effect.andThen(Effect.logWarning(`layerWebSocket at ${path} could not resume a socket's kept event subscriptions, and closes it`), Effect.sync(() => {
-		closeQuietly(socket, 1e3, unresumable);
+		closeQuietly(socket, resumeFailedCode, unresumable);
 	}));
-	/**
-	* Writes each kept subscription of a socket of this path still open to the server, from where
-	* it reached, and forgets the rest: `held` answers whether a socket stays open, given whether
-	* one of its requests is a subscription kept for it, and closes one that does not.
-	*/
 	const resumed = (write, held) => Effect.gen(function* () {
 		const kept = yield* listed(requests);
 		const resumeFrom = new Map(yield* listed(payloads));
@@ -88,7 +76,7 @@ const makeSubscriptions = (state, path) => {
 		const unread = new Set(entries.flatMap(({ socket, request }) => open.has(socket) && Option.isNone(request) ? [socket] : []));
 		const gone = [...resumeFrom.keys()].flatMap((suffix) => keptIds.has(suffix) ? [] : [`${payloads}${suffix}`]);
 		for (const { suffix, socket, request } of entries) if (open.has(socket) && !unread.has(socket) && Option.isSome(request)) {
-			live.set(suffix, Function.constUndefined);
+			liveSubscriptionsMirror.set(suffix, Function.constUndefined);
 			yield* write(socket, request.value);
 		} else gone.push(...keysOf(suffix));
 		yield* deleted(storage, gone);

package/dist/tasks.mjs

@@ -1,6 +1,5 @@
 import { Clock, Context, Effect } from "effect";
 // src/durable/tasks.ts
-/** The alarm owner a task's time is kept under, one per task name. */
 const taskOwner = (name) => `task:${name}`;
 /**
 * Runs the object's tasks, `make`'s or `handlers`' `tasks`, by name, after a change, on the
@@ -15,16 +14,12 @@ const taskOwner = (name) => `task:${name}`;
 * - A run that fails is logged and retried as the alarm retries an owner: 2 seconds later, doubling, six times, then hourly.
 */
 var Tasks = class extends Context.Service()("effect-actions-cloudflare/ActionDurableObject/Tasks") {};
-/**
-* The instance's `Tasks` over its `schedule`, and the alarm owners that run each of `tasks`, by
-* the name `runAfter` takes.
-*/
 const makeTasks = (schedule, tasks) => ({
 	tasks: Tasks.of({ runAfter: (name, change) => Effect.gen(function* () {
 		if (!Object.hasOwn(tasks, name)) return yield* Effect.die(/* @__PURE__ */ new Error(`ActionDurableObject.Tasks: this object has no task ${name} (give make or handlers a tasks entry named ${name})`));
-		const marked = schedule.set(taskOwner(name), yield* Clock.currentTimeMillis);
-		yield* marked;
-		return yield* Effect.ensuring(change, marked);
+		const markDueNow = schedule.set(taskOwner(name), yield* Clock.currentTimeMillis);
+		yield* markDueNow;
+		return yield* Effect.ensuring(change, markDueNow);
 	}) }),
 	owners: Object.fromEntries(Object.entries(tasks).map(([name, task]) => [taskOwner(name), () => task]))
 });

package/dist/webhooks.mjs

@@ -4,12 +4,7 @@ import { Clock, Context, Deferred, Duration, Effect, Exit, Layer, Option, Schema
 import * as Webhook from "@gjermundgaraba/effect-actions/Webhook";
 import { KeyValueStore } from "effect/persistence";
 // src/durable/webhooks.ts
-/** The owner of the object's alarm times that end its long waits. */
 const clockOwner = "webhooks";
-/**
-* Where `layerWebhooks` keeps its subscriptions in the object's storage: every key of its store,
-* whatever layout `Webhook.layer`'s `persist` gives them, is under it.
-*/
 const webhookPrefix = "effect-actions/webhooks/";
 /**
 * The instance's long waits, which the object's alarm ends: `until(at)` waits until the alarm
@@ -17,13 +12,9 @@ const webhookPrefix = "effect-actions/webhooks/";
 * `make` provide it to the routes, over the instance's schedule, for `layerWebhooks`.
 */
 var Waits = class extends Context.Service()("effect-actions-cloudflare/ActionDurableObject/Waits") {};
-/**
-* The instance's `Waits`, their time set on `schedule`, the one its `alarm` handler runs, and
-* `wakeDue`, which that handler runs at their time.
-*/
 const makeWaits = (schedule) => {
 	const held = /* @__PURE__ */ new Set();
-	const armed = Semaphore.makeUnsafe(1).withPermits(1)(Effect.suspend(() => held.size === 0 ? schedule.clear(clockOwner) : schedule.set(clockOwner, Math.min(...[...held].map(({ at }) => at)))));
+	const armForEarliestWait = Semaphore.makeUnsafe(1).withPermits(1)(Effect.suspend(() => held.size === 0 ? schedule.clear(clockOwner) : schedule.set(clockOwner, Math.min(...[...held].map(({ at }) => at)))));
 	return {
 		waits: Waits.of({ until: (at) => Effect.suspend(() => {
 			const wait = {
@@ -31,25 +22,19 @@ const makeWaits = (schedule) => {
 				woken: Deferred.makeUnsafe()
 			};
 			held.add(wait);
-			return Effect.andThen(armed, Deferred.await(wait.woken)).pipe(Effect.ensuring(Effect.suspend(() => held.delete(wait) ? armed : Effect.void)));
+			return Effect.andThen(armForEarliestWait, Deferred.await(wait.woken)).pipe(Effect.ensuring(Effect.suspend(() => held.delete(wait) ? armForEarliestWait : Effect.void)));
 		}) }),
-		/** Ends each wait that is due, and sets the alarm for the next. */
 		wakeDue: Effect.gen(function* () {
 			const now = yield* Clock.currentTimeMillis;
 			for (const wait of held) if (wait.at <= now) {
 				held.delete(wait);
 				Deferred.doneUnsafe(wait.woken, Exit.void);
 			}
-			yield* armed;
+			yield* armForEarliestWait;
 		})
 	};
 };
-const timed = Duration.seconds(10);
-/**
-* The Clock the webhook layer runs on: a wait of 10 seconds or more waits on the object's alarm
-* and holds no timer, so the object may hibernate meanwhile; if the instance is evicted, the
-* alarm builds the next, which restores the subscriptions from storage.
-*/
+const alarmWaitThreshold = Duration.seconds(10);
 const alarmClock = (base, { until }) => ({
 	currentTimeMillisUnsafe: () => base.currentTimeMillisUnsafe(),
 	currentTimeMillis: base.currentTimeMillis,
@@ -57,7 +42,7 @@ const alarmClock = (base, { until }) => ({
 	currentTimeNanos: base.currentTimeNanos,
 	monotonicTimeNanosUnsafe: () => base.monotonicTimeNanosUnsafe(),
 	monotonicTimeNanos: base.monotonicTimeNanos,
-	sleep: (duration) => Duration.isLessThan(duration, timed) || !Duration.isFinite(duration) ? base.sleep(duration) : until(base.currentTimeMillisUnsafe() + Duration.toMillis(duration))
+	sleep: (duration) => Duration.isLessThan(duration, alarmWaitThreshold) || !Duration.isFinite(duration) ? base.sleep(duration) : until(base.currentTimeMillisUnsafe() + Duration.toMillis(duration))
 });
 const stringOf = Schema.decodeUnknownOption(Schema.String);
 const attempted = (method, key, run) => Effect.tryPromise({
@@ -70,7 +55,6 @@ const attempted = (method, key, run) => Effect.tryPromise({
 	})
 });
 const keyOf = (key) => `${webhookPrefix}${key}`;
-/** A `KeyValueStore` over the object's storage under `webhookPrefix`, every key of it there. */
 const storageStore = (storage) => {
 	const listed = attempted("list", void 0, async () => await storage.list({ prefix: webhookPrefix }));
 	return KeyValueStore.makeStringOnly({

package/docs/ActionDurableObject-events.md

@@ -14,19 +14,12 @@ import { authorize } from "./authorize.js";
 import { MessagePosted } from "./Chat.js";
 import { MessageStore } from "./store.js";
 
-// A cursor is the id of the last message a page holds, as `readMessages`' `after` is.
 const idOf = Schema.decodeUnknownOption(
   Schema.NumberFromString.pipe(Schema.check(Schema.isInt()))
 );
 
-// An agent polling over MCP asks again after `nextPoll`, 5 seconds by default: a request that
-// often keeps the object from the 10 idle seconds after which the runtime may hibernate it, so it
-// asks every 30 seconds, and an agent that needs a message sooner holds a stream open instead.
 const nextPoll = "30 seconds";
 
-// The room's messages as an event, read from the store that keeps them: a check source.
-// `postMessage` notifies after each post, so a page receives it at once: when an object reads a
-// check source, and what a write that does not notify misses, is on `ActionDurableObject.handlers`.
 export const messageEvents = Event.implement(
   MessagePosted,
   Effect.gen(function* () {
@@ -42,11 +35,6 @@ export const messageEvents = Event.implement(
             (id) => id >= 0 && id <= last
           );
 
-          // No cursor starts after the room's last message. One this room never gave, such as
-          // an id past its last from another copy of its database, is answered `truncated` from
-          // there: the page learns it missed messages, and reads them with `readMessages`. A
-          // message deleted or expired after a cursor is simply not read: the store keeps no
-          // record of either, so no gap marks it.
           if (Option.isNone(after)) {
             return {
               cursor: String(last),
@@ -89,7 +77,6 @@ import { LobbyHost } from "./host.js";
 import { Previews, PreviewsChanged } from "./Lobby.js";
 import { PreviewStore } from "./store.js";
 
-// The Worker's `previews`, as the lobby's object keeps them.
 export const lobby = Action.implement(
   Previews,
   Effect.map(
@@ -98,8 +85,6 @@ export const lobby = Action.implement(
   )
 );
 
-// The lobby's own API, in its object. A change notifies `PreviewsChanged`, which an object
-// outside this one could not do itself: its event is this object's.
 export const calls = LobbyCalls.toLayer(
   Effect.gen(function* () {
     const store = yield* PreviewStore;
@@ -125,11 +110,6 @@ import { Effect } from "effect";
 import { PreviewsChanged } from "./Lobby.js";
 import { PreviewStore } from "./store.js";
 
-// Every room's preview as one event, read from the lobby's store: a current source, for a value
-// small enough to send whole. A page watching is sent the previews as they are, then again after
-// each notify, which `roomChanged` makes after each change, so it needs no read before it and is
-// never sent each change it missed, which a whole value makes needless. The object keeps the
-// revision a page's cursor holds, so a page resuming at the latest is sent nothing.
 export const previewEvents = Event.implement(
   PreviewsChanged,
   Effect.map(PreviewStore, (store) => ({

package/docs/ActionDurableObject-failures.md

@@ -15,4 +15,4 @@ Messages the library does not own, workerd's, the compiler's and Effect's, and t
 - `Could not serialize object of type "<Class>". This type does not support serialization`, workerd's `DataCloneError`, as an `RpcClientError`'s cause: a value of the call, success, error or defect, is one structured clone refuses, such as a class instance in a `Schema.Unknown`; declare its schema, whose plain form clones, or die with an `Error`.
 - `Your Durable Object class must have an alarm() handler in order to call setAlarm()`, workerd's, from `storage.setAlarm`, which `Alarm.set` calls: the class delegating to `handlers` defines no `alarm`; delegate `handlers`' own, as `make`'s classes do, and on celld 0.6.2, Deno's self-hosted Durable Object runtime, which accepts the call and drops the alarm when it is due, an alarm that never runs means the same.
 - `The Workers runtime canceled this request because it detected that your Worker's code had hung and would never generate a response`, workerd's, from every call through a client kept across a Worker's requests, `client` or `RpcClient.make` over `layerStubClient`, or through a handler or runtime holding one: it was first built lazily inside a request that ended without waiting on I/O, succeeding or refused, whose timer would have started the client's own fiber; run each call as its own program, or share it built at module scope under Effect's sync scheduler, as `HttpRouter.toWebHandler`'s gotchas show, a `ManagedRuntime.make` there building only at its first run, as `ActionDurableObject.layerStubClient`'s gotchas say.
-- `RpcClientError` from every call over a stub, Effect's own error: the stub failed, its `reason.cause` the runtime's or the object's message; a stub an exception broke fails every later call with the same one, so call through `client`, or give `layerStubClient` a function, `() => stub`, either making a new stub for each call.
+- `RpcClientError` from every call over a stub, Effect's own error: the stub failed, its `reason.cause` the runtime's or the object's message; a stub an exception broke fails every later call with the same one, so call through `client` or `layerStubClient`, either making a new stub for each call from its function.

package/docs/ActionDurableObject-placement.md

@@ -13,13 +13,10 @@ import { MessagePosted, Messages } from "./chat/Chat.js";
 import { Login } from "./identity/Identity.js";
 import { Previews } from "./lobby/Lobby.js";
 
-// The rooms' JSON routes, at `/api/<action>` and `/api/events/<name>`: the Worker's, which a
-// client without a socket calls, and each room's object's, where the Worker sends each call on.
 export const RoomHttp = ActionHttp.make([...Messages, MessagePosted], {
   authentication: Login,
 });
 
-// The Worker's own JSON routes.
 export const LobbyHttp = ActionHttp.make([Previews]);
 ```
 
@@ -30,7 +27,7 @@ Then, as `routes.ts` on [ActionDurableObject.md](ActionDurableObject.md) does:
 - The class is given the placement as `make`'s `placed`, in `worker.ts`: the object then refuses `Forbidden`, on every surface, its socket and its stub included, a call or a watch whose key names another object, so a page's socket to one room cannot reach another.
 - The Worker serves `ActionDurableObject.reaching(rooms, () => env.CHAT_ROOM)` beside its own implementations, in `ActionHttp.layer` and `ActionMcp.layerHttp`, each call sent to the room's object with the caller's headers.
 
-The Worker authenticates each protected call as its own, and the object authenticates and authorizes it again, so both are given the verifier. A key's schema, `RoomName` in `Chat.ts`, is what keeps a caller from creating objects: an unknown room is `InvalidInput` before any object is reached. [chat-rooms/test/worker.test.ts](../examples/chat-rooms/test/worker.test.ts) reaches two rooms through one MCP connection and has a room refuse a call naming another.
+The Worker authenticates each protected call as its own, and the object authenticates and authorizes it again, so both are given the verifier. A key's schema, `DemoRoomName` in `Chat.ts`, is what keeps a caller from creating objects: an unknown room is `InvalidInput` before any object is reached. [chat-rooms/test/worker.test.ts](../examples/chat-rooms/test/worker.test.ts) reaches two rooms through one MCP connection and has a room refuse a call naming another.
 
 ## Serve them over MCP from the Worker
 

package/docs/ActionDurableObject-stub.md

@@ -12,11 +12,6 @@ import { Rpc, RpcGroup } from "effect/rpc";
 
 import { RoomPreview } from "./Lobby.js";
 
-// The lobby's own API, over its stub: a room tells it its latest activity, and the Worker reads
-// the previews. A plain Effect `RpcGroup`, not actions: no page calls it, so it needs no contract
-// checks, no authentication and no JSON route, and nothing authenticates a stub call anyway, as
-// only a binding reaches it. Why a report heard late never overwrites a later one is at
-// `tellLobby`, in lobby-stubs.ts, which sends it.
 export const LobbyCalls = RpcGroup.make(
   Rpc.make("roomChanged", { payload: RoomPreview }),
   Rpc.make("previews", { success: Schema.Array(RoomPreview) })
@@ -25,7 +20,7 @@ export const LobbyCalls = RpcGroup.make(
 
 Its handlers read the store the instance built ([chat-rooms/src/lobby/handlers.ts](../examples/chat-rooms/src/lobby/handlers.ts)), and `RpcServer.layer(LobbyCalls)` over them is the object's `calls`, beside its routes ([chat-rooms/src/routes.ts](../examples/chat-rooms/src/routes.ts)), given to `make` in [chat-rooms/src/worker.ts](../examples/chat-rooms/src/worker.ts). `make` gives the calls their protocol; what crosses it, as values and not JSON, what it refuses and what the calls may require are on `ActionDurableObject.Options`' `calls`.
 
-A plain group suits an object's own API, which no page calls. Actions served on other surfaces too are served the same way, `calls: ActionRpc.layer(RoomRpc, room)`, and called with `ActionRpc.client(RoomRpc)` over `layerStubClient(env.CHAT_ROOM.getByName(room))`: their values cross as JSON, and a protected action authenticates each call from its headers, so the caller forwards the user's credential with `RpcClient.withHeaders`.
+A plain group suits an object's own API, which no page calls. Actions served on other surfaces too are served the same way, `calls: ActionRpc.layer(RoomRpc, room)`, and called with `ActionRpc.client(RoomRpc)` over `layerStubClient(() => env.CHAT_ROOM.getByName(room))`: their values cross as JSON, and a protected action authenticates each call from its headers, so the caller forwards the user's credential with `RpcClient.withHeaders`.
 
 ## Call it from a Worker or another object
 
@@ -42,25 +37,14 @@ import { MessageStore } from "../chat/store.js";
 import { LobbyCalls } from "../lobby/Calls.js";
 import { LobbyHost } from "../lobby/host.js";
 
-// The lobby is one object, named `lobby`: a new stub for each call, read from `env` as the call
-// is sent, never as the module loads.
 const lobbyStub = () => env.CHAT_LOBBY.getByName("lobby");
 
-// The lobby's object as the Worker reaches it, for the previews: a lobby that cannot be reached
-// is the deployment's failure, not the caller's, so it is a defect, the Worker answers 500, and
-// the cause is in its logs.
 export const layerLobbyHost = Layer.effect(LobbyHost)(
   Effect.map(ActionDurableObject.client(LobbyCalls), (lobby) =>
     LobbyHost.of({ previews: Effect.orDie(lobby(lobbyStub).previews()) })
   )
 );
 
-// The room's task, worker.ts's `lobby`: telling the lobby the room's latest activity. The room's
-// alarm runs its tasks one run at a time, each waiting for the lobby's answer, and each run reads
-// the activity as it is then: the lobby hears a room's reports in the order the room made them,
-// so a report heard late never overwrites a later one, and the last it hears is the room's
-// latest. A run repeated after a lost answer sends what the lobby holds, which `record` finds
-// unchanged, notifying no page.
 export const tellLobby = Effect.gen(function* () {
   const room = yield* Room;
   const latest = yield* MessageStore.use((store) => store.latest);
@@ -69,10 +53,6 @@ export const tellLobby = Effect.gen(function* () {
   yield* lobby(lobbyStub).roomChanged({ room, latestAt: latest?.at ?? null });
 });
 
-// A room's activity, a startup service of the room's: each change runs the `lobby` task after it,
-// on the room's alarm once the call has answered, and again until the lobby hears it, so a lobby
-// that cannot be reached fails no post and misses no change. `runAfter` marks the task before the
-// change and again after it, so a crash at any point leaves the task to the alarm.
 export const layerActivity = Layer.effect(Activity)(
   Effect.map(ActionDurableObject.Tasks, (tasks) =>
     Activity.of({ changing: (change) => tasks.runAfter("lobby", change) })
@@ -88,21 +68,13 @@ A Worker's entrypoint that is no Effect program, such as a `WorkerEntrypoint` me
 import { WorkerEntrypoint } from "cloudflare:workers";
 import { Effect, Schema } from "effect";
 
-import { RoomName } from "./chat/Chat.js";
+import { DemoRoomName } from "./chat/Chat.js";
 import { LobbyHost } from "./lobby/host.js";
 import { layerLobbyHost } from "./platform/lobby-stubs.js";
 
-const decodeRoom = Schema.decodeUnknownEffect(RoomName);
+const decodeRoom = Schema.decodeUnknownEffect(DemoRoomName);
 
-// The rooms' activity for another Worker, over a service binding to this one's `RoomsEntrypoint`,
-// which worker.ts exports, as the lobby keeps it. A method of a `WorkerEntrypoint` is no Effect
-// program, so each call runs as one, given the lobby's Layer: its client is built in the request
-// that uses it and closed with it, which costs no I/O. Why a client kept across requests strands
-// is on `ActionDurableObject.layerStubClient`.
 export class RoomsEntrypoint extends WorkerEntrypoint {
-  // The calling Worker is another deployment, so its room is checked as any input is: an unknown
-  // room rejects the call with the schema's error, as a lobby that cannot be reached rejects it
-  // with the defect lobby-stubs.ts makes of it.
   async latestAt(room: string) {
     return await Effect.runPromise(
       Effect.flatMap(decodeRoom(room), (name) =>

package/docs/ActionDurableObject-testing.md

@@ -10,7 +10,6 @@ Run the tests inside the runtime with `@cloudflare/vitest-plugin`, on the Worker
 import { cloudflareTest } from "@cloudflare/vitest-plugin";
 import { defineConfig } from "vite-plus";
 
-// Its tests run inside the Workers runtime, on the Worker wrangler.jsonc describes.
 export default defineConfig({
   plugins: [
     cloudflareTest({
@@ -19,10 +18,6 @@ export default defineConfig({
   ],
   test: {
     include: ["test/**/*.test.ts"],
-    // Why: under @cloudflare/vitest-plugin 1.4.4, the warm-module response for a later file in a
-    // pool slot can exceed what the runner's control socket accepts, 41 MB in 709 entries
-    // measured on chat-rooms, which closes it with 1009 and loses the file as "Worker exited
-    // unexpectedly"; two small files alone did not trigger it.
     fsModuleCache: false,
   },
 });

package/docs/ActionDurableObject.md

@@ -14,7 +14,7 @@ import { Effect, Layer, Schema } from "effect";
 import { HttpRouter, HttpServer } from "effect/http";
 
 import { Activity } from "./chat/activity.js";
-import { RoomName } from "./chat/Chat.js";
+import { DemoRoomName } from "./chat/Chat.js";
 import { Room } from "./chat/room.js";
 import { MessageStore } from "./chat/store.js";
 import { layerKvPreviews } from "./platform/kv-previews.js";
@@ -32,22 +32,10 @@ import {
   workerRoutes,
 } from "./routes.js";
 
-// The rooms for another Worker, over a service binding: a named entrypoint of this one.
 export { RoomsEntrypoint } from "./rooms-entrypoint.js";
 
-// Entrypoint, Wrangler's `main`: the composition root of the Worker and of every object. It
-// chooses the stores, the room and the stubs, and routes each request.
+const decodeRoom = Schema.decodeUnknownEffect(DemoRoomName);
 
-const decodeRoom = Schema.decodeUnknownEffect(RoomName);
-
-// A room's Durable Object, bound as CHAT_ROOM in wrangler.jsonc under this export's name. Each
-// instance builds its services, the store, the room and its activity, then its routes, as it is
-// constructed, again after every eviction. The room is the name the Worker reached the object by,
-// `getByName(room)`, decoded once there: `ActionDurableObject.name` dies for an object reached by
-// an id, and the build fails for a name `RoomName` does not list, each a bug in the Worker. Given
-// `rooms`, it refuses a call or a watch whose input names another room. Its `lobby` task tells
-// the lobby of each change, on the alarm until the lobby hears. The alarm expires old messages
-// and tells the lobby, as an expired message can be the room's latest.
 export class ChatRoom extends ActionDurableObject.make({
   placed: rooms,
   services: () =>
@@ -64,18 +52,12 @@ export class ChatRoom extends ActionDurableObject.make({
     ),
 }) {}
 
-// The lobby's Durable Object, bound as CHAT_LOBBY: one for the Worker, named `lobby`, keeping
-// every room's preview, which each room tells it of and its pages follow.
 export class ChatLobby extends ActionDurableObject.make({
   services: () => layerKvPreviews,
   routes: lobbyRoutes,
   calls: lobbyCalls,
 }) {}
 
-// The Worker's own handler, built once, when the module loads, which keeps the lobby's client
-// from stranding as `ActionDurableObject.layerStubClient`'s gotchas say: building it does no I/O,
-// which a Worker refuses outside a request. `toWebHandler` reads no `MaxBodySize`, so the
-// platform limits request bodies.
 const served = HttpRouter.toWebHandler(
   workerRoutes.pipe(
     Layer.provide(layerLobbyHost),
@@ -83,11 +65,8 @@ const served = HttpRouter.toWebHandler(
   )
 );
 
-const isRoomName = Schema.is(RoomName);
+const isRoomName = Schema.is(DemoRoomName);
 
-// A page's socket, `/rooms/<room>/rpc` or `/lobby/rpc`, is its object's `/rpc`: forwarding the
-// request forwards its upgrade, and the object answers it. Everything else is the Worker's own,
-// the rooms' calls among them, which it sends on to each room's object itself.
 export default {
   async fetch(request: Request, env: Cloudflare.Env) {
     const url = new URL(request.url);
@@ -148,9 +127,6 @@ const room = [messages, messageEvents];
 
 const byRoom = (input: { readonly room: string }) => input.room;
 
-// Where each room's calls and watches are served: in the room's object, the one each contract's
-// key names. worker.ts gives it to the room's class, which then refuses an input naming another
-// room, on its socket too; the Worker serves it below.
 export const rooms = ActionDurableObject.placed(RoomHttp, {
   readMessages: byRoom,
   postMessage: byRoom,
@@ -158,48 +134,26 @@ export const rooms = ActionDurableObject.placed(RoomHttp, {
   "message.posted": byRoom,
 });
 
-// One socket route for each object's pages, refusing a page of another version.
 const pageSocket = ActionDurableObject.layerWebSocket({
   path: "/rpc",
   protocol: { version: protocolVersion, code: unsupportedProtocol },
 });
 
-// What a room's object serves. Its rpcs on WebSockets the runtime holds while the object
-// hibernates: a socket keeps the token its upgrade request carried, and each message is
-// authenticated with it, or with the message's own. The socket's route refuses a page naming
-// another version in its URL, `?protocol=<n>` as browser.ts sends it, with a close code the page's
-// client reads as `SocketCloseError` and stops connecting again at, not a 403, which a browser
-// reports as a bare 1006 its page connects again after. Its JSON routes, where the Worker sends
-// each call and watch on, the token with it: the object authenticates it again, and authorizes.
-// It requires `MessageStore`, `Room` and `Activity` at startup: worker.ts chooses them.
 export const roomRoutes = Layer.mergeAll(
   ActionRpc.layer(RoomRpc, room).pipe(Layer.provide(pageSocket)),
   ActionHttp.layer(RoomHttp, room)
 ).pipe(Layer.provide(authenticate));
 
-// What the lobby's object serves: `PreviewsChanged` on its pages' sockets, a socket a page
-// signed out opens too, as nothing on it is protected. It requires `PreviewStore` at startup.
 export const lobbyRoutes = ActionRpc.layer(LobbyRpc, [previewEvents]).pipe(
   Layer.provide(pageSocket)
 );
 
-// What the lobby's object serves over its stub: its own calls, on Effect's own RpcServer, for
-// the rooms and the Worker, which call them with Cloudflare's own RPC. It requires `PreviewStore`
-// at startup.
 export const lobbyCalls = RpcServer.layer(LobbyCalls).pipe(
   Layer.provide(lobbyHandlers)
 );
 
-// The rooms as the Worker serves them, each call sent on to its room's object. The room is read
-// from `env` as each call is sent.
 const inRooms = ActionDurableObject.reaching(rooms, () => env.CHAT_ROOM);
 
-// What the Worker serves: the rooms' JSON routes and `previews`, which it asks the lobby's object
-// for, at `/api`, and all of them at `/mcp`, the actions as tools and `MessagePosted` as an MCP
-// event, so one agent's connection reaches every room. Nothing in a Worker outlives a request, so
-// the endpoint is request scoped: MCP 2026-07-28 alone, and events by `events/poll`, a poll every
-// 30 seconds as events.ts asks. The Worker authenticates each call, and the room's object again.
-// It requires `LobbyHost`.
 export const workerRoutes = Layer.mergeAll(
   ActionHttp.layer(LobbyHttp, lobby),
   ActionHttp.layer(RoomHttp, inRooms),
@@ -224,7 +178,7 @@ Give each of a binding's contracts a key of its input, `rooms` in `routes.ts` ab
 
 ## Run an alarm
 
-Give `make` an `alarm`, and set when it runs from a handler or a store with the `Alarm` service: the room's store sets it for the oldest message's expiry and, each run, for the next ([chat-rooms/src/platform/sql-store.ts](../examples/chat-rooms/src/platform/sql-store.ts)), and `worker.ts` above gives the alarm the store the routes read. How it runs, and how a failure is retried, are on `ActionDurableObject.Options`' `alarm`; why `State`'s `storage.setAlarm` is not the way, on `ActionDurableObject.Alarm`.
+Give `make` an `alarm`, and set when it runs from a handler or a store with the `Alarm` service, which keeps the earliest time it is given: the room's store sets it for each message's expiry as it is posted and, each run, for the oldest left ([chat-rooms/src/platform/sql-store.ts](../examples/chat-rooms/src/platform/sql-store.ts)), and `worker.ts` above gives the alarm the store the routes read. How it runs, and how a failure is retried, are on `ActionDurableObject.Options`' `alarm`; how to postpone it, and why `State`'s `storage.setAlarm` is not the way, on `ActionDurableObject.Alarm`.
 
 ## Call an object from a Worker
 

package/docs/README.md

@@ -9,7 +9,7 @@ These pages cover what this package adds. Everything else, contracts, implementa
 **Arriving with an error?** A message the library throws says its fix; for any other, step 4.
 
 1. **Open one page per tool call, with your file-reading tool.** Pages are kept small to reduce truncation; if an output says it was truncated, read that page again alone.
-2. **Start from [chat-rooms](../examples/chat-rooms/)**, the one example: its README has a layout tree and a "Where to look" table naming the file for each thing, and its comments carry the traps it shows.
+2. **Start from [chat-rooms](../examples/chat-rooms/)**, the one example: its README has a layout tree and a "Where to look" table naming the file for each thing, and its code and README carry the traps it shows.
 3. **Read [ActionDurableObject.md](ActionDurableObject.md) completely**, then the page of each task you have ([Pages](#pages)), and the example files their sections link.
 4. **For workerd's, a compiler diagnostic or Effect's own error, search [ActionDurableObject-failures.md](ActionDurableObject-failures.md)** for a fragment of the message without quotes, then the core's `*-failures.md` pages.
 

package/examples/chat-rooms/README.md

@@ -18,10 +18,10 @@ In a project that installs the package, copy this directory out of `node_modules
 
 ## When you copy this
 
-Each trap is a comment in the file named.
+Each trap below is shown in the code of the files it names.
 
 - **A page sends its token on each message**, as a browser WebSocket sets no header on its upgrade: `src/browser.ts`; `test/worker.test.ts` connects both ways.
-- **The room is the object's name**, and only a room `RoomName` lists is reached: `src/chat/Chat.ts`, `src/worker.ts`.
+- **The room is the object's name**, and only a room `DemoRoomName` lists is reached: `src/chat/Chat.ts`, `src/worker.ts`.
 - **The Worker serves every room, each room answers**, through the placement `rooms`: `src/routes.ts`.
 - **A page reads, then watches from the last message it holds**: `src/browser.ts`, `src/chat/events.ts`.
 - **`postMessage` notifies `MessagePosted`**: `src/chat/handlers.ts`, `src/chat/events.ts`.

package/examples/chat-rooms/src/Api.ts

@@ -4,11 +4,8 @@ import { MessagePosted, Messages } from "./chat/Chat.js";
 import { Login } from "./identity/Identity.js";
 import { Previews } from "./lobby/Lobby.js";
 
-// The rooms' JSON routes, at `/api/<action>` and `/api/events/<name>`: the Worker's, which a
-// client without a socket calls, and each room's object's, where the Worker sends each call on.
 export const RoomHttp = ActionHttp.make([...Messages, MessagePosted], {
   authentication: Login,
 });
 
-// The Worker's own JSON routes.
 export const LobbyHttp = ActionHttp.make([Previews]);

package/examples/chat-rooms/src/Rpc.ts

@@ -4,19 +4,12 @@ import { MessagePosted, Messages } from "./chat/Chat.js";
 import { Login } from "./identity/Identity.js";
 import { PreviewsChanged } from "./lobby/Lobby.js";
 
-// A room's rpcs and its event, on the socket a page keeps open to its object. Plain data: the
-// object and a browser page both import it.
 export const RoomRpc = ActionRpc.make([...Messages, MessagePosted], {
   authentication: Login,
 });
 
-// The lobby's event, on the socket a page keeps open to the lobby's object: public, so a page
-// signed out follows it, and refused at another version as a room's socket is.
 export const LobbyRpc = ActionRpc.make([PreviewsChanged]);
 
-// The version of these rpcs a page was built with, which it names in its socket's URL, and the
-// close code an object answers a page naming another with: raise the version when a change would
-// break a page still open from before a deployment.
 export const protocolVersion = "1";
 
 export const unsupportedProtocol = 4000;