Store

The Store is the seam between inseam’s core and whichever SQL backend the host ships with. Hosts construct a backend adapter, hand it to openStore, and get back a Store that core uses for every durable write. Plugins never touch the Store directly — typed APIs (Source, Access, Events, Connection) sit above it.

How it fits

Two packages, by design:

• @inseam/store-contract is the adapter surface. It exports StoreAdapter, Statement, RunResult, Migration, and the StoreError / AdapterError hierarchy. Zero runtime deps. Third-party backends compile against this alone.
• @inseam/core wraps an adapter with the migration runner, batch serialization, and closed-state propagation. This is the surface hosts call.

Atomicity is batch only — there are no interactive transactions. Migrations are core-owned, applied in ascending id order, and idempotent across re-opens. Concurrent batch calls on the same Store are serialized in submission order.

Key pieces

• openStore(adapter) — the host entry point. Runs pending migrations, then returns the wrapped Store.
• Store.prepare(sql) / Statement.bind(...) — prepared statements; bind produces a new bound statement and leaves the original reusable.
• Store.batch(statements) — the only atomic unit. The adapter MUST execute these as a real transaction.
• Store.close() — quiesces in-flight batches then releases the adapter. Subsequent calls throw StoreClosedError.

For exact signatures and error semantics see the @inseam/store-contract API reference and arch/store/spec.md.

When to use this vs alternatives

You do not normally write against Store directly inside a plugin. If you are writing a plugin, reach for the typed APIs above it: Source for indexable rows, Events for outbox writes, Access for permission state. The Store API is the right surface only when you are writing a new adapter or working inside core.

When you do need persistence outside the typed APIs (a new core subsystem, an experiment), prefer batch over chained single-statement writes — a single batch is the only way to keep a write and its companion outbox event atomic.

See also

• LLM summary — dense reference for agents.
• Bun-SQLite & D1 adapters — the two first-party adapters.
• arch/store/design.md — rationale for the two-adapter strategy.
• arch/store/spec.md — mechanical contract and acceptance criteria.