Browser blob adapter — the browser story is currently records-only

[cuibonobo]

From docs/design-review-2026-08.md §B2.

Problem

record-adapter-sqljs is a StackRecordAdapter only, and there is no browser StackBlobAdapter (blob-adapter-disk is Node-only) — so a browser app cannot construct a full StackAdapter without writing its own blob adapter. Attachments are load-bearing across the design (commons photo, the embed convention, avatar labels, file-ref fields), so "browser support" currently means "browser support except files," and nothing in the README says so — an adopter discovers it at integration time.

Work items

• blob-adapter-opfs (or an in-memory blob adapter with the same persist-callback contract record-adapter-sqljs already uses, letting the host wire it to OPFS/IndexedDB) — shaped like the existing pattern, implements the Extend the typed error taxonomy to attachment paths: blob not-found/bad-fileId (reuse) and payload-too-large (new type) #114 C3 error contract (StackNotFoundError / StackQueryError) and ideally listFiles() so GC works in the browser
• Until it ships: an honest row in the README package table ("browser blob adapter: bring your own — implement StackBlobAdapter")

Cross-refs: #72 (streaming blob methods — worth a glance so the new adapter's shape doesn't fight it), #93 (optional-capability discovery), design-review-2026-08 §B2.

[cuibonobo]

Closing this — the diagnosis is right, but the resolution is deletion rather than a new blob adapter.

record-adapter-sqljs was built for runtimes without full Node support (Cloudflare Workers), not for browsers; a Stack in a browser tab isn't a target. But it never served the Workers case either:

• Both entry points call initSqlJs() with no options, and Workers forbid compiling WASM from bytes at runtime — the only route is injecting a pre-compiled WebAssembly.Module via Emscripten's instantiateWasm, and the adapter exposes no options pass-through at all. The same gap means a bundled browser app can't set locateFile either.
• persist() serializes the whole database after every write. In a per-request Worker isolate that's fetch-whole-DB / mutate / put-whole-DB, with no single-writer guarantee — two concurrent requests silently lose one's writes, against docs/spec/adapters.md § Concurrency & storage ownership.
• Its tests run under environment: 'node', so the package only ever demonstrated sql.js working in the one environment its module comment says it's not for.

So "browser support except files" is real, and the fix is to stop claiming browser support: the README advertises it in three places and the spec builds it into the concurrency section. The adapter is being removed along with the FTS4 branch that existed solely to serve it (FTS4_SCHEMA_SQL, fts.ts, the FtsStrategy seam, and the FTS4→FTS5 migration in record-adapter-sqlite).

Superseded by:

• blob-adapter-s3 — blob storage is Node-disk-only, so object storage means writing your own #160 — blob-adapter-s3 for S3/R2. Takes the useful half of the work item here (blob storage beyond a local disk) and points it at server deployments, where it's a live gap today. Not an OPFS adapter.
• record-adapter-do-sqlite — a Workers story that fits the sync SqlExecutor and the ownership rule #161 — record-adapter-do-sqlite for Durable Objects, if a Workers story is wanted. Its synchronous ctx.storage.sql.exec() fits the existing SqlExecutor as-is, it has FTS5, and a DO instance is a single owning writer.

The listFiles() / C3 error-contract requirements from the work items above carry over to #160.

---

Generated by Claude Code