Browser runtime: platform seam, SQLite WASM adapter, worker host

[cardmagic]

Implements all four milestones of #17: the full Solid Objects runtime runs inside a browser, stores actor state in SQLite WASM on OPFS, shares one runtime across tabs, and syncs its outbox to a server runtime.

The shape

One import gives a browser worker the whole programming model, and multi-tab coordination is invisible. This code runs identically in every tab:

import { Actor, configure, sharedSqliteWasm } from "solid-objects/browser/host"

class Counter extends Actor {
  static actorType = "Counter"

  count = 0

  increment({ amount = 1 } = {}) {
    this.count += amount
    return this.count
  }
}

const runtime = configure({
  database: sharedSqliteWasm({ path: "app.db" }),
  /* authorize callbacks */
})
await runtime.install()

await Counter.ref("page-hits").increment()

State survives page reloads (the same actor id loads the same durable OPFS state), and every tab sees the same counter: sharedSqliteWasm elects one database holder per origin through the Web Locks API, carries the other tabs' SQL to it over a BroadcastChannel, and fails over onto the same durable state when the holder's tab dies. For a single dedicated worker, sqliteWasm({ storage: "persistent" }) opens the database directly.

With the shared database, typed references work in every tab, because every tab runs a full runtime and the existing leases and fencing arbitrate their workers exactly as they arbitrate Node processes. The tab host below is the request-level alternative: one runtime on the leader, other tabs invoking by name over a channel.

Many tabs, one runtime (request-level alternative)

sharedSqliteWasm above is the primary multi-tab path. solid-objects/browser/tab-host remains for a different resource profile: exactly one worker set per origin. The Web Locks API elects a leader, only the leader runs a runtime, and the other tabs stay thin — no workers, no polling — invoking by name over a BroadcastChannel client with idempotent request ids (startTabHost / connectTabClient, documented in docs/api.md). Choose it when most tabs only issue commands and should not run background work; choose the shared database when every tab wants typed references and the full runtime. Failover works the same way in both: the leader's death releases the lock and the next candidate promotes on the same OPFS state.

Offline transmit through the transactional outbox

An actor stages a sync intent in the same transaction as its state change, with the same fluent shape as schedule() and sendTo(). The effect worker drains the outbox with at-least-once delivery, per-actor order, and retry backoff; the server ingest deduplicates on the effect id.

The browser side, in the worker that hosts the local runtime:

import { Actor, configure, registerTransmit, sharedSqliteWasm } from "solid-objects/browser/host"

class Counter extends Actor {
  static actorType = "Counter"

  count = 0

  increment({ amount = 1 } = {}) {
    this.count += amount
    this.transmit().increment({ amount })   // replay on the server twin, committed with the state change
    return this.count
  }
}

const runtime = configure({ database: sharedSqliteWasm({ path: "app.db" }) /* , authorize callbacks */ })
registerTransmit({
  runtime,
  deliver: async (envelope) => {
    const response = await fetch("/sync", { method: "POST", body: JSON.stringify(envelope) })
    if (!response.ok) throw new Error(`sync failed with ${response.status}`)   // throw while offline; the outbox retries
  },
})
await runtime.install()

The server side is one route in the host application. On a Node backend — shown Fetch-style, any HTTP framework works:

import { receiveTransmitEnvelope } from "solid-objects"

// POST /sync — the route the browser's deliver callback posts to
async function handleSync(request) {
  const sender = await authenticate(request)          // host-owned; internal delivery skips authorizeMessage
  if (!sender) return new Response("Forbidden", { status: 403 })
  const envelope = await request.json()
  await receiveTransmitEnvelope({ runtime: serverRuntime, envelope })   // idempotent: keyed on the effect id
  return Response.json({})
}

The backend does not have to be Node. cardmagic/solid-objects-ruby#47 proposes the same ingest for the Ruby gem over the identical wire contract, so a solid-objects-js browser front end can replay its operations onto Rails server actors:

class TransmitController < ApplicationController
  skip_forgery_protection

  def create
    head :forbidden and return unless authenticated_device?

    SolidObjects::Transmission.receive(JSON.parse(request.body.read))
    head :ok
  rescue SolidObjects::InvalidTransmission, SolidObjects::UnknownMessage, JSON::ParserError
    head :unprocessable_entity   # tells the browser outbox to dead-letter, not retry
  end
end

Both ingests dedup on the same transmit:<effectId> idempotency key and accept the same camelCase envelope, so the browser side cannot tell which runtime answered.

transmit() covers the common case (same actor type and id on both sides). emit(TRANSMIT_EFFECT, ...) stages the same intent with an explicit target when the server actor differs.

What is underneath

• Platform seam (M1). Shared modules no longer import Node builtins. A registered factory supplies async context (AsyncLocalStorage in Node, a turn-scoped store in the browser), one seam supplies host identity, and check:browser-imports fails the build when a node: import or a server driver reaches the browser graph — including through export ... from edges.
• Storage (M2). solid-objects/database/sqlite-wasm implements the Database contract on @sqlite.org/sqlite-wasm (optional peer dependency) with the same serialized-access, deadline, and transaction semantics as the Node SQLite adapter. Deadlines survive without ambient context: the adapter captures the absolute expiry at access entry and enforces it in every statement and before COMMIT.
• Hosts (M3). solid-objects/browser/host registers the browser platform on import. solid-objects/browser/tab-host adds the runtime-level election and client.
• Transparent multi-tab (beyond the PRD). solid-objects/database/shared-sqlite-wasm moves the election behind the Database seam: the holder opens the pool, other instances run SQL sessions over BroadcastChannel through the holder's serialized access queue, requests carry the holder epoch so failover surfaces as a fast rejection, a not-yet-executed session retries automatically (a partially executed one never replays), and an idle-session watchdog reclaims the slot when a tab dies mid-session. The PRD named a SharedWorker host; Web Locks election between dedicated workers replaced it, because OPFS sync access handles exist only in dedicated workers.
• Transmit (M4). solid-objects/transmit rides the existing effects outbox. Per-actor order comes from an ordered drain: a claimed effect transmits every undelivered envelope for its actor up to its own mailbox sequence, oldest first, and the server dedups.

Tests

• 321 Vitest tests pass, with new suites for the context store, host identity, WASM adapter contract, the shared database adapter (cross-instance statements, transactions, serialization, two full runtimes on one database, failover, session watchdog), the tab host (election, failover, error propagation, timeout, on real Node Web Locks), and the sync bridge (order under transmit failures, replay dedup, offline recovery, transmit and raw emit staging).
• 8 Playwright tests pass in Chromium: OPFS persistence across reloads, the full runtime in a module worker, an expired transaction that rolls back under the browser context store, two tabs that share one durable runtime through the tab host and fail over, plain actor references incrementing one durable counter from two tabs through the shared database with failover, and a browser outbox that drains into the Node server runtime.
• The PostgreSQL and MySQL CI jobs run the transmit round trip against real servers: two runtimes on one database under distinct table prefixes, a failed delivery that preserves per-actor order, and a doubled delivery the ingest deduplicates — so the drain query's portability is proven, not argued.
• The floor CI job (Node 24.4.0) passes; the tab host and shared database suites skip there because navigator.locks arrived in Node 24.5, and the docs record that boundary.

Docs

The documentation set covers the browser runtime end to end: docs/api.md documents all four new entry points with failover fence tuning and offline dead-letter guidance; docs/browser-protocol.md documents the tab host BroadcastChannel protocol, the shared database channel protocol, and the sync envelope; docs/architecture.md describes the platform seam, the browser host layers, and the sync bridge; docs/support.md records the SQLite WASM peer dependency and the OPFS and Web Locks platform boundaries; docs/correctness.md records the browser guard boundary under limitations; docs/fit.md adds the local-first use case; the README gains a 'Solid Objects in the browser' section; docs/parity.md records the JavaScript-only capability with all milestones complete; and CHANGELOG.md carries the Unreleased notes.

[greptile-apps]

Greptile Summary

The PR introduces browser platform registration, SQLite WASM storage, multi-tab runtime hosting, and a transactional synchronization bridge.

• Adds browser and Node platform seams for context, identity, and UUID generation.
• Adds temporary and OPFS-backed SQLite WASM storage with serialized access and deadline enforcement.
• Adds Web Locks leader election, BroadcastChannel invocation, failover support, and synchronization outbox delivery.
• Extends package exports, documentation, import checks, and browser/runtime coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/database/sqlite-wasm.ts	Implements serialized SQLite WASM access, OPFS persistence, transaction rollback, and captured deadline enforcement.
src/browser/tab-host.ts	Implements Web Locks leadership, BroadcastChannel requests, idempotent runtime invocation, retries, and failover lifecycle.
src/sync-bridge.ts	Implements ordered outbox transmission and idempotent server-side synchronization ingest.
src/platform/turn-context-store.ts	Provides deliberately synchronous browser context scoping with a documented post-await boundary.
scripts/check-browser-imports.mjs	Walks browser-safe import and re-export graphs to reject Node built-ins and server drivers.

Sequence Diagram

sequenceDiagram
    participant T as Browser Tab
    participant C as BroadcastChannel
    participant L as Elected Leader
    participant R as Solid Objects Runtime
    participant D as SQLite WASM / OPFS
    T->>C: Invoke with request ID
    C->>L: Deliver invocation
    L->>R: Enqueue idempotent message
    R->>D: Commit actor state and work
    D-->>R: Durable result
    R-->>L: Invocation result
    L-->>C: Broadcast result
    C-->>T: Resolve request

Loading

_{Reviews (3): Last reviewed commit: "fix: enforce transaction deadlines witho..." | Re-trigger Greptile}

[cardmagic]

@greptile-apps review

[cardmagic]

@greptile-apps review

[cardmagic]

The server-side counterpart for the transmit family in Ruby is proposed in cardmagic/solid-objects-ruby#47: SolidObjects::Transmission.receive gives a Rails application the ingest for browser transmit envelopes, over the same wire contract this PR defines (camelCase envelope keys, the transmit:<effectId> idempotency key, order owned by the browser's drain). Together they complete the local-first story: a solid-objects-js browser front end replaying its operations onto Ruby server actors.

[cardmagic]

Manual cross-runtime QA against the Rails backend (cardmagic/solid-objects-ruby#49): a Node runtime staged transmits into a real Rails app over HTTP, and a Rails app staged transmits into a Node ingest. One contract bug surfaced; everything else held.

Bug: receiveTransmitEnvelope rejects an envelope without arguments. The Ruby ingest treats arguments as optional and defaults it to {}. The JS staging side does the same in parseTransmitEnvelope (argumentsValue.arguments ?? {}), so the JS ingest disagrees with both the Ruby ingest and its own staging. The shared fixture "increment without arguments" (compatibility/transmit-envelopes.json in the Ruby repo) returns 200 from Rails and 422 from Node. Suggested fix in receiveTransmitEnvelope:

const argumentsValue = envelope.arguments ?? {}
if (!isJsonObject(argumentsValue)) {
  throw new InvalidPayload("sync envelope arguments must be a JSON object")
}

and enqueue argumentsValue. The fixture file lands here with a consuming test when this PR and the Ruby PR pair up, and that test pins the contract.

What held in both directions:

• Node → Rails: per-actor order, at-least-once redelivery deduped on transmit:<effectId>, UUID effect ids accepted verbatim.
• Rails → Node: same-actor default target, explicit actorType/actorId raw-emit target, per-actor order.
• Both ingests skip message authorization for the internal enqueue (authorizeMessage: () => false on the Node side did not block ingest), so the host must authenticate before the call.
• Malformed envelopes (missing effectId, empty actorId, snake_case keys, non-string operation, non-object arguments) reject on both sides.
• A conflicting replay (same effectId, different arguments) raises IdempotencyConflict on both sides; the host route must map it to 422, or the sending outbox retries a permanently unappliable envelope forever. The Ruby docs controller example now includes it.