statewire 0.17.1 → 0.18.0

package/src/client/session.ts

@@ -1,4 +1,5 @@
 import { encodeDocument } from "../document";
+import { wrapStorageError } from "./storageError";
 import {
   DEFAULT_PROTOCOL,
   WIRE_VERSION,
@@ -58,7 +59,7 @@ type Pending = {
   /** The server acknowledged admission; the terminal verdict is still due. */
   applied: boolean;
   resolve: (payload: unknown) => void;
-  reject: (error: StatewireSendError) => void;
+  reject: (error: unknown) => void;
 };
 
 type CtxPending = {
@@ -100,6 +101,10 @@ type Session = {
   record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
   recordPersisted: boolean;
+  hydrated: boolean;
+  ready: Promise<void> | undefined;
+  storageError: unknown;
+  persistedRecord: StatewireClient.SessionRecord | null;
   store: StatewireClient.SessionStorage;
   documentStore: StatewireDocuments.Storage | undefined;
   shared: Shared | false;
@@ -162,9 +167,23 @@ const sleepUntilWake = (s: Session, delayMs: number) =>
     s.waiters.push(waiter);
   });
 
+const storageFailed = (s: Session, cause: unknown) => {
+  const error = wrapStorageError(cause);
+  s.storageError = error;
+  for (const entry of s.pending) entry.reject(error);
+  s.transport?.storageFailed(error);
+};
+
 const setRecord = (s: Session, record: StatewireClient.SessionRecord) => {
   s.record = record;
-  if (!s.deactivated) s.store.save(record);
+  if (!s.deactivated) {
+    try {
+      s.store.save(record);
+    } catch (cause) {
+      storageFailed(s, cause);
+      throw s.storageError;
+    }
+  }
 };
 
 const backlog = (s: Session): StatewireClient.SessionCommand[] =>
@@ -208,7 +227,7 @@ const syncBacklogInner = (s: Session) => {
 
 const syncBacklog = (s: Session) => {
   if (!s.shared) return syncBacklogInner(s);
-  void transact(s, () => syncBacklogInner(s));
+  transactBackground(s, () => syncBacklogInner(s));
 };
 
 // Every record mutation over shared storage is a locked read-modify-write.
@@ -241,13 +260,23 @@ const transact = (s: Session, fn: () => void): Promise<void> => {
         }
       }
       fn();
+      const persistence = s.store.flush?.();
+      if (persistence) await persistence;
     }),
   );
-  shared.txq = run.then(
+  const result = run.catch((cause: unknown) => {
+    storageFailed(s, cause);
+    throw s.storageError;
+  });
+  shared.txq = result.then(
     () => {},
     () => {},
   );
-  return run;
+  return result;
+};
+
+const transactBackground = (s: Session, fn: () => void, done?: () => void) => {
+  void transact(s, fn).then(done, () => {});
 };
 
 const setIdle = (s: Session, level: boolean) => {
@@ -305,7 +334,7 @@ const retainFailed = (
     retainFailedInner(s, entry, failure);
     return;
   }
-  void transact(s, () => retainFailedInner(s, entry, failure));
+  transactBackground(s, () => retainFailedInner(s, entry, failure));
 };
 
 const settleEntry = (
@@ -580,6 +609,32 @@ const publishIngested = (s: Session) => {
 // unloaded): held seqs resend as-is and the frame's answer arbitrates —
 // absorption where the record survived, a gap refusal where it did not.
 const snapCtxClock = (s: Session, ctxWm: number) => {
+  if (s.record.context?.recover === "version-1") {
+    const document = s.contextDocuments.documents.get(0);
+    if (s.contextDocuments.documents.size !== 1 || !document?.main)
+      throw new Error(
+        "statewire: version-1 context recovery requires one main document at doc 0",
+      );
+    const encoded = encodeDocument(document.value);
+    const ops = [
+      {
+        ...(ctxWm === 0
+          ? { op: "mount", protocol: document.protocol, main: true }
+          : { op: "replace", path: [] }),
+        ...encoded,
+      },
+    ];
+    s.ctxPending = [{ seq: ctxWm + 1, ops, posted: false }];
+    setRecord(s, {
+      ...s.record,
+      ctxNextSeq: ctxWm + 2,
+      context: {
+        ops: contextSnapshot(s.contextDocuments),
+        pending: s.ctxPending,
+      },
+    });
+    return;
+  }
   const ctxAligned =
     s.ctxPending.every((c, i) => c.seq === ctxWm + 1 + i) &&
     s.record.ctxNextSeq === ctxWm + s.ctxPending.length + 1;
@@ -671,7 +726,7 @@ const handleHello = (
     void pump(s);
     return;
   }
-  void transact(s, reconcile).then(() => {
+  transactBackground(s, reconcile, () => {
     publishIngested(s);
     void pump(s);
   });
@@ -718,13 +773,17 @@ const handleRefusal = (s: Session, syn: StatewireSyn) => {
     firstCtx !== undefined &&
     firstCtx.seq > ctxSeq + 1;
   if (cmdGap || ctxGap) {
-    void transact(s, () => {
-      if (cmdGap) sessionLostInner(s, seq!, ctxSeq ?? 0);
-      else snapCtxClock(s, ctxSeq!);
-    }).then(() => {
-      wake(s);
-      void pump(s);
-    });
+    transactBackground(
+      s,
+      () => {
+        if (cmdGap) sessionLostInner(s, seq!, ctxSeq ?? 0);
+        else snapCtxClock(s, ctxSeq!);
+      },
+      () => {
+        wake(s);
+        void pump(s);
+      },
+    );
     return;
   }
   wake(s);
@@ -755,10 +814,16 @@ type Lanes = {
 
 // A lane must be strictly consecutive within a frame: the first unposted run
 // per lane rides now, later runs ride follow-up frames.
-const buildLanes = (s: Session): Lanes | null => {
+const buildLanes = (s: Session, persisted = false): Lanes | null => {
   const ctxEntries: CtxPending[] = [];
   for (const entry of s.ctxPending) {
     if (entry.posted) continue;
+    if (
+      persisted &&
+      (s.persistedRecord?.clientId !== s.record.clientId ||
+        entry.seq >= s.persistedRecord.ctxNextSeq)
+    )
+      break;
     if (ctxEntries.length >= MAX_COMMANDS_PER_FRAME) break;
     if (ctxEntries.length > 0 && entry.seq !== ctxEntries.at(-1)!.seq + 1)
       break;
@@ -767,6 +832,12 @@ const buildLanes = (s: Session): Lanes | null => {
   const cmdEntries: Pending[] = [];
   for (const entry of s.pending) {
     if (entry.posted) continue;
+    if (
+      persisted &&
+      (s.persistedRecord?.clientId !== s.record.clientId ||
+        entry.seq >= s.persistedRecord.nextSeq)
+    )
+      break;
     if (cmdEntries.length >= MAX_COMMANDS_PER_FRAME) break;
     if (cmdEntries.length > 0 && entry.seq !== cmdEntries.at(-1)!.seq + 1)
       break;
@@ -794,8 +865,9 @@ const takeAttachLanes = (s: Session): StatewireFrame | null => {
   s.attachLaneSeqs = [new Set(), new Set()];
   const wanted = s.lanesOnAttach;
   s.lanesOnAttach = false;
-  if (!wanted || !s.sessionKnown) return null;
-  const lanes = buildLanes(s);
+  if (!wanted || !s.sessionKnown || s.record.context?.recover !== undefined)
+    return null;
+  const lanes = buildLanes(s, true);
   if (!lanes) return null;
   s.attachLaneSeqs = [
     new Set(lanes.cmdEntries.map((p) => p.seq)),
@@ -805,16 +877,38 @@ const takeAttachLanes = (s: Session): StatewireFrame | null => {
   return lanes.frame;
 };
 
+const persistBeforeSend = (s: Session): void | Promise<void> => {
+  if (s.storageError !== undefined) throw s.storageError;
+  if (!s.hydrated) return s.ready!.then(() => persistBeforeSend(s));
+  const record = s.record;
+  try {
+    const pending = s.store.flush?.();
+    if (pending)
+      return pending.then(
+        () => {
+          s.persistedRecord = record;
+        },
+        (cause: unknown) => {
+          throw wrapStorageError(cause);
+        },
+      );
+    s.persistedRecord = record;
+  } catch (cause) {
+    throw wrapStorageError(cause);
+  }
+};
+
 const pump = async (s: Session) => {
   if (s.pumping) return;
   s.pumping = true;
   try {
     while (s.running && !isFinished(s)) {
+      if (!s.hydrated) await s.ready;
       const transport = s.transport;
       if (buildLanes(s) === null) return;
       if (s.attach !== "attached" || !transport) {
         if (
-          (transport?.connection.status === "disconnected" &&
+          (transport?.connection.status === "standby" &&
             transport.connection.reason === "idle") ||
           (transport?.parked && s.pending.length > 0)
         ) {
@@ -831,6 +925,10 @@ const pump = async (s: Session) => {
       const lanes = buildLanes(s);
       if (!lanes) continue;
       const epoch = s.attachEpoch;
+      const persistence = persistBeforeSend(s);
+      if (persistence) await persistence;
+      if (!s.running || isFinished(s)) return;
+      if (epoch !== s.attachEpoch || s.attach !== "attached") continue;
       for (const entry of lanes.cmdEntries) entry.attempted = true;
       let result;
       try {
@@ -877,23 +975,39 @@ const pump = async (s: Session) => {
         }
       }
     }
+  } catch (error) {
+    storageFailed(s, error);
   } finally {
     s.pumping = false;
   }
 };
 
 const start = (s: Session) => {
+  s.running = true;
+  if (!s.hydrated) {
+    void s.ready!.then(
+      () => {
+        if (s.running) start(s);
+      },
+      () => {},
+    );
+    return;
+  }
   if (s.shared) {
     s.shared.unsubscribe = s.store.subscribe!(() => {
-      void transact(s, () => consumeVerdicts(s));
+      transactBackground(s, () => consumeVerdicts(s));
     });
     s.running = true;
-    void transact(s, () => {
-      if (s.store.load() === null) s.store.save(s.record);
-      s.recordPersisted = true;
-      adoptStored(s);
-      consumeVerdicts(s);
-    }).then(() => void pump(s));
+    transactBackground(
+      s,
+      () => {
+        if (s.store.load() === null) s.store.save(s.record);
+        s.recordPersisted = true;
+        adoptStored(s);
+        consumeVerdicts(s);
+      },
+      () => void pump(s),
+    );
     return;
   }
   if (!s.recordPersisted) {
@@ -926,7 +1040,7 @@ const enqueueInner = (
   command: WireCommand,
   params: readonly unknown[],
   resolve: (payload: unknown) => void,
-  reject: (error: StatewireSendError) => void,
+  reject: (error: unknown) => void,
 ) => {
   const seq = s.record.nextSeq;
   const entry: Pending = {
@@ -956,7 +1070,7 @@ const enqueue = (
   command: WireCommand,
   params: readonly unknown[],
   resolve: (payload: unknown) => void,
-  reject: (error: StatewireSendError) => void,
+  reject: (error: unknown) => void,
 ) => {
   if (!s.shared) {
     enqueueInner(s, command, params, resolve, reject);
@@ -977,7 +1091,7 @@ const enqueue = (
   }).then(() => {
     wake(s);
     void pump(s);
-  });
+  }, reject);
 };
 
 // A stored command may have reached a server: attempted settles it lost,
@@ -1026,6 +1140,18 @@ const sendCommand = (
   params: readonly unknown[],
   protocol = s.options.protocol ?? DEFAULT_PROTOCOL,
 ): Promise<unknown> => {
+  if (!s.hydrated) {
+    const result = s.ready!.then(() =>
+      sendCommand(s, method, params, protocol),
+    );
+    result.catch(() => {});
+    return result;
+  }
+  if (s.storageError !== undefined) {
+    const result = Promise.reject(s.storageError);
+    result.catch(() => {});
+    return result;
+  }
   if (!s.running) {
     return rejectedSend({ fate: "aborted", cause: "unmount" });
   }
@@ -1091,7 +1217,7 @@ export const discardFailed = (
     return;
   }
   if (findFailed(s, entry) === undefined) throw unknownFailed(entry);
-  void transact(s, () => {
+  transactBackground(s, () => {
     if (findFailed(s, entry) !== undefined) takeFailed(s, entry);
   });
 };
@@ -1180,6 +1306,9 @@ const persistContext = (s: Session) => {
     ...s.record,
     context: {
       ops,
+      ...(s.record.context?.recover === undefined
+        ? {}
+        : { recover: s.record.context.recover }),
       pending: s.ctxPending.map(({ seq, ops }) => ({ seq, ops })),
     },
   });
@@ -1189,6 +1318,16 @@ const changeContext = (
   s: Session,
   build: (documents: StatewireDocuments.State) => readonly unknown[],
 ): void => {
+  if (!s.hydrated) {
+    void s
+      .ready!.then(() => changeContext(s, build))
+      .catch((cause: unknown) => {
+        const error = wrapStorageError(cause);
+        s.storageError = error;
+        s.transport?.storageFailed(error);
+      });
+    return;
+  }
   if (!s.running || isFinished(s)) return;
   const submit = () => {
     if (!s.running || isFinished(s)) return;
@@ -1233,7 +1372,7 @@ const changeContext = (
     wake(s);
     void pump(s);
   } else
-    void transact(s, submit).then(() => {
+    transactBackground(s, submit, () => {
       wake(s);
       void pump(s);
     });
@@ -1328,6 +1467,52 @@ const storedCommandCompatible = (
   );
 };
 
+const loadSessionRecord = (
+  store: StatewireClient.SessionStorage,
+  options: StatewireSessionOptions,
+) => {
+  let stored = store.load();
+  if (stored !== null && !Array.isArray(stored.commands))
+    throw new Error(
+      "statewire: session storage loaded a record without a commands array",
+    );
+  const current = {
+    wire: options.wireVersion ?? { version: WIRE_VERSION },
+    protocols: protocolOffers(options),
+  };
+  if (
+    stored !== null &&
+    !stored.commands.every((command) =>
+      storedCommandCompatible(command, current),
+    )
+  ) {
+    if (!store.migrate)
+      throw new Error("statewire: stored commands require a storage migration");
+    stored = store.migrate(stored, current);
+    if (
+      stored !== null &&
+      !stored.commands.every((command) =>
+        storedCommandCompatible(command, current),
+      )
+    )
+      throw new Error("statewire: migrated commands are incompatible");
+    if (stored !== null) store.save(stored);
+  }
+  if (stored !== null && !Array.isArray(stored.commands)) {
+    throw new Error(
+      "statewire: session storage loaded a record without a commands array",
+    );
+  }
+  const record = stored ?? {
+    clientId: newClientId(),
+    nextSeq: 1,
+    ctxNextSeq: 1,
+    commands: [],
+  };
+  if (stored === null) store.save(record);
+  return { record, stored };
+};
+
 export const useStatewireSession = (
   options: StatewireSessionOptions,
 ): Session => {
@@ -1346,47 +1531,18 @@ export const useStatewireSession = (
     );
   }
   const [s] = useState((): Session => {
-    let stored = store.load();
-    if (stored !== null && !Array.isArray(stored.commands))
-      throw new Error(
-        "statewire: session storage loaded a record without a commands array",
-      );
-    const current = {
-      wire: options.wireVersion ?? { version: WIRE_VERSION },
-      protocols: protocolOffers(options),
-    };
-    if (
-      stored !== null &&
-      !stored.commands.every((command) =>
-        storedCommandCompatible(command, current),
-      )
-    ) {
-      if (!store.migrate)
-        throw new Error(
-          "statewire: stored commands require a storage migration",
-        );
-      stored = store.migrate(stored, current);
-      if (
-        stored !== null &&
-        !stored.commands.every((command) =>
-          storedCommandCompatible(command, current),
-        )
-      )
-        throw new Error("statewire: migrated commands are incompatible");
-      if (stored !== null) store.save(stored);
-    }
-    if (stored !== null && !Array.isArray(stored.commands)) {
-      throw new Error(
-        "statewire: session storage loaded a record without a commands array",
-      );
-    }
-    const record = stored ?? {
-      clientId: newClientId(),
-      nextSeq: 1,
-      ctxNextSeq: 1,
-      commands: [],
-    };
-    if (stored === null) store.save(record);
+    const { record, stored } =
+      store.ready === undefined
+        ? loadSessionRecord(store, options)
+        : {
+            record: {
+              clientId: newClientId(),
+              nextSeq: 1,
+              ctxNextSeq: 1,
+              commands: [],
+            },
+            stored: null,
+          };
     const session: Session = {
       options,
       selection: undefined,
@@ -1399,6 +1555,7 @@ export const useStatewireSession = (
             ),
       record,
       ctx: {
+        beforeAttach: () => persistBeforeSend(session),
         get clientId() {
           return session.record.clientId;
         },
@@ -1411,7 +1568,11 @@ export const useStatewireSession = (
         onDetach: () => handleDetach(session),
         onFinish: (args) => handleFinish(session, args),
       },
-      recordPersisted: stored !== null,
+      recordPersisted: store.ready === undefined,
+      hydrated: store.ready === undefined,
+      ready: undefined,
+      storageError: undefined,
+      persistedRecord: store.ready === undefined ? record : null,
       store,
       documentStore,
       shared:
@@ -1461,6 +1622,35 @@ export const useStatewireSession = (
         sendCommand(session, method, params),
       ),
     };
+    if (store.ready !== undefined) {
+      session.ready = store.ready.then(() => {
+        const { record } = loadSessionRecord(store, session.options);
+        session.record = record;
+        session.contextDocuments =
+          record.context === undefined
+            ? { mode: "mounted", documents: new Map() }
+            : applyDocumentOps(
+                { mode: "mounted", documents: new Map() },
+                record.context.ops,
+              );
+        session.ctxOps = record.context?.ops;
+        session.ctxPending =
+          record.context?.pending.map((entry) => ({
+            ...entry,
+            posted: false,
+          })) ?? [];
+        session.recordPersisted = true;
+        session.hydrated = true;
+        if (session.running) session.notify();
+      });
+      session.ready = session.ready.catch((cause: unknown) => {
+        const error = wrapStorageError(cause);
+        session.storageError = error;
+        session.transport?.storageFailed(error);
+        throw error;
+      });
+      session.ready.catch(() => {});
+    }
     bindCommandsHost(session.commands, {
       setListener: (listener) => {
         session.lifecycle = listener;

package/src/client/storageError.ts

@@ -0,0 +1,9 @@
+export const isStorageError = (error: unknown): error is Error =>
+  error instanceof Error && error.name === "StatewireStorageError";
+
+export const wrapStorageError = (cause: unknown): Error => {
+  if (isStorageError(cause)) return cause;
+  const error = new Error("statewire: session storage failed", { cause });
+  error.name = "StatewireStorageError";
+  return error;
+};

package/src/statewire.ts

@@ -303,36 +303,37 @@ export namespace StatewireClient {
     discardFailed: (entry: FailedCommand) => void;
   };
 
-  /** `cause`/`nextRetryAt`/`lastError` are present only while waiting out the backoff timer; a dial in flight carries `attempt` alone. */
+  /** Connection lifecycle and whether its current state warrants a problem indicator. */
   export type ConnectionState =
+    | { status: "standby"; reason: "deferred" | "idle"; degraded: false }
+    | { status: "connecting"; degraded: false }
+    | { status: "connected"; degraded: false }
     | {
-        status: "disconnected";
-        reason:
-          | "deferred"
-          | "idle"
-          | "gone"
-          | "forbidden"
-          | "protocol-error"
-          | "unauthorized";
-        message?: string;
-        payload?: unknown;
-      }
-    | {
-        status: "connecting";
-        /** 0 = the episode's first dial, >0 = retry. */
+        status: "retrying";
+        degraded: true;
         attempt: number;
+        /** Backoff details are absent while the retry dial is in flight. */
         cause?: "dropped" | "reconnect" | "error" | "unauthorized";
         code?: string;
         nextRetryAt?: number;
         lastError?: string;
         message?: string;
       }
-    | { status: "connected" };
+    | {
+        status: "stopped";
+        degraded: true;
+        reason:
+          | "gone"
+          | "forbidden"
+          | "protocol-error"
+          | "unauthorized"
+          | "storage-error";
+        message?: string;
+        payload?: unknown;
+      };
   export type Connection = ConnectionState & {
     error?: ConnectionError;
     reconnect: () => void;
-    /** True while retrying (`connecting` with `attempt > 0`) or parked `gone`. */
-    degraded: boolean;
   };
   export type ConnectionStatus = Connection["status"];
 
@@ -436,7 +437,12 @@ export namespace StatewireClient {
     clientId: string;
     nextSeq: number;
     ctxNextSeq: number;
-    context?: { ops: unknown[]; pending: { seq: number; ops: unknown[] }[] };
+    context?: {
+      ops: unknown[];
+      pending: { seq: number; ops: unknown[] }[];
+      /** Recover the original wire's unpersisted single-document context after the next hello. */
+      recover?: "version-1";
+    };
     commands: readonly SessionCommand[];
     /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
     verdicts?: readonly SessionVerdict[];
@@ -454,8 +460,12 @@ export namespace StatewireClient {
     meta?: unknown;
   };
 
-  /** Session storage seam; `save` must persist synchronously in the caller's flow. */
+  /** Session storage seam with optional asynchronous hydration and persistence. */
   export type SessionStorage = {
+    /** Resolves when a synchronous load can return the hydrated record. */
+    ready?: Promise<void>;
+    /** Resolves after all queued saves are persisted; awaited before sending statements. */
+    flush?: () => void | Promise<void>;
     load: () => SessionRecord | null;
     save: (record: SessionRecord) => void;
     /** Upgrade incompatible stored commands; null discards the old record and starts a new client identity. */
@@ -470,7 +480,7 @@ export namespace StatewireClient {
   };
 
   /** Static headers, or a resolver invoked per request/attach; `staleAuth` is true right after an auth rejection. */
-  export type ConnectionError = Error & { fin: StatewireHost.Fin };
+  export type ConnectionError = Error & { fin?: StatewireHost.Fin };
 
   export type HeadersOption =
     | HeadersInit