experimental-a2 0.19.0 → 0.21.1

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.21.1
+
+### Patch Changes
+
+- 65ab0df: Under `fx()` and `pi()`, steering that hands off before any of the turn's model calls finished, as after a pause during the first one, now joins the turn's prompt. The turn's first model call sees it, and under `fx()` its files go with the prompt instead of failing the turn. Before, the engine got it only after that call, as steering, so the model answered without it once.
+
+## 0.21.0
+
+### Minor Changes
+
+- a80ad79: `session.consume(consumer, { through?, signal? })` runs a consumer with a string lane on a session, in the calling invocation, until it has handled every event it takes through `through` (default: the head), and returns `{ index }`. Use it to read your writes before querying a table a consumer keeps, to start a backfill right away with `{ through: 0 }`, or in one consumer to wait for another's table to reach its trigger. The server's own consumer shares its cursor with background work, and `consume` waits for whichever invocation holds it; a consumer the server doesn't run is pulled only by `consume` and keeps its place between calls. A dead-lettered head throws `CONSUMER_DEAD_LETTERED`. Custom stores implement `wakeLog`, which creates or wakes one log consumer's cursor without an append, and writes nothing for a session with nothing after its latest clear. A consumer with `backfill` can't use `abortOn`: defining one throws a `TypeError`, since checking cancellation while replaying history would read the rest of the log for every event.
+- 2cbb952: Consumers: `consumer({ contract, name, types?, lane?, backfill?, abortOn? }).run(fn)` defines a named reader of every session's log, registered with `createServer({ consumers })`. Several consumers can react to one event, each with its own durable cursor, lanes, retries, and dead letters; a consumer with a string lane runs everything it takes in log order and can start from the beginning of the log with `backfill: true`. Dead letters now carry their `consumer`, and `session.redrive()` takes `{ consumer, index }`. The store contract moves dispatch bookkeeping from event rows to cursors: custom adapters implement `cursors()` and the cursor-keyed claim, completion, failure, and redrive methods. Let earlier deployments finish their work first: on Postgres, then apply the new `sql/postgres/schema.sql` while none of them is running. On Postgres and Redis every event is kept, and work an earlier release's handlers hadn't finished is dropped; Redis reads an earlier release's sessions under the same `keyPrefix`, and its old dispatch keys stay until you delete them. SQLite starts fresh: a file from an earlier release throws `STORE_NOT_CONFIGURED`, so delete it or pass another `path`. Upgrade steps for each store: https://www.a2.dev/upgrades/0-21.
+- 59a655d: `handlers` are gone: consumers are the one way to react to events. `createServer({ handlers })`, the `handler()` helper, and the `Handler`, `HandlerEntry`, and `Lane` types are removed; write each reaction in `createServer({ consumers })`, inline as `{ name, types?, lane?, run }` on the server's contract, or as `consumer({ contract, name, types?, lane? }).run(fn)` to define one on its own. An inline `run` narrows `event` to its `types`; `agent({ consumers })` takes both forms too. A handler table whose types shared a lane becomes one consumer that takes those types, with a lane function returning that lane. `agent({ handlers })` is now `agent({ consumers })`. `HandlerContext` is now `ConsumerContext`, `HandlerAppend` is `ConsumerAppend`, `ToolHandlerContext` is `ToolConsumerContext`, `handlerContext()` is `consumerContext()`, and `runWithHandlerContext` is `runWithConsumerContext`. A consumer of an AI event type runs beside the agent's own, so `agent()` no longer rejects app code on those types. `session.redrive()` takes only `{ consumer, index }`. Actors (`actor({ handlers })` keeps its name) and the AI runtime run on A2's own consumers, named under the reserved `a2.` prefix: `a2.actor` and `a2.actor.concurrent`, and `a2.ai.metadata`, `a2.ai.control`, `a2.ai.model`, and `a2.ai.tools`. Their event ids are unchanged. The `a2.append.source` telemetry attribute reads `consumer` where it read `handler`. Every rename, old to new: https://www.a2.dev/upgrades/0-21.
+
+  Lag telemetry: every `a2.event` span carries `a2.event.age_ms`, how old the event was when its run started, and `a2.event.lag`, how many events the session had appended after it when it was claimed. Group them by `a2.event.consumer` to see how far each consumer is behind. Claim results from a store may now report the session's `head`, which every built-in store does.
+
+  `server.fetch` refuses a pushed event `id` longer than 256 characters, or shaped like a UUIDv5, with `INVALID_PAYLOAD`. A2 derives the ids of what consumers append, return, and schedule as UUIDv5s from inputs a caller can know, so a caller who pushed one first could take its place: dead-letter the consumer, or turn a scheduled event into a no-op. Client ids from `crypto.randomUUID()` (v4) and `idempotentId()` (v8) are unaffected.
+
+- 59a655d: The Postgres store checks nothing up front. It no longer reads a schema version before its first query, and `schema.sql` drops the `a2_schema` table. A query that finds one of A2's tables or columns missing, or that its role can't use, throws `STORE_NOT_CONFIGURED`, naming the files to apply or the grants to make. A store with `listenConnectionString` still looks for its triggers, since a missing one fails no query: its first subscription throws `STORE_NOT_CONFIGURED` until `notifications.sql` is applied. When to apply the new `schema.sql`: https://www.a2.dev/upgrades/0-21.
+
+  `sql/postgres/drizzle-schema.ts` shows A2's tables as Drizzle definitions: an example of one way to fit them into a Drizzle project, so your own migrations create them. `schema.sql` also works as a migration as it ships: a breakpoint comment ends each statement, so a tool that sends one statement per query, like Drizzle on PGlite, applies it unchanged.
+
+- af3cb3e: The Postgres store runs each append, claim, completion, `session.consume` poll, and redrive in one round trip, through a new function in `schema.sql`, `a2_batch`. A session's lock is held only while the database runs the call, not across round trips from your app, so one busy session keeps up on a database a few milliseconds away. A completion that moves its lane or log cursor to the next event takes no session lock at all, and neither does a `consume` poll that finds nothing new.
+
+  Apply the new `schema.sql` before you deploy. It adds the function and changes no table, and the deployment that is running keeps working against it. Deployed first, writes throw `STORE_NOT_CONFIGURED` naming `schema.sql`, and the next call after you apply it succeeds. With Drizzle, add the function as a custom migration (`drizzle-kit generate --custom`), copied from `schema.sql`: Drizzle can't declare functions. The function needs `read committed`, Postgres's default isolation level; under a stricter default it throws `STORE_NOT_CONFIGURED`.
+
+  Two fixes ride along. A drain whose last runs finish while it is claiming now claims again, instead of stopping with their cursors' next events unclaimed until the next append or scheduler watchdog. And on Postgres, a claim that waited on a cursor while its completion moved it to a newer event now returns that event; before, it held the head without running it, until a takeover counted the claim as a failed attempt.
+
+  A payload Postgres can't store, one with a NUL character (`\u0000`), now throws `INVALID_PAYLOAD` with nothing written, instead of `STORE_UNAVAILABLE`, which said to retry.
+
+### Patch Changes
+
+- 59a655d: Docs: an Upgrades section, `docs/upgrades/`, with one page per release that needs steps from you, from 0.17 through 0.21. `docs/server/05-sql-projections.mdx` keeps tables in your own database from A2's logs: it claims each event with one upsert on a position row, first in the transaction, and covers reading your writes, live views, SQLite, lag, and rebuilds.
+
+## 0.20.0
+
+### Minor Changes
+
+- 123c993: The Postgres store no longer creates its tables. Before you deploy this release, apply the SQL it needs, `node_modules/experimental-a2/sql/postgres/schema.sql`, once per database, however you run SQL against it. It creates only what is missing and leaves existing data alone, so it is safe on a database an earlier release set up, and the deployment that is running now keeps working against it, without waiting on its writes. It also records a schema version in a new `a2_schema` table. Apply it as the role your app connects with; if another role applies it, grant your app's role `select` on `a2_schema`. With `listenConnectionString`, also apply `sql/postgres/notifications.sql`, which installs the triggers A2 used to install for you.
+
+  If you deploy first, the store throws `STORE_NOT_CONFIGURED` on its first query, naming the file to apply, and the next call after you apply it succeeds without a redeploy. Until then, nothing is written: appends fail, and scheduled work waits. Vercel Queues keeps redelivering it, and the QStash scheduler now treats `STORE_NOT_CONFIGURED` like a store outage, handing each task to a later message (30 seconds, backing off to one day) instead of letting QStash's retries run out into its DLQ. That also covers a missing driver package, which used to dead-letter.
+
+  Each cold start now reads the schema version instead of running DDL. The DDL took a share lock on `a2_events` even when every table existed, so a cold start waited behind any open write to it, and writes waited behind the cold start. The store also no longer needs permission to create tables, so a runtime role with only read and write access works. SQLite still creates its tables on open.
+
+### Patch Changes
+
+- 123c993: Docs: stores and schedulers each get their own section, with one page per adapter, such as `docs/stores/04-postgres.mdx` and `docs/schedulers/03-qstash.mdx`. `docs/server/05-production.mdx` is gone: resolving dead letters moved to `docs/server/01-handlers.mdx`, and traces to `docs/reference/05-telemetry.mdx`, which replaces `docs/reference/05-adapters.mdx`.
+- 5228ecb: A returned batch the store refuses, such as one that reuses an event id, now dead-letters the event on that first attempt, like a `NonRetriableError`, with the store's error as its `lastError`: a retry would return the same ids. Before, the refused completion left the claim to lapse, so the event was retried on every watchdog wake and dead-lettered with no error. A scheduler delivery whose drain throws after arming its successor watchdog now acknowledges once that successor is durable, with the error on its `a2.drain` span (`a2.drain.outcome: failed`). Before, it threw: Vercel Queues redelivered the message alongside the successor, each redelivery arming another, and QStash retried it or, for a store outage, published a second, outage successor. `server.drain()` still throws.
+- 272e603: `fx()` model calls now carry the same AI Gateway defaults as the AI SDK harness: `caching: 'auto'` in the request's Gateway options, under any Gateway options FX sets itself such as its fast tier, and the session's stable `x-session-affinity` header. Before, FX asked for no caching and sent its own affinity, which changed every time A2 rebuilt the kernel, so a response's model calls rarely reused the provider's prompt cache. The rest of each request goes as FX wrote it.
+
 ## 0.19.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
 # experimental-a2
 
 A2 syncs your immutable event log, from server to browser. Each session has an
-event log, derived state, handlers, timers, and a live client.
+event log, derived state, consumers, timers, and a live client.
 
 ## Read the package
 

package/dist/{actor-C7b-1arn.d.ts → actor-HnGmrOZZ.d.ts}

@@ -1,7 +1,7 @@
-import { s as Contract, t as Reducer, u as EventDefs, v as StandardSchemaV1 } from "./reducer-CqA59Q6U.js";
-import { t as A2Store } from "./store-CyLUy86v.js";
-import { h as Session, n as A2Server, p as ScheduleTiming, t as A2Scheduler } from "./server-DYAATFuT.js";
-import { i as A2Telemetry } from "./telemetry-Cyfqo6Qt.js";
+import { s as Contract, t as Reducer, u as EventDefs, v as StandardSchemaV1 } from "./reducer-CYPHsSmd.js";
+import { t as A2Store } from "./store-Z2qjw50n.js";
+import { g as ScheduleTiming, n as A2Server, t as A2Scheduler, y as Session } from "./server-BshFZ0eL.js";
+import { i as A2Telemetry } from "./telemetry-CWwsh-Gx.js";
 //#region src/actor-shared.d.ts
 /**
  * A handler answered by throwing `NonRetriableError`: the event
@@ -317,4 +317,4 @@ type ActorDefinition<D extends ActorProtocol> = {
 declare function actor<D extends ActorProtocol>(options: ActorOptions<D>): ActorDefinition<D>;
 //#endregion
 export { ActorProtocol as _, ActorHandle as a, ActorScheduleSend as b, ActorOptions as c, concurrent as d, ActorConcurrentContext as f, ActorPresenceValues as g, ActorPresenceOf as h, ActorFetchOptions as i, ActorSendOptions as l, ActorPresenceMap as m, ActorCallResult as n, ActorHandler as o, ActorContext as p, ActorDefinition as r, ActorOperation as s, ActorCallOptions as t, actor as u, ActorRefusedError as v, ActorSend as x, ActorScheduleOptions as y };
-//# sourceMappingURL=actor-C7b-1arn.d.ts.map
+//# sourceMappingURL=actor-HnGmrOZZ.d.ts.map

package/dist/{actor-C7b-1arn.d.ts.map → actor-HnGmrOZZ.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"actor-C7b-1arn.d.ts","names":[],"sources":["../src/actor-shared.ts","../src/actor.ts"],"mappings":";;;;;;;;;;;cAiCa,0BAA0B;;WAE5B;;WAEA;EACT,YAAY,eAAe,mBAAmB;;;;;;;;;KAepC;EACV;EACA;;;;;;;EAOA;;;KAIU,gBAAgB,UAAU,iBAAiB;EACrD,gBAAgB;IAEd;;KAIQ,oBAAoB,QAC7B,WAAW,cAAc,EAAE;;;;;;KAQlB,iBAAiB;GAExB,yBAAA,WAAW;IAAgB,OAAO,EAAE;IAAI;IAAc,IAAI;;;;;;;;;;;;KAanD,UAAU,iBACV,WAAW,eAAe,EAAE,MACjC,QAAQ,EAAE,eACV,OAAO,EAAE;;;;;;;;;KAWJ,uBAAuB;EAAmB;;;;;;;;;;;;KAY1C,kBAAkB,iBAClB,WAAW,eAAe,EAAE,MACjC,OAAO,EAAE,gBAAgB,SAAS,yBAAyB,iBAC3D,OAAO,EAAE,IAAI,SAAS,yBAAyB;;KAI1C,aAAa,UAAU;;EAEjC,OAAO;;EAEP;;EAEA;;EAEA,QAAQ;;EAER,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;;;;;;;KASlB,uBAAuB,UAAU;;EAE3C;;EAEA;;EAEA,QAAQ;;EAER,SAAS;IAAU,OAAO;IAAY;;;EAEtC,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;KAGlB,kBAAkB;EAC5B,OAAO;;EAEP;;EAEA;;EAEA;;;KAWU,qBAAqB;EAC/B,kBAAkB,iBAAiB,kBAAkB;;;;;;;;;;;;;;KCzE3C,aAAa,UAAU,eAAe,gBAAgB,iBAC5D,KAAK,aAAa,IAAI,OAAO,YAAY,cAAc;EAEvD;EACA,SACE,KAAK,uBAAuB,IAC5B,OAAO,YAAY,cACT;;;;;;;;;;;;;;;;iBAiBF,WAAW,KAAK,GAC9B,SAAS,KAAK,KAAK,OAAO,aAAa;EACpC;EAAkB,SAAS,KAAK,KAAK,OAAO,aAAa;;KAIlD,aAAa,UAAU;;EAEjC;;EAEA,OAAO;;;;;EAKP,aAAa,WAAW,cAAc,aAAa,GAAG;EACtD,QAAQ;EACR,YAAY;EACZ,YAAY;MACR,gBAAgB;EAChB;;;;;;;;;;;;EAYA;;;;;;;KAQM;WACG;WAAwB;;WAExB;WACA;WACA;;WAGA;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA,QAAQ,SAAS;;KAGpB,kBAAkB,UAAU;;EAEtC,aAAa,WAAW,6BAA6B;;;;;;;;;;;;EAYrD,QAAQ,OAAO;;KAGL;;EAEV;;KAGU,mBAAmB;;EAE7B;;KAGU,gBAAgB;;EAE1B,OAAO;;EAEP;;;;;EAKA;;KAGG,WACH,UAAU,eACV,gBAAgB,0BACH,YAAY,MAErB,QAAQ,YAAY,IACpB,UAAU,qBACP,QAAQ,gBAAgB,gBAE3B,OAAO,YAAY,IACnB,UAAU,qBACP,QAAQ,gBAAgB;KAE5B,WACH,UAAU,eACV,gBAAgB,0BACH,YAAY,MAErB,QAAQ,YAAY,IACpB,UAAU,qBACP;EAAU;EAAY;MAEzB,OAAO,YAAY,IACnB,UAAU,qBACP;EAAU;EAAY;;;KAGnB,YAAY,UAAU;WACvB;;;;;;;;WAQA,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,aAAa,QAAQ,gBAAgB;;;;;;;;;;;WAWrC,QACP,SAAS,SACT,UAAU,kBAAkB,OACzB,QAAQ;;WAEJ,SAAS,QAAQ;;KAGhB,gBAAgB,UAAU;WAC3B;;;;;;WAMA,WAAW;;WAEX,UAAU,SAAS;;WAEnB,QAAQ,SAAS;;WAEjB,SAAS,QAAQ,qBAAqB,aAAa;EAC5D,MAAM,aAAa,YAAY;;;;;;;iBAsDjB,MAAM,UAAU,eAC9B,SAAS,aAAa,KACrB,gBAAgB"}
+{"version":3,"file":"actor-HnGmrOZZ.d.ts","names":[],"sources":["../src/actor-shared.ts","../src/actor.ts"],"mappings":";;;;;;;;;;;cAiCa,0BAA0B;;WAE5B;;WAEA;EACT,YAAY,eAAe,mBAAmB;;;;;;;;;KAepC;EACV;EACA;;;;;;;EAOA;;;KAIU,gBAAgB,UAAU,iBAAiB;EACrD,gBAAgB;IAEd;;KAIQ,oBAAoB,QAC7B,WAAW,cAAc,EAAE;;;;;;KAQlB,iBAAiB;GAExB,yBAAA,WAAW;IAAgB,OAAO,EAAE;IAAI;IAAc,IAAI;;;;;;;;;;;;KAanD,UAAU,iBACV,WAAW,eAAe,EAAE,MACjC,QAAQ,EAAE,eACV,OAAO,EAAE;;;;;;;;;KAWJ,uBAAuB;EAAmB;;;;;;;;;;;;KAY1C,kBAAkB,iBAClB,WAAW,eAAe,EAAE,MACjC,OAAO,EAAE,gBAAgB,SAAS,yBAAyB,iBAC3D,OAAO,EAAE,IAAI,SAAS,yBAAyB;;KAI1C,aAAa,UAAU;;EAEjC,OAAO;;EAEP;;EAEA;;EAEA,QAAQ;;EAER,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;;;;;;;KASlB,uBAAuB,UAAU;;EAE3C;;EAEA;;EAEA,QAAQ;;EAER,SAAS;IAAU,OAAO;IAAY;;;EAEtC,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;KAGlB,kBAAkB;EAC5B,OAAO;;EAEP;;EAEA;;EAEA;;;KAWU,qBAAqB;EAC/B,kBAAkB,iBAAiB,kBAAkB;;;;;;;;;;;;;;KClE3C,aAAa,UAAU,eAAe,gBAAgB,iBAC5D,KAAK,aAAa,IAAI,OAAO,YAAY,cAAc;EAEvD;EACA,SACE,KAAK,uBAAuB,IAC5B,OAAO,YAAY,cACT;;;;;;;;;;;;;;;;iBAiBF,WAAW,KAAK,GAC9B,SAAS,KAAK,KAAK,OAAO,aAAa;EACpC;EAAkB,SAAS,KAAK,KAAK,OAAO,aAAa;;KAIlD,aAAa,UAAU;;EAEjC;;EAEA,OAAO;;;;;EAKP,aAAa,WAAW,cAAc,aAAa,GAAG;EACtD,QAAQ;EACR,YAAY;EACZ,YAAY;MACR,gBAAgB;EAChB;;;;;;;;;;;;EAYA;;;;;;;KAQM;WACG;WAAwB;;WAExB;WACA;WACA;;WAGA;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA,QAAQ,SAAS;;KAGpB,kBAAkB,UAAU;;EAEtC,aAAa,WAAW,6BAA6B;;;;;;;;;;;;EAYrD,QAAQ,OAAO;;KAGL;;EAEV;;KAGU,mBAAmB;;EAE7B;;KAGU,gBAAgB;;EAE1B,OAAO;;EAEP;;;;;EAKA;;KAGG,WACH,UAAU,eACV,gBAAgB,0BACH,YAAY,MAErB,QAAQ,YAAY,IACpB,UAAU,qBACP,QAAQ,gBAAgB,gBAE3B,OAAO,YAAY,IACnB,UAAU,qBACP,QAAQ,gBAAgB;KAE5B,WACH,UAAU,eACV,gBAAgB,0BACH,YAAY,MAErB,QAAQ,YAAY,IACpB,UAAU,qBACP;EAAU;EAAY;MAEzB,OAAO,YAAY,IACnB,UAAU,qBACP;EAAU;EAAY;;;KAGnB,YAAY,UAAU;WACvB;;;;;;;;WAQA,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,aAAa,QAAQ,gBAAgB;;;;;;;;;;;WAWrC,QACP,SAAS,SACT,UAAU,kBAAkB,OACzB,QAAQ;;WAEJ,SAAS,QAAQ;;KAGhB,gBAAgB,UAAU;WAC3B;;;;;;WAMA,WAAW;;WAEX,UAAU,SAAS;;WAEnB,QAAQ,SAAS;;WAEjB,SAAS,QAAQ,qBAAqB,aAAa;EAC5D,MAAM,aAAa,YAAY;;;;;;;iBAsDjB,MAAM,UAAU,eAC9B,SAAS,aAAa,KACrB,gBAAgB"}

package/dist/actor-client.d.ts

@@ -1,4 +1,4 @@
-import { n as ActorCallResult, v as ActorRefusedError } from "./actor-C7b-1arn.js";
+import { n as ActorCallResult, v as ActorRefusedError } from "./actor-HnGmrOZZ.js";
 //#region src/actor-client.d.ts
 declare class ActorRequestError extends Error {
   readonly status: number | undefined;

package/dist/actor-client.js

@@ -1,5 +1,5 @@
-import { i as A2Error } from "./session-clear-DGI4jTQ5.js";
-import { i as ActorRefusedError } from "./actor-shared-t7w8xIKP.js";
+import { i as A2Error } from "./session-clear-wHd5GCpZ.js";
+import { i as ActorRefusedError } from "./actor-shared-DFET5q16.js";
 //#region src/actor-client.ts
 /**
 * experimental-a2/actor/client — typed calls to an actor over HTTP.

package/dist/actor-react.d.ts

@@ -1,7 +1,7 @@
-import { c as ContractEvent, u as EventDefs } from "./reducer-CqA59Q6U.js";
-import { g as ActorPresenceValues, m as ActorPresenceMap } from "./actor-C7b-1arn.js";
+import { c as ContractEvent, u as EventDefs } from "./reducer-CYPHsSmd.js";
+import { g as ActorPresenceValues, m as ActorPresenceMap } from "./actor-HnGmrOZZ.js";
 import { ActorClientCall, ActorStateOf, AnyActorDefinition } from "./actor-client.js";
-import { a as Connection } from "./client-h_DKFAjj.js";
+import { a as Connection } from "./client-CUMbS_38.js";
 //#region src/actor-react.d.ts
 /** The server-to-client handoff: `await def.actor(id).state()`. */
 type ActorSnapshot<S> = {

package/dist/actor-react.js

@@ -1,10 +1,10 @@
 "use client";
-import { n as isSessionCleared } from "./session-clear-DGI4jTQ5.js";
-import { r as foldsClearMarkers } from "./reducer-BAXc8JyF.js";
-import { n as internalContract } from "./contract-BYKASlCV.js";
-import { t as createClient } from "./client-BhHLoNKF.js";
+import { n as isSessionCleared } from "./session-clear-wHd5GCpZ.js";
+import { r as foldsClearMarkers } from "./reducer-CjmvZSAb.js";
+import { n as internalContract } from "./contract-CWukt01d.js";
+import { t as createClient } from "./client-9IeTsiAs.js";
 import { useSession } from "./react.js";
-import { l as openPresenceDefs } from "./actor-shared-t7w8xIKP.js";
+import { l as openPresenceDefs } from "./actor-shared-DFET5q16.js";
 import { createActorClient } from "./actor-client.js";
 import { useMemo } from "react";
 //#region src/actor-react.ts

package/dist/{actor-shared-t7w8xIKP.js → actor-shared-DFET5q16.js}

@@ -1,5 +1,5 @@
-import { a as reducer } from "./reducer-BAXc8JyF.js";
-import { n as internalContract } from "./contract-BYKASlCV.js";
+import { a as reducer } from "./reducer-CjmvZSAb.js";
+import { n as internalContract } from "./contract-CWukt01d.js";
 //#region src/actor-shared.ts
 /**
 * Internal shared vocabulary of the actor module — the reserved event
@@ -129,4 +129,4 @@ function actorReducer(options) {
 //#endregion
 export { actorFailedSchema as a, isJsonTree as c, ActorRefusedError as i, openPresenceDefs as l, ACTOR_LANE as n, actorReducer as o, ACTOR_STATE_EVENT as r, actorStateSchema as s, ACTOR_FAILED_EVENT as t };
 
-//# sourceMappingURL=actor-shared-t7w8xIKP.js.map
+//# sourceMappingURL=actor-shared-DFET5q16.js.map

package/dist/{actor-shared-t7w8xIKP.js.map → actor-shared-DFET5q16.js.map}

@@ -1 +1 @@
-{"version":3,"file":"actor-shared-t7w8xIKP.js","names":["createContract"],"sources":["../src/actor-shared.ts"],"sourcesContent":["import { reducer } from './reducer.ts'\n/**\n * Internal shared vocabulary of the actor module — the reserved event\n * envelopes, the protocol and context types, the state fold. Not an\n * entry point: the public surfaces are experimental-a2/actor (server),\n * /actor/client, and /actor/react.\n *\n * An actor is a durable mailbox with memory: one session per instance,\n * events processed one at a time (a lane) unless a handler opts out\n * with `concurrent: true`, state materialized as `a2.actor.state`\n * events committed atomically with each handler's completion.\n */\n\nimport { internalContract as createContract } from './contract.ts'\nimport type { Reducer } from './reducer.ts'\nimport type { ScheduleTiming } from './server.ts'\nimport type { StandardSchemaV1 } from './standard-schema.ts'\n\n/** Event type of a committed state change — one per completed serial handler. */\nexport const ACTOR_STATE_EVENT = 'a2.actor.state'\n/** Event type of a refusal — a handler that answered by throwing NonRetriableError. */\nexport const ACTOR_FAILED_EVENT = 'a2.actor.failed'\n/** The per-instance lane every serial handler shares — the state's write lock. */\nexport const ACTOR_LANE = 'a2.actor'\n/** Reducer identity — bump when the fold's meaning changes. */\nexport const ACTOR_REDUCER_NAME = 'a2.actor.v1'\n\n/**\n * A handler answered by throwing `NonRetriableError`: the event\n * settled, the state did not change. Isomorphic — the server raises it\n * from calls and `fetch()` serializes it as a 409; the client's `call`\n * proxy revives it from that response.\n */\nexport class ActorRefusedError extends Error {\n  /** The refused event's name. */\n  readonly event: string\n  /** The refused event's message id. */\n  readonly messageId: string\n  constructor(event: string, messageId: string, message: string) {\n    super(message)\n    this.name = 'ActorRefusedError'\n    this.event = event\n    this.messageId = messageId\n  }\n}\n\n/**\n * The declaration an actor is defined over: its state shape and its\n * event vocabulary, as types. Core A2 contracts are schemas because\n * the wire is untrusted; actor protocols are types because your\n * server is trusted — same contract-first design language, dialed to\n * the trust level.\n */\nexport type ActorProtocol = {\n  state: object\n  events: object\n  /**\n   * Optional third vocabulary: presence field → value type. Ephemeral\n   * audience state (who is here, cursors), replicated to subscribers\n   * and never stored in the log. Declaring it requires `presence:\n   * true` in the actor options — the wire bit types cannot carry.\n   */\n  presence?: object\n}\n\n/** The protocol's presence vocabulary, `never` when undeclared. */\nexport type ActorPresenceOf<D extends ActorProtocol> = D extends {\n  presence: infer P extends object\n}\n  ? P\n  : never\n\n/** A `setPresence` patch: changed fields, `null` clears one. */\nexport type ActorPresenceValues<P> = {\n  [F in keyof P & string]?: P[F] | null\n}\n\n/**\n * The replicated presence map: participant → field → latest value,\n * last write wins per field. Values are peer-authored — render them\n * like user input.\n */\nexport type ActorPresenceMap<P> = {\n  [participant: string]: {\n    [F in keyof P & string]?: { value: P[F]; seen: number; at: Date }\n  }\n}\n\n/**\n * The typed self-send surface: one method per declared event —\n * `ctx.send.transfer({ ref, amount })`. Buffered, not immediate: every\n * send requested during a handler commits atomically with that\n * handler's completion (a serial handler's state commit, a concurrent\n * handler's settlement), riding core's returned-events semantics — so\n * a reserve-and-trigger can never half-happen, and re-runs converge on\n * the same deterministic message ids.\n */\nexport type ActorSend<E> = {\n  readonly [K in keyof E]: {} extends E[K]\n    ? (input?: E[K]) => void\n    : (input: E[K]) => void\n}\n\n/**\n * Timing for a scheduled event: exactly `{ delay: '5d' }` or\n * `{ at: Date }` (core §6 semantics — relative delays anchor to the\n * triggering message's durable `createdAt`, so re-runs resolve the\n * same due time). `name` overrides the timer's identity — it defaults\n * to the target event name, scoped to the triggering message, so one\n * handler run gets one timer per target event unless named apart.\n */\nexport type ActorScheduleOptions = ScheduleTiming & { name?: string }\n\n/**\n * The typed durable-timer surface: one method per declared event —\n * `ctx.schedule.refund({ ref: ctx.id }, { delay: '1h' })`. Unlike\n * `send`, scheduling is immediate, not buffered: it awaits provider\n * acceptance at call time (a timer is provider-side, not a log row),\n * so a handler that schedules and then refuses has still armed the\n * timer. That is safe by the guarded-delivery idiom — the stale timer\n * fires into an idempotent no-op — but it is the one exception to\n * \"refusals are total\". Requires a configured `scheduler`.\n */\nexport type ActorScheduleSend<E> = {\n  readonly [K in keyof E]: {} extends E[K]\n    ? (input: E[K] | undefined, options: ActorScheduleOptions) => Promise<void>\n    : (input: E[K], options: ActorScheduleOptions) => Promise<void>\n}\n\n/** What a serial handler receives alongside its typed input. */\nexport type ActorContext<D extends ActorProtocol> = {\n  /** Mutable draft, committed atomically with the handler's completion. */\n  state: D['state']\n  /** The message id — stable across re-runs; the idempotency key for external I/O. */\n  id: string\n  /** Durable 1-based dispatch ordinal of this message. */\n  attempt: number\n  /** The ordinary A2 handler signal — fires on claim expiry or supersession. */\n  signal: AbortSignal\n  /** Typed buffered self-send — committed atomically with the state commit. */\n  send: ActorSend<D['events']>\n  /** Typed durable timers — immediate provider handoff, see ActorScheduleSend. */\n  schedule: ActorScheduleSend<D['events']>\n}\n\n/**\n * What a `concurrent: true` handler receives. No draft — concurrent\n * handlers run off the lane, in parallel, so state is a snapshot read\n * (honest about staleness) and mutations happen by sending events\n * whose serial handlers decide against fresh state.\n */\nexport type ActorConcurrentContext<D extends ActorProtocol> = {\n  /** The message id — stable across re-runs; the idempotency key for external I/O. */\n  id: string\n  /** Durable 1-based dispatch ordinal of this message. */\n  attempt: number\n  /** The ordinary A2 handler signal — fires on claim expiry or supersession. */\n  signal: AbortSignal\n  /** Snapshot read — observational; the world moves while this runs. */\n  state(): Promise<{ state: D['state']; index: number }>\n  /** Typed buffered self-send — committed atomically with settlement. */\n  send: ActorSend<D['events']>\n  /** Typed durable timers — immediate provider handoff, see ActorScheduleSend. */\n  schedule: ActorScheduleSend<D['events']>\n}\n\nexport type ActorStatePayload<S> = {\n  state: S\n  /** The event whose handler committed this state. */\n  event: string\n  /** The message (invocation event) id this state answers. */\n  message: string\n  /** The session's latest clear marker when this state was read. */\n  clearIndex?: number\n}\n\nexport type ActorFailedPayload = {\n  /** The message (invocation event) id this refusal answers. */\n  message: string\n  event: string\n  error: string\n}\n\n/** The event vocabulary a client needs to follow an actor's state. */\nexport type ActorClientEventDefs<S> = {\n  'a2.actor.state': StandardSchemaV1<ActorStatePayload<S>>\n}\n\ntype SchemaResult<T> = StandardSchemaV1.Result<T>\n\nconst issue = <T>(message: string): SchemaResult<T> => ({\n  issues: [{ message }],\n})\n\nconst schema = <T>(\n  label: string,\n  parse: (value: unknown) => SchemaResult<T>,\n): StandardSchemaV1<T> => ({\n  '~standard': {\n    version: 1,\n    vendor: 'a2',\n    validate(value) {\n      try {\n        return parse(value)\n      } catch (error) {\n        return issue(\n          `${label}: ${error instanceof Error ? error.message : String(error)}`,\n        )\n      }\n    },\n  },\n})\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/** True for plain JSON trees — what the log can store without loss. */\nexport function isJsonTree(\n  value: unknown,\n  seen: Set<object> = new Set(),\n): boolean {\n  if (\n    value === null ||\n    typeof value === 'string' ||\n    typeof value === 'boolean'\n  ) {\n    return true\n  }\n  if (typeof value === 'number') return Number.isFinite(value)\n  if (typeof value !== 'object') return false\n  if (seen.has(value)) return false\n  seen.add(value)\n  const valid = Array.isArray(value)\n    ? value.every((item) => isJsonTree(item, seen))\n    : Object.getPrototypeOf(value) === Object.prototype &&\n      Object.values(value).every(\n        (item) => item === undefined || isJsonTree(item, seen),\n      )\n  seen.delete(value)\n  return valid\n}\n\n/** Per-field ceiling for presence values — presence is a cursor, not a document. */\nexport const PRESENCE_VALUE_MAX_BYTES = 8_192\n\n/**\n * The open presence vocabulary: the '*' catch-all validates any field\n * name against the JSON floor. The protocol types the vocabulary at\n * compile time; the route's `authorize` sees every set before\n * acceptance; renderers treat values as user input. Meaning has three\n * guards — this schema only owns the bytes.\n */\nexport const openPresenceDefs: Readonly<\n  Record<string, StandardSchemaV1<unknown>>\n> = Object.freeze({\n  '*': {\n    '~standard': {\n      version: 1,\n      vendor: 'a2',\n      validate: (value: unknown) => {\n        if (!isJsonTree(value)) {\n          return {\n            issues: [{ message: 'presence values must be plain JSON trees' }],\n          }\n        }\n        if (JSON.stringify(value).length > PRESENCE_VALUE_MAX_BYTES) {\n          return {\n            issues: [\n              {\n                message: `presence values are capped at ${PRESENCE_VALUE_MAX_BYTES} bytes`,\n              },\n            ],\n          }\n        }\n        return { value }\n      },\n    },\n  } satisfies StandardSchemaV1<unknown>,\n})\n\n/**\n * The `a2.actor.state` envelope: provenance plus the state, held to a\n * plain JSON tree (a `Date` or `Map` in state fails loudly at commit,\n * never silently coerces in the log).\n */\nexport function actorStateSchema<S>(): StandardSchemaV1<ActorStatePayload<S>> {\n  return schema(ACTOR_STATE_EVENT, (value) => {\n    if (\n      !isRecord(value) ||\n      typeof value['event'] !== 'string' ||\n      typeof value['message'] !== 'string'\n    ) {\n      return issue(`invalid ${ACTOR_STATE_EVENT} payload`)\n    }\n    const state = value['state']\n    if (!isJsonTree(state)) {\n      return issue('the actor state must be a plain JSON tree')\n    }\n    const clearIndex = value['clearIndex']\n    if (\n      clearIndex !== undefined &&\n      (!Number.isSafeInteger(clearIndex) || (clearIndex as number) < 1)\n    ) {\n      return issue('the actor clearIndex must be a positive safe integer')\n    }\n    return {\n      value: {\n        state: state as S,\n        event: value['event'],\n        message: value['message'],\n        ...(clearIndex === undefined\n          ? {}\n          : { clearIndex: clearIndex as number }),\n      },\n    }\n  })\n}\n\nexport const actorFailedSchema: StandardSchemaV1<ActorFailedPayload> = schema(\n  ACTOR_FAILED_EVENT,\n  (value) => {\n    if (\n      !isRecord(value) ||\n      typeof value['message'] !== 'string' ||\n      typeof value['event'] !== 'string' ||\n      typeof value['error'] !== 'string'\n    ) {\n      return issue(`invalid ${ACTOR_FAILED_EVENT} payload`)\n    }\n    return {\n      value: {\n        message: value['message'],\n        event: value['event'],\n        error: value['error'],\n      },\n    }\n  },\n)\n\nexport type ActorReducerOptions<S> = {\n  /** The actor's name — must match the server-side definition. */\n  name: string\n  /** The initial state — a plain JSON tree, the fold's seed. */\n  state: S\n}\n\n/**\n * The library fold over an actor's state commits — last write wins.\n * Pure library code: a browser bundle folds an actor's live state with\n * no user code, so the actor definition itself stays server-only\n * (import the server module's type for typing, this reducer for data).\n */\nexport function actorReducer<S>(\n  options: ActorReducerOptions<S>,\n): Reducer<ActorClientEventDefs<S>, S> {\n  if (!isJsonTree(options.state)) {\n    throw new TypeError(\n      `actor '${options.name}': the initial state must be a plain JSON tree`,\n    )\n  }\n  const events: ActorClientEventDefs<S> = {\n    [ACTOR_STATE_EVENT]: actorStateSchema(),\n  }\n  return reducer({\n    contract: createContract({ name: options.name, events }),\n    name: ACTOR_REDUCER_NAME,\n    initialState: options.state,\n  }).fold((state, event) =>\n    event.type === ACTOR_STATE_EVENT ? event.payload.state : state,\n  )\n}\n"],"mappings":"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"}
+{"version":3,"file":"actor-shared-DFET5q16.js","names":["createContract"],"sources":["../src/actor-shared.ts"],"sourcesContent":["import { reducer } from './reducer.ts'\n/**\n * Internal shared vocabulary of the actor module — the reserved event\n * envelopes, the protocol and context types, the state fold. Not an\n * entry point: the public surfaces are experimental-a2/actor (server),\n * /actor/client, and /actor/react.\n *\n * An actor is a durable mailbox with memory: one session per instance,\n * events processed one at a time (a lane) unless a handler opts out\n * with `concurrent: true`, state materialized as `a2.actor.state`\n * events committed atomically with each handler's completion.\n */\n\nimport { internalContract as createContract } from './contract.ts'\nimport type { Reducer } from './reducer.ts'\nimport type { ScheduleTiming } from './server.ts'\nimport type { StandardSchemaV1 } from './standard-schema.ts'\n\n/** Event type of a committed state change — one per completed serial handler. */\nexport const ACTOR_STATE_EVENT = 'a2.actor.state'\n/** Event type of a refusal — a handler that answered by throwing NonRetriableError. */\nexport const ACTOR_FAILED_EVENT = 'a2.actor.failed'\n/** The per-instance lane every serial handler shares — the state's write lock. */\nexport const ACTOR_LANE = 'a2.actor'\n/** Reducer identity — bump when the fold's meaning changes. */\nexport const ACTOR_REDUCER_NAME = 'a2.actor.v1'\n\n/**\n * A handler answered by throwing `NonRetriableError`: the event\n * settled, the state did not change. Isomorphic — the server raises it\n * from calls and `fetch()` serializes it as a 409; the client's `call`\n * proxy revives it from that response.\n */\nexport class ActorRefusedError extends Error {\n  /** The refused event's name. */\n  readonly event: string\n  /** The refused event's message id. */\n  readonly messageId: string\n  constructor(event: string, messageId: string, message: string) {\n    super(message)\n    this.name = 'ActorRefusedError'\n    this.event = event\n    this.messageId = messageId\n  }\n}\n\n/**\n * The declaration an actor is defined over: its state shape and its\n * event vocabulary, as types. Core A2 contracts are schemas because\n * the wire is untrusted; actor protocols are types because your\n * server is trusted — same contract-first design language, dialed to\n * the trust level.\n */\nexport type ActorProtocol = {\n  state: object\n  events: object\n  /**\n   * Optional third vocabulary: presence field → value type. Ephemeral\n   * audience state (who is here, cursors), replicated to subscribers\n   * and never stored in the log. Declaring it requires `presence:\n   * true` in the actor options — the wire bit types cannot carry.\n   */\n  presence?: object\n}\n\n/** The protocol's presence vocabulary, `never` when undeclared. */\nexport type ActorPresenceOf<D extends ActorProtocol> = D extends {\n  presence: infer P extends object\n}\n  ? P\n  : never\n\n/** A `setPresence` patch: changed fields, `null` clears one. */\nexport type ActorPresenceValues<P> = {\n  [F in keyof P & string]?: P[F] | null\n}\n\n/**\n * The replicated presence map: participant → field → latest value,\n * last write wins per field. Values are peer-authored — render them\n * like user input.\n */\nexport type ActorPresenceMap<P> = {\n  [participant: string]: {\n    [F in keyof P & string]?: { value: P[F]; seen: number; at: Date }\n  }\n}\n\n/**\n * The typed self-send surface: one method per declared event —\n * `ctx.send.transfer({ ref, amount })`. Buffered, not immediate: every\n * send requested during a handler commits atomically with that\n * handler's completion (a serial handler's state commit, a concurrent\n * handler's settlement), riding core's returned-events semantics — so\n * a reserve-and-trigger can never half-happen, and re-runs converge on\n * the same deterministic message ids.\n */\nexport type ActorSend<E> = {\n  readonly [K in keyof E]: {} extends E[K]\n    ? (input?: E[K]) => void\n    : (input: E[K]) => void\n}\n\n/**\n * Timing for a scheduled event: exactly `{ delay: '5d' }` or\n * `{ at: Date }` (core §6 semantics — relative delays anchor to the\n * triggering message's durable `createdAt`, so re-runs resolve the\n * same due time). `name` overrides the timer's identity — it defaults\n * to the target event name, scoped to the triggering message, so one\n * handler run gets one timer per target event unless named apart.\n */\nexport type ActorScheduleOptions = ScheduleTiming & { name?: string }\n\n/**\n * The typed durable-timer surface: one method per declared event —\n * `ctx.schedule.refund({ ref: ctx.id }, { delay: '1h' })`. Unlike\n * `send`, scheduling is immediate, not buffered: it awaits provider\n * acceptance at call time (a timer is provider-side, not a log row),\n * so a handler that schedules and then refuses has still armed the\n * timer. That is safe by the guarded-delivery idiom — the stale timer\n * fires into an idempotent no-op — but it is the one exception to\n * \"refusals are total\". Requires a configured `scheduler`.\n */\nexport type ActorScheduleSend<E> = {\n  readonly [K in keyof E]: {} extends E[K]\n    ? (input: E[K] | undefined, options: ActorScheduleOptions) => Promise<void>\n    : (input: E[K], options: ActorScheduleOptions) => Promise<void>\n}\n\n/** What a serial handler receives alongside its typed input. */\nexport type ActorContext<D extends ActorProtocol> = {\n  /** Mutable draft, committed atomically with the handler's completion. */\n  state: D['state']\n  /** The message id — stable across re-runs; the idempotency key for external I/O. */\n  id: string\n  /** Durable 1-based dispatch ordinal of this message. */\n  attempt: number\n  /** The ordinary A2 handler signal — fires on claim expiry or supersession. */\n  signal: AbortSignal\n  /** Typed buffered self-send — committed atomically with the state commit. */\n  send: ActorSend<D['events']>\n  /** Typed durable timers — immediate provider handoff, see ActorScheduleSend. */\n  schedule: ActorScheduleSend<D['events']>\n}\n\n/**\n * What a `concurrent: true` handler receives. No draft — concurrent\n * handlers run off the lane, in parallel, so state is a snapshot read\n * (honest about staleness) and mutations happen by sending events\n * whose serial handlers decide against fresh state.\n */\nexport type ActorConcurrentContext<D extends ActorProtocol> = {\n  /** The message id — stable across re-runs; the idempotency key for external I/O. */\n  id: string\n  /** Durable 1-based dispatch ordinal of this message. */\n  attempt: number\n  /** The ordinary A2 handler signal — fires on claim expiry or supersession. */\n  signal: AbortSignal\n  /** Snapshot read — observational; the world moves while this runs. */\n  state(): Promise<{ state: D['state']; index: number }>\n  /** Typed buffered self-send — committed atomically with settlement. */\n  send: ActorSend<D['events']>\n  /** Typed durable timers — immediate provider handoff, see ActorScheduleSend. */\n  schedule: ActorScheduleSend<D['events']>\n}\n\nexport type ActorStatePayload<S> = {\n  state: S\n  /** The event whose handler committed this state. */\n  event: string\n  /** The message (invocation event) id this state answers. */\n  message: string\n  /** The session's latest clear marker when this state was read. */\n  clearIndex?: number\n}\n\nexport type ActorFailedPayload = {\n  /** The message (invocation event) id this refusal answers. */\n  message: string\n  event: string\n  error: string\n}\n\n/** The event vocabulary a client needs to follow an actor's state. */\nexport type ActorClientEventDefs<S> = {\n  'a2.actor.state': StandardSchemaV1<ActorStatePayload<S>>\n}\n\ntype SchemaResult<T> = StandardSchemaV1.Result<T>\n\nconst issue = <T>(message: string): SchemaResult<T> => ({\n  issues: [{ message }],\n})\n\nconst schema = <T>(\n  label: string,\n  parse: (value: unknown) => SchemaResult<T>,\n): StandardSchemaV1<T> => ({\n  '~standard': {\n    version: 1,\n    vendor: 'a2',\n    validate(value) {\n      try {\n        return parse(value)\n      } catch (error) {\n        return issue(\n          `${label}: ${error instanceof Error ? error.message : String(error)}`,\n        )\n      }\n    },\n  },\n})\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/** True for plain JSON trees — what the log can store without loss. */\nexport function isJsonTree(\n  value: unknown,\n  seen: Set<object> = new Set(),\n): boolean {\n  if (\n    value === null ||\n    typeof value === 'string' ||\n    typeof value === 'boolean'\n  ) {\n    return true\n  }\n  if (typeof value === 'number') return Number.isFinite(value)\n  if (typeof value !== 'object') return false\n  if (seen.has(value)) return false\n  seen.add(value)\n  const valid = Array.isArray(value)\n    ? value.every((item) => isJsonTree(item, seen))\n    : Object.getPrototypeOf(value) === Object.prototype &&\n      Object.values(value).every(\n        (item) => item === undefined || isJsonTree(item, seen),\n      )\n  seen.delete(value)\n  return valid\n}\n\n/** Per-field ceiling for presence values — presence is a cursor, not a document. */\nexport const PRESENCE_VALUE_MAX_BYTES = 8_192\n\n/**\n * The open presence vocabulary: the '*' catch-all validates any field\n * name against the JSON floor. The protocol types the vocabulary at\n * compile time; the route's `authorize` sees every set before\n * acceptance; renderers treat values as user input. Meaning has three\n * guards — this schema only owns the bytes.\n */\nexport const openPresenceDefs: Readonly<\n  Record<string, StandardSchemaV1<unknown>>\n> = Object.freeze({\n  '*': {\n    '~standard': {\n      version: 1,\n      vendor: 'a2',\n      validate: (value: unknown) => {\n        if (!isJsonTree(value)) {\n          return {\n            issues: [{ message: 'presence values must be plain JSON trees' }],\n          }\n        }\n        if (JSON.stringify(value).length > PRESENCE_VALUE_MAX_BYTES) {\n          return {\n            issues: [\n              {\n                message: `presence values are capped at ${PRESENCE_VALUE_MAX_BYTES} bytes`,\n              },\n            ],\n          }\n        }\n        return { value }\n      },\n    },\n  } satisfies StandardSchemaV1<unknown>,\n})\n\n/**\n * The `a2.actor.state` envelope: provenance plus the state, held to a\n * plain JSON tree (a `Date` or `Map` in state fails loudly at commit,\n * never silently coerces in the log).\n */\nexport function actorStateSchema<S>(): StandardSchemaV1<ActorStatePayload<S>> {\n  return schema(ACTOR_STATE_EVENT, (value) => {\n    if (\n      !isRecord(value) ||\n      typeof value['event'] !== 'string' ||\n      typeof value['message'] !== 'string'\n    ) {\n      return issue(`invalid ${ACTOR_STATE_EVENT} payload`)\n    }\n    const state = value['state']\n    if (!isJsonTree(state)) {\n      return issue('the actor state must be a plain JSON tree')\n    }\n    const clearIndex = value['clearIndex']\n    if (\n      clearIndex !== undefined &&\n      (!Number.isSafeInteger(clearIndex) || (clearIndex as number) < 1)\n    ) {\n      return issue('the actor clearIndex must be a positive safe integer')\n    }\n    return {\n      value: {\n        state: state as S,\n        event: value['event'],\n        message: value['message'],\n        ...(clearIndex === undefined\n          ? {}\n          : { clearIndex: clearIndex as number }),\n      },\n    }\n  })\n}\n\nexport const actorFailedSchema: StandardSchemaV1<ActorFailedPayload> = schema(\n  ACTOR_FAILED_EVENT,\n  (value) => {\n    if (\n      !isRecord(value) ||\n      typeof value['message'] !== 'string' ||\n      typeof value['event'] !== 'string' ||\n      typeof value['error'] !== 'string'\n    ) {\n      return issue(`invalid ${ACTOR_FAILED_EVENT} payload`)\n    }\n    return {\n      value: {\n        message: value['message'],\n        event: value['event'],\n        error: value['error'],\n      },\n    }\n  },\n)\n\nexport type ActorReducerOptions<S> = {\n  /** The actor's name — must match the server-side definition. */\n  name: string\n  /** The initial state — a plain JSON tree, the fold's seed. */\n  state: S\n}\n\n/**\n * The library fold over an actor's state commits — last write wins.\n * Pure library code: a browser bundle folds an actor's live state with\n * no user code, so the actor definition itself stays server-only\n * (import the server module's type for typing, this reducer for data).\n */\nexport function actorReducer<S>(\n  options: ActorReducerOptions<S>,\n): Reducer<ActorClientEventDefs<S>, S> {\n  if (!isJsonTree(options.state)) {\n    throw new TypeError(\n      `actor '${options.name}': the initial state must be a plain JSON tree`,\n    )\n  }\n  const events: ActorClientEventDefs<S> = {\n    [ACTOR_STATE_EVENT]: actorStateSchema(),\n  }\n  return reducer({\n    contract: createContract({ name: options.name, events }),\n    name: ACTOR_REDUCER_NAME,\n    initialState: options.state,\n  }).fold((state, event) =>\n    event.type === ACTOR_STATE_EVENT ? event.payload.state : state,\n  )\n}\n"],"mappings":"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"}

package/dist/actor.d.ts

@@ -1,2 +1,2 @@
-import { _ as ActorProtocol, a as ActorHandle, b as ActorScheduleSend, c as ActorOptions, d as concurrent, f as ActorConcurrentContext, g as ActorPresenceValues, h as ActorPresenceOf, i as ActorFetchOptions, l as ActorSendOptions, m as ActorPresenceMap, n as ActorCallResult, o as ActorHandler, p as ActorContext, r as ActorDefinition, s as ActorOperation, t as ActorCallOptions, u as actor, v as ActorRefusedError, x as ActorSend, y as ActorScheduleOptions } from "./actor-C7b-1arn.js";
+import { _ as ActorProtocol, a as ActorHandle, b as ActorScheduleSend, c as ActorOptions, d as concurrent, f as ActorConcurrentContext, g as ActorPresenceValues, h as ActorPresenceOf, i as ActorFetchOptions, l as ActorSendOptions, m as ActorPresenceMap, n as ActorCallResult, o as ActorHandler, p as ActorContext, r as ActorDefinition, s as ActorOperation, t as ActorCallOptions, u as actor, v as ActorRefusedError, x as ActorSend, y as ActorScheduleOptions } from "./actor-HnGmrOZZ.js";
 export { ActorCallOptions, ActorCallResult, type ActorConcurrentContext, type ActorContext, ActorDefinition, ActorFetchOptions, ActorHandle, ActorHandler, ActorOperation, ActorOptions, type ActorPresenceMap, type ActorPresenceOf, type ActorPresenceValues, type ActorProtocol, ActorRefusedError, type ActorScheduleOptions, type ActorScheduleSend, type ActorSend, ActorSendOptions, actor, concurrent };

package/dist/actor.js

@@ -1,8 +1,9 @@
-import { a as NonRetriableError, i as A2Error, n as isSessionCleared, r as sessionClearedError } from "./session-clear-DGI4jTQ5.js";
-import { n as internalContract } from "./contract-BYKASlCV.js";
-import { v as serverInternals } from "./internal-CscSY7K_.js";
-import { c as parsePresenceSibling, o as setServerFetchHooks, s as sseResponse, t as createServer } from "./server-D-Y4pqwu.js";
-import { a as actorFailedSchema, c as isJsonTree, i as ActorRefusedError, l as openPresenceDefs, n as ACTOR_LANE, o as actorReducer, r as ACTOR_STATE_EVENT, s as actorStateSchema, t as ACTOR_FAILED_EVENT } from "./actor-shared-t7w8xIKP.js";
+import { a as NonRetriableError, i as A2Error, n as isSessionCleared, r as sessionClearedError } from "./session-clear-wHd5GCpZ.js";
+import { n as internalContract } from "./contract-CWukt01d.js";
+import { b as serverInternals } from "./internal-Bc4PvfHk.js";
+import { c as parsePresenceSibling, n as createServer, o as setServerFetchHooks, s as sseResponse } from "./server-DvIB8kj5.js";
+import { t as runtimeConsumer } from "./runtime-consumer-BWmht60z.js";
+import { a as actorFailedSchema, c as isJsonTree, i as ActorRefusedError, l as openPresenceDefs, n as ACTOR_LANE, o as actorReducer, r as ACTOR_STATE_EVENT, s as actorStateSchema, t as ACTOR_FAILED_EVENT } from "./actor-shared-DFET5q16.js";
 //#region src/actor.ts
 /**
 * experimental-a2/actor — durable actors over the log. Server-only
@@ -148,10 +149,11 @@ function actor(options) {
 		});
 		return send;
 	};
-	const handlers = {};
+	const concurrentRuns = /* @__PURE__ */ new Map();
+	const serialRuns = /* @__PURE__ */ new Map();
 	for (const [eventName, def] of handlersByEvent) {
 		if (def.kind === "concurrent") {
-			handlers[eventName] = async (ctx) => {
+			concurrentRuns.set(eventName, async (ctx) => {
 				const sends = [];
 				try {
 					await def.handle({
@@ -181,48 +183,45 @@ function actor(options) {
 					};
 				}
 				return sends;
-			};
+			});
 			continue;
 		}
-		handlers[eventName] = {
-			lane: ACTOR_LANE,
-			handler: async (ctx) => {
-				const { state, clearIndex } = await ctx.session.state(serverReducer, { through: "latest" });
-				const draft = structuredClone(state);
-				const sends = [];
-				try {
-					await def.handle({
-						state: draft,
-						id: ctx.event.id,
-						attempt: ctx.attempt,
-						signal: ctx.signal,
-						send: makeSend(sends),
-						schedule: makeSchedule((taskName, timing, event) => ctx.session.schedule(taskName, timing, event))
-					}, ctx.event.payload);
-				} catch (error) {
-					if (!(error instanceof NonRetriableError)) throw error;
-					const payload = {
-						message: ctx.event.id,
-						event: eventName,
-						error: describeError(error)
-					};
-					return {
-						type: ACTOR_FAILED_EVENT,
-						payload
-					};
-				}
-				const payload = {
+		serialRuns.set(eventName, async (ctx) => {
+			const { state, clearIndex } = await ctx.session.state(serverReducer, { through: "latest" });
+			const draft = structuredClone(state);
+			const sends = [];
+			try {
+				await def.handle({
 					state: draft,
-					event: eventName,
+					id: ctx.event.id,
+					attempt: ctx.attempt,
+					signal: ctx.signal,
+					send: makeSend(sends),
+					schedule: makeSchedule((taskName, timing, event) => ctx.session.schedule(taskName, timing, event))
+				}, ctx.event.payload);
+			} catch (error) {
+				if (!(error instanceof NonRetriableError)) throw error;
+				const payload = {
 					message: ctx.event.id,
-					...clearIndex === void 0 ? {} : { clearIndex }
+					event: eventName,
+					error: describeError(error)
 				};
-				return [...sends, {
-					type: ACTOR_STATE_EVENT,
+				return {
+					type: ACTOR_FAILED_EVENT,
 					payload
-				}];
+				};
 			}
-		};
+			const payload = {
+				state: draft,
+				event: eventName,
+				message: ctx.event.id,
+				...clearIndex === void 0 ? {} : { clearIndex }
+			};
+			return [...sends, {
+				type: ACTOR_STATE_EVENT,
+				payload
+			}];
+		});
 	}
 	const presenceEnabled = options.presence === true;
 	const contract = presenceEnabled ? internalContract({
@@ -233,9 +232,21 @@ function actor(options) {
 		name,
 		events
 	});
+	const serialTypes = [...serialRuns.keys()];
+	const concurrentTypes = [...concurrentRuns.keys()];
+	const consumers = [...serialTypes.length === 0 ? [] : [runtimeConsumer({
+		contract,
+		name: "a2.actor",
+		types: serialTypes,
+		lane: () => ACTOR_LANE
+	}).run((ctx) => serialRuns.get(ctx.event.type)(ctx))], ...concurrentTypes.length === 0 ? [] : [runtimeConsumer({
+		contract,
+		name: "a2.actor.concurrent",
+		types: concurrentTypes
+	}).run((ctx) => concurrentRuns.get(ctx.event.type)(ctx))]];
 	const server = createServer({
 		contract,
-		handlers,
+		consumers,
 		...options.store ? { store: options.store } : {},
 		...options.scheduler ? { scheduler: options.scheduler } : {},
 		...options.telemetry ? { telemetry: options.telemetry } : {}