Statewire

Signatures quoted from source. Usage: Consume a Statewire, Host a Statewire. Wire: protocol spec. Related: Statewire bindings, Python Statewire.

Entry pointsCopy Anchor Link

statewireCopy Anchor Link

StatewireCopy Anchor Link

interface Statewire<TState = any, TCommands extends Statewire.Commands = Statewire.Commands> {
  state: TState; commands: Statewire.CommandsProxy<TCommands>;
  connection?: StatewireClient.Connection; source?: Statewire.StateSource;
  isBusy?: boolean; setContext?: (protocol: string, value: Statewire.Context) => void;
  /** Host side: the read filter for each document entering an attach's view. */
  filter?: StatewireHost.FilterDecider;
  /** Present on transports with a durable session. */
  outbox?: {
    list: () => readonly StatewireClient.OutboxEntry[]; clientId: () => string;
    hold: StatewireClient.Outbox["hold"]; release: StatewireClient.Outbox["release"]; remove: StatewireClient.Outbox["remove"];
    update: StatewireClient.Outbox["update"]; insert: StatewireClient.Outbox["insert"];
  };
}

The transport contract every transport: element resolves to (type-only export).

ConnectionCopy Anchor Link

type ConnectionState =
  | { status: "standby"; reason: "deferred" | "idle"; degraded: false }
  | { status: "connecting"; degraded: false }
  | { status: "connected"; degraded: false }
  | { status: "retrying"; degraded: true; attempt: number; cause?: "dropped" | "reconnect" | "error" | "unauthorized"; code?: string; nextRetryAt?: number; lastError?: string; message?: string }
  | { status: "stopped"; degraded: true; reason: "gone" | "forbidden" | "unauthorized" | "protocol-error" | "storage-error"; message?: string; payload?: unknown };
type Connection = ConnectionState & { reconnect: () => void; error?: ConnectionError };
type ConnectionStatus = Connection["status"];

• connection.degraded: show a connection problem indicator.
• connection.status === "stopped": automatic recovery has ended.
• connection.status === "retrying": a recovery attempt is waiting or dialing after a scheduled wait.
• The first redial after a failed dial or a drop is immediate and is part of the current dial: the status stays connecting (or moves connected → connecting) and degraded stays false. retrying appears once a wait is scheduled, so the first retrying is attempt: 2 unless the server's retry hint delays attempt 1.
• Redial n ≥ 2 waits at least min(5 s, 1 s · 2^(n-2)), stretched by up to 50 % jitter and never shortened: 1, 2, 4, 5 s. The attempt counter resets after 30 s of a healthy connection. A server retry hint, capped at 5 s, is a lower bound on every wait.
• Coming back redials a connected attach at once: online, a document resume, a back-forward cache pageshow, the page shown after 30 s or more hidden, or, over WebSocket, a clock tick (read every second) over 5 s late on a shown page.
• Any wake (also focus, pageshow, the page shown again) redials a retrying connection (no sooner than a host retry hint allows), or a connecting one dialing for 5 s or more, at once.
• An attempt ends when its silence deadline passes or reconnect() is called, without waiting for the socket's close.
• Backoff fields (cause, code, nextRetryAt, lastError, message) are present while waiting and absent during the dial.
• reconnect() starts a fresh connection attempt from standby or stopped.

useStatewire, StatewireResourceCopy Anchor Link

const useStatewire: <TState, TCommands extends Statewire.Commands = Statewire.Commands>(options: StatewireClient.Options<TState, TCommands>) => StatewireClient.Helpers<TState, TCommands>;
const StatewireResource: <TState, TCommands extends Statewire.Commands = Statewire.Commands>(options: StatewireClient.Options<TState, TCommands>) => ResourceElement<StatewireClient.Helpers<TState, TCommands>>;

React hook over a transport element (state, commands, connection, outbox), and the same hook as a tap resource element. A key change remounts a fresh session.

StatewireClientCopy Anchor Link

class StatewireClient<TState, TCommands extends Statewire.Commands = Statewire.Commands> {
  constructor(options: StatewireClient.Options<TState, TCommands>);
  get state(): TState; get connection(): StatewireClient.Connection; get commands(): Statewire.CommandsProxy<TCommands>; get isBusy(): boolean;
  setContext(protocol: string, value: Statewire.Context): void;
  get outbox(): StatewireClient.Outbox;
  invoke(protocol: string, method: string, params: readonly unknown[], options?: StatewireClient.InvokeOptions): Promise<unknown>;
  subscribe(listener: () => void): () => void; dispose(): void;
}

Framework-agnostic client over the same core; Helpers fields as getters.

• Held state remains renderable during retries.
• Reconnects never re-send a sequence number: answers for admitted commands ride the hello, commands that never arrived get new sequence numbers through the outbox.
• Terminal failures settle pending commands and preserve the fin's message and payload.
• WebSocket hosts send the fin as a text frame before closing. Implementations that discard it can only report a dropped connection.

StatewireClient.Options<TState, TCommands>Copy Anchor Link

StatewireClient.Helpers<TState, TCommands>Copy Anchor Link

OutboxCopy Anchor Link

A command waits in the outbox, without a sequence number, until a flush stamps it. Flushes run on every enqueue, hold, release, remove and attach, under the storage lock, so exactly one sharer stamps each entry.

type Outbox = {
  readonly entries: readonly OutboxEntry[];
  hold: (id: string) => void;
  release: (id: string) => Promise<unknown>;
  remove: (id: string) => void;
  update: (id: string, fn: (entry: OutboxEntry) => OutboxPatch) => void;
  insert: (entry: OutboxInsert) => string;
};
type OutboxState = "queued" | "held" | "sending";
type OutboxEntry = {
  readonly id: string;
  readonly protocol: string;
  readonly command: { readonly method: string; readonly params: readonly unknown[] };
  readonly ts: number;
  readonly state: OutboxState;
  readonly localMeta: unknown;
  readonly durable: boolean;
};
type OutboxPatch = { held?: boolean; localMeta?: unknown; command?: { params: readonly unknown[] } };
type OutboxInsert = {
  from?: string;
  protocol: string;
  command: { method: string; params: readonly unknown[] };
  held?: boolean;
  localMeta?: unknown;
  after?: string;
  before?: string;
};
type FlushReason = "enqueue" | "reconnect" | "reload" | "release";
type OnFlush = (flush: { commands: readonly OutboxEntry[]; reason: FlushReason }) => void;
type CanOvertake = (entry: OutboxEntry, ahead: OutboxEntry) => boolean;
type InvokeOptions = { hold?: boolean; localMeta?: unknown };

• entries lists every unsettled command across sharers, per lane in queue order: stamped commands ("sending") by seq, then the outbox's "queued" and "held" entries. id is the client id the command keeps from enqueue to verdict.
• ts is the enqueue time. durable is false when the entry lives in page memory only.
• localMeta is client-only: persisted with the entry, never sent. invoke(..., { localMeta }), update and insert set it.
• hold(id): "queued" → "held". No flush stamps a held entry until it is released. The hold persists in the session record; every sharer sees it and it survives reloads.
• release(id): "held" → "queued". Works from any sharer; the promise settles with the command's outcome.
• remove(id) drops a queued or held entry; its pending send rejects { fate: "aborted", cause: "removed" }.
• update(id, fn) runs fn on the current entry under the storage lock and applies the returned patch: held, localMeta, or command.params. Any other command field throws outbox: a patch may only replace command.params.
• insert(entry) adds a command no send awaits, at the lane's tail or next to after / before, and returns its id. after and before together throw. from names the settled update the insert re-queues: the same write consumes the update, so a redelivery never inserts twice (Settled updates).
• Every verb throws outbox: no entry <id> for an unknown id and outbox: <id> is in flight for a "sending" entry. insert throws the same for an unknown or in-flight after / before anchor.
• Inside onFlush, verbs on the offered entries apply before stamping.

Ordering: each entry moves toward the front past held or waiting entries it may overtake (canOvertake(entry, ahead)) and stops behind the first it can't. Entries with nothing held or waiting ahead are stamped, in the reordered order, which the session record keeps. Without canOvertake, a held entry blocks every later entry on its protocol.

Optimistic folds run in queue order: this client's "sending" commands, then every sharer's "queued" and "held" entries, each with ctx.state and ctx.localMeta. A non-accepted settle drops the command from the outbox and the fold, and rejects its promise.

Settled updatesCopy Anchor Link

queued, posted and applied updates are in memory and best-effort. A settled update of a stamped command on a durable lane is persisted to the lane's inbox in the same write that drops the stamp, so a reload either resends the command or delivers the update.

• Delivered through onCommandChange, one sharer at a time under SessionStorage.notifyLock.
• Delivery starts after the first hello, so ctx.state is the attached state.
• At-least-once under the command's id; acked once the handler's returned promise resolves.
• A pending delivery blocks later ones for the same session.
• A handler that throws leaves the update for the next mount.
• Updates carry the command's localMeta.
• Each lane keeps the newest 256 undelivered updates; older ones are dropped and reported through SessionStorage.onEvict with reason "inbox".
• An update whose payload storage dropped to fit its byte budget carries compacted: true, params: [] and no result; id, seq, ts, failure and localMeta remain.

Re-queue a failed command held, for the user to edit, release or remove:

const client = new StatewireClient({
  transport: StatewireHttp({ url, sessionStore }),
  onCommandChange: (update) => {
    if (update.status !== "settled" || update.failure === undefined) return;
    client.outbox.insert({
      from: update.id,
      protocol: update.protocol!,
      command: { method: update.method, params: update.params },
      held: true,
      localMeta: { error: update.failure },
    });
  },
});

Session lossCopy Anchor Link

A proven record gap (a gap refusal) drops the lane's whole queue: every stamped and outbox command settles { fate: "lost", cause: "session-lost" } and becomes a settled update. The lane clock restarts at the watermark.

With unshared session storage, a gap refusal at or above every seq the lane saw answered since the hello, whose stamps above the watermark were all first sent on the current attach or never sent, loses nothing: the stamps go back to the front of the outbox and the lane clock restarts at the watermark.

An ephemeral-lane gap refusal loses nothing: the refused frame's statements go out again after the ones still in flight.

onSessionLost returning "requeue" instead re-enqueues this client's lost stamps with fresh ids at the tail and keeps the outbox. It is temporary and discouraged, and will be removed. Each requeue calls onDeprecatedPath({ kind: "session-lost-requeue", count }), or console.warn without it.

FailuresCopy Anchor Link

type SendFailure =
  | { fate: "rejected"; cause: "server"; code?: string; message?: string; payload?: unknown }
  | { fate: "failed"; cause: "server"; message?: string }
  | { fate: "crashed"; cause: "server" }
  | { fate: "expired"; cause: "server" }
  | { fate: "aborted"; cause: "unmount" | "stream-gone" | "session-lost" | "removed" | "quota"; predecessorLost?: true }
  | { fate: "lost"; cause: "unmount" | "stream-gone" | "session-lost" };

cause: "server" is the server's answer; the rest settle locally. "quota": a session storage limit refused the write that would add the command. Host-minted code values: unknown-command, invalid-params. Per-fate meaning and resend safety: failure and retry.

StatewireClient.HttpOptionsCopy Anchor Link

StatewireClient.WebsocketOptionsCopy Anchor Link

KeyValueSessionStorageCopy Anchor Link

import { KeyValueSessionStorage } from "statewire/storage";

const storage = KeyValueSessionStorage({
  backend: myStorage,
  namespace: "my-app:sessions:",
  principal: userId,
  key: threadId,
  retention: { maxAgeMs: 30 * 24 * 60 * 60 * 1000, maxEntries: 50 },
  limits: { outboxEntries: 100 },
  onEvict: ({ key, reason, dropped }) => report(key, reason, dropped),
});

namespace KeyValueSessionStorage {
  type Backend = {
    getItem: (key: string) => string | null | Promise<string | null>;
    setItem: (key: string, value: string) => void | Promise<void>;
    removeItem: (key: string) => void | Promise<void>;
    getAllKeys?: () => readonly string[] | Promise<readonly string[]>;
    withUnused?: (key: string, action: () => Promise<void>) => Promise<void>;
    subscribe?: (listener: (key: string) => void) => () => void;
  };
  type Codec = { encode: (plain: string) => Promise<string>; decode: (stored: string) => Promise<string> };
  type EvictEvent = StatewireClient.EvictEvent;
  type Options = {
    backend: Backend;
    key: string;
    namespace?: string;
    principal: string;
    protocol?: string;
    migrate?: StatewireClient.SessionStorage["migrate"];
    retention?: { maxAgeMs?: number; maxEntries?: number };
    limits?: { outboxEntries?: number; recordBytes?: number; totalBytes?: number };
    codec?: Codec;
    onError?: (error: unknown) => void;
    onEvict?: (event: EvictEvent) => void;
  };
}

const sessionNamespace: (namespace: string, principal: string) => string;

• Mount with storage: { session: storage } in StatewireClient or useStatewire.
• principal: the signed-in account, non-empty. The record is stored under <namespace><encoded-principal>:<key>; sessionNamespace(namespace, principal) returns that prefix. Changing principal on a mounted resource throws; remount the session per account.
• Each record names its principal. Loading a record that names another principal fails with storage-error and leaves the record in place: its queued commands are not sent and its settled updates are not delivered.
• backend: each method may return synchronously or through a promise. getAllKeys() enables retention and totalBytes within namespace. withUnused runs cleanup under exclusive access, skipping keys another runtime uses. subscribe reports keys other runtimes wrote.
• protocol: the lane that sessions saved in a single-lane format lift into; defaults to the client's default protocol.
• codec transforms the stored string (encryption, compression). With a codec, hydration is asynchronous.
• Hydration completes before attaching. Command persistence completes before network submission.
• Records are written as storage format 6 (STORAGE_FORMAT), which adds principal. Formats 1 to 5 upgrade on load and belong to the principal whose key holds them: a format 4 hold: { meta } becomes held: true with localMeta: meta, and each lane.failed entry becomes a settled update in lane.inbox under a fresh id.
• Malformed records and storage failures surface as errors; the stored record remains available for recovery.
• A stored string that is not JSON (a truncated or emptied write) reads as absent: the session starts a new client identity, its next save replaces the string, and onEvict reports reason: "corrupt" once. A sweep removes it from an unmounted session. A codec decode failure is an error.
• LocalStorageSession in @assistant-ui/react-statewire/local-storage provides browser coordination over this adapter.

Limits (limits), off by default:

• outboxEntries caps unsettled entries in the record, recordBytes the record's stored size, totalBytes the stored size of every record the principal keeps under namespace (requires getAllKeys). Each must be a positive integer.
• The other records count as they stand at the write: sessions mounted in the same runtime with each save they accept, the rest read again on a synchronous backend, or recounted on an asynchronous one after same-runtime saves and the keys subscribe reports.
• A write past recordBytes, or past totalBytes given the other records, first drops the payloads of the record's stored settled updates: failures before results, oldest first, until it fits.
• Past totalBytes, with retention set, a sweep under pressure frees the excess from the other records.
• A write that still adds an entry past a limit rejects that send { fate: "aborted", cause: "quota" } and changes nothing. Settling and stamping always land.
• On a synchronous backend, a QuotaExceededError on a write that adds an entry rejects the same way, a sweep under pressure frees the write's size, and the session keeps running. Other writes, and every write on an asynchronous backend, retry after each step of a sweep under pressure; a QuotaExceededError once nothing is left to free stops the session with storage-error.

Retention (retention), across the principal's records under namespace:

• A record mounted in this runtime, or in use by another (withUnused), is never touched.
• Records that are not JSON go on every sweep ("corrupt").
• Every record goes once past maxAgeMs ("expired"); empty records also past maxEntries ("overflow").
• Under pressure (a backend quota error, or past totalBytes), oldest savedAt first, until the write fits: empty records, then the payloads of stored settled updates (records kept), then records holding only settled updates, then records with queued, held or stamped entries ("quota").
• onEvict({ key, reason, dropped }) reports each evicted record with the settled updates and unsent commands that went with it, and updates the session dropped past its inbox cap (reason: "inbox").

MemorySessionStorageCopy Anchor Link

const MemorySessionStorage: (options: { principal: string; scope: string }) => ResourceElement<StatewireClient.SessionStorage>;

Session storage in page memory, keyed by principal and scope: the record and client identity survive remounts, not reloads. Its outbox entries report durable: false. principal is required and non-empty; changing it on a mounted resource throws.

IndexedDbSession, indexedDbBackendCopy Anchor Link

const IndexedDbSession: (options: IndexedDbSession.Options) => ResourceElement<StatewireClient.SessionStorage>;
namespace IndexedDbSession {
  type Options = Omit<KeyValueSessionStorage.Options, "backend" | "namespace"> & { database?: string; namespace?: string };
}
const indexedDbBackend: (database: string) => KeyValueSessionStorage.Backend;

const storage = IndexedDbSession({ principal: userId, key: threadId });

• Shared session storage on IndexedDB: sharers serialize through Web Locks and hear each other over a BroadcastChannel. Provides lock, subscribe, owner and notifyLock.
• database defaults to "statewire", namespace to "statewire-session:". The other options are KeyValueSessionStorage's, principal required.
• Stores the record under <namespace><encoded-principal>:<key>; the Web Lock names carry that key. Changing principal throws; another principal's record is refused as in KeyValueSessionStorage.
• Records saved by 0.24 under the unscoped <namespace><key> are not read. An app that knows their owner moves them to the scoped key before mounting.
• Requires indexedDB and navigator.locks.
• indexedDbBackend(database) is the key-value backend it writes through, one per database; pass it to readOutboxes.

readOutboxes, subscribeOutboxesCopy Anchor Link

const readOutboxes: (backend: KeyValueSessionStorage.Backend, options: ReadOutboxes.Options) => Promise<readonly ReadOutboxes.Outbox[]>;
const subscribeOutboxes: (
  backend: KeyValueSessionStorage.Backend,
  options: ReadOutboxes.Options,
  listener: (outboxes: readonly ReadOutboxes.Outbox[]) => void,
  onError: (error: unknown) => void,
) => () => void;
namespace ReadOutboxes {
  type Options = { namespace: string; principal: string; codec?: KeyValueSessionStorage.Codec; protocol?: string };
  type Outbox = { key: string; entries: readonly StatewireClient.OutboxEntry[] };
}

• readOutboxes reads the outbox of every session principal keeps under namespace, mounted or not; records without entries are skipped. A record naming another principal rejects. Requires getAllKeys, a non-empty namespace and a non-empty principal.
• subscribeOutboxes calls listener now and after every save to principal's sessions under namespace, in this runtime and, through backend.subscribe, in others; a read that rejects goes to onError. Returns unsubscribe.

StatewireHttp, StatewireWebsocketCopy Anchor Link

const StatewireHttp: <TState = any, TCommands extends Statewire.Commands = Statewire.Commands>(options: StatewireClient.HttpOptions) => ResourceElement<Statewire<TState | undefined, TCommands>>;
const StatewireWebsocket: <TState = any, TCommands extends Statewire.Commands = Statewire.Commands>(options: StatewireClient.WebsocketOptions) => ResourceElement<Statewire<TState | undefined, TCommands>>;

StatewireSendErrorCopy Anchor Link

class StatewireSendError extends Error { readonly failure: StatewireClient.SendFailure; constructor(failure: StatewireClient.SendFailure); }

Rejection value of a command promise. name is "StatewireSendError".

statewire/hostCopy Anchor Link

useStatewireState, useStatewireCommandsCopy Anchor Link

const useStatewireState: <TState>(init: () => TState) => readonly [TState, StatewireHost.StateCtl<TState>];
const useStatewireCommands: <THandlers extends Statewire.Commands>(commands: (THandlers & ThisType<StatewireHost.Ctx>) | undefined | null | false, options?: StatewireHost.CommandsOptions) => Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>>;

Recording-draft state (every mutation records a wire op) and handler registration (own enumerable function properties) for a host resource returning { state, commands }. A method named statewire/* throws statewire: cannot register "<m>": the "statewire/" method namespace is reserved; calls queued past unmount reject. The ThisType<StatewireHost.Ctx> intersection types this inside method shorthand and function handlers; arrow handlers keep the enclosing this.

append, getStateHost, StatewireRejectCopy Anchor Link

const append: <TKey extends string | number>(parent: { readonly [P in TKey]: string }, key: TKey, suffix: string) => void;
const getStateHost: (state: object) => StatewireHost.StateHost | undefined;
class StatewireReject extends Error { readonly payload?: unknown; constructor(message: string, options?: { payload?: unknown }); }

append records one end-offset text-insert add op (throws off a draft, on a non-string suffix, or when the field holds a non-string; an empty suffix is a no-op). getStateHost reads a useStatewireState object's source. A thrown StatewireReject settles the command rejected with message and payload.

ANY, readFilterCopy Anchor Link

const ANY: unique symbol; // Symbol.for("statewire.any")
const readFilter: (entries: readonly { readonly path: StatewireHost.FilterPath; readonly rule: StatewireHost.FilterRule }[]) => StatewireHost.Filter;

readFilter validates and freezes: it throws on an empty or non-string segment (other than ANY), a non-function rule, or two entries that can match the same node. A host resource returns filter?: StatewireHost.FilterDecider beside state and commands; the socket host calls it synchronously for each document entering an attach's view (after attaching, and at the flush that adds a document). null sends the document unfiltered; a throw, a result not built by readFilter, or a failing rule ends the attach with fin error / filter-failed. Attaches sharing a document and a filter instance compute once per flush. Rules re-run on the final state for every node an op touched at or under, and a changed instruction sends one replace of the node. Guide.

StatewireHostCopy Anchor Link

statewire/host-internalCopy Anchor Link

StatewireSocketHostCopy Anchor Link

const StatewireSocketHost: (transport: ResourceElement<Statewire>, options?: StatewireHostInternal.SocketHostOptions, persistence?: StatewireHostInternal.SocketHostPersistence) => StatewireHostInternal.SocketHost;
const WS_SUBPROTOCOL = "statewire.v1";

Transport-agnostic serving engine over any send/close socket. dispose() finishes { reason: "reconnect", code: "evicted" }. persistence.clients keeps each client id's lane watermarks in a ClientStore across restarts: records load before an attach registers, admitted commands run and their dur goes out after save settles, and a re-sent seq at or below a stored watermark answers expired.

clientIdFromUrl, textFrameOrCloseCopy Anchor Link

const clientIdFromUrl: (url: string | null | undefined) => string;
const textFrameOrClose: (socket: Pick<StatewireHostInternal.Socket, "close">, data: unknown) => string | null;

clientIdFromUrl reads the client query parameter (throws when missing or unparseable). textFrameOrClose returns a string frame or closes 1008 ("text frames only") and returns null.

StatewireHostInternalCopy Anchor Link

StatewireHostInternal.SocketHostOptions<TAuth>Copy Anchor Link

Fixed wire limits (limits): 256 commands per frame, 256 in flight per client, 8 MiB frame body, 64 KiB per context value, capacity refusals carry retry: 1000.

statewire/testingCopy Anchor Link

createMockTransportCopy Anchor Link

const createMockTransport: <TState>(initialState: TState) => MockTransport<TState>;
type MockTransport<TState> = {
  transport: ResourceElement<Statewire<TState | undefined, any>>;
  commands: { method?: string; params?: unknown[]; context?: unknown }[];
  setState: (state: TState) => Promise<void>; applied: (seq: number) => Promise<void>; settle: (seq: number, payload?: unknown) => Promise<void>;
  sendEnvelope: (envelope: StatewireEnvelope) => Promise<void>; finish: (reason: string, message?: string) => Promise<void>;
  readonly clientId: string; readonly attached: boolean;
};

Mock backend: initialState is the attach snapshot, frames land in commands. Acks and verdicts come from test code. StatewireEnvelope is one packet: { ops?: unknown[]; cmd?: StatewireCmd[]; next?: true; idle?: boolean; syn?: StatewireSyn; fin?: StatewireHost.Fin }.

tick, settleCopy Anchor Link

const tick: () => Promise<void>;     // one macrotask
const settle: () => Promise<void>;   // three ticks

applyOptimisticCopy Anchor Link

const applyOptimistic: <TState>(state: TState, mutate: (draft: TState) => void) => TState;

Runs a mutator against a recording draft, as the client does for optimistic. Throws statewire: cannot record mutations on primitive state.

createCounterElementCopy Anchor Link

const createCounterElement: () => ResourceElement<{ state: { count: number }; commands: Statewire.CommandsProxy<{ increment: () => void }> }>;

Minimal host element: { count } state with an increment command.

commandFrameCopy Anchor Link

const commandFrame: (method: string, seq: number, params?: unknown[]) => string;

Serializes a one-statement cmd-lane frame, { cmd: [{ method, params, seq }] }. params defaults to [].

createSocketRecorderCopy Anchor Link

const createSocketRecorder: () => SocketRecorder;
type SocketRecorder = { sent: string[]; closes: { code?: number; reason?: string }[]; last: () => any; send: (data: string) => void; close: (code?: number, reason?: string) => void };

Records sent frames and close calls. last() parses the latest frame.

Lease contextCopy Anchor Link

const client = new StatewireClient({
  context: { default: { page: "overview" } },
  transport: StatewireWebsocket({ url: "/workspace" }),
});
client.setContext("default", { page: "changes", openedAt: new Date() });

• setContext(protocol, value) replaces the selected protocol's object. {} clears its fields.
• Date values use Statewire Document encoding. Each encoded entry is limited to 64 KiB.
• Context updates leave command clocks and durable replay records unchanged.
• New attachments receive the latest retained context, including a new hello on a preserved socket.
• Host transports implement validateContext(protocol, value, attach) and contextChanged(protocol, value, attach). Validators run for the whole frame before installation; change hooks run after installation.
• attach.caller carries authorization. attach.context(protocol) reads that attachment's current context. this.context in a command handler is its captured admission snapshot.
• useStatewireCommands(handlers, { context: () => value, version }) supplies context and this.version to in-process dispatch.