experimental-a2 0.16.1 → 0.17.0

package/dist/{server-DbD7IJVK.d.ts → server-CGM8WzRG.d.ts}

@@ -1,6 +1,7 @@
-import { a as ContractEvent, c as PresenceDefs, d as PresenceSnapshot, i as Contract, l as PresenceMap, p as WithPresence, r as AppendInput, s as EventDefs, t as Reducer, u as PresencePatch } from "./reducer-otzHjuJj.js";
-import { t as A2Store } from "./store-DyZM6fS5.js";
-import { i as A2Telemetry } from "./telemetry-B5jzpy6y.js";
+import { c as ContractEvent, d as PresenceDefs, f as PresenceMap, g as WithPresence, m as PresenceSnapshot, o as AppendInput, p as PresencePatch, r as RegisteredReducer, s as Contract, t as Reducer, u as EventDefs } from "./reducer-BYu6DT7h.js";
+import { t as A2Store } from "./store-Gpkq7WBo.js";
+import { t as SessionCleared } from "./session-clear-Dshpuhff.js";
+import { i as A2Telemetry } from "./telemetry-cZH-cibj.js";
 //#region src/session-socket.d.ts
 /**
  * The structural socket `sessionsSocket` speaks against — satisfied
@@ -38,6 +39,7 @@ type A2Operation<D extends EventDefs = EventDefs, P extends PresenceDefs = Recor
   readonly type: "stream";
   readonly sessionId: string;
   readonly startAfter: number;
+  readonly bootstrap?: true;
   readonly transport: "http" | "websocket";
 } | {
   readonly type: "history";
@@ -87,23 +89,41 @@ type SchedulerAppendTask = {
   /** Earliest useful delivery as epoch milliseconds. */
   dueAt: number;
   events: readonly ScheduledEvent[];
+  /** The scheduling handler's event; delivery skips once it is cleared. */
+  originIndex?: number;
+};
+/** A durable conditional clear. */
+type SchedulerClearTask = {
+  version: 1;
+  kind: "clear";
+  /** Stable identity for provider-level deduplication. */
+  id: string;
+  contract: string;
+  sessionId: string;
+  /** Earliest useful delivery as epoch milliseconds. */
+  dueAt: number;
+  /** Clear only while this is still the head. */
+  ifLastIndex: number;
 };
 /** The versioned message protocol shared by scheduler adapters. */
-type SchedulerTask = SchedulerDrainTask | SchedulerAppendTask;
+type SchedulerTask = SchedulerDrainTask | SchedulerAppendTask | SchedulerClearTask;
 //#endregion
 //#region src/server.d.ts
+type PublicState<R> = undefined extends R ? never : R extends {
+  initialState: infer S;
+} ? S : never;
 /** What every handler receives. */
-type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>> = {
+type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>, S = 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>;
+  session: Session<D, HandlerAppend<D>, P, S>;
   /** 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 Handler<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>, S = never> = (ctx: HandlerContext<D, K, P, S>) => 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"> & {
@@ -125,10 +145,28 @@ type ScheduleTiming = {
   at: Date;
   delay?: never;
 };
-type SessionSchedule<D extends EventDefs> = (name: string, timing: ScheduleTiming, ...events: AppendInput<D>[]) => Promise<void>;
+type SessionSchedule<D extends EventDefs> = {
+  (name: string, timing: ScheduleTiming, ...events: AppendInput<D>[]): Promise<void>;
+  /**
+   * Publish a durable conditional clear. Delivery clears only while
+   * `ifLastIndex` is still the head, and finishes deleting before it
+   * acknowledges.
+   */
+  clear(name: string, options: ScheduleTiming & {
+    ifLastIndex: number;
+  }): Promise<void>;
+};
 type StateOptions = {
   through?: number | "latest";
 };
+type SessionClearOptions = {
+  /** Clear only while this is the head; a mismatch changes nothing. */
+  ifLastIndex?: number;
+};
+type SessionClearResult = {
+  cleared: boolean;
+  index: number;
+};
 /**
  * The presence members of a session — intersected in via
  * `WithPresence`, so they exist exactly when the contract declares
@@ -145,7 +183,7 @@ type SessionPresence<D extends EventDefs, P extends PresenceDefs> = {
   stream(opts: {
     startAfter?: number;
     presence: true;
-  }): AsyncIterable<ContractEvent<D> | PresencePatch<P> | PresenceSnapshot<P>>;
+  }): AsyncIterable<ContractEvent<D> | SessionCleared | 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`
@@ -162,25 +200,40 @@ type SessionPresence<D extends EventDefs, P extends PresenceDefs> = {
   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>> & {
+type Session<D extends EventDefs, Append = SessionAppend<D>, P extends PresenceDefs = Record<never, never>, S = never> = WithPresence<P, SessionPresence<D, P>> & {
   readonly id: string;
   append: Append;
   schedule: SessionSchedule<D>;
+  /**
+   * End the current lifetime: atomically append a clear marker, then
+   * delete the history below it. Indexes never restart.
+   */
+  clear(options?: SessionClearOptions): Promise<SessionClearResult>;
   history(options?: {
     gte?: number;
     lte?: number;
   }): Promise<ContractEvent<D>[]>;
-  state<S, V = S>(reducer: Reducer<D, S, Record<never, never>, V>, options?: StateOptions): Promise<{
-    state: S;
-    index: number;
-  }>;
+  state: {
+    <T>(reducer: Reducer<D, T, Record<never, never>>, options?: StateOptions): Promise<{
+      state: T;
+      index: number;
+      clearIndex?: number;
+    }>;
+  } & ([S] extends [never] ? unknown : {
+    (): Promise<{
+      state: S;
+      index: number;
+      clearIndex?: number;
+    }>;
+  });
   /**
    * A live feed of this session's events, starting after `startAfter`
    * (exclusive). Server-side only. `server.fetch` exposes it over SSE.
+   * A clear arrives as a `SessionCleared` marker.
    */
   stream(opts?: {
     startAfter?: number;
-  }): AsyncIterable<ContractEvent<D>>;
+  }): AsyncIterable<ContractEvent<D> | SessionCleared>;
 };
 /**
  * The public server shape scheduler handlers accept. It stays structural so
@@ -208,14 +261,14 @@ 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>> = {
+type A2Server<D extends EventDefs, P extends PresenceDefs = Record<never, never>, R extends RegisteredReducer<D, P> | undefined = RegisteredReducer<D, P> | undefined> = {
   /** The contract this server implements. */
-  readonly contract: Contract<D, P>;
+  readonly contract: Contract<D, P, R>;
   readonly fetch: {
     (request: Request): Promise<Response>;
     (request: Request, options: ServerFetchOptions<D, P>): Promise<Response>;
   };
-  session(id: string): Session<D, SessionAppend<D>, P>;
+  session(id: string): Session<D, SessionAppend<D>, P, PublicState<R>>;
   /**
    * Process every currently eligible event. `settled` means nothing
    * actionable remains, including work blocked behind a dead letter.
@@ -230,6 +283,14 @@ type A2Server<D extends EventDefs, P extends PresenceDefs = Record<never, never>
  * their transport envelope; application code normally uses `session.schedule`.
  */
 declare function deliverSchedulerAppend(server: DrainableServer, task: SchedulerAppendTask): Promise<void>;
+/**
+ * Deliver one authenticated scheduler clear: a conditional
+ * `clear({ ifLastIndex })` that resolves after its deletion finishes, so a
+ * provider retry resumes an interrupted deletion. Custom scheduler adapters
+ * call this after validating their transport envelope; application code uses
+ * `session.schedule.clear`.
+ */
+declare function deliverSchedulerClear(server: DrainableServer, task: SchedulerClearTask): Promise<void>;
 /**
  * Which events fire `ctx.signal` while a handler runs — the preemption
  * channel for user cancellation. The array form matches by type; the
@@ -241,11 +302,11 @@ declare function deliverSchedulerAppend(server: DrainableServer, task: Scheduler
 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> | {
+type HandlerEntry<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>, S = never> = Handler<D, K, P, S> | {
   abortOn?: AbortSpec<D, K>;
   /** Session-scoped FIFO key, resolved and persisted when the event lands. */
   lane?: Lane<D, K>;
-  handler: Handler<D, K, P>;
+  handler: Handler<D, K, P, S>;
 };
 type HandlerFunction = (ctx: never) => Promise<unknown>;
 declare function handler<H extends HandlerFunction | {
@@ -253,9 +314,9 @@ declare function handler<H extends HandlerFunction | {
 }>(entry: H): H extends HandlerFunction ? {
   handler: H;
 } : H;
-type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, never>> = {
+type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, never>, R extends RegisteredReducer<D, P> | undefined = RegisteredReducer<D, P> | undefined> = {
   /** The contract this server implements (see `a2.contract`). */
-  contract: Contract<D, P>;
+  contract: Contract<D, P, R>;
   /** Where events live. Defaults: sqlite in dev, memory in tests, required in prod. */
   store?: A2Store;
   /**
@@ -281,10 +342,10 @@ type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, n
    * 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>; };
+  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K, P, PublicState<R>>; };
 };
 /** 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>;
+declare function createServer<D extends EventDefs, P extends PresenceDefs = Record<never, never>, R extends RegisteredReducer<D, P> | undefined = RegisteredReducer<D, P> | undefined>(options: ServerOptions<D, P, R>): A2Server<D, P, R>;
 //#endregion
-export { ServerFetchOptions as A, ScheduledEvent as C, A2Operation as D, SchedulerTask as E, A2Socket as M, A2PushEvent as O, handler as S, SchedulerDrainTask as T, SessionPresence as _, Handler as a, createServer as b, HandlerEntry as c, ScheduleDelay as d, ScheduleTiming as f, SessionDispatch as g, SessionAppend as h, DrainableServer as i, UpgradeWebSocket as j, A2PushPresence as k, Lane as l, Session as m, A2Server as n, HandlerAppend as o, ServerOptions as p, AbortSpec as r, HandlerContext as s, A2Scheduler as t, LaneContext as u, SessionSchedule as v, SchedulerAppendTask as w, deliverSchedulerAppend as x, StateOptions as y };
-//# sourceMappingURL=server-DbD7IJVK.d.ts.map
+export { SchedulerTask as A, deliverSchedulerAppend as C, SchedulerAppendTask as D, ScheduledEvent as E, UpgradeWebSocket as F, A2Socket as I, A2PushEvent as M, A2PushPresence as N, SchedulerClearTask as O, ServerFetchOptions as P, createServer as S, handler as T, SessionClearResult as _, Handler as a, SessionSchedule as b, HandlerEntry as c, ScheduleDelay as d, ScheduleTiming as f, SessionClearOptions as g, SessionAppend as h, DrainableServer as i, A2Operation as j, SchedulerDrainTask as k, Lane as l, Session as m, A2Server as n, HandlerAppend as o, ServerOptions as p, AbortSpec as r, HandlerContext as s, A2Scheduler as t, LaneContext as u, SessionDispatch as v, deliverSchedulerClear as w, StateOptions as x, SessionPresence as y };
+//# sourceMappingURL=server-CGM8WzRG.d.ts.map

package/dist/server-CGM8WzRG.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-CGM8WzRG.d.ts","names":[],"sources":["../src/session-socket.ts","../src/server-fetch.ts","../src/scheduler-task.ts","../src/server.ts"],"mappings":"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"}