@ontrails/store 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,329 @@
+# @ontrails/store
+
+## 0.2.0
+
+### Patch Changes
+
+- [`664e8bb`](https://github.com/outfitter-dev/trails/commit/664e8bb049e61f1d47cec1dd246606707af5d1a8): Point public installation examples at exact approved 0.2.0 versions and distinguish the prepared source release from pending npm publication.
+- [`b3ddf91`](https://github.com/outfitter-dev/trails/commit/b3ddf918ada8211f44983512e2bbdfbc5b66d722): Prepare the first normal Trails release at `0.2.0` on `latest`, replacing the unpublished 1.0.0 source release. The target advances the original `0.1.0` source minor, which was never published under the current package names. Public packages remain in lockstep. Update consumer installation guidance and provide a temporary manifest bridge for old 1.0 beta sources. Published beta versions remain unchanged; minor 0.x releases may carry documented breaking changes.
+
+  The `1.0.0` section retained below records an unpublished preparation, not an npm release. Its accumulated changes are included in `0.2.0`; the section remains as source history alongside the published beta entries.
+
+## 1.0.0
+
+### Major Changes
+
+- [`3395234`](https://github.com/outfitter-dev/trails/commit/33952349f2d475b170376a63587c89e50be3247a): Move store adapter-binding helpers to `@ontrails/store/adapter-support` and topographer direct database/admin helpers to `@ontrails/topographer/backend-support`, keeping root exports focused on contract-level APIs.
+- [`6300f70`](https://github.com/outfitter-dev/trails/commit/6300f709bb6dffc0e6cc82479fe8d0204c52bbba): BREAKING: rename the shared store backend option type from `StoreConnectorOptions` to `StoreAdapterOptions`.
+
+### Minor Changes
+
+- [`69057e9`](https://github.com/outfitter-dev/trails/commit/69057e9348006b2b70c9f6237572a5aa8de3ee1f): Add hierarchical CLI command trees and structured input, enforce established-only topo exports across surfaces, move developer topo and tracing state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+- [`6712075`](https://github.com/outfitter-dev/trails/commit/67120754df3f614c7f4dd98be1fa0ba9d69b7765): Complete the v1 hard cutover from the `contour` domain-object declaration
+  vocabulary to `entity` across contracts, topo facts, store helpers, Warden,
+  Wayfinder, operator surfaces, examples, and generated locks. Existing
+  applications must rename contour APIs, run `trails dev reset --yes` to discard
+  pre-cutover local Topographer snapshots, and then recompile committed
+  `trails.lock` artifacts before upgrading. Those derived snapshots are
+  intentionally not read through a compatibility layer.
+  The entity-shaped wire contract advances `TopoGraph` and split lock manifests
+  from schema version 3 to 4; old split artifacts fail with regeneration guidance,
+  while the canonical root `trails.lock` remains schema version 5.
+  Wayfinder reports those stale rows as topo-store drift while keeping current
+  committed lock facts available for inspection.
+
+### Patch Changes
+
+- [`e41c382`](https://github.com/outfitter-dev/trails/commit/e41c3829c2d692683b78c730e67fd5b17ac0ff4e): Document beta-channel install guidance in package and adapter README install snippets so consumers use explicit `@beta` (or pinned `1.0.0-beta.N`) tags instead of accidental `latest` resolution during the prerelease line. Adds the policy doc at `docs/releases/beta-channel-policy.md`, prints both `latest` and `beta` dist-tags in `bun run publish:registry-check`, and aligns plugin/skill install snippets.
+- [`9874e0b`](https://github.com/outfitter-dev/trails/commit/9874e0bb034c0f98edeb19833d9d3519c2a07a4c): Add `@ontrails/cloudflare/d1`, an env-bound Cloudflare D1 store resource for `@ontrails/store` definitions. The new subpath exports `cloudflareD1` and `connectD1`, supports the backend-agnostic store accessor contract (`get`, `list`, `upsert`, `remove`), versioned-table optimistic concurrency, fixture/mock seeding, store-derived write signals, Miniflare-backed conformance tests, and Worker env-bridge integration.
+
+  `@ontrails/core` and `@ontrails/store` no longer require the Bun global for signal fire ids or late-bound store signal tokens, so store definitions and store-derived signal emission work inside Worker modules. `@ontrails/warden` now treats `cloudflareD1` as a required Cloudflare public export with `@example` coverage.
+
+- [`e898cc4`](https://github.com/outfitter-dev/trails/commit/e898cc4042ffa66f977b425a98419ee77183f27d): Add repo-level Knip dead-code detection and remove stale internal exports and unused package dependencies surfaced by the new check.
+- [`851a2a3`](https://github.com/outfitter-dev/trails/commit/851a2a3cb805993d16ef74d43d3c963f286cce15): Derive trail caller and blaze input types from the authored input schema while keeping one public input contract.
+- [`f7ec225`](https://github.com/outfitter-dev/trails/commit/f7ec225c01482f8fb55afd174add3d961a63171b): `sync()` gains the factory-contract options `crud()` and `reconcile()` received in TRL-1195: a `permit` option declared on the produced trail, and per-endpoint `contour` options on `SyncEndpoint` so a `crud()` bundle's table contour can be shared instead of colliding as a duplicate registration at `topo()`.
+- [`49c2e7d`](https://github.com/outfitter-dev/trails/commit/49c2e7d5c7c063b9aa6abee1d2932bf3003133cc): Refresh published package README taxonomy to use adapter language instead of retired connector vocabulary.
+- [`5a38c73`](https://github.com/outfitter-dev/trails/commit/5a38c73092f81612769be4b44944d828c3436e07): Complete the store factory trail contracts (TRL-1195, absorbing TRL-1177 and TRL-1178). `crud()` gains `permit` (applied to every produced trail) and `permits` (per-operation overrides, so destroy trails satisfy permit governance) plus a `contour` option, and the returned tuple now exposes the table contour it registered as a `contour` property. `reconcile()` gains `permit` and accepts a shared `contour` instance, so crud + reconcile on one table register cleanly in a single `topo()` instead of colliding on a duplicate contour name. `TableContour` is exported from `@ontrails/store/trails`. Consuming apps no longer need to post-process factory trails to attach permits or strip contours.
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+- [`ab1c77c`](https://github.com/outfitter-dev/trails/commit/ab1c77cddd90c30af28887f2bbd2cf2416900068): Advertise first-party adapter target metadata for catalog derivation.
+- [`9bf592d`](https://github.com/outfitter-dev/trails/commit/9bf592ddba46aa12e3f4e6ffc0f772f7a41ed3df): Declare verified first-party adapter metadata for Drizzle, HTTP/Bun, and Store/Jsonfile so shared adapter checks can dogfood real owner targets.
+- [`df9a7d0`](https://github.com/outfitter-dev/trails/commit/df9a7d00fe4d9ebec948b6ebed6dc4525fc8e0dc): Add project-aware public export-map governance for @ontrails workspace docs,
+  imports, root barrels, and bin-only package surfaces.
+
+## 1.0.0-beta.50
+
+## 1.0.0-beta.49
+
+## 1.0.0-beta.48
+
+## 1.0.0-beta.47
+
+## 1.0.0-beta.46
+
+## 1.0.0-beta.45
+
+## 1.0.0-beta.44
+
+### Patch Changes
+
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.43
+
+### Minor Changes
+
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+
+## 1.0.0-beta.42
+
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+- [`6712075`](https://github.com/outfitter-dev/trails/commit/67120754df3f614c7f4dd98be1fa0ba9d69b7765): Complete the v1 hard cutover from the `contour` domain-object declaration
+  vocabulary to `entity` across contracts, topo facts, store helpers, Warden,
+  Wayfinder, operator surfaces, examples, and generated locks. Existing
+  applications must rename contour APIs, run `trails dev reset --yes` to discard
+  pre-cutover local Topographer snapshots, and then recompile committed
+  `trails.lock` artifacts before upgrading. Those derived snapshots are
+  intentionally not read through a compatibility layer.
+  The entity-shaped wire contract advances `TopoGraph` and split lock manifests
+  from schema version 3 to 4; old split artifacts fail with regeneration guidance,
+  while the canonical root `trails.lock` remains schema version 5.
+  Wayfinder reports those stale rows as topo-store drift while keeping current
+  committed lock facts available for inspection.
+
+### Patch Changes
+
+- [`9874e0b`](https://github.com/outfitter-dev/trails/commit/9874e0bb034c0f98edeb19833d9d3519c2a07a4c): Add `@ontrails/cloudflare/d1`, an env-bound Cloudflare D1 store resource for `@ontrails/store` definitions. The new subpath exports `cloudflareD1` and `connectD1`, supports the backend-agnostic store accessor contract (`get`, `list`, `upsert`, `remove`), versioned-table optimistic concurrency, fixture/mock seeding, store-derived write signals, Miniflare-backed conformance tests, and Worker env-bridge integration.
+
+  `@ontrails/core` and `@ontrails/store` no longer require the Bun global for signal fire ids or late-bound store signal tokens, so store definitions and store-derived signal emission work inside Worker modules. `@ontrails/warden` now treats `cloudflareD1` as a required Cloudflare public export with `@example` coverage.
+
+- [`9bf592d`](https://github.com/outfitter-dev/trails/commit/9bf592ddba46aa12e3f4e6ffc0f772f7a41ed3df): Declare verified first-party adapter metadata for Drizzle, HTTP/Bun, and Store/Jsonfile so shared adapter checks can dogfood real owner targets.
+
+## 1.0.0-beta.39
+
+### Patch Changes
+
+- [`f7ec225`](https://github.com/outfitter-dev/trails/commit/f7ec225c01482f8fb55afd174add3d961a63171b): `sync()` gains the factory-contract options `crud()` and `reconcile()` received in TRL-1195: a `permit` option declared on the produced trail, and per-endpoint `contour` options on `SyncEndpoint` so a `crud()` bundle's table contour can be shared instead of colliding as a duplicate registration at `topo()`.
+- [`5a38c73`](https://github.com/outfitter-dev/trails/commit/5a38c73092f81612769be4b44944d828c3436e07): Complete the store factory trail contracts (TRL-1195, absorbing TRL-1177 and TRL-1178). `crud()` gains `permit` (applied to every produced trail) and `permits` (per-operation overrides, so destroy trails satisfy permit governance) plus a `contour` option, and the returned tuple now exposes the table contour it registered as a `contour` property. `reconcile()` gains `permit` and accepts a shared `contour` instance, so crud + reconcile on one table register cleanly in a single `topo()` instead of colliding on a duplicate contour name. `TableContour` is exported from `@ontrails/store/trails`. Consuming apps no longer need to post-process factory trails to attach permits or strip contours.
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [21c6dda]
+- Updated dependencies [fe72b84]
+  - @ontrails/core@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [38907cc]
+  - @ontrails/core@1.0.0-beta.31
+
+## 1.0.0-beta.30
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.30
+
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+  - @ontrails/core@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.24
+
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.23
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.22
+
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- Updated dependencies [99523f2]
+  - @ontrails/core@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Patch Changes
+
+- 851a2a3: Derive trail caller and blaze input types from the authored input schema while keeping one public input contract.
+- Updated dependencies [851a2a3]
+  - @ontrails/core@1.0.0-beta.20
+
+## 1.0.0-beta.19
+
+### Patch Changes
+
+- e41c382: Document beta-channel install guidance in package and adapter README install snippets so consumers use explicit `@beta` (or pinned `1.0.0-beta.N`) tags instead of accidental `latest` resolution during the prerelease line. Adds the policy doc at `docs/releases/beta-channel-policy.md`, prints both `latest` and `beta` dist-tags in `bun run publish:registry-check`, and aligns plugin/skill install snippets.
+- ab1c77c: Advertise first-party adapter target metadata for catalog derivation.
+- Updated dependencies [e41c382]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [846a597]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [d76be13]
+- Updated dependencies [84f56a5]
+- Updated dependencies [431b04c]
+- Updated dependencies [5d88104]
+- Updated dependencies [f04a9ef]
+  - @ontrails/core@1.0.0-beta.19
+
+## 1.0.0-beta.18
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.18
+
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- Updated dependencies [3dc8254]
+  - @ontrails/core@1.0.0-beta.17
+
+## 1.0.0-beta.16
+
+### Major Changes
+
+- 3395234: Move store adapter-binding helpers to `@ontrails/store/adapter-support` and topographer direct database/admin helpers to `@ontrails/topographer/backend-support`, keeping root exports focused on contract-level APIs.
+- 6300f70: BREAKING: rename the shared store backend option type from `StoreConnectorOptions` to `StoreAdapterOptions`.
+
+### Patch Changes
+
+- e898cc4: Add repo-level Knip dead-code detection and remove stale internal exports and unused package dependencies surfaced by the new check.
+- 49c2e7d: Refresh published package README taxonomy to use adapter language instead of retired connector vocabulary.
+- df9a7d0: Add project-aware public export-map governance for @ontrails workspace docs,
+  imports, root barrels, and bin-only package surfaces.
+- Updated dependencies [73622ae]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [e898cc4]
+- Updated dependencies [3395234]
+- Updated dependencies [bcdc484]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+  - @ontrails/core@1.0.0-beta.16
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+
+## 1.0.0-beta.14
+
+### Minor Changes
+
+- 69057e9: Add hierarchical CLI command trees and structured input, enforce established-only topo exports across trailheads, move developer topo and tracker state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+
+### Patch Changes
+
+- Updated dependencies [69057e9]
+  - @ontrails/core@1.0.0-beta.14

package/README.md

@@ -0,0 +1,290 @@
+# @ontrails/store
+
+Schema-derived persistence for Trails.
+
+The root package owns the backend-agnostic `store(...)` declaration. External adapter packages such as `@ontrails/drizzle` bind that declaration to a concrete runtime, and first-party built-ins such as `@ontrails/store/jsonfile` live as opt-in subpaths on the same package.
+
+## The two layers
+
+### 1. Declare the store contract
+
+```typescript
+import { store } from '@ontrails/store';
+
+export const db = store({
+  gists: {
+    schema: gistSchema,
+    identity: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+    indexed: ['owner', 'createdAt'],
+    versioned: true,
+  },
+  files: {
+    schema: fileSchema,
+    identity: 'id',
+    generated: ['id'],
+    references: { gistId: 'gists' },
+  },
+});
+```
+
+This declaration is pure metadata:
+
+- full entity schema
+- insert schema
+- update schema
+- fixture schema
+- derived change-signal handles (`table.signals.created|updated|removed`)
+- identity field
+- generated-field metadata
+- optional framework-managed version tracking
+- indexed markers
+- references
+
+No database connection is opened here. The returned value is the durable authored source of truth.
+
+### 2. Bind it to a concrete runtime
+
+```typescript
+import { store } from '@ontrails/store';
+import { connectDrizzle } from '@ontrails/drizzle';
+
+const definition = store({
+  gists: {
+    schema: gistSchema,
+    identity: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+  },
+});
+
+export const db = connectDrizzle(definition, {
+  id: 'db.main',
+  url: ':memory:',
+});
+```
+
+The bound store is a resource. Use it directly in trails:
+
+```typescript
+export const list = trail('gist.list', {
+  resources: [db],
+  intent: 'read',
+  implementation: async (_input, ctx) => {
+    const conn = db.from(ctx);
+    const gists = await conn.gists.list();
+    return Result.ok(gists);
+  },
+});
+```
+
+### Built-in local backend
+
+For a zero-extra-package local backend, use the first-party JSON file binding:
+
+```typescript
+import { store } from '@ontrails/store';
+import { jsonFile } from '@ontrails/store/jsonfile';
+
+const definition = store({
+  gists: {
+    schema: gistSchema,
+    identity: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+  },
+});
+
+export const db = jsonFile(definition, {
+  dir: './data',
+});
+```
+
+## Typed accessors
+
+Every writable table on a bound connection exposes the backend-agnostic accessor contract:
+
+```typescript
+const conn = db.from(ctx);
+
+const created = await conn.gists.upsert({
+  ownerId: 'matt',
+  description: 'Hello, Trails',
+});
+
+const found = await conn.gists.get(created.id);
+const page = await conn.gists.list({ ownerId: 'matt' }, { limit: 20, offset: 0 });
+const updated = await conn.gists.upsert({
+  description: 'Updated description',
+  id: created.id,
+  ownerId: 'matt',
+});
+const removed = await conn.gists.remove(created.id);
+```
+
+Types are derived from the Zod schema:
+
+- `upsert()` uses the fixture/entity shape with generated fields optional
+- `get()` returns `Entity | null`
+- `list()` accepts typed partial filters and pagination options
+- `versioned: true` adds a framework-managed `version` field to returned entities and lets `upsert()` accept an expected `version` for optimistic concurrency
+
+Each normalized table also derives typed change signals from the same schema:
+
+```typescript
+const createdHandle = definition.tables.gists.signals.created;
+const updatedHandle = definition.tables.gists.signals.updated;
+const removedHandle = definition.tables.gists.signals.removed;
+```
+
+These pre-bind handles preserve payload shape, but the canonical signal id materializes only when an adapter binds the store to a resource. The bound form is always `resource:table.change`:
+
+```typescript
+const created = db.store.tables.gists.signals.created;
+
+created.id;
+// "db.main:gists.created"
+```
+
+## Adapter Support Subpath
+
+Adapter authors who bind a `store(...)` definition to a concrete backend should import signal-binding helpers from `@ontrails/store/adapter-support`:
+
+```typescript
+import { bindStoreDefinition } from '@ontrails/store/adapter-support';
+```
+
+The subpath owns `bindStoreDefinition`, `createStoreTableSignals`, `composeStoreSignalId`, `isValidResourceId`, and `StoreSignalChange`. The root package stays focused on backend-agnostic store contracts.
+
+Writable bindings fire those canonical scoped signals automatically when you access the resource through `db.from(ctx)` inside a trail context.
+
+See [Store Signal Identity Migration](../../docs/store-signal-identity-migration.md) when updating existing `on:` clauses, surface-map fixtures, or custom resource wrappers from bare ids to scoped ids.
+
+Tabular adapters such as `@ontrails/drizzle` also expose `insert()` and `update()` as convenience methods when the backend natively distinguishes create and patch operations.
+
+## Fixtures and mocks
+
+Fixtures belong on the root definition:
+
+```typescript
+export const db = store({
+  gists: {
+    schema: gistSchema,
+    identity: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+    fixtures: [
+      { id: 'g_1', ownerId: 'matt', description: 'Seed gist' },
+    ],
+  },
+});
+```
+
+When an adapter binds the store, those fixtures feed the resource mock automatically. Adapter options can also add or override seed data for tests.
+
+That means `testAll(app)` can auto-resolve adapter-bound store resources without extra ceremony, as long as the resource is registered in the topo.
+
+## Read-only bindings
+
+Use the Drizzle adapter's read-only binding when a trail should inspect persisted state without exposing writes:
+
+```typescript
+import { connectReadOnlyDrizzle } from '@ontrails/drizzle';
+
+const analytics = connectReadOnlyDrizzle(definition, {
+  id: 'analytics.db',
+  url: './data/analytics.sqlite',
+});
+```
+
+Read-only bindings expose `get()`, `list()`, and `query()`, but not `upsert()`, `remove()`, `insert()`, or `update()`.
+
+## Accessor contract testing
+
+Adapters can reuse the shared writable-accessor contract tests from `@ontrails/store/testing`:
+
+```typescript
+import { createStoreAccessorContractCases } from '@ontrails/store/testing';
+```
+
+That helper provides reusable cases for the baseline `get()`, `list()`, `upsert()`, and `remove()` behavior so adapter suites only need to wrap them with their normal `test(...)` calls and add backend-specific coverage on top.
+
+## Drizzle escape hatch
+
+Complex queries use the adapter-native query builder through `query()`:
+
+```typescript
+const conn = db.from(ctx);
+
+const rows = await conn.query(({ drizzle, tables }) =>
+  drizzle
+    .select()
+    .from(tables.gists)
+);
+```
+
+This keeps the default happy path derived and typed, while still giving you full access to the underlying adapter when the CRUD accessors are not enough.
+
+## Adapter binding
+
+`@ontrails/drizzle` keeps the durable `store(...)` declaration in `@ontrails/store` and binds it to a concrete runtime:
+
+```typescript
+import { connectDrizzle, connectReadOnlyDrizzle } from '@ontrails/drizzle';
+import { store } from '@ontrails/store';
+
+const definition = store({
+  gists: {
+    schema: gistSchema,
+    identity: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+  },
+});
+
+export const writable = connectDrizzle(definition, { url: ':memory:' });
+
+export const readonly = connectReadOnlyDrizzle(definition, {
+  url: './data/gists.sqlite',
+});
+```
+
+The root package still owns the authored persistence model; adapter packages render that model into runnable resources.
+
+## Schema export for external tooling
+
+If you need the raw derived Drizzle tables for tooling such as `drizzle-kit`, read them from the bound resource's `tables` field:
+
+```typescript
+import { connectDrizzle } from '@ontrails/drizzle';
+import { store } from '@ontrails/store';
+
+const definition = store({
+  gists: {
+    schema: gistSchema,
+    identity: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+  },
+});
+
+const db = connectDrizzle(definition, { url: ':memory:' });
+const schema = db.tables;
+```
+
+## Installation
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bun add --exact @ontrails/store@0.2.0 zod
+```
+
+Add Drizzle only when you want the external SQLite/ORM adapter:
+
+```bash
+bun add --exact @ontrails/drizzle@0.2.0
+```
+
+## Migration
+
+The Drizzle binding now lives in `@ontrails/drizzle`.
+
+<!-- warden-ignore-next-line -->
+- Replace `import { ... } from '@ontrails/store/drizzle'` with `import { ... } from '@ontrails/drizzle'`
+- Keep backend-agnostic store declarations on `@ontrails/store`

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ontrails/store",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/store"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./adapter-support": "./src/adapter-support.ts",
+    "./jsonfile": "./src/jsonfile/index.ts",
+    "./trails": "./src/trails/index.ts",
+    "./testing": "./src/testing.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^0.2.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapters": {
+      "./jsonfile": {
+        "target": "store"
+      }
+    },
+    "adapterTargets": {
+      "store": {
+        "placements": [
+          "extracted",
+          "subpath"
+        ],
+        "supportImport": "@ontrails/store/adapter-support",
+        "testingImport": "@ontrails/store/testing"
+      }
+    }
+  }
+}