@ontrails/store 1.0.0-beta.14

package/.agents/notes/2026-04-04/handoff-202604032309-9e85a104.md

@@ -0,0 +1,38 @@
+---
+created: 2026-04-04T03:09:15.424Z
+type: handoff
+session: 9e85a104-864f-4273-b68d-a4a95eb2d5fc
+---
+
+# Handoff 2026-04-04 23:09
+
+> Session `9e85a104` — PR feedback loop on 14-branch Graphite stack (#64-#77)
+
+## Done
+
+- **Round 1**: Fixed 11 P1s across the stack — `persistEstablishedTopoSave` throw→Result, hash pipeline unification in drift.ts, store type safety (nullable defaults, PK leak, InsertOf/UpdateOf precision), drizzle error mapping, legacy tracker DB cleanup, transitive cache TSDoc, duplicate const before compile error
+- **Round 2**: Fixed absorb regressions (variable reference splits across branches), plus new P1s — Commander undefined opts, toTrackStore close() no-op, verifyCurrentTopo hash pipeline, duplicate verifyCurrentTopo removal
+- **Round 3**: Fixed remaining P1s — ADR depends_on slug→integer normalization, draft-promote preflight rename validation (duplicates + existing targets), NOT NULL on PK columns in generated SQL, InternalError passthrough, warden README method names (.trailhead→.blaze), vocabulary verb fix
+- **Thread resolution**: 128 threads resolved across 3 rounds, re-reviews requested each time
+- **Key learning**: `gt absorb` splits changes across branches unpredictably when a function definition and its callers span different branches — always walk up and typecheck each branch after absorb
+
+## State
+
+- On branch `trl-129-topo-and-dev-surfaces` (#69) with an uncommitted fix (drift.ts resolveTrailsDir import + readTrailheadLock dir fix) — lint failed, needs investigation
+- 4 new P1s surfaced in Round 4 (from `-p 2` run which includes P0-P2):
+  - **#69**: drift.ts passes workspace root instead of `.trails/` to readTrailheadLock (fix attempted, lint error pending)
+  - **#71**: v2→v3 migration gap in topo-saves.ts — crash on existing schema version 2 databases
+  - **#72**: createMockTopoStore returns data without seeded saves (diverges from real store)
+  - **#77**: Three broken API examples in warden README (wrong signatures, invalid lefthook key)
+- P2s not yet addressed across #65, #68, #70, #72, #75
+
+## Next
+
+- [ ] Debug lint failure on #69 drift.ts fix and commit
+- [ ] Fix #71: Add v2→v3 migration guard in `ensureTopoHistorySchema` to create `topo_schemas`/`topo_exports` tables
+- [ ] Fix #72: Add empty-save guard to `createMockTopoStore` `trails.list()`/`trails.get()`
+- [ ] Fix #77: Correct `runWarden` and `checkDrift` signatures + lefthook key in warden README
+- [ ] Walk up all branches verifying typecheck after each fix
+- [ ] Submit stack, resolve threads, write loop record
+- [ ] Then address P2s: gitignore duplicate-append (#68), stale TSDoc (#70), test harness fallback (#65), readonlyStore mock factory (#75)
+- [ ] Consider: the `isDraftMarkedFile` vs `stripDraftFileMarkers` inconsistency on #67 is still open (P2)

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc -b

package/.turbo/turbo-lint.log

@@ -0,0 +1,3 @@
+$ oxlint ./src
+Found 0 warnings and 0 errors.
+Finished in 27ms on 9 files with 93 rules using 24 threads.

package/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @ontrails/store
+
+## 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,213 @@
+# @ontrails/store
+
+Schema-derived persistence for Trails.
+
+The root package owns the connector-agnostic `store(...)` declaration. Connector packages such as `@ontrails/store/drizzle` bind that declaration to a concrete runtime, just like a trailhead connector binds a topo to CLI, MCP, or HTTP.
+
+## The two layers
+
+### 1. Declare the store contract
+
+```typescript
+import { store } from '@ontrails/store';
+
+export const db = store({
+  gists: {
+    schema: gistSchema,
+    primaryKey: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+    indexes: ['owner', 'createdAt'],
+  },
+  files: {
+    schema: fileSchema,
+    primaryKey: 'id',
+    generated: ['id'],
+    references: { gistId: 'gists' },
+  },
+});
+```
+
+This declaration is pure metadata:
+
+- full entity schema
+- insert schema
+- update schema
+- fixture schema
+- generated-field metadata
+- indexes
+- 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/store/drizzle';
+
+const definition = store({
+  gists: {
+    schema: gistSchema,
+    primaryKey: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+  },
+});
+
+export const db = connectDrizzle(definition, {
+  id: 'db.main',
+  url: ':memory:',
+});
+```
+
+The bound store is a provision. Use it directly in trails:
+
+```typescript
+export const list = trail('gist.list', {
+  provisions: [db],
+  intent: 'read',
+  blaze: async (_input, ctx) => {
+    const conn = db.from(ctx);
+    const gists = await conn.gists.list();
+    return Result.ok(gists);
+  },
+});
+```
+
+## Typed accessors
+
+Every table on a bound connection exposes typed CRUD accessors:
+
+```typescript
+const conn = db.from(ctx);
+
+const created = await conn.gists.insert({
+  owner: 'matt',
+  description: 'Hello, Trails',
+});
+
+const found = await conn.gists.get(created.id);
+const page = await conn.gists.list({ owner: 'matt' }, { limit: 20, offset: 0 });
+const updated = await conn.gists.update(created.id, {
+  description: 'Updated description',
+});
+const removed = await conn.gists.remove(created.id);
+```
+
+Types are derived from the Zod schema:
+
+- `insert()` uses the entity schema minus generated fields
+- `update()` uses the entity schema minus generated fields, then makes it partial
+- `get()` returns `Entity | null`
+- `list()` accepts typed partial filters and pagination options
+
+## Fixtures and mocks
+
+Fixtures belong on the root definition:
+
+```typescript
+export const db = store({
+  gists: {
+    schema: gistSchema,
+    primaryKey: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+    fixtures: [
+      { id: 'g_1', owner: 'matt', description: 'Seed gist' },
+    ],
+  },
+});
+```
+
+When a connector binds the store, those fixtures feed the provision mock automatically. Connector options can also add or override seed data for tests.
+
+That means `testAll(app)` can auto-resolve connector-bound store provisions without extra ceremony, as long as the provision is registered in the topo.
+
+## Read-only bindings
+
+Use the Drizzle connector's read-only helpers when a trail should inspect persisted state without exposing writes:
+
+```typescript
+import { connectReadOnlyDrizzle, readonlyStore } from '@ontrails/store/drizzle';
+
+const analytics = connectReadOnlyDrizzle(definition, {
+  id: 'analytics.db',
+  url: './data/analytics.sqlite',
+});
+
+const auditLog = readonlyStore(
+  {
+    entries: {
+      schema: auditEntrySchema,
+      primaryKey: 'id',
+      generated: ['id', 'createdAt'],
+    },
+  },
+  { id: 'audit.db', url: './data/audit.sqlite' }
+);
+```
+
+Read-only bindings expose `get()`, `list()`, and `query()`, but not `insert()`, `update()`, or `remove()`.
+
+## Drizzle escape hatch
+
+Complex queries use the connector-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 connector when the CRUD accessors are not enough.
+
+## Connector conveniences
+
+`@ontrails/store/drizzle` also exports one-line conveniences when you want declaration and binding together:
+
+```typescript
+import { store, readonlyStore } from '@ontrails/store/drizzle';
+
+export const writable = store(
+  {
+    gists: {
+      schema: gistSchema,
+      primaryKey: 'id',
+      generated: ['id', 'createdAt', 'updatedAt'],
+    },
+  },
+  { url: ':memory:' }
+);
+
+export const readonly = readonlyStore(
+  {
+    gists: {
+      schema: gistSchema,
+      primaryKey: 'id',
+      generated: ['id', 'createdAt', 'updatedAt'],
+    },
+  },
+  { url: './data/gists.sqlite' }
+);
+```
+
+These are conveniences, not the architectural source of truth. The root package still owns the durable authored `store(...)` model.
+
+## Schema export for external tooling
+
+If you need the raw derived Drizzle tables for tooling such as `drizzle-kit`, use `getSchema()`:
+
+```typescript
+import { getSchema } from '@ontrails/store/drizzle';
+
+const schema = getSchema(db);
+```
+
+## Installation
+
+```bash
+bun add @ontrails/store zod
+bun add drizzle-orm
+```

package/dist/drizzle/index.d.ts

@@ -0,0 +1,3 @@
+export { connectDrizzle, connectReadOnlyDrizzle, getSchema, readonlyStore, store, } from './runtime.js';
+export type { ConnectDrizzleOptions, DrizzleMockSeed, DrizzleQueryContext, DrizzleStoreConnection, DrizzleStoreProvision, DrizzleStoreSchema, ReadOnlyDrizzleOptions, ReadOnlyDrizzleStoreConnection, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/drizzle/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/drizzle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,KAAK,GACN,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,YAAY,CAAC"}

package/dist/drizzle/index.js

@@ -0,0 +1,2 @@
+export { connectDrizzle, connectReadOnlyDrizzle, getSchema, readonlyStore, store, } from './runtime.js';
+//# sourceMappingURL=index.js.map

package/dist/drizzle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/drizzle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,KAAK,GACN,MAAM,cAAc,CAAC"}

package/dist/drizzle/runtime.d.ts

@@ -0,0 +1,21 @@
+import { store as defineStore } from '../store.js';
+import type { AnyStoreDefinition, StoreAccessMode, StoreTablesInput } from '../types.js';
+import type { ConnectDrizzleOptions, DrizzleStoreConnection, DrizzleStoreProvision, DrizzleStoreSchema, ReadOnlyDrizzleOptions, ReadOnlyDrizzleStoreConnection } from './types.js';
+/**
+ * Bind a store definition to a Drizzle-backed SQLite provision.
+ *
+ * The returned provision manages its own connection lifecycle. The `mock()`
+ * factory creates an in-memory SQLite database seeded with fixtures — callers
+ * who obtain a mock connection are responsible for calling `closeConnection()`
+ * when done, or letting the connection be garbage-collected (the underlying
+ * `Database` client is tracked via `WeakMap`).
+ *
+ * Note: the `search` field on `StoreTableInput` is not yet interpreted by
+ * this connector — it is reserved for future full-text search support.
+ */
+export declare const connectDrizzle: <const TStore extends AnyStoreDefinition>(definition: TStore, options: ConnectDrizzleOptions<TStore>) => DrizzleStoreProvision<TStore, DrizzleStoreConnection<TStore>, "readwrite">;
+export declare const connectReadOnlyDrizzle: <const TStore extends AnyStoreDefinition>(definition: TStore, options: ReadOnlyDrizzleOptions) => DrizzleStoreProvision<TStore, ReadOnlyDrizzleStoreConnection<TStore>, "readonly">;
+export declare const store: <const TTables extends StoreTablesInput>(tables: TTables, options: ConnectDrizzleOptions<ReturnType<typeof defineStore<TTables>>>) => DrizzleStoreProvision<ReturnType<typeof defineStore<TTables>>, DrizzleStoreConnection<ReturnType<typeof defineStore<TTables>>>, "readwrite">;
+export declare const readonlyStore: <const TTables extends StoreTablesInput>(tables: TTables, options: ReadOnlyDrizzleOptions) => DrizzleStoreProvision<ReturnType<typeof defineStore<TTables>>, ReadOnlyDrizzleStoreConnection<ReturnType<typeof defineStore<TTables>>>, "readonly">;
+export declare const getSchema: <TStore extends AnyStoreDefinition>(binding: Pick<DrizzleStoreProvision<TStore, unknown, StoreAccessMode>, "tables">) => DrizzleStoreSchema<TStore>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/drizzle/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/drizzle/runtime.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EACV,kBAAkB,EAMlB,eAAe,EAGf,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AAMrB,OAAO,KAAK,EACV,qBAAqB,EAErB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAmqBpB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,CAAC,MAAM,SAAS,kBAAkB,EACpE,YAAY,MAAM,EAClB,SAAS,qBAAqB,CAAC,MAAM,CAAC,KACrC,qBAAqB,CACtB,MAAM,EACN,sBAAsB,CAAC,MAAM,CAAC,EAC9B,WAAW,CAoDZ,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,KAAK,CAAC,MAAM,SAAS,kBAAkB,EAC5E,YAAY,MAAM,EAClB,SAAS,sBAAsB,KAC9B,qBAAqB,CACtB,MAAM,EACN,8BAA8B,CAAC,MAAM,CAAC,EACtC,UAAU,CAkCX,CAAC;AAEF,eAAO,MAAM,KAAK,GAAI,KAAK,CAAC,OAAO,SAAS,gBAAgB,EAC1D,QAAQ,OAAO,EACf,SAAS,qBAAqB,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,KACtE,qBAAqB,CACtB,UAAU,CAAC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,EACvC,sBAAsB,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAC/D,WAAW,CACoC,CAAC;AAElD,eAAO,MAAM,aAAa,GAAI,KAAK,CAAC,OAAO,SAAS,gBAAgB,EAClE,QAAQ,OAAO,EACf,SAAS,sBAAsB,KAC9B,qBAAqB,CACtB,UAAU,CAAC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,EACvC,8BAA8B,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EACvE,UAAU,CAC6C,CAAC;AAE1D,eAAO,MAAM,SAAS,GAAI,MAAM,SAAS,kBAAkB,EACzD,SAAS,IAAI,CACX,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,eAAe,CAAC,EACvD,QAAQ,CACT,KACA,kBAAkB,CAAC,MAAM,CAAmB,CAAC"}