@rikalabs/akter 0.1.0-alpha.0

package/dist/client/fleet.js

@@ -0,0 +1,51 @@
+import { Effect, Option, Predicate, Schema, Stream } from "effect";
+import { FLEET_PAGE_DEFAULT, FleetPageJson, fleetFilterText } from "./fleet-page.js";
+import { joinUrl } from "./calls.js";
+import { networkFailure, undecodableFailure } from "./transport.js";
+import { watchStream } from "./sessions/watch.js";
+const decodePage = Schema.decodeUnknownEffect(FleetPageJson);
+/**
+ * The Promise client of `options.views`, served by `Actor.serve({ fleet })`. Each
+ * `subscribe` is an `AsyncIterable` of pages for the tenant the server
+ * authenticates, over `GET /fleet/{View}`: the current page first, then a page
+ * whenever the view changed. A dropped connection reopens after a growing,
+ * jittered delay, and its first page is the current state. It fails with the
+ * `ActorError` that ended it when a retry cannot help, and retries an expired
+ * credential once. `options.headers` is read for every attempt.
+ */
+export const fleetClient = (options) => {
+    const views = options.views;
+    const fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const provided = Effect.suspend(() => {
+        const headers = options.headers;
+        return Predicate.isFunction(headers)
+            ? Effect.promise(() => Promise.resolve(headers()))
+            : Effect.succeed(headers);
+    });
+    const view = (declared) => ({
+        subscribe: (filter = {}, subscribe = {}) => {
+            const query = new URLSearchParams(fleetFilterText(filter));
+            query.set("limit", String(subscribe.limit ?? FLEET_PAGE_DEFAULT));
+            const url = joinUrl({
+                baseUrl: options.baseUrl,
+                path: `/fleet/${declared.name}?${query.toString()}`,
+            });
+            return Stream.toAsyncIterable(watchStream({
+                decode: (json) => decodePage(json).pipe(Effect.mapError(undecodableFailure)),
+                declared: () => Option.none(),
+                token: () => undefined,
+                options: subscribe,
+                open: (_version, signal) => Effect.gen(function* () {
+                    const headers = new Headers(yield* provided);
+                    headers.set("accept", "text/event-stream");
+                    headers.set("durable-protocol", "1");
+                    return yield* Effect.tryPromise({
+                        try: () => fetch(url, { method: "GET", headers, signal }),
+                        catch: networkFailure,
+                    });
+                }),
+            }));
+        },
+    });
+    return Object.fromEntries(views.map((declared) => [declared.name, view(declared)]));
+};

package/dist/client/index.d.ts

@@ -0,0 +1,17 @@
+import * as Inspection from "../protocol/inspection.ts";
+export type { ActorClient, ClientHandle, ClientOptions, ClientState, CommandOptions, ConnectionClient, StreamCall, WatchCall, HeadersProvider, QueryOptions, } from "./make.ts";
+export type { PendingInput } from "./optimistic.ts";
+export type { OfflineQueue, PendingCommand } from "./offline/queue.ts";
+export { Offline, OfflineStoreError } from "./offline/store.ts";
+export type { OfflineStore, QueuedCommand } from "./offline/store.ts";
+export type { ClientConnection, ConnectionMessage, ConnectOptions, ProgressMessage, ProgressOfConnection, ProgressUpdate, } from "./sessions/connection.ts";
+export type { FeedEntry, FeedOptions } from "./sessions/feed.ts";
+export type { StreamOptions } from "./sessions/stream.ts";
+export type { WatchOptions } from "./sessions/watch.ts";
+export { fleetClient } from "./fleet.ts";
+export type { FleetClient, FleetSubscribeOptions, FleetViewClient } from "./fleet.ts";
+export type { FleetFilter, FleetPage, FleetRow } from "../tables/fleet.ts";
+export type { Failure } from "./transport.ts";
+export { ActorError, ActorUnavailable, CommandConflict, CommandExpired, InvalidCommandId, InvalidInput, MailboxFull, NotCreated, RunnerAtCapacity, QuotaExceeded, SpendLimitExceeded, ConnectionLimitExceeded, StorageQuotaExceeded, SessionEnded, Timeout, TransportError, Unauthorized, } from "../errors/actor.ts";
+export { RetentionGap, UnknownCursor } from "../errors/events.ts";
+export { Inspection };

package/dist/client/index.js

@@ -0,0 +1,6 @@
+import * as Inspection from "../protocol/inspection.js";
+export { Offline, OfflineStoreError } from "./offline/store.js";
+export { fleetClient } from "./fleet.js";
+export { ActorError, ActorUnavailable, CommandConflict, CommandExpired, InvalidCommandId, InvalidInput, MailboxFull, NotCreated, RunnerAtCapacity, QuotaExceeded, SpendLimitExceeded, ConnectionLimitExceeded, StorageQuotaExceeded, SessionEnded, Timeout, TransportError, Unauthorized, } from "../errors/actor.js";
+export { RetentionGap, UnknownCursor } from "../errors/events.js";
+export { Inspection };

package/dist/client/make.d.ts

@@ -0,0 +1,157 @@
+import type { ServedDefinition } from "../actor/served.ts";
+import type { AnyMember, MemberRecord } from "../members/command.ts";
+import type { AnyConnection } from "../members/connection.ts";
+import type { AnyStream } from "../members/stream.ts";
+import type { EventClass } from "../members/event.ts";
+import { type ClientConnection, type ConnectOptions, type ProgressOfConnection } from "./sessions/connection.ts";
+import { type FeedEntry, type FeedOptions } from "./sessions/feed.ts";
+import { type StreamOptions } from "./sessions/stream.ts";
+import { type WatchOptions } from "./sessions/watch.ts";
+import type { OfflineQueue } from "./offline/queue.ts";
+import type { OfflineStore } from "./offline/store.ts";
+import { type PendingInput } from "./optimistic.ts";
+type HeadersValue = Readonly<Record<string, string>> | Headers | Array<[string, string]>;
+/** Headers sent with every attempt; a function is called again for each attempt, including retries. */
+export type HeadersProvider = HeadersValue | (() => HeadersValue | Promise<HeadersValue>);
+/** Options of `X.client`. */
+export interface ClientOptions {
+    /** Where `Actor.serve` is mounted, absolute or relative to the page. */
+    readonly baseUrl: string;
+    /**
+     * Headers for every request. A connection sends the `authorization` header
+     * in `hello` instead, because browsers can't set headers on a WebSocket.
+     */
+    readonly headers?: HeadersProvider;
+    /** How long one call, retries included, may wait. Defaults to 60,000. */
+    readonly timeoutInMs?: number;
+    /** Defaults to the global `fetch`. */
+    readonly fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    /**
+     * `client` (default) mints ids from the database clock learned through
+     * `/protocol`; `server` asks `/command-ids` for each one.
+     */
+    readonly commandIds?: "client" | "server";
+    /**
+     * Saves every command before its first attempt and delivers it in order per
+     * actor under its original id, across outages and reloads; see
+     * `ActorClient.offline`. Queries and streams are unaffected.
+     */
+    readonly offline?: OfflineStore;
+    /**
+     * A stable key for who the client runs as, such as the signed-in user's id,
+     * read before each offline command is saved and before each attempt. The
+     * offline queue sends only the commands saved under the current key and
+     * holds the rest. Never a credential. Without it, the key is the `iss` and
+     * `sub` of an `authorization: Bearer` JWT, and an offline client with
+     * neither refuses to queue commands.
+     */
+    readonly identity?: () => string | Promise<string>;
+}
+/** Options of one query call. */
+export interface QueryOptions {
+    /** Stops waiting; server work already accepted is not cancelled. */
+    readonly signal?: AbortSignal;
+    /** Overrides `ClientOptions.timeoutInMs` for this call. */
+    readonly timeoutInMs?: number;
+}
+/** Options of one command call. */
+export interface CommandOptions extends QueryOptions {
+    /** Sent as `Idempotency-Key` on every attempt; minted once when omitted. */
+    readonly commandId?: string;
+}
+/**
+ * The `watch` of a query declared `watch: true`: an `AsyncIterable` of the
+ * query's current result and then its newest result after each change. It is
+ * state, not history: intermediate results are skipped and a reconnect sends the
+ * current result first, never one older than one already delivered.
+ */
+export type WatchCall<M extends AnyMember> = (...args: M["payload"]["Type"] extends void ? [options?: WatchOptions] : [input: M["payload"]["Type"], options?: WatchOptions]) => AsyncIterable<M["success"]["Type"]>;
+type Call<M extends AnyMember> = (M["payload"]["Type"] extends void ? (options?: M["kind"] extends "query" ? QueryOptions : CommandOptions) => Promise<M["success"]["Type"]> : (input: M["payload"]["Type"], options?: M["kind"] extends "query" ? QueryOptions : CommandOptions) => Promise<M["success"]["Type"]>) & (M extends {
+    readonly watch: true;
+} ? {
+    readonly watch: WatchCall<M>;
+} : unknown);
+/**
+ * A handle's view of its actor's state: the committed state it last learned,
+ * from a reducer's reply or `reconcile`, with its pending reducer inputs applied.
+ * Reducer calls send one at a time, so each reply is the committed state
+ * before every later pending input. The view has settled before the caller's
+ * own callbacks run, and a listener that calls another reducer queues it
+ * behind the current one.
+ */
+export interface ClientState<State> {
+    /** Committed state plus pending inputs; undefined until committed state is known. */
+    readonly current: State | undefined;
+    /** Reducer inputs applied ahead of their receipts, in call order. */
+    readonly pending: ReadonlyArray<PendingInput>;
+    /** Calls `listener` with `current` after each change; returns the unsubscribe. */
+    readonly subscribe: (listener: (state: State | undefined) => void) => () => void;
+    /** Replaces the committed state, e.g. with one a query read, and reapplies pending inputs. */
+    readonly reconcile: (committed: State) => void;
+}
+/** A connection member: `connect` opens one session over WebSocket. */
+export interface ConnectionClient<M extends AnyConnection> {
+    /** Opens a session; the `authorization` header from `headers` travels in `hello`. */
+    readonly connect: (...args: M["payload"]["Type"] extends void ? [params?: M["payload"]["Type"], options?: ConnectOptions] : [params: M["payload"]["Type"], options?: ConnectOptions]) => Promise<ClientConnection<M["server"]["Type"], M["client"]["Type"], ProgressOfConnection<M>>>;
+}
+/** A stream member: each call subscribes once, as an `AsyncIterable` of its elements. */
+export type StreamCall<M extends AnyStream> = (...args: M["payload"]["Type"] extends void ? [options?: StreamOptions] : [input: M["payload"]["Type"], options?: StreamOptions]) => AsyncIterable<M["success"]["Type"]>;
+/** One actor over HTTP: each public member as a Promise-returning method, connections as `connect`. */
+export type ClientHandle<Members extends MemberRecord, Id = string, State = unknown, Events extends EventClass = never> = {
+    readonly [K in keyof Members]: Members[K] extends AnyConnection ? ConnectionClient<Members[K]> : Members[K] extends AnyStream ? StreamCall<Members[K]> : Call<Members[K]>;
+} & {
+    /** The actor type's name and this handle's id. */
+    readonly ref: {
+        readonly actor: string;
+        readonly id: Id;
+    };
+    /** The handle's committed and optimistic state. */
+    readonly state: ClientState<State>;
+    /**
+     * The actor's committed `event`s after `options.after`, over its event feed,
+     * as they commit. Only events the actor type lists in `feeds` are served.
+     */
+    readonly events: <E extends Events>(event: E, options?: FeedOptions) => AsyncIterable<FeedEntry<E["Type"]>>;
+};
+/** The client of one actor type: `get` (and `create` for minted ids) return handles. */
+export type ActorClient<Members extends MemberRecord, Kind extends ServedDefinition["key"], Id, State = unknown, Events extends EventClass = never> = {
+    /** A fresh command id, for a caller that saves it before sending the command. */
+    readonly commandId: () => Promise<string>;
+    /**
+     * The persisted command queue when `ClientOptions.offline` is set, else
+     * `undefined`. A command call then resolves with its output once the server
+     * answers, and rejects with `Timeout` carrying the command's id if the
+     * call's own timeout or signal ends the wait first; the command stays
+     * queued and is still delivered under that id.
+     */
+    readonly offline: OfflineQueue | undefined;
+} & (Kind extends "singleton" ? {
+    readonly get: () => ClientHandle<Members, string, State, Events>;
+} : Kind extends "minted" ? {
+    readonly get: (id: Id) => ClientHandle<Members, Id, State, Events>;
+    /** A handle to a new actor whose UUIDv7 id is minted here; it exists once a command reaches it. */
+    readonly create: () => ClientHandle<Members, Id, State, Events>;
+} : {
+    readonly get: (id: Id) => ClientHandle<Members, Id, State, Events>;
+});
+/**
+ * A connection's WebSocket URL from its route's URL, resolved against the page
+ * when relative: `wss:` for `https:` or `wss:`, and `ws:` otherwise.
+ */
+export declare const socketUrl: (route: string) => string;
+/**
+ * The Promise client of one served actor type, typed by its caller.
+ *
+ * Every response carries `durable-now`, so each round trip refreshes the
+ * database clock, except a 504, which waited out a deadline and says little
+ * about when it was stamped. `/protocol` is read again when no recent clock
+ * sample remains, since the offset may have drifted, and a `window` rejection
+ * clears the cached window because a deployment at this URL may have changed
+ * it. Without a usable clock sample, such as after a slow `/protocol`, the
+ * server mints the id instead. An unanswered command's outcome is unknown, so
+ * its `Timeout` carries the id a caller retries later. Past 1,024 handles the
+ * least recently used other handle with nothing pending and no listener is
+ * dropped.
+ */
+export declare const clientOf: <Client>(definition: ServedDefinition) => (options: ClientOptions) => Client;
+export {};

package/dist/client/make.js

@@ -0,0 +1,221 @@
+import { Effect, Exit, Option, Schema, SchemaAST, Stream } from "effect";
+import { ActorError, InvalidInput, Timeout } from "../errors/actor.js";
+import { callsOf, declaredDecoder, joinUrl, uuid } from "./calls.js";
+import { connect, } from "./sessions/connection.js";
+import { feedStream } from "./sessions/feed.js";
+import { subscription } from "./sessions/stream.js";
+import { watchStream } from "./sessions/watch.js";
+import { Optimistic } from "./optimistic.js";
+import { undecodableFailure } from "./transport.js";
+/** Handles kept per client. */
+const HANDLE_LIMIT = 1_024;
+const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Json));
+const invalid = () => ActorError.make({ reason: InvalidInput.make({ code: "decode" }) });
+/**
+ * A connection's WebSocket URL from its route's URL, resolved against the page
+ * when relative: `wss:` for `https:` or `wss:`, and `ws:` otherwise.
+ */
+export const socketUrl = (route) => {
+    const url = new URL(route, "location" in globalThis ? globalThis.location.href : undefined);
+    url.protocol = url.protocol === "https:" || url.protocol === "wss:" ? "wss:" : "ws:";
+    return url.href;
+};
+const decodeInputCopy = (member) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(member.input)));
+const isVoidInput = (member) => SchemaAST.isVoid(member.input.ast) || SchemaAST.isUndefined(member.input.ast);
+/**
+ * The Promise client of one served actor type, typed by its caller.
+ *
+ * Every response carries `durable-now`, so each round trip refreshes the
+ * database clock, except a 504, which waited out a deadline and says little
+ * about when it was stamped. `/protocol` is read again when no recent clock
+ * sample remains, since the offset may have drifted, and a `window` rejection
+ * clears the cached window because a deployment at this URL may have changed
+ * it. Without a usable clock sample, such as after a slow `/protocol`, the
+ * server mints the id instead. An unanswered command's outcome is unknown, so
+ * its `Timeout` carries the id a caller retries later. Past 1,024 handles the
+ * least recently used other handle with nothing pending and no listener is
+ * dropped.
+ */
+export const clientOf = (definition) => (options) => {
+    const { authorization, token, openEvents, mint, waiting, withRetries, asAttempt, poster, queue, commandId: mintCommandId, } = callsOf({ definition, options });
+    /**
+     * Encodes one call's input now, so every attempt under one id sends the same
+     * bytes, and returns what sends it, with a decoded copy of that input.
+     */
+    const prepare = (member, segment, args) => {
+        const isVoid = isVoidInput(member);
+        const call = (isVoid ? args[0] : args[1]) ?? {};
+        const isQuery = member.kind === "query";
+        let commandId = isQuery ? undefined : call.commandId;
+        const body = Effect.runSyncExit(Schema.encodeUnknownEffect(Schema.toCodecJson(member.input))(isVoid ? undefined : args[0]).pipe(Effect.flatMap((json) => json === undefined ? Effect.succeedNone : Effect.asSome(encodeJson(json))), Effect.mapError(invalid)));
+        const post = poster(member);
+        const attempt = Effect.gen(function* () {
+            const path = `/actors/${definition.name}${yield* segment}/${member.tag}`;
+            const payload = Option.getOrUndefined(yield* body);
+            if (!isQuery && commandId === undefined)
+                commandId = yield* mint;
+            return yield* post(path, payload, commandId);
+        }).pipe(Effect.mapError((error) => asAttempt(commandId)(error)));
+        const input = Exit.isSuccess(body)
+            ? Option.getOrUndefined(Exit.getSuccess(Effect.runSyncExit(Option.match(body.value, {
+                onNone: () => Effect.void,
+                onSome: (json) => decodeInputCopy(member)(json),
+            }))))
+            : undefined;
+        /**
+         * Saves this command in the offline queue, minting its id first when the
+         * caller gave none, and reports when it is delivered. `call` is the
+         * caller's view, bounded by its timeout and signal; `delivered` outlives
+         * both, so state that follows the command follows its real outcome.
+         */
+        const enqueue = queue === undefined || isQuery
+            ? undefined
+            : () => {
+                const make = Effect.gen(function* () {
+                    const target = `/actors/${definition.name}${yield* segment}`;
+                    const payload = Option.getOrUndefined(yield* body);
+                    commandId ??= yield* mint;
+                    return { commandId, target, member: member.tag, body: payload };
+                });
+                const delivered = queue.submit(make, call.signal).then((delivery) => delivery === undefined
+                    ? Promise.reject(ActorError.make({
+                        reason: Timeout.make(commandId === undefined ? {} : { commandId }),
+                    }))
+                    : Effect.runPromise(delivery.settled));
+                return {
+                    delivered,
+                    call: waiting(Effect.tryPromise({
+                        try: () => delivered,
+                        catch: (thrown) => thrown,
+                    }), call, () => commandId),
+                };
+            };
+        return {
+            input: Exit.isSuccess(body) ? Option.some(input) : Option.none(),
+            send: (after) => withRetries(attempt, call, () => commandId, after),
+            enqueue,
+        };
+    };
+    const method = (member, segment, store) => (...args) => {
+        const { input, send, enqueue } = prepare(member, segment, args);
+        const reducer = member.reducer;
+        if (reducer === undefined || Option.isNone(input))
+            return enqueue === undefined ? send() : enqueue().call;
+        const entry = { member: member.tag, input: input.value, reducer };
+        if (enqueue === undefined)
+            return store.sendInOrder(entry, send);
+        const { call, delivered } = enqueue();
+        store.follow(entry, delivered);
+        return call;
+    };
+    const handles = new Map();
+    const stores = new Map();
+    const handle = (id, segment) => {
+        const existing = handles.get(id);
+        const existingStore = stores.get(id);
+        if (existing !== undefined && existingStore !== undefined) {
+            handles.delete(id);
+            handles.set(id, existing);
+            return existing;
+        }
+        const store = new Optimistic(definition.members.find((member) => member.reducer !== undefined)?.reducer);
+        const path = (member) => segment.pipe(Effect.map((encoded) => `/actors/${definition.name}${encoded}/${member}`));
+        const watching = (member) => (...args) => {
+            const isVoid = isVoidInput(member);
+            const watchOptions = (isVoid ? args[0] : args[1]) ?? {};
+            const body = Schema.encodeUnknownEffect(Schema.toCodecJson(member.input))(isVoid ? undefined : args[0]).pipe(Effect.flatMap((json) => json === undefined ? Effect.succeedNone : Effect.asSome(encodeJson(json))), Effect.map(Option.getOrUndefined), Effect.mapError(invalid));
+            return Stream.toAsyncIterable(watchStream({
+                decode: (json) => Schema.decodeEffect(Schema.toCodecJson(member.output))(json).pipe(Effect.mapError(undecodableFailure)),
+                declared: declaredDecoder(member),
+                options: watchOptions,
+                token: () => token.value,
+                open: (version, signal) => Effect.gen(function* () {
+                    const payload = yield* body;
+                    const headers = {};
+                    if (payload !== undefined)
+                        headers["content-type"] = "application/json";
+                    if (version !== undefined)
+                        headers["durable-min-version"] = version;
+                    return yield* openEvents(path(member.tag).pipe(Effect.map((query) => `${query}/watch`)), signal, { method: "POST", body: payload, headers });
+                }),
+            }));
+        };
+        const created = {
+            ...Object.fromEntries(definition.members.map((member) => [
+                member.tag,
+                member.watch
+                    ? Object.assign(method(member, segment, store), { watch: watching(member) })
+                    : method(member, segment, store),
+            ])),
+            ...Object.fromEntries(definition.connections.map((member) => [
+                member.tag,
+                {
+                    connect: (params, connectOptions) => Effect.runPromise(path(member.tag)).then((memberPath) => connect({
+                        member,
+                        url: socketUrl(joinUrl({ baseUrl: options.baseUrl, path: memberPath })),
+                        authorization,
+                        params,
+                        options: connectOptions ?? {},
+                    })),
+                },
+            ])),
+            ...Object.fromEntries(definition.streams.map((member) => [
+                member.tag,
+                (...args) => {
+                    const isVoid = isVoidInput(member);
+                    const streamOptions = (isVoid ? args[0] : args[1]) ?? {};
+                    const body = Schema.encodeUnknownEffect(Schema.toCodecJson(member.input))(isVoid ? undefined : args[0]).pipe(Effect.flatMap((json) => json === undefined ? Effect.succeedNone : Effect.asSome(encodeJson(json))), Effect.map(Option.getOrUndefined), Effect.mapError(invalid));
+                    return Stream.toAsyncIterable(subscription({
+                        member,
+                        declared: declaredDecoder(member),
+                        options: streamOptions,
+                        open: (signal) => Effect.gen(function* () {
+                            const payload = yield* body;
+                            return yield* openEvents(path(member.tag), signal, {
+                                method: "POST",
+                                body: payload,
+                                headers: payload === undefined ? {} : { "content-type": "application/json" },
+                            });
+                        }),
+                    }));
+                },
+            ])),
+            events: (event, feedOptions) => Stream.toAsyncIterable(feedStream({
+                event,
+                options: feedOptions ?? {},
+                open: (cursor, signal) => openEvents(path("events").pipe(Effect.map((events) => `${events}?${new URLSearchParams({ event: event.identifier })}`)), signal, { headers: cursor === undefined ? {} : { "last-event-id": cursor } }),
+            })),
+            ref: { actor: definition.name, id },
+            state: {
+                get current() {
+                    return store.state;
+                },
+                get pending() {
+                    return store.pending;
+                },
+                subscribe: (listener) => store.subscribe(listener),
+                reconcile: (committed) => store.reconcile(committed),
+            },
+        };
+        handles.set(id, created);
+        stores.set(id, store);
+        if (handles.size > HANDLE_LIMIT)
+            for (const key of handles.keys())
+                if (key !== id && stores.get(key)?.isIdle === true) {
+                    handles.delete(key);
+                    stores.delete(key);
+                    break;
+                }
+        return created;
+    };
+    const keyed = (id) => handle(id, definition.encodeId(id).pipe(Effect.map((encoded) => `/${encodeURIComponent(encoded)}`), Effect.mapError(invalid)));
+    const client = {
+        offline: queue,
+        commandId: mintCommandId,
+        get: definition.key === "singleton"
+            ? () => handle("singleton", Effect.succeed(""))
+            : (id) => keyed(id),
+        create: definition.key === "minted" ? () => keyed(Effect.runSync(uuid(7))) : undefined,
+    };
+    return client;
+};

package/dist/client/offline/queue.d.ts

@@ -0,0 +1,118 @@
+import { Effect, Option, Schema } from "effect";
+import type { Failure } from "../transport.ts";
+import { type OfflineStore, type QueuedCommand } from "./store.ts";
+/** A queued command as an application sees it. */
+export interface PendingCommand {
+    readonly commandId: string;
+    /** The actor's route under the client's `baseUrl`. */
+    readonly target: string;
+    readonly member: string;
+    /** The JSON the command was called with, as sent. */
+    readonly input: Schema.Json | undefined;
+    /**
+     * `queued` is still being delivered; `held` was queued under another
+     * principal and waits until that principal signs back in or the application
+     * discards it; `expired` and `failed` wait for the application to `discard` them.
+     */
+    readonly status: QueuedCommand["status"] | "held";
+    /**
+     * While `queued`, the last answer that did not settle the command, such as a
+     * network failure or a rejected credential. For `expired`, its
+     * `CommandExpired`; for `failed`, the failure the server answered with.
+     */
+    readonly failure: Failure | undefined;
+}
+/**
+ * A client's persisted command queue. Every command is saved before its first
+ * attempt and sent under the id it was saved with until the server answers or
+ * the id expires; nothing here ever mints a replacement id.
+ */
+export interface OfflineQueue {
+    /** Settles once saved commands are read; rejects with `OfflineStoreError` when the store cannot be read. */
+    readonly ready: Promise<void>;
+    /** Every command not yet removed, in queue order. Empty until `ready`. */
+    readonly pending: ReadonlyArray<PendingCommand>;
+    /** Calls `listener` with `pending` after each change; returns the unsubscribe. */
+    readonly subscribe: (listener: (pending: ReadonlyArray<PendingCommand>) => void) => () => void;
+    /**
+     * Tries again now: skips any wait between attempts and resumes an actor
+     * whose commands stopped on a rejected credential. It also runs when the
+     * browser reports it is back online.
+     */
+    readonly flush: () => void;
+    /**
+     * Forgets a command and never sends it again; a command already sent may
+     * have been applied. It settles a caller still waiting with `Timeout`.
+     * The only way to resolve an `expired`, `failed`, or `held` command.
+     */
+    readonly discard: (commandId: string) => Promise<void>;
+    /** Stops delivering. Saved commands stay saved for the next session. */
+    readonly close: () => void;
+}
+/** What a client asks the queue to save; the queue adds its position, base URL, principal and status. */
+type NewCommand = Pick<QueuedCommand, "commandId" | "target" | "member" | "body">;
+/** One answered attempt that did not settle the command, with when to try again if the client knows. */
+export interface Refused {
+    readonly failure: Failure;
+    readonly retryAfterMs: Option.Option<number>;
+    readonly answer: QueuedCommand["answer"];
+}
+export interface QueueOptions<Output> {
+    readonly store: OfflineStore;
+    /** Only commands saved under this base URL are delivered. */
+    readonly baseUrl: string;
+    /** Only commands of this actor type are delivered. */
+    readonly actor: string;
+    /**
+     * The principal the client runs as now, read before each command is saved
+     * and before each attempt; only commands saved under it are sent.
+     */
+    readonly principal: Effect.Effect<string>;
+    /** The estimated database time, for judging a command's expiry. */
+    readonly now: () => number;
+    /**
+     * Starts one command's delivery and returns one attempt at it, which may be
+     * run again. It succeeds with the decoded output or fails with why it did
+     * not settle.
+     */
+    readonly begin: (command: QueuedCommand) => Effect.Effect<Output, Refused>;
+    /** The failure a saved `failed` command's answer decodes to. */
+    readonly failureOf: (command: QueuedCommand) => Failure;
+    /** Learns the retry window and the database clock while the network is up, so commands can be minted offline. */
+    readonly warm: Effect.Effect<void>;
+}
+/** What the queue hands back for a saved command. */
+export interface Delivery<Output> {
+    /** Succeeds with the command's output once the server answers; fails with the terminal failure. */
+    readonly settled: Effect.Effect<Output, Failure>;
+}
+/** The queue a client drives: what an application sees, plus saving commands. */
+export interface CommandQueue<Output> extends OfflineQueue {
+    /**
+     * Saves the command `make` builds, then delivers it. Calls are taken one at
+     * a time in the order they were made, so an id that takes longer to mint
+     * still queues in front of a later call. Resolves to nothing when `signal`
+     * aborted before the command was saved, in which case nothing was queued.
+     * Rejects with `OfflineStoreError` when the command could not be saved, and
+     * then nothing was sent.
+     */
+    readonly submit: (make: Effect.Effect<NewCommand, Failure>, signal: AbortSignal | undefined) => Promise<Delivery<Output> | undefined>;
+}
+/**
+ * The queue behind a client's `offline` option. It keeps each actor's commands
+ * in the order they were called and sends one at a time, so a later command
+ * never overtakes an earlier one that is still waiting for the network;
+ * different actors are delivered independently. A command that expires or is
+ * rejected for good does not hold back those after it.
+ *
+ * Each command is saved under the principal the client ran as, and only
+ * commands of the current principal are sent: another's are `held`, so a
+ * shared store never sends one user's commands with another's credential.
+ *
+ * Ids are minted by the caller and stored with the command, so a replay after
+ * a lost reply, a reload, or a second tab is a retry the receipt answers, never
+ * a second execution. Tabs sharing one store each deliver what they read, and
+ * only the order within a tab is kept.
+ */
+export declare const openCommandQueue: <Output>(options: QueueOptions<Output>) => CommandQueue<Output>;
+export {};