experimental-a2 0.2.0 → 0.4.0

package/dist/server-YtPq7hjw.d.ts

@@ -0,0 +1,260 @@
+import { a as EventDefs, c as PresencePatch, d as WithPresence, l as PresenceSnapshot, n as Contract, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
+import { t as A2Store } from "./store-C3sNAaBT.js";
+import { i as A2Telemetry } from "./telemetry-BjYHTfh2.js";
+//#region src/scheduler-task.d.ts
+/** One event carried by a delayed append task. */
+type ScheduledEvent = {
+  id: string;
+  type: string;
+  payload: unknown;
+};
+/** A durable wake-up for pending handler work. */
+type SchedulerDrainTask = {
+  version: 1;
+  kind: "drain";
+  contract: string;
+  sessionId: string;
+  /** Earliest useful delivery as epoch milliseconds. */
+  dueAt: number;
+};
+/** A durable delayed append. */
+type SchedulerAppendTask = {
+  version: 1;
+  kind: "append";
+  /** Stable identity for provider-level deduplication. */
+  id: string;
+  contract: string;
+  sessionId: string;
+  /** Earliest useful delivery as epoch milliseconds. */
+  dueAt: number;
+  events: readonly ScheduledEvent[];
+};
+/** The versioned message protocol shared by scheduler adapters. */
+type SchedulerTask = SchedulerDrainTask | SchedulerAppendTask;
+//#endregion
+//#region src/server.d.ts
+/**
+ * Events that arrived over the wire through `parsePushBody` — already
+ * envelope-validated, headed for schema validation inside `append`.
+ * The brand lets the documented push route hand them straight to
+ * `session.append` without weakening typed appends for app code: a
+ * hand-written `{ type: string }` literal still fails to compile.
+ */
+type PushedEvent = {
+  type: string;
+  payload: unknown;
+  id?: string;
+  readonly "~a2.pushed": true;
+};
+/**
+ * A presence patch that arrived over the wire through `parsePushBody`
+ * — same provenance brand as `PushedEvent`, so the documented route
+ * hands it whole to `session.setPresence` while a hand-written
+ * untyped patch still fails to compile. Field validation happens
+ * inside `setPresence`.
+ */
+type PushedPresence = {
+  participant: string;
+  values: Record<string, unknown>;
+  seen?: number;
+  /** The sender's LWW stamp in epoch ms; receipt time when absent. */
+  at?: number;
+  readonly "~a2.pushed": true;
+};
+type PushValidationContext = {
+  sessionId: string;
+  events: readonly PushedEvent[];
+  /** The whole pushed patch — present exactly on the presence-plane
+   * invocation, so the callback authorizes the participant id and can
+   * apply size or cardinality policy. */
+  presence?: PushedPresence;
+};
+/** What every handler receives. */
+type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>> = {
+  /** The triggering event. */
+  event: ContractEvent<D, K>;
+  /** Durable, 1-based dispatch ordinal for this event. */
+  attempt: number;
+  /** This session, with handler-scoped idempotent append. */
+  session: Session<D, HandlerAppend<D>, P>;
+  /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
+  signal: AbortSignal;
+};
+type Handler<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>> = (ctx: HandlerContext<D, K, P>) => Promise<void | AppendInput<D> | readonly AppendInput<D>[]>;
+type LaneContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
+  sessionId: string;
+  event: Pick<ContractEvent<D, K>, "type" | "payload"> & {
+    id?: string;
+  };
+};
+type Lane<D extends EventDefs, K extends keyof D & string = keyof D & string> = string | ((context: LaneContext<D, K>) => string);
+type SessionDispatch<D extends EventDefs> = {
+  (...events: AppendInput<D>[]): Promise<ContractEvent<D>[]>;
+  /** The push-route path: events from `parsePushBody`. */
+  (...events: PushedEvent[]): Promise<ContractEvent<D>[]>;
+};
+type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
+  /** Commit, then hand pending work directly to configured scheduler. */
+  dispatch: SessionDispatch<D>;
+};
+type HandlerAppend<D extends EventDefs> = (name: string, ...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
+type ScheduleDelay = `${number}${"ms" | "s" | "m" | "h" | "d"}`;
+type ScheduleTiming = {
+  delay: ScheduleDelay;
+  at?: never;
+} | {
+  at: Date;
+  delay?: never;
+};
+type SessionSchedule<D extends EventDefs> = (name: string, timing: ScheduleTiming, ...events: AppendInput<D>[]) => Promise<void>;
+/**
+ * The presence members of a session — intersected in via
+ * `WithPresence`, so they exist exactly when the contract declares
+ * presence fields. Intersected before the base members so the widened
+ * `stream` overload is tried first: the literal `presence: true`
+ * selects it, everything else falls through to the events-only base.
+ */
+type SessionPresence<D extends EventDefs, P extends PresenceDefs> = {
+  /**
+   * The two-plane feed: one snapshot of the current pruned map first
+   * (per-field stamps exact), then presence patches interleaved with
+   * events.
+   */
+  stream(opts: {
+    startAfter?: number;
+    presence: true;
+  }): AsyncIterable<ContractEvent<D> | PresencePatch<P> | PresenceSnapshot<P>>;
+  /**
+   * Validate against the contract's presence schemas, then broadcast.
+   * Never an append: no log row, no dispatch, no scheduler arm. `at`
+   * is the sender's LWW stamp in epoch ms; omitted, receipt time
+   * stands in (single writer, so receipt order is sender order).
+   */
+  setPresence(patch: {
+    participant: string;
+    values: PresencePatch<P>["values"];
+    seen?: number;
+    at?: number;
+  } | PushedPresence): Promise<void>;
+  /** The current map, expired values pruned — a point-in-time read. */
+  presence(): Promise<PresenceMap<P>>;
+};
+/** A handle on one instance of the machine. Creating it does no I/O. */
+type Session<D extends EventDefs, Append = SessionAppend<D>, P extends PresenceDefs = Record<never, never>> = WithPresence<P, SessionPresence<D, P>> & {
+  readonly id: string;
+  append: Append;
+  schedule: SessionSchedule<D>;
+  history(options?: {
+    gte?: number;
+    lte?: number;
+  }): Promise<ContractEvent<D>[]>;
+  state<S>(reducer: Reducer<D, S>): Promise<{
+    state: S;
+    index: number;
+  }>;
+  /**
+   * A live feed of this session's events, starting after `startAfter`
+   * (exclusive). Server-side only — expose it over SSE with
+   * `sseResponse` from experimental-a2/http.
+   */
+  stream(opts?: {
+    startAfter?: number;
+  }): AsyncIterable<ContractEvent<D>>;
+};
+/**
+ * The public server shape scheduler handlers accept. It stays structural so
+ * servers of any contract mix in one route; A2's private server internals add
+ * delayed-append delivery without exposing an untyped append method here.
+ */
+type DrainableServer = {
+  readonly contract: {
+    readonly name: string;
+  };
+  drain(sessionId: string): Promise<{
+    settled: boolean;
+  }>;
+};
+/**
+ * The scheduler seam (a2-implementation.md §7, §9). `schedule` puts a
+ * versioned drain or delayed append task on durable infrastructure;
+ * `handler` returns the route the transport delivers to. Claim holders
+ * move the watchdog alongside their renewable execution window.
+ * Implementations ship as
+ * entry points (`experimental-a2/scheduler-vercel`); core never imports a
+ * transport.
+ */
+type A2Scheduler = {
+  schedule(task: SchedulerTask): Promise<void>;
+  handler(...servers: DrainableServer[]): (req: Request) => Promise<Response>;
+};
+type A2Server<D extends EventDefs, P extends PresenceDefs = Record<never, never>> = {
+  /** The contract this server implements. */
+  readonly contract: Contract<D, P>;
+  session(id: string): Session<D, SessionAppend<D>, P>;
+  /**
+   * Process every currently eligible event. `settled` means nothing
+   * actionable remains, including work blocked behind a dead letter.
+   */
+  drain(sessionId: string): Promise<{
+    settled: boolean;
+  }>;
+};
+/**
+ * Deliver one authenticated scheduler append through an A2 server's ordinary
+ * top-level append path. Custom scheduler adapters call this after validating
+ * their transport envelope; application code normally uses `session.schedule`.
+ */
+declare function deliverSchedulerAppend(server: DrainableServer, task: SchedulerAppendTask): Promise<void>;
+/**
+ * Which events fire `ctx.signal` while a handler runs — the preemption
+ * channel for user cancellation. The array form matches by type; the
+ * object form takes per-type predicates for targeted cancellation
+ * (`(event, trigger) => event.payload.of === trigger.id`). Handlers
+ * without `abortOn` pay nothing. An aborted handler should catch and
+ * return normally; throwing means "retry me".
+ */
+type AbortSpec<D extends EventDefs, K extends keyof D & string> = Array<keyof D & string> | { [T in keyof D & string]?: true | ((event: ContractEvent<D, T>, trigger: ContractEvent<D, K>, context: {
+  attempt: number;
+}) => boolean); };
+type HandlerEntry<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>> = Handler<D, K, P> | {
+  abortOn?: AbortSpec<D, K>;
+  /** Session-scoped FIFO key, resolved and persisted when the event lands. */
+  lane?: Lane<D, K>;
+  handler: Handler<D, K, P>;
+};
+type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, never>> = {
+  /** The contract this server implements (see `a2.contract`). */
+  contract: Contract<D, P>;
+  /** Where events live. Defaults: sqlite in dev, memory in tests, required in prod. */
+  store?: A2Store;
+  /**
+   * Queue-backed scheduler — e.g. `vercelQueues()` from
+   * `experimental-a2/scheduler-vercel`. Absent means append-driven healing only: a
+   * working configuration, but a clockless one. Recommended in
+   * production.
+   */
+  scheduler?: A2Scheduler;
+  /** Optional instrumentation — e.g. `otel()` from `experimental-a2/otel`. */
+  telemetry?: A2Telemetry;
+  /** Validate events that came through `parsePushBody` before writing them. */
+  validatePush?: (context: PushValidationContext) => void | PromiseLike<void>;
+  /**
+   * Presence-plane policy — valid only when the contract declares
+   * presence fields (TypeError at construction otherwise). `ttlMs` is
+   * how long a value survives without a refreshing set; default 60s.
+   */
+  presence?: {
+    ttlMs?: number;
+  };
+  /**
+   * The reactions, keyed by event type — all present at construction,
+   * so a handler can never be silently missing because its module
+   * wasn't imported. Compose across files by spreading objects (note:
+   * a duplicate key under spread silently last-wins).
+   */
+  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K, P>; };
+};
+/** Implement a contract: bind its vocabulary to storage and reactions. */
+declare function createServer<D extends EventDefs, P extends PresenceDefs = Record<never, never>>(options: ServerOptions<D, P>): A2Server<D, P>;
+//#endregion
+export { deliverSchedulerAppend as C, SchedulerTask as D, SchedulerDrainTask as E, createServer as S, SchedulerAppendTask as T, Session as _, Handler as a, SessionPresence as b, HandlerEntry as c, PushValidationContext as d, PushedEvent as f, ServerOptions as g, ScheduleTiming as h, DrainableServer as i, Lane as l, ScheduleDelay as m, A2Server as n, HandlerAppend as o, PushedPresence as p, AbortSpec as r, HandlerContext as s, A2Scheduler as t, LaneContext as u, SessionAppend as v, ScheduledEvent as w, SessionSchedule as x, SessionDispatch as y };

package/dist/server.d.ts

@@ -1,155 +1,4 @@
-import { a as EventDefs, c as Reducer, n as Contract, r as ContractEvent, t as AppendInput } from "./contract-C_3dIIEU.js";
-import { a as Event, c as IdSource, d as LogStateRead, f as StoredEvent, h as StoredSnapshot, i as Clock, l as LogAppendResult, m as StoredSessionSummary, n as A2LogInspection, o as EventCause, p as StoredSessionPage, r as AppendEvent, s as FailAttemptResult, t as A2Log, u as LogClaimAvailableResult } from "./log-ldf5g8Cx.js";
-import { i as A2Telemetry } from "./telemetry-Cso0qyHQ.js";
-//#region src/server.d.ts
-/**
- * Events that arrived over the wire through `parsePushBody` — already
- * envelope-validated, headed for schema validation inside `append`.
- * The brand lets the documented push route hand them straight to
- * `session.append` without weakening typed appends for app code: a
- * hand-written `{ type: string }` literal still fails to compile.
- */
-type PushedEvent = {
-  type: string;
-  payload: unknown;
-  id?: string;
-  readonly "~a2.pushed": true;
-};
-type PushValidationContext = {
-  sessionId: string;
-  events: readonly PushedEvent[];
-};
-/** What every handler receives. */
-type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
-  /** The triggering event. */
-  event: ContractEvent<D, K>;
-  /** Durable, 1-based dispatch ordinal for this event. */
-  attempt: number;
-  /** This session, with handler-scoped idempotent append. */
-  session: Session<D, HandlerAppend<D>>;
-  /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
-  signal: AbortSignal;
-};
-type Handler<D extends EventDefs, K extends keyof D & string = keyof D & string> = (ctx: HandlerContext<D, K>) => Promise<void | AppendInput<D> | readonly AppendInput<D>[]>;
-type LaneContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
-  sessionId: string;
-  event: Pick<ContractEvent<D, K>, "type" | "payload"> & {
-    id?: string;
-  };
-};
-type Lane<D extends EventDefs, K extends keyof D & string = keyof D & string> = string | ((context: LaneContext<D, K>) => string);
-type SessionDispatch<D extends EventDefs> = {
-  (...events: AppendInput<D>[]): Promise<ContractEvent<D>[]>;
-  /** The push-route path: events from `parsePushBody`. */
-  (...events: PushedEvent[]): Promise<ContractEvent<D>[]>;
-};
-type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
-  /** Commit, then hand pending work directly to configured recovery. */
-  dispatch: SessionDispatch<D>;
-};
-type HandlerAppend<D extends EventDefs> = (name: string, ...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
-/** A handle on one instance of the machine. Creating it does no I/O. */
-type Session<D extends EventDefs, Append = SessionAppend<D>> = {
-  readonly id: string;
-  append: Append;
-  history(): Promise<ContractEvent<D>[]>;
-  state<S>(reducer: Reducer<D, S>): Promise<{
-    state: S;
-    index: number;
-  }>;
-  /**
-   * A live feed of this session's events, starting after `startAt`
-   * (exclusive). Server-side only — expose it over SSE with
-   * `sseResponse` from experimental-a2/http.
-   */
-  stream(opts?: {
-    startAt?: number;
-  }): AsyncIterable<ContractEvent<D>>;
-};
-/**
- * What recovery needs from a server — structural, so servers of any
- * contract mix in one `handler(...)` call. Deliberately tiny: recovery
- * consults the log through `drain` and nothing else.
- */
-type RecoverableServer = {
-  readonly contract: {
-    readonly name: string;
-  };
-  drain(sessionId: string): Promise<{
-    settled: boolean;
-  }>;
-};
-/**
- * The recovery seam (a2-implementation.md §7, §9). `arm` puts a
- * delayed, coalesced "drain this session" message on durable
- * infrastructure while inline work starts; `handler` returns the route
- * the transport delivers to. Claim holders move the watchdog alongside
- * their renewable execution window. Implementations ship as
- * entry points (`experimental-a2/recovery-vercel`); core never imports a transport.
- */
-type A2Recovery = {
-  arm(opts: {
-    contract: string;
-    sessionId: string;
-    /** Earliest useful delivery as epoch milliseconds. */
-    dueAt?: number;
-  }): Promise<void>;
-  handler(...servers: RecoverableServer[]): (req: Request) => Promise<Response>;
-};
-type A2Server<D extends EventDefs> = {
-  /** The contract this server implements. */
-  readonly contract: Contract<D>;
-  session(id: string): Session<D>;
-  /**
-   * Process every currently eligible event. `settled` means nothing
-   * actionable remains, including work blocked behind a dead letter.
-   */
-  drain(sessionId: string): Promise<{
-    settled: boolean;
-  }>;
-};
-/**
- * Which events fire `ctx.signal` while a handler runs — the preemption
- * channel for user cancellation. The array form matches by type; the
- * object form takes per-type predicates for targeted cancellation
- * (`(event, trigger) => event.payload.of === trigger.id`). Handlers
- * without `abortOn` pay nothing. An aborted handler should catch and
- * return normally; throwing means "retry me".
- */
-type AbortSpec<D extends EventDefs, K extends keyof D & string> = Array<keyof D & string> | { [T in keyof D & string]?: true | ((event: ContractEvent<D, T>, trigger: ContractEvent<D, K>, context: {
-  attempt: number;
-}) => boolean); };
-type HandlerEntry<D extends EventDefs, K extends keyof D & string = keyof D & string> = Handler<D, K> | {
-  abortOn?: AbortSpec<D, K>;
-  /** Session-scoped FIFO key, resolved and persisted when the event lands. */
-  lane?: Lane<D, K>;
-  handler: Handler<D, K>;
-};
-type ServerOptions<D extends EventDefs> = {
-  /** The contract this server implements (see `a2.contract`). */
-  contract: Contract<D>;
-  /** Where events live. Defaults: sqlite in dev, memory in tests, required in prod. */
-  log?: A2Log;
-  /**
-   * Queue-backed recovery — e.g. `vercelQueues()` from
-   * `experimental-a2/recovery-vercel`. Absent means append-driven healing only: a
-   * working configuration, but a clockless one. Recommended in
-   * production.
-   */
-  recovery?: A2Recovery;
-  /** Optional instrumentation — e.g. `otel()` from `experimental-a2/otel`. */
-  telemetry?: A2Telemetry;
-  /** Validate events that came through `parsePushBody` before writing them. */
-  validatePush?: (context: PushValidationContext) => void | PromiseLike<void>;
-  /**
-   * The reactions, keyed by event type — all present at construction,
-   * so a handler can never be silently missing because its module
-   * wasn't imported. Compose across files by spreading objects (note:
-   * a duplicate key under spread silently last-wins).
-   */
-  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K>; };
-};
-/** Implement a contract: bind its vocabulary to storage and reactions. */
-declare function createServer<D extends EventDefs>(options: ServerOptions<D>): A2Server<D>;
-//#endregion
-export { type A2Log, type A2LogInspection, A2Recovery, A2Server, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type LogAppendResult, type LogClaimAvailableResult, type LogStateRead, PushValidationContext, PushedEvent, RecoverableServer, ServerOptions, Session, SessionAppend, SessionDispatch, type StoredEvent, type StoredSessionPage, type StoredSessionSummary, type StoredSnapshot, createServer };
+import { a as EventDefs, c as PresencePatch, l as PresenceSnapshot, n as Contract, o as PresenceDefs, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
+import { a as Event, c as IdSource, d as StoreClaimAvailableResult, f as StoreStateRead, g as StoredSnapshot, h as StoredSessionSummary, i as Clock, l as PresenceRow, m as StoredSessionPage, n as A2StoreInspection, o as EventCause, p as StoredEvent, r as AppendEvent, s as FailAttemptResult, t as A2Store, u as StoreAppendResult } from "./store-C3sNAaBT.js";
+import { C as deliverSchedulerAppend, D as SchedulerTask, E as SchedulerDrainTask, S as createServer, T as SchedulerAppendTask, _ as Session, a as Handler, b as SessionPresence, c as HandlerEntry, d as PushValidationContext, f as PushedEvent, g as ServerOptions, h as ScheduleTiming, i as DrainableServer, l as Lane, m as ScheduleDelay, n as A2Server, o as HandlerAppend, p as PushedPresence, r as AbortSpec, s as HandlerContext, t as A2Scheduler, u as LaneContext, v as SessionAppend, w as ScheduledEvent, x as SessionSchedule, y as SessionDispatch } from "./server-YtPq7hjw.js";
+export { A2Scheduler, A2Server, type A2Store, type A2StoreInspection, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, DrainableServer, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceRow, type PresenceSnapshot, PushValidationContext, PushedEvent, PushedPresence, ScheduleDelay, ScheduleTiming, type ScheduledEvent, type SchedulerAppendTask, type SchedulerDrainTask, type SchedulerTask, ServerOptions, Session, SessionAppend, SessionDispatch, SessionPresence, SessionSchedule, type StoreAppendResult, type StoreClaimAvailableResult, type StoreStateRead, type StoredEvent, type StoredSessionPage, type StoredSessionSummary, type StoredSnapshot, createServer, deliverSchedulerAppend };

package/dist/server.js

@@ -1,2 +1,2 @@
-import { t as createServer } from "./server-DJgD2YWP.js";
-export { createServer };
+import { n as deliverSchedulerAppend, t as createServer } from "./server-CcNnFnoW.js";
+export { createServer, deliverSchedulerAppend };