statewire 0.12.0 → 0.13.0

package/src/client/core.ts

@@ -15,6 +15,8 @@ export const LIVE_CONNECTION: StatewireClient.Connection = {
   reconnect: () => {},
 };
 
+const NO_FAILED: readonly StatewireClient.FailedCommand[] = [];
+
 const failureOf = (error: unknown): StatewireClient.SendFailure =>
   error instanceof StatewireSendError
     ? error.failure
@@ -40,6 +42,7 @@ type Core = {
   notifiedOverlayPaths: readonly StatewirePath[];
   notifiedConnection: StatewireClient.Connection | null;
   notifiedBusy: boolean;
+  notifiedFailed: readonly StatewireClient.FailedCommand[];
   stale: boolean;
   everAttached: boolean;
   overlaysDirty: boolean;
@@ -50,6 +53,7 @@ type Core = {
   commandsListener: CommandsListener;
   getState: () => unknown;
   getBusy: () => boolean;
+  getFailed: () => readonly StatewireClient.FailedCommand[];
   commands: Statewire.CommandsProxy<any>;
   subscribe: (listener: () => void) => () => void;
 };
@@ -89,11 +93,21 @@ const drainCanonical = (c: Core) => {
   }
 };
 
+const dropCovered = (c: Core) => {
+  const { failureCovered } = c.getOptions();
+  const failures = c.value?.failures;
+  if (!failureCovered || !failures || c.canonical === undefined) return;
+  for (const entry of failures.list()) {
+    if (failureCovered(c.canonical as never, entry)) failures.discard(entry);
+  }
+};
+
 const recompute = (c: Core) => {
   if (!c.stale || !c.value) return;
   c.stale = false;
   const prevCanonical = c.canonical;
   drainCanonical(c);
+  if (c.canonical !== prevCanonical) dropCovered(c);
   if (c.canonical === prevCanonical && !c.overlaysDirty) return;
   c.overlaysDirty = false;
   const { optimistic, materialize } = c.getOptions();
@@ -148,7 +162,7 @@ const recompute = (c: Core) => {
 const getConnection = (c: Core): StatewireClient.Connection =>
   c.value?.connection ?? LIVE_CONNECTION;
 
-const flush = (c: Core) => {
+const flush = (c: Core, scheduled = false) => {
   if (!c.value) return;
   if (c.flushing) {
     schedule(c);
@@ -187,7 +201,19 @@ const flush = (c: Core) => {
     const busy = c.getBusy();
     const busyChanged = busy !== c.notifiedBusy;
     c.notifiedBusy = busy;
-    if (stateChanged || connectionChanged || busyChanged) {
+    // The failed snapshot advances only on the scheduled pass: settles land
+    // mid-unmount, where a changed snapshot re-renders the unmounting tree.
+    const failed = c.value.failures?.list() ?? NO_FAILED;
+    let failedChanged = false;
+    if (failed !== c.notifiedFailed) {
+      if (scheduled) {
+        c.notifiedFailed = failed;
+        failedChanged = true;
+      } else {
+        schedule(c);
+      }
+    }
+    if (stateChanged || connectionChanged || busyChanged || failedChanged) {
       for (const listener of [...c.listeners]) listener();
     }
   } finally {
@@ -271,6 +297,7 @@ export const useStatewireCore = (
       notifiedOverlayPaths: [],
       notifiedConnection: null,
       notifiedBusy: true,
+      notifiedFailed: NO_FAILED,
       stale: false,
       everAttached: false,
       overlaysDirty: false,
@@ -279,7 +306,7 @@ export const useStatewireCore = (
       listeners: new Set(),
       post: createMacrotaskPoster(() => {
         c.scheduled = false;
-        flush(c);
+        flush(c, true);
       }),
       commandsListener: {
         onStart: (inv) => {
@@ -313,6 +340,7 @@ export const useStatewireCore = (
         return c.published;
       },
       getBusy: () => c.value?.isBusy ?? true,
+      getFailed: () => c.notifiedFailed,
       commands: createMethodProxy<Statewire.CommandsProxy<any>>(
         (method, params) => {
           if (!c.value) {

package/src/client/session.ts

@@ -232,6 +232,34 @@ const cover = (s: Session, entry: Pending) => {
   s.lifecycle?.onCovered?.(entry.inv);
 };
 
+const NO_FAILED: readonly StatewireClient.FailedCommand[] = [];
+
+export const failedCommands = (
+  s: Session,
+): readonly StatewireClient.FailedCommand[] => s.record.failed ?? NO_FAILED;
+
+const retainFailed = (
+  s: Session,
+  entry: Pending,
+  failure: StatewireClient.SendFailure,
+) => {
+  setRecord(s, {
+    ...s.record,
+    failed: [
+      ...(s.record.failed ?? []),
+      {
+        command: entry.command.method,
+        params: entry.command.params,
+        ...(entry.command.meta !== undefined && { meta: entry.command.meta }),
+        failure,
+        ts: entry.inv.ts,
+        seq: entry.seq,
+      },
+    ],
+  });
+  s.notify();
+};
+
 const settleEntry = (
   s: Session,
   entry: Pending,
@@ -247,6 +275,13 @@ const settleEntry = (
       payload: outcome.payload,
     });
   } else {
+    // A statement the record still carries resends on the next attach; only
+    // invocations the record no longer owns become failed history.
+    const rides =
+      (outcome.failure.cause === "unmount" ||
+        outcome.failure.cause === "stream-gone") &&
+      entry.seq > s.durableSeq;
+    if (!rides) retainFailed(s, entry, outcome.failure);
     entry.reject(new StatewireSendError(outcome.failure));
     s.lifecycle?.onSettle(entry.inv, {
       type: "rejected",
@@ -307,7 +342,15 @@ const rebaseRecord = (s: Session, adopt: () => void) => {
   );
   s.pending = [];
   s.durableSeq = 0;
+  // Failed entries are user-owned history: they ride through every record replacement.
+  const failed = s.record.failed;
   adopt();
+  if (failed !== undefined && s.record.failed !== failed) {
+    setRecord(s, {
+      ...s.record,
+      failed: [...(s.record.failed ?? []), ...failed],
+    });
+  }
   for (const old of survivors) {
     s.lifecycle?.onCovered?.(old.inv);
     enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
@@ -475,6 +518,7 @@ const sessionLostInner = (s: Session, seqWm: number, ctxWm: number) => {
     nextSeq: seqWm + 1,
     ctxNextSeq: ctxWm + 1,
     commands: [],
+    ...(s.record.failed !== undefined && { failed: s.record.failed }),
   });
   restateContext(s);
   if (
@@ -876,6 +920,62 @@ const sendCommand = (
   return result;
 };
 
+const takeFailed = (
+  s: Session,
+  entry: StatewireClient.FailedCommand,
+): StatewireClient.FailedCommand => {
+  const failed = s.record.failed ?? [];
+  const found = failed.find(
+    (f) =>
+      f.seq === entry.seq && f.ts === entry.ts && f.command === entry.command,
+  );
+  if (found === undefined) {
+    throw new Error(`statewire: unknown failed command "${entry.command}"`);
+  }
+  setRecord(s, { ...s.record, failed: failed.filter((f) => f !== found) });
+  s.notify();
+  return found;
+};
+
+export const discardFailed = (
+  s: Session,
+  entry: StatewireClient.FailedCommand,
+): void => {
+  takeFailed(s, entry);
+};
+
+export const retryFailed = (
+  s: Session,
+  entry: StatewireClient.FailedCommand,
+): Promise<unknown> => {
+  if (!s.running) {
+    return rejectedSend({ fate: "aborted", cause: "unmount" });
+  }
+  if (isFinished(s)) {
+    return rejectedSend({ fate: "aborted", cause: "stream-gone" });
+  }
+  const found = takeFailed(s, entry);
+  const params =
+    found.meta === undefined
+      ? found.params
+      : (reviveValue([...found.params], found.meta) as unknown[]);
+  const result = new Promise<unknown>((resolve, reject) => {
+    enqueue(
+      s,
+      {
+        method: found.command,
+        params: [...found.params],
+        ...(found.meta !== undefined && { meta: found.meta }),
+      },
+      params,
+      resolve,
+      reject,
+    );
+  });
+  result.catch(() => {});
+  return result;
+};
+
 const setContext = (s: Session, value: Record<string, unknown>): void => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error("statewire: context must be a plain object");

package/src/host/draft.ts

@@ -30,6 +30,16 @@ const invalid = (path: StatewirePath, message: string) =>
 
 type Container = Record<string | number, unknown>;
 
+// Text-insert offsets are Unicode code points on the wire, not UTF-16 units.
+const codePointLength = (text: string): number => {
+  let count = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    if (text.codePointAt(index)! > 0xffff) index += 1;
+    count += 1;
+  }
+  return count;
+};
+
 type Node = {
   parent: Node | null;
   key: string | number;
@@ -96,7 +106,11 @@ export const createStateDraft = <T>(host: DraftHost): StateDraft<T> => {
     if (suffix === "") return;
     prepareForWrite(node)[key] = existing + suffix;
     host.record(
-      { op: "add", path: [...node.path, key, existing.length], value: suffix },
+      {
+        op: "add",
+        path: [...node.path, key, codePointLength(existing)],
+        value: suffix,
+      },
       changedPathFor(node, key),
     );
   };

package/src/statewire.ts

@@ -59,10 +59,21 @@ export const useStatewire = <
     core.getState,
   ) as TState;
   const isBusy = useSyncExternalStore(subscribe, core.getBusy, core.getBusy);
+  const failed = useSyncExternalStore(
+    subscribe,
+    core.getFailed,
+    core.getFailed,
+  );
   const connection = value.connection ?? LIVE_CONNECTION;
 
-  return useMemo(
-    () => ({
+  return useMemo(() => {
+    const failures = (): NonNullable<typeof value.failures> => {
+      if (!value.failures) {
+        throw new Error("statewire: this transport has no failed-send lane");
+      }
+      return value.failures;
+    };
+    return {
       state,
       getState: core.getState as () => TState,
       connection,
@@ -76,9 +87,13 @@ export const useStatewire = <
         }
         value.setContext(contextValue);
       },
-    }),
-    [state, isBusy, connection, core, value],
-  );
+      failed,
+      retryFailed: (entry: StatewireClient.FailedCommand) =>
+        failures().retry(entry),
+      discardFailed: (entry: StatewireClient.FailedCommand) =>
+        failures().discard(entry),
+    };
+  }, [state, isBusy, failed, connection, core, value]);
 };
 
 export const StatewireResource = <
@@ -121,6 +136,18 @@ export class StatewireClient<
     this.root.getValue().setContext(value);
   }
 
+  get failed(): readonly StatewireClient.FailedCommand[] {
+    return this.root.getValue().failed;
+  }
+
+  retryFailed(entry: StatewireClient.FailedCommand): Promise<unknown> {
+    return this.root.getValue().retryFailed(entry);
+  }
+
+  discardFailed(entry: StatewireClient.FailedCommand): void {
+    this.root.getValue().discardFailed(entry);
+  }
+
   subscribe(listener: () => void): () => void {
     return this.root.subscribe(listener);
   }
@@ -155,6 +182,11 @@ export namespace StatewireClient {
       ctx: { state: NonNullable<TState> },
     ) => void;
     onConnectionChange?: (connection: Connection) => void;
+    /** Drops a retained failed entry once a canonical snapshot shows its effect landed; checked against each new snapshot. */
+    failureCovered?: (
+      state: NonNullable<TState>,
+      entry: FailedCommand,
+    ) => boolean;
   };
 
   export type Helpers<
@@ -171,6 +203,12 @@ export namespace StatewireClient {
     isBusy: boolean;
     /** Replace this client's ambient context on the server; throws on transports without a client context channel. */
     setContext: (value: Record<string, unknown>) => void;
+    /** Non-accepted sends retained in the session record; reload with it. */
+    failed: readonly FailedCommand[];
+    /** Re-enqueues the entry's command on fresh clocks and removes the entry. */
+    retryFailed: (entry: FailedCommand) => Promise<unknown>;
+    /** Removes the entry. */
+    discardFailed: (entry: FailedCommand) => void;
   };
 
   export type ConnectionState =
@@ -259,6 +297,16 @@ export namespace StatewireClient {
     }>,
   ) => "requeue" | "drop";
 
+  /** A non-accepted send retained for the user: the wire statement, its failure, and its original clocks. */
+  export type FailedCommand = {
+    readonly command: string;
+    readonly params: readonly unknown[];
+    readonly meta?: unknown;
+    readonly failure: SendFailure;
+    readonly ts: number;
+    readonly seq: number;
+  };
+
   /** A command as persisted while un-durable: its lane seq plus the wire statement. */
   export type SessionCommand = {
     seq: number;
@@ -275,6 +323,8 @@ export namespace StatewireClient {
     commands: readonly SessionCommand[];
     /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
     verdicts?: readonly SessionVerdict[];
+    /** Non-accepted sends retained for the user; survive record rebases and resets. */
+    failed?: readonly FailedCommand[];
   };
 
   /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */

package/src/transports/remote.ts

@@ -1,6 +1,9 @@
 import { useEffect } from "react";
 import type { Statewire } from "../types";
 import {
+  discardFailed,
+  failedCommands,
+  retryFailed,
   setContext,
   setTransport,
   useStatewireSession,
@@ -39,5 +42,10 @@ export const useStatewireRemote = <
       return !s.idle;
     },
     setContext: (value) => setContext(s, value),
+    failures: {
+      list: () => failedCommands(s),
+      retry: (entry) => retryFailed(s, entry),
+      discard: (entry) => discardFailed(s, entry),
+    },
   };
 };

package/src/types.ts

@@ -59,6 +59,12 @@ export interface Statewire<
   isBusy?: boolean;
   /** Replace this client's ambient context on the server; it rides the ctx lane (no verdict). */
   setContext?: (value: Record<string, unknown>) => void;
+  /** The retained failed-send lane; present on transports with a durable session. */
+  failures?: {
+    list: () => readonly StatewireClient.FailedCommand[];
+    retry: (entry: StatewireClient.FailedCommand) => Promise<unknown>;
+    discard: (entry: StatewireClient.FailedCommand) => void;
+  };
 }
 
 const describe = (failure: StatewireClient.SendFailure): string => {

package/src/wire/ops.ts

@@ -64,15 +64,42 @@ export const sanitizeValue = (value: unknown, parent?: string): unknown =>
 const invalid = (op: Statewire.Op) =>
   new Error(`Statewire cannot apply ${op.op} at path: ${op.path.join(".")}`);
 
+// Text-insert offsets are Unicode code points on the wire, not UTF-16 units.
+const utf16Index = (text: string, offset: number): number => {
+  let index = 0;
+  for (let remaining = offset; remaining > 0; remaining -= 1) {
+    if (index >= text.length) return -1;
+    index += text.codePointAt(index)! > 0xffff ? 2 : 1;
+  }
+  return index;
+};
+
+const countCodePoints = (text: string): number => {
+  let count = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    if (text.codePointAt(index)! > 0xffff) index += 1;
+    count += 1;
+  }
+  return count;
+};
+
+let last: { str: string; count: number } | null = null;
+
 const insertedText = (
   current: string,
   op: Extract<Statewire.Op, { op: "add" }>,
   offset: number,
 ): string => {
-  if (typeof op.value !== "string" || offset > current.length) {
-    throw invalid(op);
+  if (typeof op.value !== "string") throw invalid(op);
+  const memoized =
+    last !== null && last.str === current && last.count === offset;
+  const index = memoized ? current.length : utf16Index(current, offset);
+  if (index < 0) throw invalid(op);
+  const next = current.slice(0, index) + op.value + current.slice(index);
+  if (index === current.length) {
+    last = { str: next, count: offset + countCodePoints(op.value) };
   }
-  return current.slice(0, offset) + op.value + current.slice(offset);
+  return next;
 };
 
 const applyAdd = (