fix: clean up wasm SQLite driver corruption + federated-object boot errors in pnpm dev

[os-zhuang]

Background

pnpm dev was spamming database errors at startup. Most trace back to the wasm SQLite driver — the dev fallback that kicks in whenever native better-sqlite3 has an ABI mismatch (NODE_MODULE_VERSION after a Node upgrade, or never built). In that mode a persistent dev DB runs with persist: 'on-write', so background dispatchers (notification / http) flush on every tick, which surfaced several latent bugs:

1. update ... - database disk image is malformed (repeated forever)
2. Insert operation failed {"0":"W","1":"r",...} — a garbled char-indexed log
3. Wrong API use : tried to bind a value of an unknown type (undefined)
4. Find operation failed … no such table: customers / orders (federated showcase objects)

Root causes & fixes

1. Non-atomic flush → torn file → malformed. flush() persisted via a plain writeFile(filename, bytes), which truncates the target and streams new bytes in place. A process killed mid-write (dev-server restart, Ctrl-C, crash — probable under per-tick on-write flushing) left a half-written file that sql.js rejects on the next boot. Now flushes write to a sibling temp file, fsync it, and atomically rename() over the target, so a reader always sees a complete image.

2. No recovery from an already-corrupt image. A malformed file made every query fail forever with no way out (deleting the DB by hand was the only escape — which the reporter tried). open() now runs PRAGMA quick_check on the loaded bytes, and on corruption quarantines the file to <db>.corrupt-<timestamp> (bytes preserved for post-mortem) and boots on a fresh database with a loud warning.

3. undefined binding crash + garbled log. sql.js's binder throws a raw string (not an Error) for an undefined value — that string aborts the write and logs as {"0":"W","1":"r",...} because it has no .message/.stack. formatBindings now coerces undefined → null, matching the driver's useNullAsDefault config and the native better-sqlite3 path.

4. Seed-ownership backfill hit federated tables. claimSeedOwnership (plugin-security) walks every registered object exposing an owner_id column and re-owns unowned rows to the first admin. owner_id is auto-injected into external (ADR-0015 federated) object schemas, so showcase_ext_customer / showcase_ext_order passed the filter and the backfill ran select id from <remote_table> where owner_id is null against a read-only remote datasource whose table isn't provisioned that early in boot → no such table. External objects are read-only (DDL forbidden, writes double-opt-in) and their ownership isn't the platform's to reassign, so they're now skipped alongside managedBy / sys_*.

Changes

• driver-sqlite-wasm/src/wasm-connection.ts — atomic atomicWriteFile() (temp + fsync + rename); assertReadable() / quarantineCorruptFile() self-heal in open().
• driver-sqlite-wasm/src/knex-wasm-dialect.ts — formatBindings maps undefined → null.
• plugin-security/src/claim-seed-ownership.ts — skip objects with an external binding.
• Tests: driver-sqlite-wasm/src/sqlite-wasm-driver-durability.test.ts (atomic write leaves no temp file & round-trips; corrupt image quarantined + boots fresh; undefined persists as NULL); plugin-security/src/claim-seed-ownership.test.ts (external objects are not scanned).

Testing

• pnpm --filter @objectstack/driver-sqlite-wasm test → 119 passed (incl. 3 new).
• pnpm --filter @objectstack/plugin-security test → 309 passed (incl. 1 new).
• Package builds (incl. DTS type-check) succeed.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 14, 2026 8:06am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/driver-sqlite-wasm, @objectstack/plugin-security.

13 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via @objectstack/driver-sqlite-wasm)
• content/docs/getting-started/cli.mdx (via @objectstack/plugin-security)
• content/docs/getting-started/glossary.mdx (via @objectstack/driver-sqlite-wasm)
• content/docs/permissions/access-recipes.mdx (via packages/plugins/plugin-security)
• content/docs/permissions/authorization.mdx (via packages/plugins/plugin-security)
• content/docs/permissions/explain.mdx (via @objectstack/plugin-security)
• content/docs/permissions/permissions-matrix.mdx (via packages/plugins/plugin-security)
• content/docs/permissions/sharing-rules.mdx (via @objectstack/plugin-security)
• content/docs/plugins/index.mdx (via @objectstack/plugin-security)
• content/docs/plugins/packages.mdx (via @objectstack/driver-sqlite-wasm, @objectstack/plugin-security)
• content/docs/releases/implementation-status.mdx (via @objectstack/driver-sqlite-wasm, @objectstack/plugin-security)
• content/docs/ui/audience-based-interfaces.mdx (via packages/plugins/plugin-security)
• content/docs/ui/dashboards.mdx (via @objectstack/plugin-security)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.