experimental-a2 0.8.0 → 0.9.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"actor-shared-DI7J5upy.js","names":["createContract"],"sources":["../src/actor-shared.ts"],"sourcesContent":["/**\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 { contract 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}\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    return {\n      value: {\n        state: state as S,\n        event: value['event'],\n        message: value['message'],\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 createContract({ name: options.name, events })\n    .reducer({ name: ACTOR_REDUCER_NAME, initialState: options.state })\n    .fold((state, event) =>\n      event.type === ACTOR_STATE_EVENT ? event.payload.state : state,\n    )\n}\n"],"mappings":"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"}

package/dist/actor.browser.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/actor.browser.js

@@ -0,0 +1,13 @@
+//#region src/actor.browser.ts
+/**
+* The browser build of experimental-a2/actor. There isn't one — on
+* purpose. Actions are server code; the browser follows an actor's
+* state with `actorReducer()` from `experimental-a2/actor` (isomorphic)
+* over the ordinary session client. This module existing in a client
+* bundle means a `'use client'` file (or something it imports)
+* value-imported your actor module.
+*/
+throw new Error("experimental-a2/actor is server-only — a client bundle imported it. Import actorReducer from experimental-a2/actor and the session client (experimental-a2/client, experimental-a2/react) in browser code instead.");
+//#endregion
+
+//# sourceMappingURL=actor.browser.js.map

package/dist/actor.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.browser.js","names":[],"sources":["../src/actor.browser.ts"],"sourcesContent":["/**\n * The browser build of experimental-a2/actor. There isn't one — on\n * purpose. Actions are server code; the browser follows an actor's\n * state with `actorReducer()` from `experimental-a2/actor` (isomorphic)\n * over the ordinary session client. This module existing in a client\n * bundle means a `'use client'` file (or something it imports)\n * value-imported your actor module.\n */\nthrow new Error(\n  'experimental-a2/actor is server-only — a client bundle imported it. Import actorReducer from experimental-a2/actor and the session client (experimental-a2/client, experimental-a2/react) in browser code instead.',\n)\nexport {}\n"],"mappings":";;;;;;;;;AAQA,MAAM,IAAI,MACR,oNACF"}

package/dist/actor.d.ts

@@ -0,0 +1,176 @@
+import { i as Contract, s as EventDefs, t as Reducer } from "./reducer-DJKWm3cp.js";
+import { t as A2Store } from "./store-DGHeBtIQ.js";
+import { m as Session, n as A2Server, t as A2Scheduler } from "./server-CKY3_lbw.js";
+import { i as A2Telemetry } from "./telemetry-CpeclqB2.js";
+import { a as ActorPresenceOf, c as ActorRefusedError, d as ActorSend, i as ActorPresenceMap, l as ActorScheduleOptions, n as ActorConcurrentContext, o as ActorPresenceValues, r as ActorContext, s as ActorProtocol, t as ActorClientEventDefs, u as ActorScheduleSend } from "./actor-shared-BACubf4x.js";
+//#region src/actor.d.ts
+/**
+ * One event's handler: ordinary server code. Serial by default — read
+ * `ctx.state`, perform I/O, mutate `ctx.state`, one atomic commit at
+ * return. `{ concurrent: true, handle }` opts the handler out of the
+ * lane for slow I/O: state becomes a snapshot read and mutations
+ * happen by sending events. The input is typed by the protocol; the
+ * wire hands handlers parsed JSON, so a wire-exposed event guards its
+ * input in its first line (`schema.parse(input)` if you like schemas —
+ * userland either way).
+ */
+type ActorHandler<D extends ActorProtocol, K extends keyof D["events"]> = ((ctx: ActorContext<D>, input: D["events"][K]) => void | Promise<void>) | {
+  concurrent: true;
+  handle: (ctx: ActorConcurrentContext<D>, input: D["events"][K]) => void | Promise<void>;
+};
+/**
+ * Mark a handler concurrent — off the lane, in parallel with the lane
+ * and with other concurrent handlers, `ctx.state()` a snapshot read.
+ * Sugar for the structural `{ concurrent: true, handle }` form:
+ *
+ * ```ts
+ * handlers: {
+ *   transfer: concurrent(async (ctx, input) => {
+ *     await bank.transfer(input, { idempotencyKey: input.ref })
+ *     ctx.send.settle({ ref: input.ref })
+ *   }),
+ * }
+ * ```
+ */
+declare function concurrent<Ctx, I>(handle: (ctx: Ctx, input: I) => void | Promise<void>): {
+  concurrent: true;
+  handle: (ctx: Ctx, input: I) => void | Promise<void>;
+};
+type ActorOptions<D extends ActorProtocol> = {
+  /** Identity — prefixes storage keys; one contract per actor definition. */
+  name: string;
+  /** The initial state — checked against the protocol, a plain JSON tree. */
+  state: D["state"];
+  /**
+   * One handler per declared event — completeness and payload shapes
+   * are compile-checked against the protocol.
+   */
+  handlers: { [K in keyof D["events"]]: ActorHandler<D, K>; };
+  store?: A2Store;
+  scheduler?: A2Scheduler;
+  telemetry?: A2Telemetry;
+} & ([ActorPresenceOf<D>] extends [never] ? {
+  presence?: never;
+} : {
+  /**
+   * The wire bit for the protocol's `presence` vocabulary — types
+   * erase, so the runtime needs one value to arm the presence
+   * lanes (frames on GET, envelopes on POST). Required exactly
+   * when the protocol declares `presence`; the vocabulary itself
+   * is typed there. Values are validated to the JSON floor and
+   * pass through `authorize` as `{ type: 'presence' }` operations;
+   * meaning stays with your renderers — treat values as user
+   * input.
+   */
+  presence: true;
+});
+/**
+ * One HTTP operation `handle.fetch` is about to serve — the actor
+ * mirror of core's `A2Operation`. `authorize` sees it before any
+ * write or subscription; returning `false` answers 403.
+ */
+type ActorOperation = {
+  readonly type: "stream";
+  readonly id: string;
+  readonly startAfter: number;
+} | {
+  readonly type: "call";
+  readonly id: string;
+  readonly event: string;
+  readonly input: unknown;
+  readonly messageId?: string;
+} | {
+  readonly type: "presence";
+  readonly id: string;
+  readonly participant: string;
+  readonly values: Readonly<Record<string, unknown>>;
+};
+type ActorFetchOptions<D extends ActorProtocol> = {
+  /** Per-operation policy — authentication happened in your route. */
+  authorize?: (operation: ActorOperation) => boolean | Promise<boolean>;
+  /**
+   * Request-time projection: what this mount's audience sees. Applied
+   * to every state frame on the stream AND to call answers (the two
+   * untrusted lanes must agree, or the call lane leaks what the
+   * stream hides). The definition stays audience-agnostic — different
+   * routes project the same actor differently, and per-viewer views
+   * are just closures over the route's auth. Output is held to the
+   * JSON-tree floor like everything else. Transport-agnostic: applied
+   * at frame emission, so any wire the door speaks emits projected
+   * frames. Absent, the full state ships (the trusted default).
+   */
+  view?: (state: D["state"]) => unknown;
+};
+type ActorSendOptions = {
+  /** Explicit message id — makes retries of this send idempotent. */
+  id?: string;
+};
+type ActorCallOptions = ActorSendOptions & {
+  /** How long to await the answer before rejecting the wait (default 30s). */
+  timeoutMs?: number;
+};
+type ActorCallResult<S> = {
+  /** The actor's state after this message was processed. */
+  state: S;
+  /** Log index of the state commit that answered this message. */
+  index: 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<{
+  id: string;
+  index: number;
+}> : (input: D["events"][K], options?: ActorSendOptions) => Promise<{
+  id: string;
+  index: number;
+}>;
+/** One instance: typed calls and sends, reads, the managed door, the escape hatch. */
+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.
+   */
+  readonly call: { readonly [K in keyof D["events"]]: CallMethod<D, K>; };
+  /** Cast: validate, append the event durably, return without waiting. */
+  readonly send: { readonly [K in keyof D["events"]]: SendMethod<D, K>; };
+  /** Snapshot read — never queues behind pending messages. */
+  readonly state: () => Promise<ActorCallResult<D["state"]>>;
+  /**
+   * 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
+   * authenticates and picks the instance; `authorize` sees every
+   * operation. Custom endpoints are route code around this call.
+   */
+  readonly fetch: (request: Request, options?: ActorFetchOptions<D>) => Promise<Response>;
+  /** Escape hatch: the raw A2 session (history, stream, schedule). */
+  readonly session: Session<EventDefs>;
+};
+type ActorDefinition<D extends ActorProtocol> = {
+  readonly name: string;
+  /**
+   * Type-only carrier of the protocol, so clients deriving from
+   * `typeof def` can see the vocabularies (`experimental-a2/actor/react`
+   * types `presence` from it). Never a runtime value.
+   */
+  readonly protocol?: D;
+  /** The assembled contract — declared events plus the reserved a2.actor.* pair. */
+  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. */
+  readonly reducer: Reducer<ActorClientEventDefs<D["state"]>, D["state"]>;
+  actor(id: string): ActorHandle<D>;
+};
+/**
+ * Define and serve an actor over its protocol: a named, durable
+ * instance-per-id with serialized state handlers, concurrent I/O
+ * handlers, and typed self-sends.
+ */
+declare function actor<D extends ActorProtocol>(options: ActorOptions<D>): ActorDefinition<D>;
+//#endregion
+export { ActorCallOptions, ActorCallResult, type ActorConcurrentContext, type ActorContext, ActorDefinition, ActorFetchOptions, ActorHandle, ActorHandler, ActorOperation, ActorOptions, type ActorPresenceMap, type ActorPresenceOf, type ActorPresenceValues, type ActorProtocol, ActorRefusedError, type ActorScheduleOptions, type ActorScheduleSend, type ActorSend, ActorSendOptions, actor, concurrent };
+//# sourceMappingURL=actor.d.ts.map

package/dist/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","names":[],"sources":["../src/actor.ts"],"mappings":";;;;;;;;;;;;;;;;KA6GY,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;WAEG;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;;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;;;;;;WAMA,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,aAAa,QAAQ,gBAAgB;;;;;;;;;;WAUrC,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.js

@@ -0,0 +1,437 @@
+import { t as contract } from "./contract-48bUMgcL.js";
+import { n as NonRetriableError, t as A2Error } from "./errors-DCk6ch5n.js";
+import { a as parsePresenceSibling, i as sseResponse, r as setServerFetchHooks, t as createServer } from "./server-CBET-jSz.js";
+import { a as actorFailedSchema, c as isJsonTree, i as ActorRefusedError, l as openPresenceDefs, n as ACTOR_LANE, o as actorReducer, r as ACTOR_STATE_EVENT, s as actorStateSchema, t as ACTOR_FAILED_EVENT } from "./actor-shared-DI7J5upy.js";
+//#region src/actor.ts
+/**
+* experimental-a2/actor — durable actors over the log. Server-only
+* (handlers are server code); the browser condition resolves to a
+* throwing stub, and the browser surfaces are experimental-a2/actor/client
+* and experimental-a2/actor/react.
+*
+* An actor is defined over a protocol — its state shape and event
+* vocabulary, as types — and one complete `handlers` bag:
+*
+* ```ts
+* interface Counter {
+*   state: { count: number }
+*   events: { increment: object; add: { by: number } }
+* }
+* const counter = actor<Counter>({
+*   name: 'counter',
+*   state: { count: 0 },
+*   handlers: {
+*     increment: (ctx) => {
+*       ctx.state.count++
+*     },
+*     add: (ctx, input) => {
+*       ctx.state.count += input.by
+*     },
+*   },
+* })
+* ```
+*
+* Handlers are serial by default: one at a time per instance (a lane —
+* the state's write lock), `ctx.state` a mutable draft committed
+* atomically with completion. A handler holding slow I/O opts out of
+* the lane with `{ concurrent: true, handle }`: it runs in parallel,
+* reads state as a snapshot, and mutates by sending events whose
+* serial handlers decide against fresh state. `ctx.send.eventName(...)`
+* is typed by the protocol and buffered — committed atomically with
+* the handler's completion, so a reserve and its trigger can never
+* half-happen.
+*
+* A thrown `NonRetriableError` is an answer (settled, delivered to a
+* waiting caller); any other error retries like every A2 handler
+* failure; a crash re-runs against the same pre-state. Everything
+* compiles to contract + reducer + laned handlers + returned events —
+* no new store operations, no new wire.
+*/
+/**
+* Mark a handler concurrent — off the lane, in parallel with the lane
+* and with other concurrent handlers, `ctx.state()` a snapshot read.
+* Sugar for the structural `{ concurrent: true, handle }` form:
+*
+* ```ts
+* handlers: {
+*   transfer: concurrent(async (ctx, input) => {
+*     await bank.transfer(input, { idempotencyKey: input.ref })
+*     ctx.send.settle({ ref: input.ref })
+*   }),
+* }
+* ```
+*/
+function concurrent(handle) {
+	return {
+		concurrent: true,
+		handle
+	};
+}
+const UNSAFE_EVENT_NAMES = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const forbidden = () => Response.json({ error: "the operation is not authorized" }, { status: 403 });
+const CALL_TIMEOUT_MS = 3e4;
+const CALL_POLL_MS = 25;
+/** Declared events accept any JSON tree; `undefined` normalizes to `{}`. */
+const jsonInputSchema = { "~standard": {
+	version: 1,
+	vendor: "a2",
+	validate(value) {
+		if (value === void 0 || value === null) return { value: {} };
+		if (!isJsonTree(value)) return { issues: [{ message: "event input must be a plain JSON tree" }] };
+		return { value };
+	}
+} };
+const describeError = (error) => error instanceof Error ? error.message : String(error);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Define and serve an actor over its protocol: a named, durable
+* instance-per-id with serialized state handlers, concurrent I/O
+* handlers, and typed self-sends.
+*/
+function actor(options) {
+	const { name } = options;
+	const handlersByEvent = /* @__PURE__ */ new Map();
+	const events = {
+		[ACTOR_STATE_EVENT]: actorStateSchema(),
+		[ACTOR_FAILED_EVENT]: actorFailedSchema
+	};
+	for (const [eventName, def] of Object.entries(options.handlers)) {
+		if (UNSAFE_EVENT_NAMES.has(eventName)) throw new TypeError(`actor '${name}': '${eventName}' collides with object plumbing and cannot name an event`);
+		if (eventName.startsWith("a2.")) throw new TypeError(`actor '${name}': event names starting with 'a2.' are reserved`);
+		handlersByEvent.set(eventName, typeof def === "function" ? {
+			kind: "serial",
+			handle: def
+		} : {
+			kind: "concurrent",
+			handle: def.handle
+		});
+		events[eventName] = jsonInputSchema;
+	}
+	const reducer = actorReducer({
+		name,
+		state: options.state
+	});
+	const serverReducer = reducer;
+	const makeSchedule = (schedule) => {
+		const surface = {};
+		for (const eventName of handlersByEvent.keys()) Object.defineProperty(surface, eventName, {
+			value: (input, scheduleOptions) => {
+				const { name: taskName, ...timing } = scheduleOptions;
+				return schedule(taskName ?? eventName, timing, {
+					type: eventName,
+					payload: input ?? {}
+				});
+			},
+			enumerable: true,
+			configurable: true,
+			writable: false
+		});
+		return surface;
+	};
+	const makeSend = (buffer) => {
+		const send = {};
+		for (const eventName of handlersByEvent.keys()) Object.defineProperty(send, eventName, {
+			value: (input) => {
+				buffer.push({
+					type: eventName,
+					payload: input ?? {}
+				});
+			},
+			enumerable: true,
+			configurable: true,
+			writable: false
+		});
+		return send;
+	};
+	const handlers = {};
+	for (const [eventName, def] of handlersByEvent) {
+		if (def.kind === "concurrent") {
+			handlers[eventName] = async (ctx) => {
+				const sends = [];
+				try {
+					await def.handle({
+						id: ctx.event.id,
+						attempt: ctx.attempt,
+						signal: ctx.signal,
+						send: makeSend(sends),
+						schedule: makeSchedule((taskName, timing, event) => ctx.session.schedule(taskName, timing, event)),
+						state: async () => {
+							const { state, index } = await ctx.session.state(serverReducer, { through: "latest" });
+							return {
+								state,
+								index
+							};
+						}
+					}, ctx.event.payload);
+				} catch (error) {
+					if (!(error instanceof NonRetriableError)) throw error;
+					const payload = {
+						message: ctx.event.id,
+						event: eventName,
+						error: describeError(error)
+					};
+					return {
+						type: ACTOR_FAILED_EVENT,
+						payload
+					};
+				}
+				return sends;
+			};
+			continue;
+		}
+		handlers[eventName] = {
+			lane: ACTOR_LANE,
+			handler: async (ctx) => {
+				const { state } = await ctx.session.state(serverReducer, { through: "latest" });
+				const draft = structuredClone(state);
+				const sends = [];
+				try {
+					await def.handle({
+						state: draft,
+						id: ctx.event.id,
+						attempt: ctx.attempt,
+						signal: ctx.signal,
+						send: makeSend(sends),
+						schedule: makeSchedule((taskName, timing, event) => ctx.session.schedule(taskName, timing, event))
+					}, ctx.event.payload);
+				} catch (error) {
+					if (!(error instanceof NonRetriableError)) throw error;
+					const payload = {
+						message: ctx.event.id,
+						event: eventName,
+						error: describeError(error)
+					};
+					return {
+						type: ACTOR_FAILED_EVENT,
+						payload
+					};
+				}
+				const payload = {
+					state: draft,
+					event: eventName,
+					message: ctx.event.id
+				};
+				return [...sends, {
+					type: ACTOR_STATE_EVENT,
+					payload
+				}];
+			}
+		};
+	}
+	const presenceEnabled = options.presence === true;
+	const contract$1 = presenceEnabled ? contract({
+		name,
+		events,
+		presence: openPresenceDefs
+	}) : contract({
+		name,
+		events
+	});
+	const server = createServer({
+		contract: contract$1,
+		handlers,
+		...options.store ? { store: options.store } : {},
+		...options.scheduler ? { scheduler: options.scheduler } : {},
+		...options.telemetry ? { telemetry: options.telemetry } : {}
+	});
+	setServerFetchHooks(server, { validateIngress: ({ events: pushed }) => {
+		for (const event of pushed) if (event.type.startsWith("a2.actor.")) throw new TypeError(`'${event.type}' is reserved — only a handler's completion can author it`);
+	} });
+	const makeHandle = (id) => {
+		const session = server.session(id);
+		const sendEvent = async (eventName, input, sendOptions) => {
+			const [message] = await session.append({
+				type: eventName,
+				payload: input ?? {},
+				...sendOptions?.id ? { id: sendOptions.id } : {}
+			});
+			if (!message) throw new Error("append returned no event");
+			return {
+				id: message.id,
+				index: message.index
+			};
+		};
+		const callEvent = async (eventName, input, callOptions) => {
+			if (handlersByEvent.get(eventName)?.kind === "concurrent") throw new TypeError(`actor '${name}': '${eventName}' is concurrent — it produces no answer to await; send it instead`);
+			const message = await sendEvent(eventName, input, callOptions);
+			const deadline = Date.now() + (callOptions?.timeoutMs ?? CALL_TIMEOUT_MS);
+			let cursor = message.index + 1;
+			for (;;) {
+				await server.drain(id);
+				const tail = await session.history({ gte: cursor });
+				for (const event of tail) {
+					if (event.type === "a2.actor.state") {
+						const payload = event.payload;
+						if (payload.message === message.id) return {
+							state: payload.state,
+							index: event.index
+						};
+					}
+					if (event.type === "a2.actor.failed") {
+						const payload = event.payload;
+						if (payload.message === message.id) throw new ActorRefusedError(eventName, message.id, payload.error);
+					}
+				}
+				const last = tail[tail.length - 1];
+				if (last) cursor = last.index + 1;
+				if (Date.now() >= deadline) throw new Error(`actor '${name}': timed out waiting for '${eventName}' (message ${message.id})`);
+				await sleep(CALL_POLL_MS);
+			}
+		};
+		const readState = async () => {
+			const { state, index } = await session.state(serverReducer);
+			return {
+				state,
+				index
+			};
+		};
+		const applyView = (view, state) => {
+			const viewed = view(state);
+			if (!isJsonTree(viewed)) throw new TypeError(`actor '${name}': the view returned a value that is not a plain JSON tree`);
+			return viewed;
+		};
+		const streamStates = async function* (startAfter, view) {
+			const source = presenceEnabled ? session.stream({
+				startAfter,
+				presence: true
+			}) : session.stream({ startAfter });
+			for await (const item of source) {
+				if (!("type" in item)) {
+					yield item;
+					continue;
+				}
+				const event = item;
+				if (event.type !== "a2.actor.state") continue;
+				if (!view) {
+					yield event;
+					continue;
+				}
+				const payload = event.payload;
+				yield {
+					...event,
+					payload: {
+						...payload,
+						state: applyView(view, payload.state)
+					}
+				};
+			}
+		};
+		const handleFetch = async (request, fetchOptions) => {
+			const authorized = async (operation) => await fetchOptions?.authorize?.(Object.freeze(operation)) !== false;
+			if (request.method === "GET") {
+				const url = new URL(request.url);
+				const raw = Number(url.searchParams.get("index"));
+				const startAfter = Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
+				if (!await authorized({
+					type: "stream",
+					id,
+					startAfter
+				})) return forbidden();
+				return sseResponse(streamStates(startAfter, fetchOptions?.view));
+			}
+			if (request.method !== "POST") return new Response(null, {
+				status: 405,
+				headers: { allow: "GET, POST" }
+			});
+			let body;
+			try {
+				body = await request.json();
+			} catch {
+				return Response.json({ error: "invalid JSON body" }, { status: 400 });
+			}
+			const record = typeof body === "object" && body !== null ? body : {};
+			if ("presence" in record) {
+				if (!presenceEnabled) return Response.json({ error: `actor '${name}' declares no presence` }, { status: 400 });
+				const pushedEvents = record["events"];
+				if (pushedEvents !== void 0 && (!Array.isArray(pushedEvents) || pushedEvents.length > 0)) return Response.json({ error: "the actor wire takes calls, not event pushes" }, { status: 400 });
+				let patch;
+				try {
+					const parsed = parsePresenceSibling(record["presence"]);
+					if (!parsed) throw new TypeError("presence must be an object");
+					patch = parsed;
+				} catch (error) {
+					return Response.json({ error: describeError(error) }, { status: 400 });
+				}
+				if (!await authorized({
+					type: "presence",
+					id,
+					participant: patch.participant,
+					values: patch.values
+				})) return forbidden();
+				try {
+					await session.setPresence(patch);
+				} catch (error) {
+					if (error instanceof A2Error && (error.code === "INVALID_PAYLOAD" || error.code === "UNKNOWN_PRESENCE_FIELD")) return Response.json({ error: error.message }, { status: 400 });
+					throw error;
+				}
+				return Response.json([]);
+			}
+			const eventName = record["event"];
+			if (typeof eventName !== "string" || handlersByEvent.get(eventName)?.kind !== "serial") return Response.json({ error: "unknown event" }, { status: 400 });
+			const messageId = record["messageId"];
+			if (messageId !== void 0 && typeof messageId !== "string") return Response.json({ error: "invalid messageId" }, { status: 400 });
+			const input = record["input"];
+			if (!await authorized({
+				type: "call",
+				id,
+				event: eventName,
+				input,
+				...messageId === void 0 ? {} : { messageId }
+			})) return forbidden();
+			try {
+				const result = await callEvent(eventName, input, messageId === void 0 ? void 0 : { id: messageId });
+				return Response.json(fetchOptions?.view ? {
+					state: applyView(fetchOptions.view, result.state),
+					index: result.index
+				} : result);
+			} catch (error) {
+				if (error instanceof ActorRefusedError) return Response.json({
+					error: error.message,
+					event: error.event,
+					messageId: error.messageId
+				}, { status: 409 });
+				if (error instanceof A2Error && (error.code === "INVALID_PAYLOAD" || error.code === "UNKNOWN_EVENT_TYPE")) return Response.json({ error: error.message }, { status: 400 });
+				throw error;
+			}
+		};
+		const call = {};
+		const send = {};
+		for (const eventName of handlersByEvent.keys()) {
+			Object.defineProperty(call, eventName, {
+				value: (input, callOptions) => callEvent(eventName, input, callOptions),
+				enumerable: true,
+				configurable: true,
+				writable: false
+			});
+			Object.defineProperty(send, eventName, {
+				value: (input, sendOptions) => sendEvent(eventName, input, sendOptions),
+				enumerable: true,
+				configurable: true,
+				writable: false
+			});
+		}
+		return {
+			id,
+			session,
+			call,
+			send,
+			state: readState,
+			fetch: handleFetch
+		};
+	};
+	return {
+		name,
+		contract: contract$1,
+		server,
+		reducer,
+		actor: makeHandle
+	};
+}
+//#endregion
+export { ActorRefusedError, actor, concurrent };
+
+//# sourceMappingURL=actor.js.map