experimental-a2 0.16.1 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,378 @@
 # Changelog
 
+## 0.18.0
+
+### Minor Changes
+
+- ba50c3e: `agent()` takes its loop as `harness`. The AI SDK's loop, one `streamText()` step per durable generation, is the default, `harness: { type: 'ai-sdk' }`, and its options move into it: `generation`, `generate`, `compaction`, and `messageMetadata` are no longer top-level `agent()` options, and passing one there throws a `TypeError`.
+
+  `model` is an AI Gateway model ID, or `ModelSettings` with one, under every harness: `agent()` no longer takes AI SDK provider model objects, and `HarnessModelSettings` is gone.
+
+  Run FX or Pi as the loop instead with `harness: fx()` from `experimental-a2/ai/fx` or `harness: pi({ sandbox })` from `experimental-a2/ai/pi`. Each model call the harness makes is one durable step, and each tool call an A2 tool call, so a crash resumes at the interrupted step without repeating finished model calls or tools.
+
+  A0 can run the AI SDK's, FX's, or Pi's loop: pick the harness in the composer before an app's first message.
+
+- f3762ef: Add `toolRecovery` to `agent()`, which per tool answers a call that a crash, a timeout, Stop, or Pause now may have cut short with an error result instead of running it again.
+- 2b409f0: Add `session.deadLetters()` and `session.redrive(index, { action })` to server sessions. List a session's dead-lettered events with their last error, then retry one with a fresh failure budget or skip it so its lane continues, in one atomic store operation that wakes the session like an append. Custom stores opt in with the optional `A2Store.deadLetters` and `A2Store.redrive` methods; every built-in store implements them. Redrives emit an `a2.redrive` span.
+
+### Patch Changes
+
+- 0df2721: Docs: the introduction now walks through a shared contract, the server, and the client, then links to handlers, state, history, and AI.
+- 3fc2253: Docs: the bundled `docs/` folder is reorganized into `contract/`, `server/`, `client/`, `agents/`, `actors/`, and `reference/`, and every page is shorter. The API reference is now one page per entry point group. Old paths such as `docs/guides/05-production.mdx` now live at their new homes, for example `docs/server/05-production.mdx`.
+- 90ffa58: The package description and README now say what A2 does: it syncs your immutable event log, from server to browser.
+
+## 0.17.0
+
+### Minor Changes
+
+- 7308a33: Serve an agent with `agent()` from `experimental-a2/ai/server` and use it in
+  React with `useAgent()` from the new `experimental-a2/ai/react`. Browsers no
+  longer need a contract: the AI protocol and `AIState` reducer are library code,
+  and `useAgent<typeof assistant>({ api, id, initial })` takes the agent's types
+  through a type-only import. `createAgentClient()` from the new
+  `experimental-a2/ai/client` covers pushes outside React.
+
+  `useAgent()` returns the session plus `messages`, `status`, an `indicator`
+  (`starting`, `thinking`, `compacting`, or `null`), and actions that fill in
+  protocol identities: `sendMessage`, `steer`, `stop`, `approve`, `deny`,
+  `respond`, `retry`, `pause`, `resume`, and `queue.edit`/`move`/`remove`/`sendNow`.
+  Actions return the same `PushResult` as `push()`.
+
+  `model` also accepts `ModelSettings`, `{ model, reasoning?, speed? }`, statically
+  or from a resolver, to choose the reasoning level and AI Gateway speed with the
+  model; both override `generation`. `reasoningLevels` lists the levels.
+
+  Compaction now appears in the transcript: the response gains a
+  `data-a2-compaction` part where its context was compacted, with its status,
+  summary, and usage. Render it with `isCompactionPart()`; `AIState` messages are
+  typed as `TranscriptMessage<M>`, so it narrows even with custom data parts. AI
+  SDK model conversion skips it.
+
+  `agent({ toolLane })` runs local tool executions one at a time on a lane.
+
+  Migration:
+
+  - `createAgentServer({ agent: definition, ... })` becomes
+    `agent({ name, ... })`, or `agent({ contract, ... })` with a shared contract.
+  - The isomorphic `agent()` becomes `agentContract()`, which returns a core
+    contract. Its `reducer` option folds application state beside the AI
+    protocol; it replaces `createReducer()` and `reducerName`.
+  - `createHandlers()` and `authorizeAgentIngress` are removed. Pass `handlers`
+    and `events` to `agent()`. Browsers push application events like any A2
+    client, narrowed by the route's `authorize`. Handlers for events `agent()`
+    already handles are rejected.
+  - `handlerContext(agent)` becomes `handlerContext()`, optionally
+    `handlerContext(contract)` to type application events.
+
+  The AI reducer identity advances to `a2.ai.state.v26`; with application state it
+  is `<name>+a2.ai.state.v26`.
+  Existing event logs remain the source for rebuilding those checkpoints.
+
+- 5ba57e5: Give agents your own events and state, and let them decide the model from it.
+  `agentContract({ events, reducer })` takes a core `contract()` reducer's
+  `name`, `initialState`, and `fold`; `fold` sees your state and every event,
+  never the transcript, and the session state is `AIState` merged with yours.
+
+  Every `agent({ contract })` resolver, and the compaction, metadata, and
+  custom-generation callbacks, receive that state as `state`. It rides in the
+  model-context checkpoint each model step already reads, so it adds no reads;
+  agents without application state keep their existing checkpoints. A `model`
+  resolver can return `{ model, reasoning, speed }` from it.
+
+  A resolver that throws, or returns an invalid value, now fails the turn once
+  with its message, like a provider error, instead of retrying the handler; the
+  attempt's `ai.generation.started` omits `model` when the model never resolved,
+  so `GenerationStartedPayload.model` is optional. `retry()` runs it again. Store
+  failures still retry durably.
+
+  `useAgent({ api, id, contract })`, or `useAgent({ client, id })` with that
+  contract's `createClient()`, folds a shared contract's state in the browser.
+  `agent({ contract })` takes only an `agentContract()`, so every agent's
+  resolvers receive `state`; any other contract throws. A fully custom contract
+  is core A2, served by `createServer()`.
+
+  A shared contract's application events follow core A2: browsers may push them,
+  and the route's `authorize` narrows who may push what. The agent still refuses
+  its own server-authored `ai.*` events, and events passed to
+  `agent({ name, events })` stay server-only.
+
+  Agents no longer handle `ai.message.completed`, `ai.message.interrupted`, or
+  `ai.generation.failed`, so apps can react to them with ordinary `handlers`.
+  The prompt cache those handlers evicted now keeps each session's latest step
+  in a bounded in-process cache, dropped when the step ends without tool calls.
+  A plain turn runs one fewer durable handler.
+
+- e779c74: Allow per-attempt generation settings resolvers for model calls, compaction, and tool approvals.
+
+  Add Thinking and Prefer fast controls to the Agent playground. Per-message preferences persist through queued turns, compaction, tool continuations, and reminders.
+
+- 707315a: `generate` and `messageMetadata` now receive the resolver context,
+  `{ event, messages, state, session, signal }`, plus what the step resolves:
+  `generationId`, `modelMessages`, and the resolved `model`, `instructions`,
+  `tools`, and `generation`. The triggering `ai.generation.requested` event is
+  `event`, as in every resolver, handler, and `handlerContext()`.
+
+  Migration: rename `request` to `event`, replace `requestId` with `event.id`, and
+  replace `responseMessageId` with `event.payload.responseMessageId`.
+
+- 862dfdb: Use `AIState` directly for AI reducers, server reads, hydration, and React.
+  Remove the public stored-state types and `view`/`fromView` conversion methods.
+  Checkpoint and subscription encoding remain internal. Reducer and client types
+  no longer distinguish stored state from view state.
+
+  Keep tool payloads in message parts and retain only identity and status in the
+  tool activity ledger. Current compaction metadata no longer repeats the model
+  context.
+
+  The AI and context reducer cache identities advance; existing event logs remain
+  the source for rebuilding those checkpoints.
+
+  Active-step recovery retains the original part count, text lengths, and
+  overwritten fields instead of another complete copy of the response. The step's
+  events remain available for exact interruption cutoffs and cold retries, and
+  recovery is released when the response closes. An extension that removes or
+  rewrites the streaming response releases that recovery instead of failing the
+  fold. Streaming updates copy only the
+  parts they change. The benchmark reports streaming, tool waiting, and completed
+  responses separately.
+
+  Export `authorizeAgentIngress` from `experimental-a2/ai/server`. Custom
+  `createServer()` assemblies pass it as `server.fetch(request, { authorize })`
+  to apply the same browser allowlist `createAgentServer()` installs.
+
+- 1987df0: Actors follow session clearing. After `handle.session.clear()`, snapshots,
+  call answers, and state commits carry `clearIndex`, and the live stream sends
+  the actor's initial state through the route's `view` as a reset, so
+  `useActor` drops older history. A delayed reset never replaces a newer
+  snapshot. A call whose message is cleared before it is answered rejects with
+  `SESSION_CLEARED`, which the route answers with `410` and the actor client
+  raises as an `ActorRequestError` with the `A2Error` as its `cause`. A message
+  that reuses the cleared call's id can't answer it.
+
+  `ActorCallResult` and `ActorSnapshot` gain an optional `clearIndex`; actors
+  that are never cleared return the same shapes as before.
+
+- 92de099: Support `session.clear()` in both Redis stores. A clear moves the session's log
+  aside in one step, drops its pending work, and writes the marker into a fresh
+  log, so every read, live feed, and cached state tail starts at the marker at
+  once. Deletion then drains the moved log in batches: event metadata, pins, lane
+  pointers, and the id keys that still name a deleted event, so an id reused after
+  a clear keeps its new owner.
+
+  Sessions that are never cleared send the same number of commands as before,
+  apart from one: a reducer's first snapshot write-back in a session records its
+  name in a `{prefix}:{session}:snap-reducers` set, so clearing can delete every
+  reducer's cached state without a key scan. This relies on the fresh `keyPrefix`
+  this release already requires; on a reused prefix, snapshots written by an
+  earlier version are left behind by a clear until their reducer writes again.
+
+  Upgrade every instance before clearing any session: an earlier version ignores
+  the clear boundary and can dispatch cleared events into the new lifetime.
+
+- eb3d6b6: Support `session.clear()` in the SQLite and Postgres stores. Both add an
+  `a2_clears` table (one row per cleared session) on their next schema setup; no
+  index is built over existing events. Clearing deletes old history in batches
+  that skip rows other transactions hold, so deletion never waits on or
+  deadlocks with foreground work. In Postgres, reusing an event id whose cleared
+  row another transaction still holds fails with the retryable
+  `STORE_UNAVAILABLE` instead of waiting, and snapshot write-back locks its head
+  row before the events it pins.
+
+  Upgrade every instance before clearing any session: an earlier version ignores
+  the clear boundary and can dispatch cleared events into the new lifetime.
+
+- 08de5d6: Add `session.clear({ ifLastIndex })`, which ends a session's current lifetime
+  without restarting its indexes. A clear appends a reserved marker in one atomic
+  step, supersedes every piece of work from the old lifetime, then deletes the old
+  history in bounded batches before it resolves. Pushes and appends after the
+  marker start the new lifetime. Every built-in store supports clearing.
+
+  `session.stream()` yields the marker as `SessionCleared`, whose `type` is
+  `'a2.cleared'`. `session.state()` returns
+  `clearIndex` once a session has been cleared, and the snapshot types, the
+  automatic subscription snapshot, and the HTTP history lane
+  (`a2-clear-index`) carry it, so clients reset and drop older history. A
+  handler whose event was cleared never folds the new lifetime: `state()`
+  throws `SESSION_CLEARED` once it reads past the clear.
+
+  Event types starting with `a2.` are now reserved for A2 and rejected by
+  `contract()`. Actors already reserved the prefix for their own events.
+
+- 1579995: Add `session.schedule.clear(name, { delay | at, ifLastIndex })`, a durable
+  conditional clear. Delivery runs `clear({ ifLastIndex })` and acknowledges
+  only after the old history is deleted, so a provider retry finishes an
+  interrupted deletion. A delivery whose condition no longer holds changes
+  nothing, and no event is appended. `deliverSchedulerClear` and the
+  `SchedulerClearTask` type are exported from `experimental-a2/server` for custom
+  scheduler adapters, and both built-in schedulers route clear tasks.
+
+  Appends scheduled by a handler now carry their triggering event's index as
+  `originIndex`. If the session is cleared before delivery, the task is
+  acknowledged without appending. Once a session has been cleared, handler task
+  ids include the clear, so a trigger id reused in the new lifetime schedules a
+  new task. Sessions that were never cleared derive the same task ids as before.
+
+  Upgrade every scheduler route before scheduling clears, and don't roll back
+  while clear tasks are pending. An earlier Vercel Queues route keeps failing a
+  clear task until retention ends; an earlier QStash route rejects it as
+  non-retryable, so QStash moves it to its dead-letter queue.
+
+- c2dd95f: Store AI generation progress in fewer bytes: 2.7 times fewer on a measured
+  tool-heavy agent session. `ai.generation.progress` payloads are
+  `{ startIndex, chunks }`: `startIndex` is the log index of the
+  generation's `ai.generation.started`, which replaces the request, input,
+  generation, and response ids and the `sequence` each batch used to repeat.
+  Adjacent text, reasoning, and tool-input deltas of one part are joined into a
+  single chunk before they are stored, and the joined batch projects exactly as
+  the separate chunks did.
+
+  `ActiveGeneration` gains `startIndex`. Reducers still read progress already in
+  a log, and history returns it in its original id-carrying shape. Upgrade
+  clients with the server: a client reducer from before this release ignores new
+  progress, so streamed output doesn't appear in that client until it reloads.
+  The AI reducer advances to `a2.ai.state.v26` and the model-context reducer to
+  `a2.ai.context.v6`, so their checkpoints rebuild from the log. No storage
+  operations, subscriptions, or timers are added.
+
+- fa5b816: Publish one optional reducer in a contract and bootstrap unseeded clients
+  with a snapshot on their existing SSE or WebSocket subscription. Keep
+  server-side reducers through `reducer({ contract, ... }).fold(...)`, the React
+  factory, raw events, and history access.
+
+  Clients bind the contract directly. Client sessions, React providers, and
+  hooks accept one optional initial state/index snapshot or its Promise. Cold
+  sessions wait for a supplied Promise before connecting; null results use
+  subscription bootstrap. React hooks can opt into Suspense for that Promise
+  with `suspend: true` without suspending automatic subscription bootstrap.
+  State starts from a supplied snapshot or the reducer's initial state, then
+  adopts the loaded snapshot atomically. Pending initial Promises show the
+  reducer seed unless the hook opts into Suspense. Pushes never wait for the
+  snapshot, and HTTP pushes do not wait for a pending initial Promise either;
+  WebSocket pushes wait for their connection, which opens once that Promise
+  settles. A push sent before the snapshot arrives stays out of the optimistic
+  view, along with pushes queued behind it, until its acknowledgement shows
+  whether the snapshot already contains it.
+
+  Multiplexed WebSocket subscribe entries carry a client `attempt` that the
+  server echoes on `subscribed` and `unsubscribed`, so a quick release and
+  re-subscribe (such as a StrictMode remount) ignores answers to the earlier
+  entry.
+
+  Preserve root `undefined` snapshots over SSE and WebSocket bootstrap without
+  conflating them with `null`.
+
+  Expose `hydrated` on client snapshots and React hook results. It distinguishes
+  the reducer seed from a known state/index baseline and remains true while that
+  baseline is retained during reconnects. It adds no I/O or connection ownership.
+
+- e779c74: Add Core claim/commit and `a2.ai.*` spans. `createAgentServer` shares telemetry
+  with its AI handlers; custom assemblies can pass it to `createHandlers`.
+  Custom recorders must support the new span names. Durations include nested work.
+- fb721f8: Fix Vercel scheduler callbacks without inline payloads by using one configured
+  QueueClient for sends, payload fetches, acknowledgements, and visibility changes.
+  Callback routing no longer depends on metadata inside the payload.
+
+  Replace `scheduledAppends` with `deploymentId?: string | null`, matching the Queue
+  SDK: omit it to use the current deployment, pass a deployment ID to target it,
+  or pass `null` for deploymentless delivery. The setting applies to all tasks,
+  including recovery drains. Publishing and consuming clients must use the same
+  deployment scope. Remove the fourth `QueueTransport.send` routing argument;
+  injected transports own their provider configuration.
+
+  Changing the setting does not move already queued tasks. Keep consumers in their
+  original scope until they finish. Unlike the former timer-only opt-out,
+  `deploymentId: null` also makes recovery deploymentless. Every eligible consumer
+  must use the same null setting and remain compatible with pending tasks and
+  session work; deploymentless delivery does not mean latest production.
+
+### Patch Changes
+
+- 3885f5e: Bound Redis append and completion retry reads to the retried batch. Retrying old
+  events no longer rereads the session's later history. Applies to both Redis
+  transports; existing idempotency and conflict checks are unchanged.
+- 05dbd13: Live events take about 80 fewer bytes each on the wire (18% for 256-byte payloads), and the client applies them in batches. The client asks for wire version 2 (`wire=2`) on SSE and WebSocket streams. In version 2, events the server's stream already holds, such as a Redis catch-up page, travel together in one frame, and the client folds each batch with one notification to listeners. Each event drops the `sessionId` its connection already names and sends `createdAt` as epoch milliseconds; a multiplexed socket names each batch's session once. Events reach application code unchanged, and older clients and servers keep working with version 1.
+- 430d1e3: Contracts with presence now get batched catch-up too. Their streams forward the events a Redis store already holds, so a replay goes out in batched frames with one client notification each, instead of one frame per event. Presence patches still arrive after the snapshot and stay reconciled by `seen`; a patch that arrives during a batch follows it.
+- a7e7491: Drain SQL streaming replay buffers in linear time, and let the memory adapter stream directly from its retained log without copying or spreading large histories. This fixes memory replay failures on large sessions and releases stream subscriptions if copying an event fails. Event ordering, resume positions, live delivery, and database query counts are unchanged.
+
+  Consumed payloads are released as they are delivered, and the buffer allocation is released with its final event, without waiting for another read or close. SQL still fetches the full unread backlog in each catch-up query.
+
+- 3f2a056: Fix Redis HTTP replay stalls when the provider returns only part of a backlog. Stream catch-up now requests bounded batches and continues immediately after nonempty replies, preserving incremental decoding and direct provider errors.
+- b55415a: Make Redis appends and completions one command cheaper by no longer reading the
+  shared event-id hash that releases before per-id ownership keys used; a streamed
+  AI progress batch now costs 7 billed commands instead of 8. A completion that
+  returns an event in its own lane also no longer rewrites that lane's pointers.
+  Use a fresh `keyPrefix` when upgrading.
+- 5c1317c: Cut the Redis commands each store operation issues. Upstash bills every call a
+  Lua script makes, so the scripts now read the counter, split, and event ids in
+  one request, batch metadata reads and writes, and skip calls that change
+  nothing. Appending a handled event and running its handler now costs 24 billed
+  commands instead of 52. Live streams no longer refresh a watched marker every
+  10 seconds, which halves an idle viewer's commands; every write now publishes
+  its wake-up instead of first checking for the marker. Applies to both Redis
+  transports.
+
+  During a rollout, writes from earlier deployments still check for the marker,
+  which new viewers no longer set, so those events reach new viewers on the
+  10-second safety read instead of immediately. Nothing is lost.
+
+- faaaff7: Store Redis event-id ownership in one key per id instead of one shared hash, so
+  long-lived deployments no longer hit provider per-key size limits as sessions
+  accumulate. Applies to both Redis transports.
+
+  This is a breaking storage change: the shared hash is no longer read, so switch
+  to a fresh `keyPrefix` when upgrading. On an existing prefix, ids recorded only
+  in the shared hash lose their ownership, and earlier versions cannot see ids
+  recorded after the upgrade, so a retry on either side can append a duplicate
+  event. Vercel Queues keeps running recovery and scheduled work on the deployment
+  that published it for up to 7 days, so do not roll back to an earlier version on
+  an upgraded prefix.
+
+- 8b5afc6: Replay Redis backlogs with much less CPU. Redis HTTP catch-up decodes the entries that complete in each response chunk with one `JSON.parse`, instead of scanning and parsing them one at a time, and hands them to the stream without an await per event. `server.fetch` writes the frames of events a Redis stream already holds together, in chunks of about 64 Ki characters plus the frame that crosses that size. Redis commands, SSE frames, event order, resume positions, and memory bounds are unchanged.
+- 8174d0d: Stream AI tokens as they arrive and stop re-reading the log on every wake-up.
+  Redis wake-up messages now carry the appended events, so live streams, including
+  the server's own stop watcher, apply them without reading; gaps, reconnects,
+  oversized batches, and the safety read still catch up from the log. A handler
+  appending only settled events no longer triggers a drain or a pending check. AI
+  progress batches now flush as soon as the previous write finishes
+  (`progress.maxDelayMs` defaults to 0 and `progress.maxChunks` to 128), so each
+  chunk is written as it arrives and chunks that arrive while a write is in flight
+  share the next one. In a measured agent turn, writing every token cost 3,737
+  Redis commands against 4,549 for the previous 30 ms batches, and a watching
+  browser added no reads.
+- cfeafec: Store Redis per-event metadata in hashes of 1,000 consecutive events instead of
+  one hash per session, so a long session's metadata no longer approaches
+  provider per-key size limits. Metadata recorded before the upgrade stays where
+  it is, and existing data needs no migration. Applies to both Redis transports.
+
+  The upgrade is one-way for a key prefix. Earlier versions read only the single
+  hash, so they cannot see metadata for events recorded after the upgrade and
+  could re-run handlers for in-flight events or stall lanes. Vercel Queues keeps
+  running recovery and scheduled work on the deployment that published it for up
+  to 7 days, so earlier deployments keep touching sessions after an upgrade.
+  Switch to a fresh `keyPrefix` when upgrading, or keep earlier deployments' work
+  away from upgraded sessions until it drains. Do not roll back to an earlier
+  version on an upgraded prefix.
+
+- 6fe0154: Write SSE frames for a Redis HTTP backlog around each event's stored payload JSON, without parsing and re-serializing it. `session.stream()` still yields parsed events, and the SSE bytes are unchanged.
+- 94b33b3: A TCP Redis store created from `url` decodes live feed catch-up pages with less work: it reads each `XRANGE` page as raw bytes and turns only the five values a row needs into strings, instead of all thirteen per event. Rows and SSE bytes are unchanged, and so are injected clients.
+- a55272b: TCP Redis live feeds catch up in pages of 1,000 events instead of 256, which cuts the billed `XRANGE` commands for a long backlog by about four. Their SSE frames also reuse each event's stored payload JSON. A catching-up TCP feed can hold up to 1,000 events in memory at once, up from 256.
+- 46fee5f: Stream Redis HTTP catch-up in one request by default, decoding events as the consumer pulls instead of materializing a full page. Closing the stream aborts its active catch-up request.
+
+  A delayed subscription-capability check cannot interrupt a channel that has already connected.
+
+  There is no new configuration or automatic fallback to smaller reads. Provider rejections, including response-size limits, surface as `STORE_UNAVAILABLE` with the provider's error message. Callers can consume bounded `history({ gte, lte })` ranges before opening `stream({ startAfter: lastIndex })` to reduce the unread range. Provider buffering remains outside A2's memory bound. An in-flight read can finish its captured pre-clear history before reaching the clear marker. History, state reads, TCP Redis, and subscription-free polling are unchanged.
+
+- e5c52b8: Keep reducer state in server memory between reads. Each server instance keeps
+  the latest state it folded per session and reducer, bounded to 1,000 entries and
+  roughly 32 MB. A handler read at its own trigger needs no store request. Other
+  reads fetch only the events after the cached one and check that event's id, so a
+  missing or rewritten log falls back to the store; on Redis that is one command
+  for up to 255 events, and longer tails read the stored snapshot. Snapshots are
+  written on cold reads, for handler retries, and every 128 events instead of
+  after nearly every read. On stores without the Redis fast path, warm reads call
+  `readHistory` (or `read`) instead of `readState`, and `a2.state` spans report
+  `a2.state.snapshot` as `memory`.
+
 ## 0.16.1
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # experimental-a2
 
-Durable sync and reactions for things with a lifecycle. Each session has an
+A2 syncs your immutable event log, from server to browser. Each session has an
 event log, derived state, handlers, timers, and a live client.
 
 ## Read the package

package/dist/{actor-ohPC-81x.d.ts → actor-Bjce9_5U.d.ts}

@@ -1,7 +1,7 @@
-import { h as StandardSchemaV1, i as Contract, s as EventDefs, t as Reducer } from "./reducer-otzHjuJj.js";
-import { t as A2Store } from "./store-DyZM6fS5.js";
-import { f as ScheduleTiming, m as Session, n as A2Server, t as A2Scheduler } from "./server-DbD7IJVK.js";
-import { i as A2Telemetry } from "./telemetry-B5jzpy6y.js";
+import { s as Contract, t as Reducer, u as EventDefs, v as StandardSchemaV1 } from "./reducer-CqA59Q6U.js";
+import { t as A2Store } from "./store-Djdv0bnZ.js";
+import { h as Session, n as A2Server, p as ScheduleTiming, t as A2Scheduler } from "./server-En7cbi3v.js";
+import { i as A2Telemetry } from "./telemetry-Cyfqo6Qt.js";
 //#region src/actor-shared.d.ts
 /**
  * A handler answered by throwing `NonRetriableError`: the event
@@ -128,6 +128,8 @@ type ActorStatePayload<S> = {
   event: string;
   /** The message (invocation event) id this state answers. */
   message: string;
+  /** The session's latest clear marker when this state was read. */
+  clearIndex?: number;
 };
 /** The event vocabulary a client needs to follow an actor's state. */
 type ActorClientEventDefs<S> = {
@@ -248,6 +250,11 @@ type ActorCallResult<S> = {
   state: S;
   /** Log index of the state commit that answered this message. */
   index: number;
+  /**
+   * The clear marker this state's lifetime began at, once the actor has been
+   * cleared. For a call answer it is the lifetime the handler read.
+   */
+  clearIndex?: number;
 };
 type CallMethod<D extends ActorProtocol, K extends keyof D["events"]> = {} extends D["events"][K] ? (input?: D["events"][K], options?: ActorCallOptions) => Promise<ActorCallResult<D["state"]>> : (input: D["events"][K], options?: ActorCallOptions) => Promise<ActorCallResult<D["state"]>>;
 type SendMethod<D extends ActorProtocol, K extends keyof D["events"]> = {} extends D["events"][K] ? (input?: D["events"][K], options?: ActorSendOptions) => Promise<{
@@ -262,8 +269,10 @@ type ActorHandle<D extends ActorProtocol> = {
   readonly id: string;
   /**
    * Send the event and await its answer: the state after the handler
-   * ran, or a rejection with `ActorRefusedError`. Serial events only —
-   * concurrent handlers produce no answer to await; `send` them.
+   * ran, or a rejection with `ActorRefusedError`. A clear before the call
+   * receives its answer rejects with `A2Error('SESSION_CLEARED')`. Serial
+   * events only — concurrent handlers produce no answer to await; `send`
+   * them.
    */
   readonly call: { readonly [K in keyof D["events"]]: CallMethod<D, K>; };
   /** Cast: validate, append the event durably, return without waiting. */
@@ -273,9 +282,10 @@ type ActorHandle<D extends ActorProtocol> = {
   /**
    * The managed door — the actor mirror of `server.fetch`, bound to
    * this instance. GET streams the state plane (`a2.actor.state`
-   * commits only, `?index` resume, heartbeat, deadline rotation);
-   * POST is the call lane `createActorClient` speaks (`{ event,
-   * input, messageId? }` → the answer, 409 for a refusal). Your route
+   * commits and clear resets, `?index` resume, heartbeat, deadline
+   * rotation); POST is the call lane `createActorClient` speaks
+   * (`{ event, input, messageId? }` → the answer, 409 for a refusal,
+   * 410 for a call cleared before its answer). Your route
    * authenticates and picks the instance; `authorize` sees every
    * operation. Custom endpoints are route code around this call.
    */
@@ -295,7 +305,7 @@ type ActorDefinition<D extends ActorProtocol> = {
   readonly contract: Contract<EventDefs>;
   /** The underlying A2 server — `server.fetch` mounts the full session wire. */
   readonly server: A2Server<EventDefs>;
-  /** The state fold — same identity as the client's follower fold. */
+  /** The state fold over commits; a clear resets it to the initial state. */
   readonly reducer: Reducer<ActorClientEventDefs<D["state"]>, D["state"]>;
   actor(id: string): ActorHandle<D>;
 };
@@ -307,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-ohPC-81x.d.ts.map
+//# sourceMappingURL=actor-Bjce9_5U.d.ts.map

package/dist/actor-Bjce9_5U.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-Bjce9_5U.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"}

package/dist/actor-client.d.ts

@@ -1,4 +1,4 @@
-import { n as ActorCallResult, v as ActorRefusedError } from "./actor-ohPC-81x.js";
+import { n as ActorCallResult, v as ActorRefusedError } from "./actor-Bjce9_5U.js";
 //#region src/actor-client.d.ts
 declare class ActorRequestError extends Error {
   readonly status: number | undefined;
@@ -27,10 +27,7 @@ type ActorStateOf<D extends AnyActorDefinition> = Awaited<ReturnType<HandleOf<D>
 type ActorClientCall<D extends AnyActorDefinition, View = ActorStateOf<D>> = { readonly [K in keyof HandleOf<D>["call"]]: HandleOf<D>["call"][K] extends ((...args: infer P) => Promise<{
   state: unknown;
   index: number;
-}>) ? (...args: P) => Promise<{
-  state: View;
-  index: number;
-}> : never; };
+}>) ? (...args: P) => Promise<ActorCallResult<View>> : never; };
 type ActorClient<D extends AnyActorDefinition, View = ActorStateOf<D>> = {
   /** Typed calls over POST — the response is the answer. */
   readonly call: ActorClientCall<D, View>;

package/dist/actor-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actor-client.d.ts","names":[],"sources":["../src/actor-client.ts"],"mappings":";;cAwBa,0BAA0B;WAC5B;EAET,YAAY,iBAAiB;IAAY;IAAiB;;;;KAQhD;EACV,MAAM;IACJ,SAAS;MAAU;MAAgB;;IACnC;;;KAIC,SAAS,UAAU,sBAAsB,WAAW;KAE7C,aAAa,UAAU,sBAAsB,QACvD,WAAW,SAAS;;;;;;KAQV,gBACV,UAAU,oBACV,OAAO,aAAa,kBAEV,WAAW,SAAS,aAAa,SAAS,WAAW,gBAC1D,YAAY,MACZ;EAAU;EAAgB;UACvB,MAAM,MAAM;EAAU,OAAO;EAAM;;KAIjC,YACV,UAAU,oBACV,OAAO,aAAa;;WAGX,MAAM,gBAAgB,GAAG;WACzB,aAAa,QAAQ,gBAAgB;;KAGpC,yBAAyB;;EAEnC;;EAEA,eAAe,WAAW;EAC1B,cAAc,UAAU,gBAAgB;;;;;;;;iBA4F1B,kBACd,UAAU,oBACV,OAAO,aAAa,IACpB,SAAS,yBAAyB,QAAQ,YAAY,GAAG"}
+{"version":3,"file":"actor-client.d.ts","names":[],"sources":["../src/actor-client.ts"],"mappings":";;cA0Ba,0BAA0B;WAC5B;EAET,YAAY,iBAAiB;IAAY;IAAiB;;;;KAQhD;EACV,MAAM;IACJ,SAAS;MAAU;MAAgB;;IACnC;;;KAIC,SAAS,UAAU,sBAAsB,WAAW;KAE7C,aAAa,UAAU,sBAAsB,QACvD,WAAW,SAAS;;;;;;KAQV,gBACV,UAAU,oBACV,OAAO,aAAa,kBAEV,WAAW,SAAS,aAAa,SAAS,WAAW,gBAC1D,YAAY,MACZ;EAAU;EAAgB;UACvB,MAAM,MAAM,QAAQ,gBAAgB;KAIlC,YACV,UAAU,oBACV,OAAO,aAAa;;WAGX,MAAM,gBAAgB,GAAG;WACzB,aAAa,QAAQ,gBAAgB;;KAGpC,yBAAyB;;EAEnC;;EAEA,eAAe,WAAW;EAC1B,cAAc,UAAU,gBAAgB;;;;;;;;iBAsG1B,kBACd,UAAU,oBACV,OAAO,aAAa,IACpB,SAAS,yBAAyB,QAAQ,YAAY,GAAG"}

package/dist/actor-client.js

@@ -1,4 +1,5 @@
-import { i as ActorRefusedError } from "./actor-shared-B5tJfzt-.js";
+import { i as A2Error } from "./session-clear-DGI4jTQ5.js";
+import { i as ActorRefusedError } from "./actor-shared-t7w8xIKP.js";
 //#region src/actor-client.ts
 /**
 * experimental-a2/actor/client — typed calls to an actor over HTTP.
@@ -8,7 +9,8 @@ import { i as ActorRefusedError } from "./actor-shared-B5tJfzt-.js";
 * `client.call` mirrors the server handle's `call` record over the
 * call lane `handle.fetch` serves — POST `{ event, input, messageId? }`
 * → the answer (post-state), a 409 refusal (revived as
-* `ActorRefusedError`), or a 400. Both ends of that wire are library
+* `ActorRefusedError`), a 410 for a call cleared before its answer
+* (an `ActorRequestError` whose `cause` is the `A2Error`), or a 400. Both ends of that wire are library
 * code: the types here are backed by `handle.fetch`, not by a
 * hand-written convention.
 *
@@ -40,7 +42,13 @@ const callOverWire = async (fetchImpl, api, event, input, options) => {
 	});
 	const body = await responseBody(response);
 	if (response.status === 409 && typeof body["error"] === "string") throw new ActorRefusedError(typeof body["event"] === "string" ? body["event"] : event, typeof body["messageId"] === "string" ? body["messageId"] : "", body["error"]);
-	if (!response.ok) throw new ActorRequestError(typeof body["error"] === "string" ? body["error"] : `actor call failed (${response.status})`, { status: response.status });
+	if (!response.ok) {
+		const message = typeof body["error"] === "string" ? body["error"] : `actor call failed (${response.status})`;
+		throw new ActorRequestError(message, {
+			status: response.status,
+			...response.status === 410 && body["code"] === "SESSION_CLEARED" ? { cause: new A2Error("SESSION_CLEARED", message) } : {}
+		});
+	}
 	return snapshotBody(body, response.status);
 };
 const requestOverWire = async (fetchImpl, api, init) => {
@@ -63,7 +71,8 @@ const responseBody = async (response) => {
 	}
 };
 const snapshotBody = (body, status) => {
-	if (!("state" in body) || !Number.isSafeInteger(body["index"]) || body["index"] < 0) throw new ActorRequestError("actor request returned an invalid snapshot", { status });
+	const clearIndex = body["clearIndex"];
+	if (!("state" in body) || !Number.isSafeInteger(body["index"]) || body["index"] < 0 || clearIndex !== void 0 && (!Number.isSafeInteger(clearIndex) || clearIndex < 1 || clearIndex > body["index"])) throw new ActorRequestError("actor request returned an invalid snapshot", { status });
 	return body;
 };
 /**

package/dist/actor-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"actor-client.js","names":[],"sources":["../src/actor-client.ts"],"sourcesContent":["/**\n * experimental-a2/actor/client — typed calls to an actor over HTTP.\n * Framework-agnostic: no React, no framework machinery; works in any\n * browser code and server-to-server.\n *\n * `client.call` mirrors the server handle's `call` record over the\n * call lane `handle.fetch` serves — POST `{ event, input, messageId? }`\n * → the answer (post-state), a 409 refusal (revived as\n * `ActorRefusedError`), or a 400. Both ends of that wire are library\n * code: the types here are backed by `handle.fetch`, not by a\n * hand-written convention.\n *\n * ```ts\n * import type { vault } from '@/app/vault/server' // type-only, erased\n * const client = createActorClient<typeof vault>({ api: `/vault/${id}` })\n * await client.call.withdraw({ amount: 60 }) // ActorRefusedError on refusal\n * ```\n */\n\nimport { ActorRefusedError } from './actor-shared.ts'\nimport type { ActorCallOptions, ActorCallResult } from './actor.ts'\n\nexport { ActorRefusedError }\n\nexport class ActorRequestError extends Error {\n  readonly status: number | undefined\n\n  constructor(message: string, options?: { status?: number; cause?: unknown }) {\n    super(message, { cause: options?.cause })\n    this.name = 'ActorRequestError'\n    this.status = options?.status\n  }\n}\n\n/** The loose shape of an `actor()` definition — carried type-only. */\nexport type AnyActorDefinition = {\n  actor(id: string): {\n    state(): Promise<{ state: unknown; index: number }>\n    call: object\n  }\n}\n\ntype HandleOf<D extends AnyActorDefinition> = ReturnType<D['actor']>\n\nexport type ActorStateOf<D extends AnyActorDefinition> = Awaited<\n  ReturnType<HandleOf<D>['state']>\n>['state']\n\n/**\n * The server handle's `call` record mirrored to the client, with\n * answers carrying `View` — the projected shape when the route mounts\n * `fetch(req, { view })`, the full state otherwise (the default).\n */\nexport type ActorClientCall<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  readonly [K in keyof HandleOf<D>['call']]: HandleOf<D>['call'][K] extends (\n    ...args: infer P\n  ) => Promise<{ state: unknown; index: number }>\n    ? (...args: P) => Promise<{ state: View; index: number }>\n    : never\n}\n\nexport type ActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  /** Typed calls over POST — the response is the answer. */\n  readonly call: ActorClientCall<D, View>\n  readonly state: () => Promise<ActorCallResult<View>>\n}\n\nexport type CreateActorClientOptions<View = unknown> = {\n  /** The route whose handler delegates to `handle.fetch` for this instance. */\n  api: string\n  /** Injectable transport (tests, custom auth headers). */\n  fetch?: typeof globalThis.fetch\n  onSnapshot?: (snapshot: ActorCallResult<View>) => void\n}\n\nconst CALL_TIMEOUT_MS = 30_000\n\nconst callOverWire = async (\n  fetchImpl: typeof globalThis.fetch,\n  api: string,\n  event: string,\n  input: unknown,\n  options?: ActorCallOptions,\n): Promise<ActorCallResult<unknown>> => {\n  const response = await requestOverWire(fetchImpl, api, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify({\n      event,\n      ...(input === undefined ? {} : { input }),\n      ...(options?.id === undefined ? {} : { messageId: options.id }),\n    }),\n    signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS),\n  })\n  const body = await responseBody(response)\n  if (response.status === 409 && typeof body['error'] === 'string') {\n    throw new ActorRefusedError(\n      typeof body['event'] === 'string' ? body['event'] : event,\n      typeof body['messageId'] === 'string' ? body['messageId'] : '',\n      body['error'],\n    )\n  }\n  if (!response.ok) {\n    const message =\n      typeof body['error'] === 'string'\n        ? body['error']\n        : `actor call failed (${response.status})`\n    throw new ActorRequestError(message, { status: response.status })\n  }\n  return snapshotBody(body, response.status)\n}\n\nconst requestOverWire = async (\n  fetchImpl: typeof globalThis.fetch,\n  api: string,\n  init: RequestInit,\n): Promise<Response> => {\n  try {\n    return await fetchImpl(api, init)\n  } catch (cause) {\n    throw new ActorRequestError('actor request did not receive a response', {\n      cause,\n    })\n  }\n}\n\nconst responseBody = async (\n  response: Response,\n): Promise<Record<string, unknown>> => {\n  try {\n    const body: unknown = await response.json()\n    if (!body || typeof body !== 'object' || Array.isArray(body))\n      throw new Error('invalid response')\n    return body as Record<string, unknown>\n  } catch (cause) {\n    throw new ActorRequestError('actor request returned an invalid response', {\n      status: response.status,\n      cause,\n    })\n  }\n}\n\nconst snapshotBody = (\n  body: Record<string, unknown>,\n  status: number,\n): ActorCallResult<unknown> => {\n  if (\n    !('state' in body) ||\n    !Number.isSafeInteger(body['index']) ||\n    (body['index'] as number) < 0\n  ) {\n    throw new ActorRequestError('actor request returned an invalid snapshot', {\n      status,\n    })\n  }\n  return body as ActorCallResult<unknown>\n}\n\n/**\n * A typed call surface for one actor instance's route. When the route\n * mounts a `view`, pass its shape as the second type argument so call\n * answers carry the projected state:\n * `createActorClient<typeof vault, PublicVault>({ api })`.\n */\nexport function createActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n>(options: CreateActorClientOptions<View>): ActorClient<D, View> {\n  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)\n  const adopt = (snapshot: ActorCallResult<unknown>): ActorCallResult<View> => {\n    const result = snapshot as ActorCallResult<View>\n    options.onSnapshot?.(result)\n    return result\n  }\n  const state = async (): Promise<ActorCallResult<View>> => {\n    const api = options.api.split('#')[0]!\n    const separator = api.includes('?') ? '&' : '?'\n    const response = await requestOverWire(\n      fetchImpl,\n      `${api}${separator}snapshot=1`,\n      {\n        cache: 'no-store',\n        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),\n      },\n    )\n    const body = await responseBody(response)\n    if (!response.ok) {\n      throw new ActorRequestError(\n        typeof body['error'] === 'string'\n          ? body['error']\n          : `actor state read failed (${response.status})`,\n        { status: response.status },\n      )\n    }\n    return adopt(snapshotBody(body, response.status))\n  }\n  const methods = new Map<\n    string,\n    (\n      input?: unknown,\n      callOptions?: ActorCallOptions,\n    ) => Promise<ActorCallResult<View>>\n  >()\n  const call = new Proxy(\n    {},\n    {\n      get: (_target, event) => {\n        if (typeof event !== 'string') return undefined\n        let method = methods.get(event)\n        if (!method) {\n          method = (input, callOptions) =>\n            callOverWire(\n              fetchImpl,\n              options.api,\n              event,\n              input,\n              callOptions,\n            ).then(adopt)\n          methods.set(event, method)\n        }\n        return method\n      },\n    },\n  ) as ActorClientCall<D, View>\n  return { call, state }\n}\n"],"mappings":"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"}
+{"version":3,"file":"actor-client.js","names":[],"sources":["../src/actor-client.ts"],"sourcesContent":["/**\n * experimental-a2/actor/client — typed calls to an actor over HTTP.\n * Framework-agnostic: no React, no framework machinery; works in any\n * browser code and server-to-server.\n *\n * `client.call` mirrors the server handle's `call` record over the\n * call lane `handle.fetch` serves — POST `{ event, input, messageId? }`\n * → the answer (post-state), a 409 refusal (revived as\n * `ActorRefusedError`), a 410 for a call cleared before its answer\n * (an `ActorRequestError` whose `cause` is the `A2Error`), or a 400. Both ends of that wire are library\n * code: the types here are backed by `handle.fetch`, not by a\n * hand-written convention.\n *\n * ```ts\n * import type { vault } from '@/app/vault/server' // type-only, erased\n * const client = createActorClient<typeof vault>({ api: `/vault/${id}` })\n * await client.call.withdraw({ amount: 60 }) // ActorRefusedError on refusal\n * ```\n */\n\nimport { ActorRefusedError } from './actor-shared.ts'\nimport type { ActorCallOptions, ActorCallResult } from './actor.ts'\nimport { A2Error } from './errors.ts'\n\nexport { ActorRefusedError }\n\nexport class ActorRequestError extends Error {\n  readonly status: number | undefined\n\n  constructor(message: string, options?: { status?: number; cause?: unknown }) {\n    super(message, { cause: options?.cause })\n    this.name = 'ActorRequestError'\n    this.status = options?.status\n  }\n}\n\n/** The loose shape of an `actor()` definition — carried type-only. */\nexport type AnyActorDefinition = {\n  actor(id: string): {\n    state(): Promise<{ state: unknown; index: number }>\n    call: object\n  }\n}\n\ntype HandleOf<D extends AnyActorDefinition> = ReturnType<D['actor']>\n\nexport type ActorStateOf<D extends AnyActorDefinition> = Awaited<\n  ReturnType<HandleOf<D>['state']>\n>['state']\n\n/**\n * The server handle's `call` record mirrored to the client, with\n * answers carrying `View` — the projected shape when the route mounts\n * `fetch(req, { view })`, the full state otherwise (the default).\n */\nexport type ActorClientCall<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  readonly [K in keyof HandleOf<D>['call']]: HandleOf<D>['call'][K] extends (\n    ...args: infer P\n  ) => Promise<{ state: unknown; index: number }>\n    ? (...args: P) => Promise<ActorCallResult<View>>\n    : never\n}\n\nexport type ActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  /** Typed calls over POST — the response is the answer. */\n  readonly call: ActorClientCall<D, View>\n  readonly state: () => Promise<ActorCallResult<View>>\n}\n\nexport type CreateActorClientOptions<View = unknown> = {\n  /** The route whose handler delegates to `handle.fetch` for this instance. */\n  api: string\n  /** Injectable transport (tests, custom auth headers). */\n  fetch?: typeof globalThis.fetch\n  onSnapshot?: (snapshot: ActorCallResult<View>) => void\n}\n\nconst CALL_TIMEOUT_MS = 30_000\n\nconst callOverWire = async (\n  fetchImpl: typeof globalThis.fetch,\n  api: string,\n  event: string,\n  input: unknown,\n  options?: ActorCallOptions,\n): Promise<ActorCallResult<unknown>> => {\n  const response = await requestOverWire(fetchImpl, api, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify({\n      event,\n      ...(input === undefined ? {} : { input }),\n      ...(options?.id === undefined ? {} : { messageId: options.id }),\n    }),\n    signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS),\n  })\n  const body = await responseBody(response)\n  if (response.status === 409 && typeof body['error'] === 'string') {\n    throw new ActorRefusedError(\n      typeof body['event'] === 'string' ? body['event'] : event,\n      typeof body['messageId'] === 'string' ? body['messageId'] : '',\n      body['error'],\n    )\n  }\n  if (!response.ok) {\n    const message =\n      typeof body['error'] === 'string'\n        ? body['error']\n        : `actor call failed (${response.status})`\n    throw new ActorRequestError(message, {\n      status: response.status,\n      ...(response.status === 410 && body['code'] === 'SESSION_CLEARED'\n        ? { cause: new A2Error('SESSION_CLEARED', message) }\n        : {}),\n    })\n  }\n  return snapshotBody(body, response.status)\n}\n\nconst requestOverWire = async (\n  fetchImpl: typeof globalThis.fetch,\n  api: string,\n  init: RequestInit,\n): Promise<Response> => {\n  try {\n    return await fetchImpl(api, init)\n  } catch (cause) {\n    throw new ActorRequestError('actor request did not receive a response', {\n      cause,\n    })\n  }\n}\n\nconst responseBody = async (\n  response: Response,\n): Promise<Record<string, unknown>> => {\n  try {\n    const body: unknown = await response.json()\n    if (!body || typeof body !== 'object' || Array.isArray(body))\n      throw new Error('invalid response')\n    return body as Record<string, unknown>\n  } catch (cause) {\n    throw new ActorRequestError('actor request returned an invalid response', {\n      status: response.status,\n      cause,\n    })\n  }\n}\n\nconst snapshotBody = (\n  body: Record<string, unknown>,\n  status: number,\n): ActorCallResult<unknown> => {\n  const clearIndex = body['clearIndex']\n  if (\n    !('state' in body) ||\n    !Number.isSafeInteger(body['index']) ||\n    (body['index'] as number) < 0 ||\n    (clearIndex !== undefined &&\n      (!Number.isSafeInteger(clearIndex) ||\n        (clearIndex as number) < 1 ||\n        (clearIndex as number) > (body['index'] as number)))\n  ) {\n    throw new ActorRequestError('actor request returned an invalid snapshot', {\n      status,\n    })\n  }\n  return body as ActorCallResult<unknown>\n}\n\n/**\n * A typed call surface for one actor instance's route. When the route\n * mounts a `view`, pass its shape as the second type argument so call\n * answers carry the projected state:\n * `createActorClient<typeof vault, PublicVault>({ api })`.\n */\nexport function createActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n>(options: CreateActorClientOptions<View>): ActorClient<D, View> {\n  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)\n  const adopt = (snapshot: ActorCallResult<unknown>): ActorCallResult<View> => {\n    const result = snapshot as ActorCallResult<View>\n    options.onSnapshot?.(result)\n    return result\n  }\n  const state = async (): Promise<ActorCallResult<View>> => {\n    const api = options.api.split('#')[0]!\n    const separator = api.includes('?') ? '&' : '?'\n    const response = await requestOverWire(\n      fetchImpl,\n      `${api}${separator}snapshot=1`,\n      {\n        cache: 'no-store',\n        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),\n      },\n    )\n    const body = await responseBody(response)\n    if (!response.ok) {\n      throw new ActorRequestError(\n        typeof body['error'] === 'string'\n          ? body['error']\n          : `actor state read failed (${response.status})`,\n        { status: response.status },\n      )\n    }\n    return adopt(snapshotBody(body, response.status))\n  }\n  const methods = new Map<\n    string,\n    (\n      input?: unknown,\n      callOptions?: ActorCallOptions,\n    ) => Promise<ActorCallResult<View>>\n  >()\n  const call = new Proxy(\n    {},\n    {\n      get: (_target, event) => {\n        if (typeof event !== 'string') return undefined\n        let method = methods.get(event)\n        if (!method) {\n          method = (input, callOptions) =>\n            callOverWire(\n              fetchImpl,\n              options.api,\n              event,\n              input,\n              callOptions,\n            ).then(adopt)\n          methods.set(event, method)\n        }\n        return method\n      },\n    },\n  ) as ActorClientCall<D, View>\n  return { call, state }\n}\n"],"mappings":"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"}

package/dist/actor-react.d.ts

@@ -1,12 +1,14 @@
-import { a as ContractEvent, s as EventDefs } from "./reducer-otzHjuJj.js";
-import { g as ActorPresenceValues, m as ActorPresenceMap } from "./actor-ohPC-81x.js";
+import { c as ContractEvent, u as EventDefs } from "./reducer-CqA59Q6U.js";
+import { g as ActorPresenceValues, m as ActorPresenceMap } from "./actor-Bjce9_5U.js";
 import { ActorClientCall, ActorStateOf, AnyActorDefinition } from "./actor-client.js";
-import { a as Connection } from "./client-CzyacQpJ.js";
+import { a as Connection } from "./client-h_DKFAjj.js";
 //#region src/actor-react.d.ts
 /** The server-to-client handoff: `await def.actor(id).state()`. */
 type ActorSnapshot<S> = {
   state: S;
   index: number;
+  /** The latest clear marker, once the actor has been cleared. */
+  clearIndex?: number;
 };
 type UseActorOptions<View> = {
   /** The route whose handler delegates to `handle.fetch` for this instance. */

package/dist/actor-react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actor-react.d.ts","names":[],"sources":["../src/actor-react.ts"],"mappings":";;;;;;KA8CY,cAAc;EAAO,OAAO;EAAG;;KAE/B,gBAAgB;;EAE1B;;EAEA;;EAEA,SAAS,cAAc;;EAEvB;;;KAIG,WAAW,UAAU,sBAAsB;EAC9C,iBAAiB;IAEf,YAAY;EAAa,gBAAgB;IACvC;KAIM,eAAe,UAAU,oBAAoB;;EAEvD,OAAO;;EAEP;EACA,YAAY;;EAEZ,MAAM,gBAAgB,GAAG;EACzB,eAAe,QAAQ,cAAc;;EAErC,QAAQ,cAAc;;;;;;;EAOtB,UAAU,iBAAiB,WAAW;;;;;EAKtC,cAAc,QAAQ,oBAAoB,WAAW;;;iBA2BvC,SAAS,UAAU,oBAAoB,OAAO,aAAa,IACzE,SAAS,gBAAgB,QACxB,eAAe,GAAG"}
+{"version":3,"file":"actor-react.d.ts","names":[],"sources":["../src/actor-react.ts"],"mappings":";;;;;;KAiDY,cAAc;EACxB,OAAO;EACP;;EAEA;;KAGU,gBAAgB;;EAE1B;;EAEA;;EAEA,SAAS,cAAc;;EAEvB;;;KAIG,WAAW,UAAU,sBAAsB;EAC9C,iBAAiB;IAEf,YAAY;EAAa,gBAAgB;IACvC;KAIM,eAAe,UAAU,oBAAoB;;EAEvD,OAAO;;EAEP;EACA,YAAY;;EAEZ,MAAM,gBAAgB,GAAG;EACzB,eAAe,QAAQ,cAAc;;EAErC,QAAQ,cAAc;;;;;;;EAOtB,UAAU,iBAAiB,WAAW;;;;;EAKtC,cAAc,QAAQ,oBAAoB,WAAW;;;iBAoCvC,SAAS,UAAU,oBAAoB,OAAO,aAAa,IACzE,SAAS,gBAAgB,QACxB,eAAe,GAAG"}