statewire 0.0.4 → 0.4.0

package/src/client/session.ts

@@ -147,6 +147,12 @@ const rejectedSend = (
 
 type AttachState = "detached" | "attached" | "finished";
 
+export type StatewireSessionOptions = StatewireSessionStoreOptions & {
+  onCommandSessionLost?:
+    | ((command: StatewireClient.SessionLostCommand) => "replay" | void)
+    | undefined;
+};
+
 type Session = {
   record: StatewireSessionRecord;
   ctx: StatewireRemoteProps;
@@ -166,13 +172,14 @@ type Session = {
   transport: RemoteLink | null;
   waiters: (() => void)[];
   lifecycle: CommandsListener | null;
+  onCommandSessionLost: StatewireSessionOptions["onCommandSessionLost"];
   notify: () => void;
   emitEvent: (event: unknown) => void;
   send: (command: StatewireWireCommand) => Promise<unknown>;
   commands: Record<string, (...params: unknown[]) => Promise<unknown>>;
 };
 
-const createSession = (options: StatewireSessionStoreOptions): Session => {
+const createSession = (options: StatewireSessionOptions): Session => {
   const store = options.sessionStore ?? createMemorySessionStore();
   const stored = store.load();
   const record = stored ?? { clientId: newClientId(), nextSeq: 1 };
@@ -212,6 +219,7 @@ const createSession = (options: StatewireSessionStoreOptions): Session => {
     transport: null,
     waiters: [],
     lifecycle: null,
+    onCommandSessionLost: options.onCommandSessionLost,
     notify: () => {},
     emitEvent: () => {},
     send: (command) => sendCommand(s, command),
@@ -274,10 +282,12 @@ const settleAll = (
     if (state.at === "awaiting-result")
       return { fate: "result-unavailable", cause };
     if (state.at === "queued") {
-      const cascades = batch.some(
+      const predecessorLost = batch.some(
         (p) => p.seq < entry.seq && p.state.at !== "queued",
       );
-      return { fate: "aborted", cause: cascades ? "cascade" : cause };
+      return predecessorLost
+        ? { fate: "aborted", cause, predecessorLost }
+        : { fate: "aborted", cause };
     }
     return { fate: "lost", cause };
   };
@@ -288,6 +298,27 @@ const settleAll = (
   }
 };
 
+// Offers every unsettled real command for replay, in seq order. Not caught:
+// a throwing callback aborts the eviction before any entry settles; the
+// attach retry evicts again and re-offers.
+const claimReplays = (s: Session): Pending[] => {
+  const handler = s.onCommandSessionLost;
+  if (!handler) return [];
+  const claimed = new Set<Pending>();
+  for (const entry of s.pending) {
+    if (!entry.inv || isResolved(entry.state)) continue;
+    const decision = handler({
+      method: entry.inv.method,
+      params: [...entry.inv.params],
+      seq: entry.seq,
+    });
+    if (decision === "replay") claimed.add(entry);
+  }
+  if (claimed.size === 0) return [];
+  s.pending = s.pending.filter((p) => !claimed.has(p));
+  return [...claimed];
+};
+
 const evict = (
   s: Session,
   verdict?: {
@@ -295,6 +326,7 @@ const evict = (
     failure: StatewireClient.SendFailure;
   },
 ) => {
+  const replays = claimReplays(s);
   settleAll(s, "evicted", verdict);
   s.record = { clientId: newClientId(), nextSeq: 1 };
   s.store.save(s.record);
@@ -302,6 +334,10 @@ const evict = (
   // The server dropped this client's record and its stored context with it:
   // the new session opens with a fresh full root replace.
   if (s.context !== undefined) void s.send({ context: s.context });
+  for (const old of replays) {
+    if (old.inv) s.lifecycle?.onCovered?.(old.inv);
+    enqueue(s, old.command, old.resolve, old.reject);
+  }
   publish(s);
   wake(s);
 };
@@ -645,16 +681,12 @@ const setTransport = (s: Session, transport: RemoteLink) => {
   wake(s);
 };
 
-const sendCommand = (
+const enqueue = (
   s: Session,
   command: StatewireWireCommand,
-): Promise<unknown> => {
-  if (!s.running) {
-    return rejectedSend({ fate: "aborted", cause: "unmount" });
-  }
-  if (isFinished(s)) {
-    return rejectedSend({ fate: "aborted", cause: "stream-gone" });
-  }
+  resolve: (payload: unknown) => void,
+  reject: (error: StatewireSendError) => void,
+) => {
   const seq = s.record.nextSeq;
   s.record = { ...s.record, nextSeq: seq + 1 };
   s.store.save(s.record);
@@ -672,17 +704,28 @@ const sendCommand = (
             clientId: s.record.clientId,
           },
     state: { at: "queued", pendingMarked: false },
-    resolve: () => {},
-    reject: () => {},
+    resolve,
+    reject,
   };
-  const result = new Promise<unknown>((resolve, reject) => {
-    entry.resolve = resolve;
-    entry.reject = reject;
-  });
-  result.catch(() => {});
   s.pending.push(entry);
   if (entry.inv) s.lifecycle?.onStart(entry.inv);
   void pump(s);
+};
+
+const sendCommand = (
+  s: Session,
+  command: StatewireWireCommand,
+): Promise<unknown> => {
+  if (!s.running) {
+    return rejectedSend({ fate: "aborted", cause: "unmount" });
+  }
+  if (isFinished(s)) {
+    return rejectedSend({ fate: "aborted", cause: "stream-gone" });
+  }
+  const result = new Promise<unknown>((resolve, reject) => {
+    enqueue(s, command, resolve, reject);
+  });
+  result.catch(() => {});
   return result;
 };
 
@@ -698,10 +741,11 @@ const setContext = (
 };
 
 export const useStatewireSession = (
-  options: StatewireSessionStoreOptions,
+  options: StatewireSessionOptions,
   emit: (event: unknown) => void,
 ): Session => {
   const [s] = useState(() => createSession(options));
+  s.onCommandSessionLost = options.onCommandSessionLost;
   useEffect(() => {
     s.emitEvent = emit;
     return () => {

package/src/host/host.ts

@@ -102,82 +102,10 @@ export const useStatewireState = <TState>(
 
 // ─── commands ───────────────────────────────────────────
 
-type ExecutionSettled =
+type Settled =
   | { type: "resolved"; value: unknown }
   | { type: "rejected"; error: unknown };
 
-type ExecutionBind = {
-  onAck: () => void;
-  onSettle: (settled: ExecutionSettled) => void;
-};
-
-type ExecutionState = {
-  acked: boolean;
-  settled: ExecutionSettled | null;
-  bind: ExecutionBind | null;
-};
-
-const executionStates = new WeakMap<object, ExecutionState>();
-
-/**
- * `CommandExecution(executor)` runs the (possibly async) `executor({ ack })`
- * immediately: its return value resolves the execution, a throw/rejection
- * rejects it; `ack()` releases the client's ack watermark before the executor
- * finishes. `CommandExecution.withResolvers()` returns `[execution,
- * { ack, resolve, reject }]` instead — settle them from your own spawned work.
- */
-export const CommandExecution = Object.assign(
-  <T = void>(
-    executor: (resolvers: {
-      ack: () => void;
-    }) => T | void | PromiseLike<T | void>,
-  ): StatewireHost.Execution<T> => {
-    const state: ExecutionState = { acked: false, settled: null, bind: null };
-    const execution = Object.freeze(
-      {},
-    ) as unknown as StatewireHost.Execution<T>;
-    executionStates.set(execution, state);
-    const settle = (settled: ExecutionSettled) => {
-      if (state.settled) return;
-      state.settled = settled;
-      state.acked = true;
-      state.bind?.onSettle(settled);
-    };
-    const ack = () => {
-      if (state.acked) return;
-      state.acked = true;
-      state.bind?.onAck();
-    };
-    void (async () => {
-      try {
-        settle({ type: "resolved", value: await executor({ ack }) });
-      } catch (error) {
-        settle({ type: "rejected", error });
-      }
-    })();
-    return execution;
-  },
-  {
-    withResolvers: <T = void>(): [
-      StatewireHost.Execution<T>,
-      StatewireHost.ExecutionResolvers<T>,
-    ] => {
-      let resolve!: (value: T) => void;
-      let reject!: (error: unknown) => void;
-      const promise = new Promise<T>((res, rej) => {
-        resolve = res;
-        reject = rej;
-      });
-      let ack!: () => void;
-      const execution = CommandExecution<T>(({ ack: a }) => {
-        ack = a;
-        return promise;
-      });
-      return [execution, { ack: () => ack(), resolve, reject }];
-    },
-  },
-);
-
 export type CommandsInvocation = {
   readonly method: string;
   readonly params: readonly unknown[];
@@ -250,6 +178,9 @@ const STALL_WARN_MS = 5000;
 
 // In-process dispatch has no wire client: never any ambient context, trivially attached.
 const LOCAL_CALLER: StatewireHost.Caller = Object.freeze({
+  get clientId(): string {
+    throw new Error("statewire: in-process dispatch has no client id");
+  },
   context: null,
   isConnected: true,
 });
@@ -276,7 +207,7 @@ const settleInvocation = (
   cell: CommandsCell,
   inv: ActiveInvocation,
   call: QueuedCall,
-  settled: ExecutionSettled,
+  settled: Settled,
 ) => {
   ackInvocation(cell, inv);
   if (settled.type === "resolved") {
@@ -296,14 +227,13 @@ const settleInvocation = (
   }
 };
 
-const pump = (cell: CommandsCell) => {
-  if (cell.running || !cell.handlers) {
-    watchStall(cell);
-    return;
-  }
-  const call = cell.queue.shift();
-  if (!call) return;
-  const handler = cell.handlers[call.method];
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as { then?: unknown }).then === "function";
+
+const dispatch = (cell: CommandsCell, call: QueuedCall) => {
+  const handler = cell.handlers![call.method];
   if (handler === undefined) {
     const error = new StatewireSendError({
       fate: "unknown-command",
@@ -311,7 +241,6 @@ const pump = (cell: CommandsCell) => {
     });
     call.origin?.onSettle?.({ type: "rejected", error });
     call.reject(error);
-    pump(cell);
     return;
   }
   const inv: ActiveInvocation = {
@@ -325,39 +254,55 @@ const pump = (cell: CommandsCell) => {
       clientId: call.origin.clientId,
     }),
   };
-  cell.running = true;
   cell.listener?.onStart(inv);
   cell.listener?.onPosted?.(inv);
   cell.listener?.onCovered?.(inv);
-  void (async () => {
-    try {
-      const value = await (
-        handler as (...args: readonly unknown[]) => unknown
-      ).call(call.origin?.caller ?? LOCAL_CALLER, ...call.params);
-      const execution =
-        typeof value === "object" && value !== null
-          ? executionStates.get(value)
-          : undefined;
-      if (execution) {
-        if (execution.acked) ackInvocation(cell, inv);
-        if (execution.settled) {
-          settleInvocation(cell, inv, call, execution.settled);
-        } else {
-          execution.bind = {
-            onAck: () => ackInvocation(cell, inv),
-            onSettle: (settled) => settleInvocation(cell, inv, call, settled),
-          };
-        }
-      } else {
-        settleInvocation(cell, inv, call, { type: "resolved", value });
-      }
-    } catch (error) {
-      settleInvocation(cell, inv, call, { type: "rejected", error });
-    } finally {
-      cell.running = false;
-      pump(cell);
+  const ctx: StatewireHost.Ctx = {
+    caller: call.origin?.caller ?? LOCAL_CALLER,
+    ack: () => ackInvocation(cell, inv),
+  };
+  try {
+    const value = (
+      handler as (
+        this: StatewireHost.Ctx,
+        ...args: readonly unknown[]
+      ) => unknown
+    ).call(ctx, ...call.params);
+    if (isThenable(value)) {
+      value.then(
+        (resolved) =>
+          settleInvocation(cell, inv, call, {
+            type: "resolved",
+            value: resolved,
+          }),
+        (error: unknown) =>
+          settleInvocation(cell, inv, call, { type: "rejected", error }),
+      );
+    } else {
+      settleInvocation(cell, inv, call, { type: "resolved", value });
+    }
+  } catch (error) {
+    settleInvocation(cell, inv, call, { type: "rejected", error });
+  }
+};
+
+// Prefix-only advancement: each handler runs synchronously to its first
+// await, then the pump moves on; settlement rides the returned promise.
+const pump = (cell: CommandsCell) => {
+  if (cell.running || !cell.handlers) {
+    watchStall(cell);
+    return;
+  }
+  cell.running = true;
+  try {
+    while (cell.handlers) {
+      const call = cell.queue.shift();
+      if (!call) break;
+      dispatch(cell, call);
     }
-  })();
+  } finally {
+    cell.running = false;
+  }
 };
 
 const watchStall = (cell: CommandsCell) => {
@@ -375,7 +320,7 @@ const watchStall = (cell: CommandsCell) => {
 
 export const useStatewireCommands = <THandlers extends Statewire.Commands>(
   commands:
-    | (THandlers & ThisType<StatewireHost.Caller>)
+    | (THandlers & ThisType<StatewireHost.Ctx>)
     | undefined
     | null
     | false,

package/src/host/socket.ts

@@ -387,6 +387,7 @@ const createSocketHost = (
   ) => settleResponse(rec, adm, responseOf(adm, outcome));
 
   const callerOf = (rec: ClientRec): StatewireHost.Caller => ({
+    clientId: rec.id,
     get context() {
       return rec.context;
     },

package/src/host.ts

@@ -4,17 +4,12 @@ import type { ServerOp } from "./host/draft";
 export { StatewireReject } from "./host/engine";
 export { append } from "./host/draft";
 export {
-  CommandExecution,
   getStateHost,
   useStatewireState,
   useStatewireCommands,
   useStatewireEmit,
 } from "./host/host";
 
-declare const executionResult: unique symbol;
-
-type UnwrapExecution<V> = V extends StatewireHost.Execution<infer T> ? T : V;
-
 export namespace StatewireHost {
   export type StateCtl<TState = unknown> = {
     /** Apply server-vocabulary ops (root replace = whole-state swap). */
@@ -31,28 +26,25 @@ export namespace StatewireHost {
   export type StateSource = Statewire.StateSource;
 
   /**
-   * Handle a command handler returns to keep the command open past its own
-   * return: `ack()` releases the client's optimistic overlay / ack watermark,
-   * `resolve`/`reject` settle the command (and imply ack). `ack` is idempotent
-   * and a no-op after settle.
+   * Per-invocation handle bound as `this` of a command handler: `caller` is
+   * the submitting client, `ack()` releases the client's optimistic overlay /
+   * ack watermark before the handler settles (idempotent, a no-op after
+   * settle). The command settles when the handler's returned promise does.
    */
-  export type Execution<T = void> = {
-    readonly [executionResult]: (value: T) => void;
-  };
-
-  export type ExecutionResolvers<T = void> = {
-    ack: () => void;
-    resolve: (value: T) => void;
-    reject: (error: unknown) => void;
+  export type Ctx = {
+    readonly caller: Caller;
+    readonly ack: () => void;
   };
 
   /**
-   * The submitting client, bound as `this` of a command handler. Holdable
-   * across a long run: `context` reads the client's current ambient context
-   * live (null until the client sends one), `isConnected` reports whether the
-   * client has an active stream attachment.
+   * The submitting client (`this.caller` in a command handler). Holdable
+   * across a long run: `clientId` is the client's `Statewire-Client-Id`
+   * (in-process dispatch has none — reading it throws), `context` reads the
+   * client's current ambient context live (null until the client sends one),
+   * `isConnected` reports whether the client has an active stream attachment.
    */
   export type Caller = {
+    readonly clientId: string;
     readonly context: Record<string, unknown> | null;
     readonly isConnected: boolean;
   };
@@ -60,7 +52,7 @@ export namespace StatewireHost {
   export type HandledCommands<THandlers extends Statewire.Commands> = {
     [K in keyof THandlers]: (
       ...args: Parameters<THandlers[K]>
-    ) => UnwrapExecution<Awaited<ReturnType<THandlers[K]>>>;
+    ) => Awaited<ReturnType<THandlers[K]>>;
   };
 
   export type Fin = {

package/src/statewire.ts

@@ -194,23 +194,31 @@ export namespace StatewireClient {
       }
     | {
         fate: "aborted";
-        cause:
-          | "cascade"
-          | "unmount"
-          | "stream-gone"
-          | "session-lost"
-          | "superseded";
+        cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
+        predecessorLost?: true;
       }
     | {
         fate: "lost";
         cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
       };
 
+  /**
+   * A pending command offered for replay while the session is being evicted.
+   * Return "replay" to re-enqueue it under the rotated client id instead of
+   * settling it as a session-lost failure.
+   */
+  export type SessionLostCommand = {
+    method: string;
+    params: unknown[];
+    seq: number;
+  };
+
   export type SSEOptions = StatewireSessionStoreOptions & {
     url: string;
     headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
     fetch?: typeof globalThis.fetch;
     onChange?: (connection: Connection) => void;
+    onCommandSessionLost?: (command: SessionLostCommand) => "replay" | void;
   };
 
   export type WSOptions = StatewireSessionStoreOptions & {
@@ -221,5 +229,6 @@ export namespace StatewireClient {
       | (() => Record<string, string> | Promise<Record<string, string>>);
     webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
     onChange?: (connection: Connection) => void;
+    onCommandSessionLost?: (command: SessionLostCommand) => "replay" | void;
   };
 }

package/src/transports/remote.ts

@@ -6,7 +6,7 @@ import {
   setTransport,
   useStatewireSession,
 } from "../client/session";
-import type { StatewireSessionStoreOptions } from "../client/sessionStore";
+import type { StatewireSessionOptions } from "../client/session";
 import type { StatewireClient } from "../statewire";
 import type { RemoteLink, StatewireRemoteProps } from "./sse";
 
@@ -14,13 +14,19 @@ export const useStatewireRemote = <
   TOptions extends {
     url: string;
     onChange?: (connection: StatewireClient.Connection) => void;
-  } & StatewireSessionStoreOptions,
+  } & StatewireSessionOptions,
 >(
   options: TOptions,
   useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
 ): Statewire<any, any, any> => {
   const emit = useStatewireEmit<any>();
-  const s = useStatewireSession({ sessionStore: options.sessionStore }, emit);
+  const s = useStatewireSession(
+    {
+      sessionStore: options.sessionStore,
+      onCommandSessionLost: options.onCommandSessionLost,
+    },
+    emit,
+  );
   const conn = useLink(options, s.ctx);
   useEffect(() => setTransport(s, conn), [s, conn]);