experimental-a2 0.20.0 → 0.22.0

package/src/store.ts

@@ -2,7 +2,7 @@
  * The A2Store interface — the storage contract every store backend
  * implements. See specs/a2-implementation.md §2–3.
  *
- * This is the whole storage contract: append, read, dispatch claims,
+ * This is the whole storage contract: append, read, consumer cursors,
  * failure markers, snapshots, and the live stream. The scheduler
  * needs nothing extra — the armed queue message is its own state, and
  * the store is the only thing it consults.
@@ -21,58 +21,102 @@ export type Event = {
   createdAt: Date
 }
 
-/** The handler dispatch whose append first persisted a child event. */
+/** The consumer attempt whose append first persisted a child event. */
 export type EventCause = {
+  consumer: string
+  /** The cursor's lane; null for a concurrent consumer's cursor of one event. */
+  lane: string | null
   index: number
   attempt: number
-  /** Size of one named handler append, used to reject truncated retries. */
+  /** Size of one named consumer append, used to reject truncated retries. */
   batchSize?: number
 }
 
-/**
- * What the store persists: immutable event history, including its causal edge,
- * plus derived dispatch and failure bookkeeping. The bookkeeping is disposable;
- * the event and its cause are not.
- */
+/** What the store persists: immutable event history and its causal edge. */
 export type StoredEvent = Event & {
-  /** Same-session handler dispatch that appended this event; null means root. */
+  /** Same-session consumer attempt that appended this event; null means root. */
   cause: EventCause | null
-  /** Session-scoped serial execution key resolved when the event is appended. */
+}
+
+/**
+ * Where a consumer's cursor stands on its head event. A cursor is one record
+ * per (session, consumer, lane): a log cursor for a consumer with one string
+ * lane, a lane cursor per lane for a lane function, and a cursor per event
+ * (lane null) for a concurrent consumer. Its attempt and failure fields
+ * describe the current head and reset when the cursor moves past it.
+ */
+export type HeadDispatch = {
+  consumer: string
   lane: string | null
-  /** Adapter clock time recorded by append settlement, completion, or manual skip; null while pending. */
-  processedAt: Date | null
-  /** Dispatch attempt that completed this event; null without dispatch or while pending. */
-  processedByAttempt: number | null
-  /** Exact ordered child ids atomically returned by the completing attempt. */
-  returnedEventIds: string[] | null
-  /** Adapter clock time recorded by the first durable dispatch claim. */
+  /** Adapter clock time recorded by the first durable claim of this head. */
   firstClaimedAt: Date | null
-  /** Adapter clock time recorded by the most recent durable dispatch claim. */
+  /** Adapter clock time recorded by the most recent durable claim of this head. */
   lastClaimedAt: Date | null
-  /** Durable dispatch claims, including claims abandoned by hard kills. */
+  /** Durable claims of this head, including claims abandoned by hard kills. */
   attemptCount: number
-  /** Current dispatch holder; null when the event is not claimed. */
+  /** Current holder; null when the head is not claimed. */
   claimHolder: string | null
   /**
-   * Adapter clock expiry for the current dispatch claim, or, with no holder,
-   * the end of a failed attempt's retry hold.
+   * Adapter clock expiry for the current claim, or, with no holder, the end
+   * of a failed attempt's retry hold.
    */
   claimExpiresAt: Date | null
   /**
-   * Failed attempts: caught handler failures, and lapsed claims a later claim
-   * took over. This alone drives dead-lettering.
+   * Failed attempts on this head: caught failures, and lapsed claims a later
+   * claim took over. This alone drives dead-lettering.
    */
   failureCount: number
-  /** Adapter clock time recorded by the most recent caught handler failure. */
+  /** Adapter clock time recorded by the most recent caught failure. */
   lastFailedAt: Date | null
-  /** Dispatch attempt that produced the most recent caught handler failure. */
+  /** Attempt that produced the most recent caught failure. */
   lastFailedAttempt: number | null
-  /** The last handler failure, stringified. */
+  /** The last failure, stringified. */
   lastError: string | null
   /** Adapter clock time recorded when dead-lettered; null otherwise. */
   failedAt: Date | null
-  /** Latest clear marker, on claimed events of a cleared session. */
-  clearIndex?: number
+}
+
+/** Where one cursor stands: its position, its head, and the head's dispatch state. */
+export type StoredCursor = HeadDispatch & {
+  /** The last index this cursor finished; a log cursor counts from the latest clear marker. */
+  position: number
+  /** The event it runs next; null when it has nothing to run. */
+  head: number | null
+}
+
+/** A cursor's head event together with its dispatch state. */
+export type HeadEvent = StoredEvent &
+  HeadDispatch & {
+    /** Latest clear marker, on claimed heads of a cleared session. */
+    clearIndex?: number
+  }
+
+/** Names one cursor head: the consumer, its lane, and the head's index. */
+export type HeadRef = {
+  consumer: string
+  lane: string | null
+  index: number
+}
+
+/**
+ * A consumer the caller serves. Work for consumers it does not name is
+ * neither pending nor claimed, so a removed consumer's cursors wait for its
+ * name to return.
+ */
+export type StoreConsumer = {
+  name: string
+  /**
+   * Set for a consumer with one string lane. Its cursor keeps one position
+   * over the log and runs the next event whose type is in `types` (null:
+   * every type). A missing cursor is created by the first append that
+   * carries one of those types: at the start of the log with `backfill`,
+   * otherwise just before that append.
+   */
+  log?: {
+    lane: string
+    types: readonly string[] | null
+    backfill: boolean
+  }
 }
 
 /**
@@ -106,8 +150,8 @@ export type StoreStateRead = {
 export type StoreSnapshotWrite = {
   index: number
   state: unknown
-  /** Unfinished trigger events that durably retain this exact checkpoint. */
-  pinEventIndexes?: readonly number[]
+  /** Unfinished cursor heads that durably retain this exact checkpoint. */
+  pins?: readonly HeadRef[]
 }
 
 export type StoreStateReadRequest = {
@@ -115,9 +159,15 @@ export type StoreStateReadRequest = {
   throughIndex?: number
   snapshotThroughIndex?: number
 }
-/** The result of atomically claiming every currently eligible event. */
+
+/** The result of atomically claiming every currently eligible head. */
 export type StoreClaimAvailableResult =
-  | { outcome: 'claimed'; events: StoredEvent[] }
+  | {
+      outcome: 'claimed'
+      events: HeadEvent[]
+      /** The session's head when the claim was made: how far behind each event is. */
+      head?: number
+    }
   | { outcome: 'busy'; retryAt: Date }
   | { outcome: 'settled' }
 
@@ -125,48 +175,61 @@ export type StoreClaimAvailableResult =
 export type CompleteAttemptResult =
   { outcome: 'completed'; events: StoredEvent[] } | { outcome: 'superseded' }
 
-/** The result of one claim-renewal heartbeat, both lists in append order. */
+/** The result of one claim-renewal heartbeat, both lists in head order. */
 export type RenewClaimsResult = {
   /** Listed claims that remain owned by the holder. */
-  renewed: number[]
-  /** Listed claims whose event a newer attempt has durably taken. */
-  superseded: number[]
+  renewed: HeadRef[]
+  /** Listed claims a newer attempt has durably taken, or whose cursor moved on. */
+  superseded: HeadRef[]
 }
 
-/** The result of atomically recording a caught handler failure. */
+/** The result of atomically recording a caught failure. */
 export type FailAttemptResult = {
   outcome: 'failed' | 'dead_lettered' | 'superseded'
   failureCount: number
 }
 
+/** A consumer an appended event starts work for, with its resolved lane. */
+export type EventTarget = {
+  consumer: string
+  /** The lane a lane function resolved; null runs the event concurrently. */
+  lane: string | null
+}
+
 /** Input to `A2Store.append` — already validated by the machine. */
 export type AppendEvent = {
   type: string
   payload: unknown
   /** Caller-supplied idempotency key; generated when absent. */
   id?: string
-  /** Internal causal edge supplied atomically by handler `session.append`. */
+  /** Internal causal edge supplied atomically by consumer `session.append`. */
   cause?: EventCause
-  /** Session-scoped serial execution key resolved before persistence. */
-  lane?: string
-  /** Internal hint: settle this event in the append transaction; no handler is registered. */
-  settled?: true
+  /**
+   * Lane-function and concurrent consumers this event starts work for,
+   * resolved before persistence. Log-cursor consumers are matched by type
+   * from `StoreConsumer.log` instead.
+   */
+  targets?: readonly EventTarget[]
 }
 
-/** A handler-returned event with the deterministic id retries require. */
+/** A consumer-returned event with the deterministic id retries require. */
 export type ReturnedEvent = AppendEvent & { id: string }
 
 /** The rows written by an append and the session's pending state. */
 export type StoreAppendResult = {
   events: StoredEvent[]
-  /** Whether the session contains an event without a completion marker. */
+  /**
+   * Whether a served consumer has a live head in this session: one that is
+   * not dead-lettered. An append whose own batch starts work for a served
+   * consumer may report true without checking that work is runnable.
+   */
   hasPending: boolean
 }
 
 export type StoreClearOptions = {
   sessionId: string
   ifLastIndex?: number
-  /** The clearing handler's dispatch, fenced like a handler append. */
+  /** The clearing consumer's attempt, fenced like a consumer append. */
   cause?: EventCause
 }
 
@@ -182,15 +245,17 @@ export type StoreReclaimResult = { deleted: number; done: boolean }
 
 export type StoreRedriveOptions = {
   sessionId: string
+  consumer: string
   index: number
-  /** `retry` clears the dead letter; `skip` settles it without a handler. */
+  /** `retry` clears the dead letter; `skip` moves the cursor past it. */
   action: 'retry' | 'skip'
+  consumers?: readonly StoreConsumer[]
 }
 
 export type StoreRedriveResult = {
-  /** Whether the event was dead-lettered and this operation resolved it. */
+  /** Whether the head was dead-lettered and this operation resolved it. */
   redriven: boolean
-  /** Whether the session contains an event without a completion marker. */
+  /** Whether a served consumer has a live head in this session: one that is not dead-lettered. */
   hasPending: boolean
 }
 
@@ -212,6 +277,20 @@ export const SYSTEM_CLOCK: Clock = {
 
 export const RANDOM_IDS: IdSource = () => crypto.randomUUID()
 
+/**
+ * Cursor rules every operation shares:
+ *
+ * - `consumers` names the consumers the caller serves. Omitted, every cursor
+ *   counts and no log cursor is created or advanced by type.
+ * - A cursor's head is the next event it runs: the lowest unfinished event of
+ *   its lane, the event itself for a concurrent cursor, or for a log cursor
+ *   the next event after its position whose type it takes. The clear marker
+ *   is never a head.
+ * - A head is eligible when no live claim or retry hold owns it, it is not
+ *   dead-lettered, and it lies above the latest clear marker.
+ * - Moving a cursor past its head resets the head's attempt and failure
+ *   fields and releases snapshot pins on it.
+ */
 export interface A2Store {
   /**
    * Accepts a batch; the batch is atomic — one transaction, consecutive
@@ -221,18 +300,26 @@ export interface A2Store {
    * lost — return the existing rows as success. If only *some* ids
    * exist, the caller mixed an already-sent batch with fresh events —
    * always a caller bug — so throw `A2Error('PARTIAL_DUPLICATE_BATCH')`.
-   * Events carrying `settled: true` get `processedAt` in this same atomic
-   * operation, with no dispatch claim or `processedByAttempt`. The result's
-   * `hasPending` reflects the whole session in the same atomic operation,
-   * including older events and idempotent retries.
+   * Ids are unique per session: the same id in another session names a
+   * different event and plays no part in these checks.
+   *
+   * In the same atomic operation, each event's `targets` start cursor work:
+   * a lane target queues the event in that consumer's lane, a null lane
+   * creates a cursor for that event alone. Each log consumer in `consumers`
+   * whose types the batch carries gets its cursor created or, when idle, a
+   * head: the next event after its position that it takes, which may
+   * precede the batch when an appender that doesn't serve it wrote in
+   * between. `hasPending` reflects the whole session for the served consumers,
+   * including older work and idempotent retries.
    *
-   * An event carrying `cause` is a handler append, fenced by attempt
-   * currency: accept it only while `cause.attempt` is still the parent
-   * event's latest attempt and the parent is not dead-lettered; otherwise
-   * throw `A2Error('SUPERSEDED_ATTEMPT')` and write nothing. The check is
-   * part of this atomic operation and must serialize against a concurrent
-   * `claimAvailable` — an unlocked read of the parent admits write skew.
-   * The idempotent-replay path runs first, so a batch whose ids all exist
+   * An event carrying `cause` is a consumer append, fenced by attempt
+   * currency: accept it only while the cause's cursor still has
+   * `cause.index` as its head, `cause.attempt` is that head's latest
+   * attempt, and the head is not dead-lettered; otherwise throw
+   * `A2Error('SUPERSEDED_ATTEMPT')` and write nothing. The check is part of
+   * this atomic operation and must serialize against a concurrent
+   * `claimAvailable` — an unlocked read of the cursor admits write skew. The
+   * idempotent-replay path runs first, so a batch whose ids all exist
    * replays regardless of the current attempt.
    *
    * Clearing stores (a2-implementation.md §17.2) fence one level earlier:
@@ -243,118 +330,162 @@ export interface A2Store {
   append(
     sessionId: string,
     events: AppendEvent[],
-    options?: { originIndex?: number },
+    options?: {
+      originIndex?: number
+      consumers?: readonly StoreConsumer[]
+    },
   ): Promise<StoreAppendResult>
 
   /**
    * Optional with `reclaim`. Serialized with `append`: checks
    * `ifLastIndex` against the head and the latest marker, then appends a
-   * settled clear marker at the next index without touching existing
-   * rows. Afterwards every event at or below the marker is superseded.
+   * clear marker at the next index without touching existing rows.
+   * Afterwards every event at or below the marker is superseded: no head
+   * lies there, and every log cursor's position counts from the marker.
    */
   clear?(options: StoreClearOptions): Promise<StoreClearResult>
 
   /**
    * Deletes one bounded batch of rows below the latest clear marker, with
-   * their bookkeeping, id records, and cached folds. `done` once nothing
+   * their cursor records, id records, and cached folds. `done` once nothing
    * remains below it. Never waits on a lock that other operations hold.
    */
   reclaim?(sessionId: string): Promise<StoreReclaimResult>
 
   /**
-   * Optional with `redrive`. The session's dead-lettered events above the
-   * latest clear marker, oldest first.
+   * Optional with `redrive`. The session's dead-lettered heads above the
+   * latest clear marker, in event order, then by consumer name.
    */
-  deadLetters?(sessionId: string): Promise<StoredEvent[]>
+  deadLetters?(sessionId: string): Promise<HeadEvent[]>
 
   /**
-   * Optional with `deadLetters`. Atomically resolves one dead-lettered event
-   * above the latest clear marker; any other event is untouched and reports
-   * `redriven: false`. `retry` clears `failedAt` and `failureCount`, so the
-   * event is claimable again with a fresh failure budget, keeping its claim
-   * history and last failure. `skip` records `processedAt` with no
-   * `processedByAttempt` or `returnedEventIds` and exposes the next event in
-   * its lane. Both serialize with `claimAvailable` and the handler-append
-   * parent fence; `skip` also serializes with lane promotion in `append` and
-   * `completeAttempt`. `hasPending` is read in the same step.
+   * Optional with `deadLetters`. Atomically resolves the consumer's
+   * dead-lettered head at `index` above the latest clear marker; anything
+   * else is untouched and reports `redriven: false`. `retry` clears
+   * `failedAt` and `failureCount`, so the head is claimable again with a
+   * fresh failure budget, keeping its claim history and last failure. `skip`
+   * moves the cursor past the head with no completion. Both serialize with
+   * `claimAvailable` and the consumer-append fence. `hasPending` is read in
+   * the same step.
    */
   redrive?(options: StoreRedriveOptions): Promise<StoreRedriveResult>
 
+  /**
+   * Brings one log consumer's cursor up to date without an append, for
+   * `session.consume()`. A missing cursor is created: with `backfill`, at
+   * the latest clear marker, taking the first event of its types after it;
+   * otherwise at the head, with nothing to run. When the session has nothing
+   * after its latest clear (or was never written), a missing cursor stays
+   * missing: nothing is written, and the cursor comes back idle at the
+   * marker, so a consume of an unknown session leaves no trace. That is
+   * exact with `backfill`; without it, the consumer starts at the first
+   * consume or serving append that finds events. An
+   * idle cursor takes the next event of its types after its position, so it
+   * finds events appended by deployments that don't serve it. A cursor with
+   * a head, claimed or not, is left as it is. Records the consumer's types,
+   * as an append would, and returns the cursor and the session's head.
+   */
+  wakeLog(options: {
+    sessionId: string
+    consumer: StoreConsumer & { log: NonNullable<StoreConsumer['log']> }
+  }): Promise<{ cursor: StoredCursor; head: number }>
+
+  /**
+   * The session's cursors: every log and lane cursor, and every concurrent
+   * cursor that still has a head, by consumer, then lane (concurrent cursors
+   * last, by head). Lane and concurrent cursors whose work lies at or below
+   * the latest clear marker are not listed.
+   */
+  cursors(sessionId: string): Promise<StoredCursor[]>
+
   /** Events for one session, oldest first. Bounds form `(afterIndex, throughIndex]`. */
   read(
     sessionId: string,
     opts?: { afterIndex?: number; throughIndex?: number },
   ): Promise<StoredEvent[]>
 
-  /** Public history without dispatch metadata; core falls back to read when absent. */
+  /** Public history without causal edges; core falls back to read when absent. */
   readHistory?(
     sessionId: string,
     opts?: { afterIndex?: number; throughIndex?: number },
   ): Promise<Event[]>
 
   /**
-   * Atomically claims every eligible pending event. Unlaned events are all
-   * independently eligible. Within a lane, only the lowest-index unfinished
-   * event is eligible. A live claim produces `busy` only when it is the sole
-   * remaining obstacle to actionable work. Claimed events are returned in event-log
-   * order. Excluded rows remain lane barriers.
+   * Atomically claims every eligible head of the served consumers. A live
+   * claim or retry hold produces `busy` only when it is the sole remaining
+   * obstacle to actionable work. Claimed heads are returned in event order,
+   * then by consumer name. Excluded heads stay unclaimed and keep blocking
+   * their lane.
    */
   claimAvailable(options: {
     sessionId: string
     holder: string
     ttlMs: number
     expiresAtMs?: number
-    excludeIndexes?: readonly number[]
+    exclude?: readonly HeadRef[]
+    consumers?: readonly StoreConsumer[]
     /**
      * Taking over a lapsed claim (one whose holder is still recorded, never
      * completed or failed) adds one to `failureCount`. When that reaches
-     * `maxFailures`, the event dead-letters instead of being claimed: it
+     * `maxFailures`, the head dead-letters instead of being claimed: it
      * comes back in `events` with `failedAt` set and no claim. Its
      * `attemptCount` still advances, fencing the lapsed attempt, and its
      * `lastFailedAttempt` is unchanged.
      */
     maxFailures?: number
+    /**
+     * Claims only heads at or below this index: a head past it is neither
+     * claimed nor reported `busy`, and stays claimable without it.
+     */
+    through?: number
   }): Promise<StoreClaimAvailableResult>
 
   /**
    * Renews the listed live claims still owned by `holder`. Each listed claim
-   * carries the attempt ordinal the holder owns. `renewed` lists the claims
-   * that remain owned after the operation; `superseded` lists the claims
-   * whose event's `attemptCount` has durably passed the listed attempt. An
-   * expired claim no successor has taken appears in neither list — its
+   * carries the attempt the holder owns. `renewed` lists the claims that
+   * remain owned after the operation; `superseded` lists the claims whose
+   * head a newer attempt has durably taken, or whose cursor has moved past
+   * it. An expired claim no successor has taken appears in neither list — its
    * attempt may still complete (`completeAttempt` is the fence), so it is
    * not reported as lost. Renewal never revives an expired claim.
    */
   renewClaims(options: {
     sessionId: string
     holder: string
-    claims: readonly { index: number; attempt: number }[]
+    claims: readonly (HeadRef & { attempt: number })[]
     ttlMs: number
     expiresAtMs?: number
   }): Promise<RenewClaimsResult>
 
   /**
-   * Atomically completes one current attempt and appends its returned events.
-   * Retrying a committed completion with the same attempt and deterministic
-   * child ids returns the existing children. A stale attempt never appends.
+   * Atomically completes one current attempt: appends its returned events
+   * (with their own targets, waking the served log consumers) and moves the
+   * cursor past its head. Retrying a committed completion with the same
+   * attempt and deterministic child ids returns the existing children. A
+   * stale attempt never appends.
    */
   completeAttempt(options: {
     sessionId: string
+    consumer: string
+    lane: string | null
     index: number
     attempt: number
     events: ReturnedEvent[]
+    consumers?: readonly StoreConsumer[]
   }): Promise<CompleteAttemptResult>
 
   /**
    * Atomically records a caught failure for one claimed attempt. A stale
-   * attempt cannot poison a processed event or a newer dispatch. Accepted
+   * attempt cannot poison a finished head or a newer attempt. Accepted
    * failures record the operation's clock time. A failure that does not
-   * dead-letter releases the claim and, with `retryAfterMs`, keeps the event
+   * dead-letter releases the claim and, with `retryAfterMs`, keeps the head
    * unclaimable for that long: its claim expiry is set with no holder, so
    * `claimAvailable` reports it `busy` until then.
    */
   failAttempt(options: {
     sessionId: string
+    consumer: string
+    lane: string | null
     index: number
     attempt: number
     error: string
@@ -389,9 +520,10 @@ export interface A2Store {
 
   /**
    * Atomically writes disposable reducer checkpoints. The greatest index
-   * advances the head cache. Older checkpoints survive only when at least one
-   * listed trigger event is still unfinished; completion and dead-lettering
-   * release that event's pins and collect unreferenced historical checkpoints.
+   * advances the head cache. Older checkpoints survive only while at least
+   * one listed cursor head is still unfinished; moving that cursor past it
+   * or dead-lettering it releases the pin and collects unreferenced
+   * historical checkpoints.
    */
   putSnapshots(
     sessionId: string,
@@ -408,11 +540,15 @@ export interface A2Store {
   presence?: {
     /**
      * Field-wise last-writer-wins merge of one participant's values:
-     * a field whose existing row has a strictly newer `at` (the
-     * sender's stamp) is left untouched; `null` deletes the row. Every
-     * applied write refreshes that field's expiry to the storage's own
+     * a field whose unexpired entry has a strictly newer `at` (the
+     * sender's stamp) is left untouched. `null` deletes the value but
+     * keeps a tombstone with its `at`, which takes part in the merge
+     * like a value until it expires, so a set older than the delete
+     * still loses when it arrives later. Every applied write, value or
+     * tombstone, refreshes that field's expiry to the storage's own
      * clock plus `ttlMs` — the sender stamp orders writes but never
-     * anchors their lifetime.
+     * anchors their lifetime. `subscribe` delivers applied writes only,
+     * a delete as `null`.
      */
     set(
       ns: string,
@@ -421,7 +557,10 @@ export interface A2Store {
       meta: { seen: number; at: Date; ttlMs: number },
     ): Promise<void>
 
-    /** The current map, pruned of rows at or past their `expiresAt`. */
+    /**
+     * The current map, pruned of rows at or past their `expiresAt`.
+     * Tombstones never appear.
+     */
     read(ns: string): Promise<PresenceRow[]>
 
     /**

package/src/telemetry.ts

@@ -18,6 +18,7 @@ export type A2SpanName =
   | 'a2.state'
   | 'a2.snapshot'
   | 'a2.redrive'
+  | 'a2.consume'
   | 'a2.ai.control'
   | 'a2.ai.ack'
   | 'a2.ai.generate'
@@ -30,7 +31,7 @@ export type A2SpanHandle = {
   setAttribute(key: string, value: A2AttributeValue): void
   /**
    * Mark the span failed without a2's control flow throwing — used for
-   * handler failures, which a2 swallows by design (they go into the
+   * consumer failures, which a2 swallows by design (they go into the
    * retry machinery, not up the stack) but telemetry must still see.
    */
   recordError(error: unknown): void

package/src/wire.ts

@@ -314,6 +314,7 @@ const ERROR_STATUS: Record<A2ServerErrorCode, number> = {
   STORE_NOT_CONFIGURED: 500,
   UNKNOWN_PRESENCE_FIELD: 400,
   PRESENCE_NOT_SUPPORTED: 500,
+  CONSUMER_DEAD_LETTERED: 500,
 }
 
 export function errorStatus(code: A2ErrorCode): number {

package/dist/actor-C7b-1arn.d.ts.map

@@ -1 +0,0 @@
-{"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"}

package/dist/actor-shared-t7w8xIKP.js.map

@@ -1 +0,0 @@
-{"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":";;;;;;;;;;;;;;;AAmBA,MAAa,oBAAoB;;AAEjC,MAAa,qBAAqB;;AAElC,MAAa,aAAa;;AAE1B,MAAa,qBAAqB;;;;;;;AAQlC,IAAa,oBAAb,cAAuC,MAAM;;CAE3C;;CAEA;CACA,YAAY,OAAe,WAAmB,SAAiB;EAC7D,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,YAAY;CACnB;AACF;AAkJA,MAAM,SAAY,aAAsC,EACtD,QAAQ,CAAC,EAAE,QAAQ,CAAC,EACtB;AAEA,MAAM,UACJ,OACA,WACyB,EACzB,aAAa;CACX,SAAS;CACT,QAAQ;CACR,SAAS,OAAO;EACd,IAAI;GACF,OAAO,MAAM,KAAK;EACpB,SAAS,OAAO;GACd,OAAO,MACL,GAAG,MAAM,IAAI,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GACpE;EACF;CACF;AACF,EACF;AAEA,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;;AAGrE,SAAgB,WACd,OACA,uBAAoB,IAAI,IAAI,GACnB;CACT,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAO,UAAU,WAEjB,OAAO;CAET,IAAI,OAAO,UAAU,UAAU,OAAO,OAAO,SAAS,KAAK;CAC3D,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,KAAK,IAAI,KAAK,GAAG,OAAO;CAC5B,KAAK,IAAI,KAAK;CACd,MAAM,QAAQ,MAAM,QAAQ,KAAK,IAC7B,MAAM,OAAO,SAAS,WAAW,MAAM,IAAI,CAAC,IAC5C,OAAO,eAAe,KAAK,MAAM,OAAO,aACxC,OAAO,OAAO,KAAK,CAAC,CAAC,OAClB,SAAS,SAAS,KAAA,KAAa,WAAW,MAAM,IAAI,CACvD;CACJ,KAAK,OAAO,KAAK;CACjB,OAAO;AACT;;AAGA,MAAa,2BAA2B;;;;;;;;AASxC,MAAa,mBAET,OAAO,OAAO,EAChB,KAAK,EACH,aAAa;CACX,SAAS;CACT,QAAQ;CACR,WAAW,UAAmB;EAC5B,IAAI,CAAC,WAAW,KAAK,GACnB,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,2CAA2C,CAAC,EAClE;EAEF,IAAI,KAAK,UAAU,KAAK,CAAC,CAAC,SAAA,MACxB,OAAO,EACL,QAAQ,CACN,EACE,SAAS,iCAAiC,yBAAyB,QACrE,CACF,EACF;EAEF,OAAO,EAAE,MAAM;CACjB;AACF,EACF,EACF,CAAC;;;;;;AAOD,SAAgB,mBAA8D;CAC5E,OAAO,OAAO,oBAAoB,UAAU;EAC1C,IACE,CAAC,SAAS,KAAK,KACf,OAAO,MAAM,aAAa,YAC1B,OAAO,MAAM,eAAe,UAE5B,OAAO,MAAM,WAAW,kBAAkB,SAAS;EAErD,MAAM,QAAQ,MAAM;EACpB,IAAI,CAAC,WAAW,KAAK,GACnB,OAAO,MAAM,2CAA2C;EAE1D,MAAM,aAAa,MAAM;EACzB,IACE,eAAe,KAAA,MACd,CAAC,OAAO,cAAc,UAAU,KAAM,aAAwB,IAE/D,OAAO,MAAM,sDAAsD;EAErE,OAAO,EACL,OAAO;GACE;GACP,OAAO,MAAM;GACb,SAAS,MAAM;GACf,GAAI,eAAe,KAAA,IACf,CAAC,IACD,EAAc,WAAqB;EACzC,EACF;CACF,CAAC;AACH;AAEA,MAAa,oBAA0D,OACrE,qBACC,UAAU;CACT,IACE,CAAC,SAAS,KAAK,KACf,OAAO,MAAM,eAAe,YAC5B,OAAO,MAAM,aAAa,YAC1B,OAAO,MAAM,aAAa,UAE1B,OAAO,MAAM,WAAW,mBAAmB,SAAS;CAEtD,OAAO,EACL,OAAO;EACL,SAAS,MAAM;EACf,OAAO,MAAM;EACb,OAAO,MAAM;CACf,EACF;AACF,CACF;;;;;;;AAeA,SAAgB,aACd,SACqC;CACrC,IAAI,CAAC,WAAW,QAAQ,KAAK,GAC3B,MAAM,IAAI,UACR,UAAU,QAAQ,KAAK,+CACzB;CAEF,MAAM,SAAkC,GACrC,oBAAoB,iBAAiB,EACxC;CACA,OAAO,QAAQ;EACb,UAAUA,iBAAe;GAAE,MAAM,QAAQ;GAAM;EAAO,CAAC;EACvD,MAAM;EACN,cAAc,QAAQ;CACxB,CAAC,CAAC,CAAC,MAAM,OAAO,UACd,MAAM,SAAA,mBAA6B,MAAM,QAAQ,QAAQ,KAC3D;AACF"}