experimental-a2 0.8.0 → 0.9.0

package/src/actor-shared.ts

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

package/src/actor.browser.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.',
+)
+export {}