solid-objects 0.12.0

package/dist/wake-up.js

@@ -0,0 +1,66 @@
+export class InProcessWakeUpAdapter {
+    generations = new Map();
+    waiters = new Map();
+    closed = false;
+    watch(role) {
+        const generation = this.generation(role);
+        return {
+            wait: (options) => this.wait({ role, generation, ...options }),
+        };
+    }
+    notify(role) {
+        if (this.closed)
+            return;
+        this.generations.set(role, this.generation(role) + 1);
+        const waiters = this.waiters.get(role);
+        if (!waiters)
+            return;
+        this.waiters.delete(role);
+        for (const wake of waiters)
+            wake();
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const waiters of this.waiters.values()) {
+            for (const wake of waiters)
+                wake();
+        }
+        this.waiters.clear();
+    }
+    wait(options) {
+        if (this.closed || options.signal?.aborted)
+            return Promise.resolve();
+        if (this.generation(options.role) !== options.generation)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            let settled = false;
+            const waiters = this.waiters.get(options.role) ?? new Set();
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                waiters.delete(finish);
+                if (waiters.size === 0)
+                    this.waiters.delete(options.role);
+                options.signal?.removeEventListener("abort", finish);
+                resolve();
+            };
+            const timeout = setTimeout(finish, options.timeoutMilliseconds);
+            waiters.add(finish);
+            this.waiters.set(options.role, waiters);
+            options.signal?.addEventListener("abort", finish, { once: true });
+            if (this.closed ||
+                options.signal?.aborted ||
+                this.generation(options.role) !== options.generation) {
+                finish();
+            }
+        });
+    }
+    generation(role) {
+        return this.generations.get(role) ?? 0;
+    }
+}
+//# sourceMappingURL=wake-up.js.map

package/dist/wake-up.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake-up.js","sourceRoot":"","sources":["../src/wake-up.ts"],"names":[],"mappings":"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"}

package/dist/worker.d.ts

@@ -0,0 +1,36 @@
+import type { SolidObjectsRuntime } from "./runtime.js";
+export declare class Worker {
+    private readonly runtime;
+    private readonly options;
+    readonly processId: `${string}-${string}-${string}-${string}-${string}`;
+    private registered;
+    private stopping;
+    private readonly activations;
+    constructor(runtime: SolidObjectsRuntime, options?: {
+        setupFailure?: "report" | "throw";
+    });
+    runOnce(options?: {
+        activationRetention?: "retain" | "release";
+    }): Promise<number>;
+    runUntilIdle(options?: {
+        maxTurns?: number;
+    }): Promise<number>;
+    run(signal: AbortSignal): Promise<void>;
+    requestShutdown(): void;
+    stopped(): boolean;
+    stop(): Promise<void>;
+    private releaseCachedActivations;
+    private ensureRegistered;
+    private claimCachedActivation;
+    private maintainCachedActivations;
+    private releaseActivation;
+    private releaseFailedSetup;
+    private reportSetupFailure;
+}
+export declare function waitFor(milliseconds: number, signal?: AbortSignal): Promise<void>;
+export declare function withProcessHeartbeat<Result>(options: {
+    runtime: SolidObjectsRuntime;
+    processId: string;
+    operation: () => Promise<Result>;
+}): Promise<Result>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AASvD,qBAAa,MAAM;IAOf,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,QAAQ,CAAC,SAAS,sDAAe;IACjC,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;gBAG/C,OAAO,EAAE,mBAAmB,EAC5B,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;KAAO;IAGhE,OAAO,CAAC,OAAO,GAAE;QAAE,mBAAmB,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAyEtF,YAAY,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAelE,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7C,eAAe,IAAI,IAAI;IAIvB,OAAO,IAAI,OAAO;IAIZ,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAWb,wBAAwB;YAUxB,gBAAgB;YAMhB,qBAAqB;YAUrB,yBAAyB;YA6BzB,iBAAiB;YASjB,kBAAkB;IAQhC,OAAO,CAAC,kBAAkB;CAgB3B;AAmBD,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAajF;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE;IAC1D,OAAO,EAAE,mBAAmB,CAAA;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACjC,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlB"}

package/dist/worker.js

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+import { ActorSetupFailed, ApplicationWriteForbidden, LostActivation, StateMigrationError, } from "./errors.js";
+export class Worker {
+    runtime;
+    options;
+    processId = randomUUID();
+    registered = false;
+    stopping = false;
+    activations = new Map();
+    constructor(runtime, options = {}) {
+        this.runtime = runtime;
+        this.options = options;
+    }
+    async runOnce(options = {}) {
+        try {
+            if (this.stopping)
+                return 0;
+            await this.ensureRegistered();
+            await this.runtime.repository.heartbeatProcess(this.processId);
+            await this.maintainCachedActivations();
+            let cached = await this.claimCachedActivation();
+            let turn = cached?.turn ?? (await this.runtime.repository.claim(this.processId));
+            if (!turn)
+                return 0;
+            let processed = 0;
+            const passStartedAt = performance.now();
+            let passExhausted = false;
+            while (turn) {
+                let execution;
+                try {
+                    execution = await this.runtime.executeTurn(turn, cached?.actor);
+                }
+                catch (error) {
+                    if (!(error instanceof ActorSetupFailed))
+                        throw error;
+                    await this.releaseFailedSetup(turn);
+                    if (this.options.setupFailure === "throw")
+                        throw error.setupError;
+                    if (!isControlledSetupFailure(error.setupError))
+                        throw error.setupError;
+                    this.reportSetupFailure(turn, error.setupError);
+                    return processed;
+                }
+                processed += 1;
+                if (!execution.retainActivation || !execution.actor) {
+                    await this.releaseActivation({
+                        turn,
+                        ...(execution.actor === undefined ? {} : { actor: execution.actor }),
+                        lifecycle: execution.activated ? "activated" : "unactivated",
+                    });
+                    return processed;
+                }
+                const now = performance.now();
+                cached = {
+                    actor: execution.actor,
+                    turn,
+                    lastUsedAt: now,
+                    renewAt: now + this.runtime.settings.leaseRenewalIntervalMilliseconds,
+                };
+                this.activations.set(turn.instance.id, cached);
+                passExhausted =
+                    processed >= this.runtime.settings.maxMessagesPerActivationPass ||
+                        performance.now() - passStartedAt >=
+                            this.runtime.settings.maxActivationDurationMilliseconds;
+                if (passExhausted)
+                    break;
+                turn = await this.runtime.repository.claim(this.processId, {
+                    activation: activationLease(cached.turn),
+                });
+            }
+            if (passExhausted) {
+                if (!cached)
+                    return processed;
+                const yielded = await this.runtime.repository.yieldReadyMessages(cached.turn.instance.id);
+                if (yielded > 0) {
+                    this.runtime.emitInstrumentation("activation.yielded", {
+                        actorType: cached.turn.message.actor_type,
+                        actorId: cached.turn.message.actor_id,
+                        processed,
+                        readyMessages: yielded,
+                    });
+                }
+                await this.releaseActivation({
+                    turn: cached.turn,
+                    actor: cached.actor,
+                    lifecycle: "activated",
+                });
+            }
+            return processed;
+        }
+        finally {
+            if (options.activationRetention === "release")
+                await this.releaseCachedActivations();
+        }
+    }
+    async runUntilIdle(options = {}) {
+        const maxTurns = options.maxTurns ?? 10_000;
+        let processed = 0;
+        try {
+            while (!this.stopping && processed < maxTurns) {
+                const count = await this.runOnce();
+                if (count === 0)
+                    break;
+                processed += count;
+            }
+            return processed;
+        }
+        finally {
+            await this.releaseCachedActivations();
+        }
+    }
+    async run(signal) {
+        await this.ensureRegistered();
+        while (!signal.aborted && !this.stopping) {
+            const wakeUp = await this.runtime.settings.wakeUp.watch("actors");
+            const processed = await this.runOnce();
+            if (processed === 0) {
+                await wakeUp.wait({
+                    timeoutMilliseconds: Math.min(this.runtime.settings.pollingIntervalMilliseconds, this.runtime.settings.leaseRenewalIntervalMilliseconds),
+                    signal,
+                });
+            }
+        }
+        await this.stop();
+    }
+    requestShutdown() {
+        this.stopping = true;
+    }
+    stopped() {
+        return this.stopping;
+    }
+    async stop() {
+        if (this.stopping && !this.registered)
+            return;
+        this.stopping = true;
+        if (this.registered)
+            await this.runtime.repository.startDrainingProcess(this.processId);
+        await this.releaseCachedActivations();
+        if (this.registered) {
+            await this.runtime.repository.stopProcess(this.processId);
+            this.registered = false;
+        }
+    }
+    async releaseCachedActivations() {
+        for (const activation of [...this.activations.values()]) {
+            await this.releaseActivation({
+                turn: activation.turn,
+                actor: activation.actor,
+                lifecycle: "activated",
+            });
+        }
+    }
+    async ensureRegistered() {
+        if (this.registered)
+            return;
+        await this.runtime.repository.registerProcess(this.processId, "worker");
+        this.registered = true;
+    }
+    async claimCachedActivation() {
+        for (const activation of this.activations.values()) {
+            const turn = await this.runtime.repository.claim(this.processId, {
+                activation: activationLease(activation.turn),
+            });
+            if (turn)
+                return { ...activation, turn };
+        }
+        return undefined;
+    }
+    async maintainCachedActivations() {
+        const now = performance.now();
+        for (const activation of [...this.activations.values()]) {
+            if (now - activation.lastUsedAt >=
+                this.runtime.settings.idleDeactivationTimeoutMilliseconds) {
+                await this.releaseActivation({
+                    turn: activation.turn,
+                    actor: activation.actor,
+                    lifecycle: "activated",
+                });
+                continue;
+            }
+            if (now < activation.renewAt)
+                continue;
+            try {
+                await this.runtime.repository.renewActivation(activationLease(activation.turn));
+                activation.renewAt = now + this.runtime.settings.leaseRenewalIntervalMilliseconds;
+            }
+            catch (error) {
+                if (!(error instanceof LostActivation))
+                    throw error;
+                await this.releaseActivation({
+                    turn: activation.turn,
+                    actor: activation.actor,
+                    lifecycle: "activated",
+                });
+            }
+        }
+    }
+    async releaseActivation(options) {
+        this.activations.delete(options.turn.instance.id);
+        await this.runtime.deactivateActor(options);
+    }
+    async releaseFailedSetup(turn) {
+        try {
+            await this.runtime.repository.releaseFailedTurnSetup(turn);
+        }
+        catch (error) {
+            if (!(error instanceof LostActivation))
+                throw error;
+        }
+    }
+    reportSetupFailure(turn, error) {
+        const errorName = error instanceof Error ? error.name : "Error";
+        this.runtime.emitInstrumentation("worker.setup_failed", {
+            actorType: turn.message.actor_type,
+            actorId: turn.message.actor_id,
+            operation: turn.message.operation,
+            errorName,
+        });
+        this.runtime.settings.logger.error({
+            event: "solid_objects.worker.setup_failed",
+            actorType: turn.message.actor_type,
+            actorId: turn.message.actor_id,
+            operation: turn.message.operation,
+            errorName,
+        });
+    }
+}
+function isControlledSetupFailure(error) {
+    return (error instanceof StateMigrationError ||
+        error instanceof ApplicationWriteForbidden ||
+        error instanceof LostActivation);
+}
+function activationLease(turn) {
+    return {
+        instanceId: turn.instance.id,
+        processId: turn.processId,
+        activationToken: turn.activationToken,
+        activationGeneration: turn.activationGeneration,
+    };
+}
+export function waitFor(milliseconds, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timeout = setTimeout(resolve, milliseconds);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timeout);
+            resolve();
+        }, { once: true });
+    });
+}
+export async function withProcessHeartbeat(options) {
+    const { runtime, processId, operation } = options;
+    const controller = new AbortController();
+    let heartbeatError;
+    const heartbeat = heartbeatUntilStopped({ runtime, processId, signal: controller.signal }).catch((error) => {
+        heartbeatError = error;
+    });
+    try {
+        const result = await operation();
+        controller.abort();
+        await heartbeat;
+        if (heartbeatError)
+            throw heartbeatError;
+        return result;
+    }
+    finally {
+        controller.abort();
+        await heartbeat;
+    }
+}
+async function heartbeatUntilStopped(options) {
+    const { runtime, processId, signal } = options;
+    while (!signal.aborted) {
+        await waitFor(runtime.settings.processHeartbeatIntervalMilliseconds, signal);
+        if (signal.aborted)
+            return;
+        await runtime.repository.heartbeatProcess(processId);
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/docs/api.md

@@ -0,0 +1,197 @@
+# Public API reference
+
+The package exports one server entry point plus database, wake-up, and browser
+subpaths. TypeScript declaration files remain the source of truth for exact
+generic signatures; this index explains the supported role of every export.
+
+## `solid-objects`
+
+### Runtime and actors
+
+- `configure(options)`: create the process default `SolidObjectsRuntime`.
+- `createRuntime(options)`: create an isolated runtime without changing the
+  default.
+- `SolidObjectsRuntime`: installation, registration, supervision, and manager
+  owner. The normal lifecycle is `install()`, `run(signal)`, then `close()`.
+- `Actor`: base class providing `ref()`, `actorId`, `currentMessage`,
+  `observables()`, `reject()`, `emit()`, `commitAction()`, `schedule()`,
+  `sendTo()`, and protected lifecycle hooks.
+- `VERSION`: running package version.
+- `ActorClass`, `ActorReference`, `ActorMessageSender`, `ActorSnapshot`,
+  `ActorOperationNames`, `ActorQueryNames`, `StagedOperations`, and
+  `ScheduledOperations`: inferred actor-class and fluent-dispatch types.
+- `MessageReference`: immutable durable message identity with `id`,
+  `requestId`, actor identity, `sequence`, `status()`, `result()`, and `wait()`.
+- `InvocationOptions`, `AsyncInvocationOptions`, `SnapshotOptions`, and
+  `DestroyOptions`: authorization, idempotency, timing, and scheduling options
+  used by reference methods.
+
+`ActorIntents`, `EffectIntent`, `CommitActionIntent`, `ReminderIntent`,
+`OutboundMessageIntent`, `ReminderOptions`, `OutboundMessageOptions`,
+`PayloadBroadcasts`, and `PayloadBroadcastValue` describe actor-declared
+transactional work and typed personalized projections.
+
+### Runtime managers
+
+Every manager below is available as a property on `SolidObjectsRuntime`; the
+class and result types are also exported for integration typing.
+
+- `runtime.deadLetters` / `DeadLetterManager`: `all()` and idempotent `retry()`.
+- `runtime.reminders` / `ReminderManager`: cursor-paginated `all()` and
+  idempotent paused-alarm `resume()`.
+- `runtime.processes` / `ProcessManager`: immutable role `all()` and stale-owner
+  `cleanup()`.
+- `runtime.reconciliation` / `ReconciliationManager`: `active()`,
+  `withoutPendingWork()`, `statesFor()`, and `orphaned()` bounded reads.
+- `runtime.retention` / `RetentionManager`: `preview()` and authorized `prune()`
+  for messages, instances, or processes.
+- `runtime.doctor` / `Doctor`: `run({ roundTrip })` structured installation
+  report.
+- `runtime.testing` / `SolidObjectsTestHelper`: deterministic `drain()` and
+  dependency-ordered `reset()`.
+- `runtime.realtime` / `RealtimeManager`: `connect()`, process-local
+  `publish()`, and `close()`.
+
+The manager types are `DeadLetter`; `ReminderPage`, `ReminderPageOptions`,
+`ReminderRecord`, `ReminderStatus`, and `ResumeReminderOptions`;
+`ProcessCleanupResult`, `ProcessMetadata`, `ProcessRecord`, and
+`ProcessShutdownState`; `DoctorCheck`, `DoctorOptions`, `DoctorReport`, and
+`DoctorStatus`; `OrphanedReconciliationOptions`,
+`QuietReconciliationOptions`, `ReconciliationInstance`, `ReconciliationPage`,
+`ReconciliationPageOptions`, and `ReconciliationStatesOptions`;
+`RetentionOptions`, `RetentionResult`, and `RetentionTarget`; and
+`TestDrainOptions` and `TestHelperRole`. `RealtimeConnectionOptions`,
+`RealtimeSession`, and `SubscriptionRequest` define the server session API.
+`AdministrationOptions` carries the application-owned authorization context
+for administration calls.
+
+### Registration and integration
+
+- `runtime.register(ActorClass)`: validate and register an actor definition.
+- `runtime.ref(ActorClass, actorId)`: register and address an actor in an
+  isolated runtime.
+- `runtime.registerEffect(name, handler)`: register an at-least-once external
+  effect handler. `EffectContext` carries the stable effect ID and source
+  identity.
+- `runtime.registerCommitAction(name, handler)`: register a same-database
+  fenced transaction handler. `CommitActionContext` includes the active
+  `DatabaseConnection`.
+- `guardApplicationDatabase(database)`: return a facade that rejects writes
+  from actor-owned execution contexts.
+- `parseSubscriptionRequest(value)`: validate the server-side JSON subscribe or
+  unsubscribe request before session routing.
+- `runCli(arguments, options)` and `CliRunOptions`: embed and configure the
+  packaged command implementation; applications normally invoke the
+  `solid-objects` executable instead.
+
+`SolidObjectsConfiguration`, `AuthorizationInput`,
+`DestroyAuthorizationInput`, `AdministrationAuthorizationInput`,
+`SubscriptionAuthorizationInput`, `BroadcastEvent`, and
+`InstrumentationEvent` type the host integration contract. `JsonPrimitive`,
+`JsonValue`, `JsonObject`, `DeepReadonly`, `ActorIdentifier`, `MessageContext`,
+`MessageStatus`, and `Logger` are shared types. `Database`,
+`DatabaseConnection`, `DatabaseFamily`, and `RunResult` support custom database
+and commit-action integration.
+
+### Runtime extensions and manual workers
+
+`runtime.registerComponent(factory, { count = 1 })` adds application-owned
+supervised roles. Each factory must return a `LongRunningComponent`:
+
+```typescript
+interface LongRunningComponent {
+  run(signal: AbortSignal): Promise<void>
+  requestShutdown(): void
+  stopped(): boolean
+  stop(): void | Promise<void>
+}
+```
+
+The runtime creates `count` independent instances, replaces an instance whose
+`run()` settles unexpectedly, and stops replacement before graceful shutdown.
+Factories should create fresh mutable state and `stop()` should be idempotent.
+
+`Worker`, `EffectWorker`, `ReminderScheduler`, and `BroadcastWorker` are
+exported for test runners and hosts that intentionally operate roles outside
+`runtime.run()`. Runtime factory methods create the same classes. Each provides
+`runOnce()`, bounded `runUntilIdle()`, `run(signal)`, `requestShutdown()`,
+`stopped()`, and `stop()`. Manual roles still register process ownership and
+must be stopped. Prefer `runtime.run()` in production and `runtime.testing` in
+tests.
+
+`InProcessWakeUpAdapter`, `WakeUpAdapter`, `WakeUpRole`, `WakeUpWatch`, and
+`WakeUpWaitOptions` define the notification extension. A watch must be obtained
+before checking durable state so a notification cannot fall between claim and
+wait.
+
+### Errors
+
+The root exports `SolidObjectsError` and its supported subclasses:
+
+- policy and caller outcomes: `Unauthorized`, `Rejected`, `ActorDestroyed`,
+  `SyncEnqueueTimeout`, `SyncTimeout`, `SyncInsideTransaction`, and
+  `MessageFailed`;
+- admission and payload failures: `MailboxFull`, `InvalidPayload`,
+  `PayloadTooLarge`, `IdempotencyConflict`, `InvalidPayloadBroadcast`, and
+  `UnknownPayloadBroadcast`;
+- definition and execution failures: `InvalidActor`, `UnknownActorType`,
+  `UnknownOperation`, `ActorCallCycle`, `QueryMutatedState`,
+  `StateMigrationError`, `ApplicationWriteForbidden`, `UnknownEffect`, and
+  `UnknownCommitAction`;
+- operational failures: `LostActivation`, `DatabaseDeadlineExceeded`,
+  `UnknownDeadLetter`, `UnknownReminder`, `ReminderNotPaused`, and
+  `UnsupportedDatabase`.
+
+`NonRetryableError` is the application subclassing point. `SyncTimeoutDetails`
+and `SyncTimeoutWaitingOn` type timeout diagnostics. See
+[Errors and recovery](errors-and-recovery.md) before deciding what to catch.
+
+## `solid-objects/database/sqlite`
+
+- `sqlite(options)`: construct `SQLiteDatabase`.
+- `SQLiteDatabase`: `Database` implementation and `close()` owner.
+- `SQLiteDatabaseOptions`: path, busy timeout, and lock retry options.
+
+## `solid-objects/database/postgresql`
+
+- `postgresql(options)`: construct `PostgreSQLDatabase`.
+- `PostgreSQLDatabase`: pooled `Database` implementation with `wakeUp()`.
+- `PostgreSQLDatabaseOptions` and `PostgreSQLDatabaseWakeUpOptions`: pool and
+  notification configuration.
+- `postgresqlWakeUp(options)` and `PostgreSQLWakeUpAdapter`: standalone
+  `LISTEN/NOTIFY` wake-up integration.
+- `PostgreSQLWakeUpOptions` and `PostgreSQLWakeUpFailure`: listener options and
+  failure callback data.
+
+## `solid-objects/database/mysql`
+
+- `mysql(options)`: construct `MySQLDatabase`.
+- `MySQLDatabase`: pooled `mysql2` `Database` implementation.
+- `MySQLDatabaseOptions`: pool configuration.
+- `mysqlSql(sql)`: translate the portable conflict syntax used by custom
+  database integrations.
+
+## `solid-objects/wake-up/redis`
+
+- `redisWakeUp(options)`: construct `RedisWakeUpAdapter`.
+- `RedisWakeUpAdapter`: optional Pub/Sub latency layer.
+- `RedisWakeUpOptions` and `RedisWakeUpFailure`: connection, channel, timeout,
+  and failure callback types.
+
+## `solid-objects/browser`
+
+- `SolidObjectsBrowserClient`: connect, subscribe, unsubscribe, receive, and
+  close a versioned WebSocket client without Node imports.
+- `BrowserClientOptions`, `ActorSubscription`, `InvalidationEnvelope`,
+  `PayloadEnvelope`, and `RealtimeEnvelope`: browser transport types.
+- `parseInvalidation(value)` and `parseRealtimeEnvelope(value)`: validate and
+  deeply freeze received JSON for custom transports.
+- `SolidObjectsComponentRegistry`: register keyed observable dependencies,
+  coalesce refreshes, abort superseded work, fence application, and close.
+- `ComponentRegistration`, `RegisteredComponent`, `ComponentRefreshStrategy`,
+  `ComponentRefreshRequest`, `ComponentRefreshResult`, `ComponentApplication`,
+  `ComponentRefreshFailure`, and `ComponentRegistryOptions`: framework-neutral
+  refresh contract types.
+
+The wire format, trust boundary, revision rules, and component semantics are in
+[Browser protocol](browser-protocol.md).