statewire 0.23.0 → 0.24.1

package/src/storage.ts

@@ -1,8 +1,10 @@
 import { useEffect, useMemo, useRef } from "react";
 import { randomId } from "./util/randomId";
 import { wrapStorageError } from "./client/storageError";
+import { reviveValue } from "./wire/meta";
 import { resource } from "@assistant-ui/tap";
 import type { StatewireClient } from "./statewire";
+import type { Statewire } from "./types";
 import type { StatewireProtocol } from "./wire/protocol";
 import {
   DEFAULT_PROTOCOL,
@@ -47,12 +49,32 @@ const isSessionCommand = (
 const isOutboxCommand = (
   value: unknown,
 ): value is StatewireClient.OutboxCommand =>
+  isStatement(value) &&
+  isIdentified(value) &&
+  (value["held"] === undefined || value["held"] === true) &&
+  (value["released"] === undefined || value["released"] === true) &&
+  isOptionalString(value["by"]);
+
+// Format 4 outbox entries carried the hold as `hold: { meta }`.
+const isLegacyOutboxCommand = (value: unknown) =>
   isStatement(value) &&
   isIdentified(value) &&
   (value["hold"] === undefined || isRecord(value["hold"])) &&
   (value["released"] === undefined || value["released"] === true) &&
   isOptionalString(value["by"]);
 
+const isStoredSettled = (
+  value: unknown,
+): value is StatewireClient.StoredSettled =>
+  isRecord(value) &&
+  isIdentified(value) &&
+  typeof value["method"] === "string" &&
+  Array.isArray(value["params"]) &&
+  (value["seq"] === undefined || isPositiveSafeInteger(value["seq"])) &&
+  (value["failure"] === undefined
+    ? isRecord(value["result"]) && Array.isArray(value["result"]["value"])
+    : value["result"] === undefined && isSendFailure(value["failure"]));
+
 const isSessionVerdict = (
   value: unknown,
 ): value is StatewireClient.SessionVerdict =>
@@ -88,7 +110,8 @@ const isSendFailure = (
         (value["cause"] === "unmount" ||
           value["cause"] === "stream-gone" ||
           value["cause"] === "session-lost" ||
-          value["cause"] === "removed") &&
+          value["cause"] === "removed" ||
+          value["cause"] === "quota") &&
         (value["predecessorLost"] === undefined ||
           value["predecessorLost"] === true)
       );
@@ -103,9 +126,18 @@ const isSendFailure = (
   }
 };
 
-const isFailedCommand = (
-  value: unknown,
-): value is StatewireClient.FailedCommand =>
+type FailedCommand = {
+  protocol: string;
+  produced?: StatewireClient.SessionCommand["produced"];
+  command: string;
+  params: unknown[];
+  meta?: unknown;
+  failure: StatewireClient.SendFailure;
+  ts: number;
+  seq: number;
+};
+
+const isFailedCommand = (value: unknown): value is FailedCommand =>
   isRecord(value) &&
   isProtocol(value["protocol"]) &&
   isProducer(value["produced"]) &&
@@ -116,30 +148,34 @@ const isFailedCommand = (
   Number.isFinite(value["ts"]) &&
   isPositiveSafeInteger(value["seq"]);
 
+const isArrayOf = (value: unknown, is: (item: unknown) => boolean) =>
+  value === undefined || (Array.isArray(value) && value.every(is));
+
+const isMark = (mark: unknown) =>
+  isRecord(mark) &&
+  typeof mark["id"] === "string" &&
+  typeof mark["by"] === "string" &&
+  (mark["failure"] === undefined || isSendFailure(mark["failure"]));
+
 const isLaneWith = (
   value: unknown,
   isCommand: (command: unknown) => boolean,
+  legacy = false,
 ): value is StatewireClient.SessionLane =>
   isRecord(value) &&
   isPositiveSafeInteger(value["nextSeq"]) &&
   Array.isArray(value["commands"]) &&
   value["commands"].every(isCommand) &&
-  (value["outbox"] === undefined ||
-    (Array.isArray(value["outbox"]) &&
-      value["outbox"].every(isOutboxCommand))) &&
-  (value["removed"] === undefined ||
-    (Array.isArray(value["removed"]) &&
-      value["removed"].every(
-        (mark) =>
-          isRecord(mark) &&
-          typeof mark["id"] === "string" &&
-          typeof mark["by"] === "string",
-      ))) &&
-  (value["verdicts"] === undefined ||
-    (Array.isArray(value["verdicts"]) &&
-      value["verdicts"].every(isSessionVerdict))) &&
-  (value["failed"] === undefined ||
-    (Array.isArray(value["failed"]) && value["failed"].every(isFailedCommand)));
+  isArrayOf(
+    value["outbox"],
+    legacy ? isLegacyOutboxCommand : isOutboxCommand,
+  ) &&
+  isArrayOf(value["removed"], isMark) &&
+  isArrayOf(value["verdicts"], isSessionVerdict) &&
+  (legacy
+    ? isArrayOf(value["failed"], isFailedCommand)
+    : value["failed"] === undefined &&
+      isArrayOf(value["inbox"], isStoredSettled));
 
 const isSessionLane = (value: unknown): value is StatewireClient.SessionLane =>
   isLaneWith(value, isSessionCommand);
@@ -209,12 +245,22 @@ const invalid = (): never => {
   throw new Error("statewire: invalid stored session record");
 };
 
+type LegacyLane = Record<string, unknown> & {
+  commands: StatewireClient.SessionCommand[];
+  outbox?: (Omit<StatewireClient.OutboxCommand, "held"> & {
+    hold?: { meta?: unknown };
+  })[];
+  failed?: FailedCommand[];
+};
+
+type LegacyRecord = { clientId: string; lanes: Record<string, LegacyLane> };
+
 // Formats 1 and 2 held one lane: it lifts under the primary protocol, failed
 // entries under their own.
 const liftLegacy = (
   value: Record<string, unknown>,
   protocol: string,
-): StatewireClient.SessionRecord => {
+): LegacyRecord => {
   const { clientId, nextSeq, commands, verdicts, failed } = value;
   const lane = {
     nextSeq,
@@ -232,24 +278,63 @@ const liftLegacy = (
     (!Array.isArray(failed) || !failed.every(isFailedCommand))
   )
     return invalid();
-  const lanes: Record<string, StatewireClient.SessionLane> = {
+  const lanes: Record<string, LegacyLane> = {
     [protocol]: {
-      ...lane,
+      ...(lane as Record<string, unknown>),
       commands: legacyCommands
         .filter((command) => (command.protocol ?? protocol) === protocol)
         .map(({ protocol: _protocol, ...command }) => command),
     },
   };
-  for (const entry of failed ?? []) {
+  for (const entry of (failed ?? []) as FailedCommand[]) {
     const target = lanes[entry.protocol] ?? { nextSeq: 1, commands: [] };
     lanes[entry.protocol] = {
       ...target,
       failed: [...(target.failed ?? []), entry],
     };
   }
-  return identify({ clientId, lanes });
+  return identify({ clientId, lanes } as never) as never;
 };
 
+// Format 5: holds are a flag with client-only localMeta; failed sends are
+// settled updates awaiting their onCommandChange ack.
+const upgrade = (record: LegacyRecord): StatewireClient.SessionRecord => ({
+  clientId: record.clientId,
+  lanes: Object.fromEntries(
+    Object.entries(record.lanes).map(([protocol, legacy]) => {
+      const { outbox, failed, ...lane } = legacy;
+      const inbox = [...(failed ?? [])]
+        .sort((a, b) => a.ts - b.ts)
+        .map((f): StatewireClient.StoredSettled => ({
+          // Stable across re-migrations until the upgraded record is saved.
+          id: `failed:${protocol}:${f.seq}:${f.ts}`,
+          method: f.command,
+          params: f.params,
+          ...(f.meta !== undefined && { meta: f.meta }),
+          ts: f.ts,
+          failure: f.failure,
+        }));
+      return [
+        protocol,
+        {
+          ...(lane as unknown as StatewireClient.SessionLane),
+          ...(outbox?.length && {
+            outbox: outbox.map(({ hold, ...command }) => ({
+              ...command,
+              ...(hold !== undefined && { held: true as const }),
+              ...(hold?.meta !== undefined && { localMeta: hold.meta }),
+            })),
+          }),
+          ...(inbox.length > 0 && { inbox }),
+        },
+      ];
+    }),
+  ),
+});
+
+const isLegacyLane = (lane: unknown) =>
+  isLaneWith(lane, isSessionCommand, true);
+
 const normalize = (
   parsed: unknown,
   protocol: string,
@@ -260,29 +345,64 @@ const normalize = (
     savedAt: _savedAt,
     ...value
   } = parsed;
-  if (format === 4) return isSessionRecord(value) ? value : invalid();
+  if (format === 5) return isSessionRecord(value) ? value : invalid();
+  if (format === 4)
+    return isRecordWith(value, isLegacyLane)
+      ? upgrade(value as never)
+      : invalid();
   if (format === 3)
-    return isRecordWith(value, (lane) => isLaneWith(lane, isLegacyCommand))
-      ? identify(value)
+    return isRecordWith(value, (lane) =>
+      isLaneWith(lane, isLegacyCommand, true),
+    )
+      ? upgrade(identify(value) as never)
       : invalid();
   if (format !== undefined && format !== 1 && format !== 2)
     throw new Error("statewire: unsupported session storage version");
   const { ctxNextSeq: _ctxNextSeq, context: _context, ...legacy } = value;
-  return liftLegacy(legacy, protocol);
+  return upgrade(liftLegacy(legacy, protocol));
 };
 
+export const STORAGE_FORMAT = 5;
+
+const parse = async (
+  raw: string | null,
+  codec: KeyValueSessionStorage.Codec | undefined,
+): Promise<unknown> =>
+  raw === null
+    ? null
+    : JSON.parse(codec === undefined ? raw : await codec.decode(raw));
+
 const decode = (
   raw: string | null,
   protocol: string,
 ): StatewireClient.SessionRecord | null =>
   raw === null ? null : normalize(JSON.parse(raw), protocol);
 
-const isEmpty = (record: StatewireClient.SessionRecord) =>
-  Object.values(record.lanes).every(
-    (lane) =>
-      lane.commands.length === 0 &&
-      !lane.outbox?.length &&
-      !lane.failed?.length,
+const isUnsent = (lane: StatewireClient.SessionLane) =>
+  lane.commands.length > 0 || (lane.outbox?.length ?? 0) > 0;
+
+const entryCount = (record: StatewireClient.SessionRecord | null) =>
+  record === null
+    ? 0
+    : Object.values(record.lanes).reduce(
+        (sum, lane) => sum + lane.commands.length + (lane.outbox?.length ?? 0),
+        0,
+      );
+
+const noticesOf = (
+  record: StatewireClient.SessionRecord,
+): Statewire.CommandUpdate[] =>
+  Object.entries(record.lanes).flatMap(([protocol, lane]) =>
+    (lane.inbox ?? []).map((n) => ({
+      protocol,
+      id: n.id,
+      method: n.method,
+      params: n.params as never[],
+      ...(n.seq !== undefined && { seq: n.seq }),
+      status: "settled" as const,
+      ...(n.failure !== undefined && { failure: n.failure }),
+      ...(n.localMeta !== undefined && { localMeta: n.localMeta }),
+    })),
   );
 
 const active = new WeakMap<
@@ -290,34 +410,70 @@ const active = new WeakMap<
   Map<string, number>
 >();
 
-const sweep = async (
+/** Same-runtime saves, per backend, for `subscribeOutboxes`. */
+const savers = new WeakMap<
+  KeyValueSessionStorage.Backend,
+  Set<(key: string) => void>
+>();
+
+const announce = (backend: KeyValueSessionStorage.Backend, key: string) => {
+  for (const listener of savers.get(backend) ?? []) listener(key);
+};
+
+type Candidate = {
+  key: string;
+  savedAt: number;
+  record: StatewireClient.SessionRecord;
+};
+
+const sweeping = new WeakMap<KeyValueSessionStorage.Backend, Promise<void>>();
+
+// Sweeps of one backend run one at a time.
+const sweep = (
+  options: KeyValueSessionStorage.Options,
+  currentKey: string,
+  quota = false,
+): Promise<void> => {
+  const run = (sweeping.get(options.backend) ?? Promise.resolve())
+    .catch(() => {})
+    .then(() => sweepOnce(options, currentKey, quota));
+  sweeping.set(options.backend, run);
+  return run;
+};
+
+// Records with unsent commands are never evicted. Empty records go first;
+// records holding only failure notices go once past their age.
+const sweepOnce = async (
   options: KeyValueSessionStorage.Options,
   currentKey: string,
   quota = false,
 ) => {
-  const { backend, retention, namespace = "" } = options;
+  const { backend, retention, namespace = "", codec, onEvict } = options;
   if (!retention || !backend.getAllKeys) return;
-  const entries: { key: string; savedAt: number }[] = [];
-  const candidate = (raw: string | null) => {
-    if (raw === null) return undefined;
+  const candidate = async (raw: string | null) => {
     let value: unknown;
     try {
-      value = JSON.parse(raw);
+      value = await parse(raw, codec);
     } catch {
       return undefined;
     }
+    if (value === null) return undefined;
+    let record: StatewireClient.SessionRecord;
     try {
-      if (!isEmpty(normalize(value, DEFAULT_PROTOCOL))) return undefined;
+      record = normalize(value, DEFAULT_PROTOCOL);
     } catch {
       return undefined;
     }
+    if (Object.values(record.lanes).some(isUnsent)) return undefined;
     const savedAt =
       (value as Record<string, unknown>)["savedAt"] ??
       (value as Record<string, unknown>)["updatedAt"];
     return typeof savedAt === "number" && Number.isFinite(savedAt)
-      ? savedAt
+      ? { savedAt, record }
       : undefined;
   };
+  const empty: Candidate[] = [];
+  const noticed: Candidate[] = [];
   for (const key of await backend.getAllKeys()) {
     if (
       !key.startsWith(namespace) ||
@@ -325,36 +481,79 @@ const sweep = async (
       active.get(backend)?.has(key)
     )
       continue;
-    const savedAt = candidate(await backend.getItem(key));
-    if (savedAt !== undefined) entries.push({ key, savedAt });
+    const found = await candidate(await backend.getItem(key));
+    if (found === undefined) continue;
+    (noticesOf(found.record).length > 0 ? noticed : empty).push({
+      key,
+      ...found,
+    });
   }
-  entries.sort((a, b) => b.savedAt - a.savedAt);
+  const remove = async (
+    entry: Candidate,
+    reason: KeyValueSessionStorage.EvictEvent["reason"],
+  ) => {
+    const run = async () => {
+      if (active.get(backend)?.has(entry.key)) return;
+      const again = await candidate(await backend.getItem(entry.key));
+      if (again?.savedAt !== entry.savedAt) return;
+      if (active.get(backend)?.has(entry.key)) return;
+      await backend.removeItem(entry.key);
+      announce(backend, entry.key);
+      onEvict?.({
+        key: entry.key,
+        reason,
+        dropped: noticesOf(again.record),
+      });
+    };
+    if (backend.withUnused) await backend.withUnused(entry.key, run);
+    else await run();
+  };
   const now = Date.now();
+  const expired = (entry: Candidate) =>
+    retention.maxAgeMs !== undefined &&
+    now - entry.savedAt > retention.maxAgeMs;
+  empty.sort((a, b) => b.savedAt - a.savedAt);
   let retained = 1;
-  const quotaStart = Math.floor(entries.length / 2);
-  for (const [index, entry] of entries.entries()) {
-    const expired =
-      retention.maxAgeMs !== undefined &&
-      now - entry.savedAt > retention.maxAgeMs;
+  const quotaStart = Math.floor(empty.length / 2);
+  for (const [index, entry] of empty.entries()) {
     const overflow =
       retention.maxEntries !== undefined && retained >= retention.maxEntries;
-    if (expired || overflow || (quota && index >= quotaStart)) {
-      const remove = async () => {
-        if (active.get(backend)?.has(entry.key)) return;
-        if (candidate(await backend.getItem(entry.key)) !== entry.savedAt)
-          return;
-        if (active.get(backend)?.has(entry.key)) return;
-        await backend.removeItem(entry.key);
-      };
-      if (backend.withUnused) await backend.withUnused(entry.key, remove);
-      else await remove();
-    } else retained++;
+    if (expired(entry)) await remove(entry, "expired");
+    else if (overflow) await remove(entry, "overflow");
+    else if (quota && index >= quotaStart) await remove(entry, "quota");
+    else retained++;
   }
+  for (const entry of noticed)
+    if (expired(entry)) await remove(entry, "expired");
 };
 
 const isQuotaError = (error: unknown) =>
   error instanceof Error && error.name === "QuotaExceededError";
 
+const quotaError = (limit: string) => {
+  const error = new Error(`statewire: session ${limit} limit reached`);
+  error.name = "StatewireQuotaError";
+  return error;
+};
+
+const otherBytes = async (
+  backend: KeyValueSessionStorage.Backend,
+  namespace: string,
+  key: string,
+) => {
+  let total = 0;
+  for (const other of (await backend.getAllKeys?.()) ?? []) {
+    if (other === key || !other.startsWith(namespace)) continue;
+    total += (await backend.getItem(other))?.length ?? 0;
+  }
+  return total;
+};
+
+const validLimit = (value: number | undefined, name: string) => {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+    throw new Error(`statewire: invalid session limit ${name}`);
+};
+
 const useKeyValueSessionStorage = (
   options: KeyValueSessionStorage.Options,
 ): StatewireClient.SessionStorage => {
@@ -365,12 +564,20 @@ const useKeyValueSessionStorage = (
     protocol = DEFAULT_PROTOCOL,
     migrate,
     retention: suppliedRetention,
+    limits: suppliedLimits,
+    codec,
     onError,
+    onEvict,
   } = options;
-  const latestErrorHandler = useRef(onError);
-  latestErrorHandler.current = onError;
+  const latest = useRef({ onError, onEvict });
+  latest.current = { onError, onEvict };
   const reportError = useMemo(
-    () => (error: unknown) => latestErrorHandler.current?.(error),
+    () => (error: unknown) => latest.current.onError?.(error),
+    [],
+  );
+  const reportEvict = useMemo(
+    () => (event: KeyValueSessionStorage.EvictEvent) =>
+      latest.current.onEvict?.(event),
     [],
   );
   const retain = suppliedRetention !== undefined;
@@ -386,14 +593,24 @@ const useKeyValueSessionStorage = (
         : undefined,
     [retain, maxAgeMs, maxEntries],
   );
+  const outboxEntries = suppliedLimits?.outboxEntries;
+  const recordBytes = suppliedLimits?.recordBytes;
+  const totalBytes = suppliedLimits?.totalBytes;
+  validLimit(outboxEntries, "outboxEntries");
+  validLimit(recordBytes, "recordBytes");
+  validLimit(totalBytes, "totalBytes");
+  if (totalBytes !== undefined && !backend.getAllKeys)
+    throw new Error("statewire: a totalBytes limit requires getAllKeys");
   const configured = useMemo(
     () => ({
       backend,
       key,
       namespace,
+      onEvict: reportEvict,
+      ...(codec === undefined ? {} : { codec }),
       ...(retention === undefined ? {} : { retention }),
     }),
-    [backend, key, namespace, retention],
+    [backend, key, namespace, retention, codec, reportEvict],
   );
   const storageKey = namespace + key;
   if (retention !== undefined) {
@@ -423,18 +640,26 @@ const useKeyValueSessionStorage = (
     }
     const state = {
       record: null as StatewireClient.SessionRecord | null,
+      bytes: 0,
+      others: undefined as number | undefined,
       ready: undefined as Promise<void> | undefined,
       queue: Promise.resolve(),
       pending: 0,
       failure: undefined as unknown,
-      asynchronous: typeof raw !== "string" && raw !== null,
-      hydrated: typeof raw === "string" || raw === null,
+      asynchronous:
+        codec !== undefined || (typeof raw !== "string" && raw !== null),
+      hydrated: false,
+    };
+    const hydrate = (record: StatewireClient.SessionRecord | null) => {
+      state.record = record;
+      state.hydrated = true;
     };
     if (state.asynchronous) {
       state.ready = Promise.resolve(raw)
-        .then((value) => {
-          state.record = decode(value, protocol);
-          state.hydrated = true;
+        .then(async (value) => {
+          state.bytes = value?.length ?? 0;
+          const parsed = await parse(value, codec);
+          hydrate(parsed === null ? null : normalize(parsed, protocol));
         })
         .catch((cause: unknown) => {
           const error = wrapStorageError(cause);
@@ -445,7 +670,8 @@ const useKeyValueSessionStorage = (
       state.ready.catch(() => {});
     } else {
       try {
-        state.record = decode(raw as string | null, protocol);
+        state.bytes = (raw as string | null)?.length ?? 0;
+        hydrate(decode(raw as string | null, protocol));
       } catch (cause) {
         const error = wrapStorageError(cause);
         reportError(error);
@@ -453,7 +679,7 @@ const useKeyValueSessionStorage = (
       }
     }
     return state;
-  }, [backend, storageKey, protocol, reportError]);
+  }, [backend, storageKey, protocol, codec, reportError]);
 
   useEffect(() => {
     const entries = active.get(backend) ?? new Map<string, number>();
@@ -475,9 +701,65 @@ const useKeyValueSessionStorage = (
       });
   }, [state, configured, storageKey, retention, reportError]);
 
-  return useMemo(
-    () => ({
+  useEffect(() => {
+    if (totalBytes === undefined) return;
+    void otherBytes(backend, namespace, storageKey).then(
+      (bytes) => {
+        state.others = bytes;
+      },
+      () => {},
+    );
+  }, [state, backend, namespace, storageKey, totalBytes]);
+
+  return useMemo(() => {
+    const checkLimits = (
+      record: StatewireClient.SessionRecord,
+      bytes: number,
+    ) => {
+      // Limits gate writes that add an entry; settling and stamping always land.
+      if (entryCount(record) <= entryCount(state.record)) return;
+      if (outboxEntries !== undefined && entryCount(record) > outboxEntries)
+        throw quotaError("outboxEntries");
+      if (recordBytes !== undefined && bytes > recordBytes)
+        throw quotaError("recordBytes");
+      if (
+        totalBytes !== undefined &&
+        state.others !== undefined &&
+        state.others + bytes > totalBytes
+      )
+        throw quotaError("totalBytes");
+    };
+    const persist = async (encoded: string) => {
+      const stored =
+        codec === undefined ? encoded : await codec.encode(encoded);
+      try {
+        await backend.setItem(storageKey, stored);
+      } catch (error) {
+        if (!isQuotaError(error)) throw error;
+        if (retention !== undefined) await sweep(configured, storageKey, true);
+        await backend.setItem(storageKey, stored);
+      }
+      announce(backend, storageKey);
+    };
+    return {
+      durable: true,
       ...(state.ready === undefined ? {} : { ready: state.ready }),
+      read: async () => {
+        if (state.failure !== undefined) throw state.failure;
+        await state.ready;
+        await state.queue.catch(() => {});
+        try {
+          const raw = await backend.getItem(storageKey);
+          const parsed = await parse(raw, codec);
+          state.bytes = raw?.length ?? 0;
+          state.record = parsed === null ? null : normalize(parsed, protocol);
+          return state.record;
+        } catch (cause) {
+          const error = wrapStorageError(cause);
+          reportError(error);
+          throw error;
+        }
+      },
       load: () => {
         if (state.failure !== undefined) throw state.failure;
         if (!state.hydrated)
@@ -498,7 +780,8 @@ const useKeyValueSessionStorage = (
             "statewire: storage backend changed from synchronous to asynchronous",
           );
         try {
-          return decode(raw, protocol);
+          state.record = decode(raw, protocol);
+          return state.record;
         } catch (cause) {
           const error = wrapStorageError(cause);
           reportError(error);
@@ -515,42 +798,49 @@ const useKeyValueSessionStorage = (
           throw new Error("statewire: invalid session record");
         const encoded = JSON.stringify({
           ...record,
-          statewireStorageVersion: 4,
+          statewireStorageVersion: STORAGE_FORMAT,
           savedAt: Date.now(),
         });
-        state.record = record;
-        const recoverQuota = async (error: unknown) => {
-          if (!isQuotaError(error) || retention === undefined) throw error;
-          await sweep(configured, storageKey, true);
-          await backend.setItem(storageKey, encoded);
-        };
-        const write = async () => {
-          try {
-            await backend.setItem(storageKey, encoded);
-          } catch (error) {
-            await recoverQuota(error);
-          }
-        };
+        checkLimits(record, encoded.length);
         if (!state.asynchronous && state.pending === 0) {
-          let result: void | Promise<void>;
           try {
-            result = backend.setItem(storageKey, encoded);
+            backend.setItem(storageKey, encoded) as void;
           } catch (error) {
-            if (!isQuotaError(error) || retention === undefined) {
+            if (!isQuotaError(error)) {
               state.failure = wrapStorageError(error);
               reportError(state.failure);
               throw state.failure;
             }
-            result = recoverQuota(error);
+            // A write that adds an entry is refused; the rest retry after the sweep.
+            if (entryCount(record) > entryCount(state.record)) {
+              if (retention !== undefined)
+                void sweep(configured, storageKey, true).catch(() => {});
+              throw quotaError("backend");
+            }
+            state.record = record;
+            state.bytes = encoded.length;
+            state.pending++;
+            state.queue = persist(encoded).finally(() => {
+              state.pending--;
+            });
+            state.queue.catch((cause: unknown) => {
+              const failure = wrapStorageError(cause);
+              if (state.failure !== failure) reportError(failure);
+              state.failure = failure;
+            });
+            return;
           }
-          if (result === undefined) return;
-          state.pending++;
-          state.queue = result;
-        } else {
-          state.pending++;
-          state.queue = state.queue.then(() => state.ready).then(write);
+          state.record = record;
+          state.bytes = encoded.length;
+          announce(backend, storageKey);
+          return;
         }
+        state.record = record;
+        state.bytes = encoded.length;
+        state.pending++;
         state.queue = state.queue
+          .then(() => state.ready)
+          .then(() => persist(encoded))
           .catch((cause: unknown) => {
             const error = wrapStorageError(cause);
             if (state.failure !== error) reportError(error);
@@ -574,19 +864,25 @@ const useKeyValueSessionStorage = (
           }
         })();
       },
+      onEvict: ({ reason, dropped }) =>
+        reportEvict({ key: storageKey, reason, dropped }),
       ...(migrate === undefined ? {} : { migrate }),
-    }),
-    [
-      state,
-      backend,
-      storageKey,
-      protocol,
-      migrate,
-      retention,
-      configured,
-      reportError,
-    ],
-  );
+    } satisfies StatewireClient.SessionStorage;
+  }, [
+    state,
+    backend,
+    storageKey,
+    protocol,
+    migrate,
+    retention,
+    configured,
+    codec,
+    outboxEntries,
+    recordBytes,
+    totalBytes,
+    reportError,
+    reportEvict,
+  ]);
 };
 
 /** Persist sessions through a synchronous or asynchronous string storage backend. */
@@ -600,7 +896,15 @@ export namespace KeyValueSessionStorage {
     getAllKeys?: () => readonly string[] | Promise<readonly string[]>;
     /** Runs cleanup under exclusive access, skipping keys in use by another runtime. */
     withUnused?: (key: string, action: () => Promise<void>) => Promise<void>;
+    /** Notifies of keys other runtimes wrote; returns unsubscribe. */
+    subscribe?: (listener: (key: string) => void) => () => void;
+  };
+  /** Transforms the stored string, e.g. encryption or compression. */
+  export type Codec = {
+    encode: (plain: string) => Promise<string>;
+    decode: (stored: string) => Promise<string>;
   };
+  export type EvictEvent = StatewireClient.EvictEvent;
   export type Options = {
     backend: Backend;
     key: string;
@@ -609,6 +913,138 @@ export namespace KeyValueSessionStorage {
     protocol?: string;
     migrate?: StatewireClient.SessionStorage["migrate"];
     retention?: { maxAgeMs?: number; maxEntries?: number };
+    /** Off by default; a write that adds an entry past one rejects `{ fate: "aborted", cause: "quota" }`. */
+    limits?: {
+      outboxEntries?: number;
+      recordBytes?: number;
+      totalBytes?: number;
+    };
+    codec?: Codec;
     onError?: (error: unknown) => void;
+    /** Reports evicted records and dropped failure notices. */
+    onEvict?: (event: EvictEvent) => void;
+  };
+}
+
+const pages = new Map<string, StatewireClient.SessionRecord | null>();
+
+const useMemorySessionStorage = ({
+  scope,
+}: MemorySessionStorage.Options): StatewireClient.SessionStorage =>
+  useMemo(
+    () => ({
+      durable: false,
+      load: () => pages.get(scope) ?? null,
+      save: (record) => {
+        pages.set(scope, record);
+      },
+    }),
+    [scope],
+  );
+
+/** Session storage in page memory, keyed by scope: the record and client identity survive remounts, not reloads. */
+export const MemorySessionStorage = resource(useMemorySessionStorage);
+
+export namespace MemorySessionStorage {
+  export type Options = { scope: string };
+}
+
+const entriesOf = (
+  record: StatewireClient.SessionRecord,
+): StatewireClient.OutboxEntry[] =>
+  Object.entries(record.lanes).flatMap(([protocol, lane]) => {
+    const view = (
+      c: StatewireClient.OutboxCommand | StatewireClient.SessionCommand,
+      state: StatewireClient.OutboxState,
+    ): StatewireClient.OutboxEntry => ({
+      id: c.id,
+      protocol,
+      command: {
+        method: c.method,
+        params:
+          c.meta === undefined
+            ? c.params
+            : (reviveValue(structuredClone(c.params), c.meta) as unknown[]),
+      },
+      ts: c.ts,
+      state,
+      localMeta: c.localMeta,
+      durable: true,
+    });
+    return [
+      ...[...lane.commands]
+        .sort((a, b) => a.seq - b.seq)
+        .map((c) => view(c, "sending")),
+      ...(lane.outbox ?? []).map((c) => view(c, c.held ? "held" : "queued")),
+    ];
+  });
+
+/** Reads the outboxes of every session under `namespace`, mounted or not. */
+export const readOutboxes = async (
+  backend: KeyValueSessionStorage.Backend,
+  options: ReadOutboxes.Options,
+): Promise<readonly ReadOutboxes.Outbox[]> => {
+  if (!backend.getAllKeys)
+    throw new Error("statewire: readOutboxes requires getAllKeys");
+  const { namespace, codec, protocol = DEFAULT_PROTOCOL } = options;
+  if (!namespace)
+    throw new Error("statewire: readOutboxes requires a namespace");
+  const result: ReadOutboxes.Outbox[] = [];
+  for (const key of await backend.getAllKeys()) {
+    if (!key.startsWith(namespace)) continue;
+    const parsed = await parse(await backend.getItem(key), codec);
+    if (parsed === null) continue;
+    const entries = entriesOf(normalize(parsed, protocol));
+    if (entries.length > 0) result.push({ key, entries });
+  }
+  return result;
+};
+
+/** Calls `listener` with `readOutboxes` now and after every save under `namespace`; returns unsubscribe. */
+export const subscribeOutboxes = (
+  backend: KeyValueSessionStorage.Backend,
+  options: ReadOutboxes.Options,
+  listener: (outboxes: readonly ReadOutboxes.Outbox[]) => void,
+  onError: (error: unknown) => void,
+): (() => void) => {
+  let closed = false;
+  let reading = Promise.resolve();
+  const refresh = () => {
+    reading = reading.then(async () => {
+      if (closed) return;
+      try {
+        const outboxes = await readOutboxes(backend, options);
+        if (!closed) listener(outboxes);
+      } catch (error) {
+        onError(error);
+      }
+    });
+  };
+  const onKey = (key: string) => {
+    if (key.startsWith(options.namespace)) refresh();
+  };
+  const local = savers.get(backend) ?? new Set();
+  savers.set(backend, local);
+  local.add(onKey);
+  const remote = backend.subscribe?.(onKey);
+  refresh();
+  return () => {
+    closed = true;
+    local.delete(onKey);
+    remote?.();
+  };
+};
+
+export namespace ReadOutboxes {
+  export type Options = {
+    namespace: string;
+    codec?: KeyValueSessionStorage.Codec;
+    /** The lane that single-lane formats lift into. */
+    protocol?: string;
+  };
+  export type Outbox = {
+    key: string;
+    entries: readonly StatewireClient.OutboxEntry[];
   };
 }
+export { IndexedDbSession, indexedDbBackend } from "./indexedDb";