@ontrails/store 1.0.0-beta.14 → 1.0.0-beta.16

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @ontrails/store
 
+## 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

package/README.md

@@ -2,7 +2,7 @@
 
 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 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
 
@@ -14,13 +14,14 @@ import { store } from '@ontrails/store';
 export const db = store({
   gists: {
     schema: gistSchema,
-    primaryKey: 'id',
+    identity: 'id',
     generated: ['id', 'createdAt', 'updatedAt'],
-    indexes: ['owner', 'createdAt'],
+    indexed: ['owner', 'createdAt'],
+    versioned: true,
   },
   files: {
     schema: fileSchema,
-    primaryKey: 'id',
+    identity: 'id',
     generated: ['id'],
     references: { gistId: 'gists' },
   },
@@ -33,8 +34,11 @@ This declaration is pure metadata:
 - insert schema
 - update schema
 - fixture schema
+- derived change-signal handles (`table.signals.created|updated|removed`)
+- identity field
 - generated-field metadata
-- indexes
+- optional framework-managed version tracking
+- indexed markers
 - references
 
 No database connection is opened here. The returned value is the durable authored source of truth.
@@ -43,12 +47,12 @@ No database connection is opened here. The returned value is the durable authore
 
 ```typescript
 import { store } from '@ontrails/store';
-import { connectDrizzle } from '@ontrails/store/drizzle';
+import { connectDrizzle } from '@ontrails/drizzle';
 
 const definition = store({
   gists: {
     schema: gistSchema,
-    primaryKey: 'id',
+    identity: 'id',
     generated: ['id', 'createdAt', 'updatedAt'],
   },
 });
@@ -59,11 +63,11 @@ export const db = connectDrizzle(definition, {
 });
 ```
 
-The bound store is a provision. Use it directly in trails:
+The bound store is a resource. Use it directly in trails:
 
 ```typescript
 export const list = trail('gist.list', {
-  provisions: [db],
+  resources: [db],
   intent: 'read',
   blaze: async (_input, ctx) => {
     const conn = db.from(ctx);
@@ -73,32 +77,91 @@ export const list = trail('gist.list', {
 });
 ```
 
+### 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 table on a bound connection exposes typed CRUD 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.insert({
-  owner: 'matt',
+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({ owner: 'matt' }, { limit: 20, offset: 0 });
-const updated = await conn.gists.update(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:
 
-- `insert()` uses the entity schema minus generated fields
-- `update()` uses the entity schema minus generated fields, then makes it partial
+- `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
 
@@ -108,48 +171,47 @@ Fixtures belong on the root definition:
 export const db = store({
   gists: {
     schema: gistSchema,
-    primaryKey: 'id',
+    identity: 'id',
     generated: ['id', 'createdAt', 'updatedAt'],
     fixtures: [
-      { id: 'g_1', owner: 'matt', description: 'Seed gist' },
+      { id: 'g_1', ownerId: '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.
+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 connector-bound store provisions without extra ceremony, as long as the provision is registered in the topo.
+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 connector's read-only helpers when a trail should inspect persisted state without exposing writes:
+Use the Drizzle adapter's read-only binding when a trail should inspect persisted state without exposing writes:
 
 ```typescript
-import { connectReadOnlyDrizzle, readonlyStore } from '@ontrails/store/drizzle';
+import { connectReadOnlyDrizzle } from '@ontrails/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 `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';
 ```
 
-Read-only bindings expose `get()`, `list()`, and `query()`, but not `insert()`, `update()`, or `remove()`.
+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 connector-native query builder through `query()`:
+Complex queries use the adapter-native query builder through `query()`:
 
 ```typescript
 const conn = db.from(ctx);
@@ -161,53 +223,72 @@ const rows = await conn.query(({ drizzle, tables }) =>
 );
 ```
 
-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.
+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.
 
-## Connector conveniences
+## Adapter binding
 
-`@ontrails/store/drizzle` also exports one-line conveniences when you want declaration and binding together:
+`@ontrails/drizzle` keeps the durable `store(...)` declaration in
+`@ontrails/store` and binds it to a concrete runtime:
 
 ```typescript
-import { store, readonlyStore } from '@ontrails/store/drizzle';
-
-export const writable = store(
-  {
-    gists: {
-      schema: gistSchema,
-      primaryKey: 'id',
-      generated: ['id', 'createdAt', 'updatedAt'],
-    },
-  },
-  { url: ':memory:' }
-);
+import { connectDrizzle, connectReadOnlyDrizzle } from '@ontrails/drizzle';
+import { store } from '@ontrails/store';
 
-export const readonly = readonlyStore(
-  {
-    gists: {
-      schema: gistSchema,
-      primaryKey: 'id',
-      generated: ['id', 'createdAt', 'updatedAt'],
-    },
+const definition = store({
+  gists: {
+    schema: gistSchema,
+    identity: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
   },
-  { url: './data/gists.sqlite' }
-);
+});
+
+export const writable = connectDrizzle(definition, { url: ':memory:' });
+
+export const readonly = connectReadOnlyDrizzle(definition, {
+  url: './data/gists.sqlite',
+});
 ```
 
-These are conveniences, not the architectural source of truth. The root package still owns the durable authored `store(...)` model.
+The root package still owns the authored persistence model; adapter packages
+project that model into runnable resources.
 
 ## Schema export for external tooling
 
-If you need the raw derived Drizzle tables for tooling such as `drizzle-kit`, use `getSchema()`:
+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 { getSchema } from '@ontrails/store/drizzle';
+import { connectDrizzle } from '@ontrails/drizzle';
+import { store } from '@ontrails/store';
+
+const definition = store({
+  gists: {
+    schema: gistSchema,
+    identity: 'id',
+    generated: ['id', 'createdAt', 'updatedAt'],
+  },
+});
 
-const schema = getSchema(db);
+const db = connectDrizzle(definition, { url: ':memory:' });
+const schema = db.tables;
 ```
 
 ## Installation
 
 ```bash
 bun add @ontrails/store zod
-bun add drizzle-orm
 ```
+
+Add Drizzle only when you want the external SQLite/ORM adapter:
+
+```bash
+bun add @ontrails/drizzle
+```
+
+## 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

@@ -1,10 +1,21 @@
 {
   "name": "@ontrails/store",
-  "version": "1.0.0-beta.14",
+  "version": "1.0.0-beta.16",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./drizzle": "./src/drizzle/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": {
@@ -15,15 +26,9 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.13"
+    "@ontrails/core": "^1.0.0-beta.15"
   },
   "peerDependencies": {
-    "drizzle-orm": "^0.45.2",
     "zod": "^4.3.5"
-  },
-  "peerDependenciesMeta": {
-    "drizzle-orm": {
-      "optional": true
-    }
   }
 }

package/src/adapter-support.ts

@@ -0,0 +1,163 @@
+import {
+  attachLateBoundSignalRef,
+  cloneSignalWithId,
+  signal,
+  ValidationError,
+} from '@ontrails/core';
+import type { Signal } from '@ontrails/core';
+import type { z } from 'zod';
+
+import type {
+  AnyStoreDefinition,
+  AnyStoreTable,
+  StoreTableSignals,
+} from './types.js';
+
+type MutableTables<TStore extends AnyStoreDefinition> = {
+  -readonly [TName in keyof TStore['tables']]: TStore['tables'][TName];
+};
+
+type StoreSignalChange = 'created' | 'removed' | 'updated';
+
+const createStoreSignalDescription = (
+  tableName: string,
+  change: StoreSignalChange
+): string => {
+  switch (change) {
+    case 'created': {
+      return `Fired after a "${tableName}" entity is created.`;
+    }
+    case 'removed': {
+      return `Fired after a "${tableName}" entity is removed.`;
+    }
+    case 'updated': {
+      return `Fired after a "${tableName}" entity is updated.`;
+    }
+    default: {
+      throw new Error(`Unsupported store signal change: ${change as string}`);
+    }
+  }
+};
+
+const createStoreSignal = <TPayload>(
+  tableName: string,
+  change: StoreSignalChange,
+  payload: z.ZodType<TPayload>
+): Signal<TPayload> =>
+  attachLateBoundSignalRef(
+    signal(`${tableName}.${change}`, {
+      description: createStoreSignalDescription(tableName, change),
+      payload,
+    }),
+    {
+      kind: 'store-derived',
+      token: Bun.randomUUIDv7(),
+    }
+  );
+
+export const createStoreTableSignals = <TPayload>(
+  tableName: string,
+  payload: z.ZodType<TPayload>
+): StoreTableSignals<TPayload> =>
+  Object.freeze({
+    created: createStoreSignal(tableName, 'created', payload),
+    removed: createStoreSignal(tableName, 'removed', payload),
+    updated: createStoreSignal(tableName, 'updated', payload),
+  });
+
+export const composeStoreSignalId = (
+  scope: string,
+  tableName: string,
+  change: StoreSignalChange
+): string => `${scope}:${tableName}.${change}`;
+
+const bindTableSignals = (
+  scope: string,
+  table: AnyStoreTable
+): StoreTableSignals<unknown> =>
+  Object.freeze({
+    created: cloneSignalWithId(
+      table.signals.created,
+      composeStoreSignalId(scope, table.name, 'created')
+    ),
+    removed: cloneSignalWithId(
+      table.signals.removed,
+      composeStoreSignalId(scope, table.name, 'removed')
+    ),
+    updated: cloneSignalWithId(
+      table.signals.updated,
+      composeStoreSignalId(scope, table.name, 'updated')
+    ),
+  });
+
+const collectStoreSignals = <TStore extends AnyStoreDefinition>(
+  normalized: MutableTables<TStore>,
+  tableNames: readonly Extract<keyof TStore['tables'], string>[]
+) =>
+  Object.freeze(
+    tableNames.flatMap((name) => {
+      const table = normalized[name];
+      return table === undefined
+        ? []
+        : [table.signals.created, table.signals.updated, table.signals.removed];
+    })
+  );
+
+/**
+ * Verifies that a resource id is safe to compose into a scoped signal id.
+ *
+ * Scoped signal ids are matched by the `SCOPED_SIGNAL_ID` pattern in
+ * `@ontrails/core` (`^[^:\s]+:[^:.\s]+(?:\.[^:.\s]+)+$`). A resource id used
+ * as the scope segment must therefore be a non-empty string that contains
+ * neither `":"` nor any whitespace.
+ */
+export const isValidResourceId = (resourceId: string): boolean =>
+  resourceId.length > 0 && !resourceId.includes(':') && !/\s/.test(resourceId);
+
+const assertValidScope = (scope: string): void => {
+  if (!isValidResourceId(scope)) {
+    throw new ValidationError(
+      `Store resource id "${scope}" is invalid: must be a non-empty string with no ":" characters and no whitespace.`
+    );
+  }
+};
+
+export const bindStoreDefinition = <TStore extends AnyStoreDefinition>(
+  definition: TStore,
+  scope: string
+): TStore => {
+  assertValidScope(scope);
+
+  const tableNames = definition.tableNames as readonly Extract<
+    keyof TStore['tables'],
+    string
+  >[];
+  const tables = {} as MutableTables<TStore>;
+
+  for (const tableName of tableNames) {
+    const table = definition.tables[tableName];
+    if (table === undefined) {
+      continue;
+    }
+
+    tables[tableName] = Object.freeze({
+      ...table,
+      signals: bindTableSignals(scope, table),
+    }) as MutableTables<TStore>[typeof tableName];
+  }
+
+  const get =
+    'get' in definition && typeof definition.get === 'function'
+      ? <TName extends Extract<keyof TStore['tables'], string>>(name: TName) =>
+          tables[name]
+      : undefined;
+
+  return Object.freeze({
+    ...definition,
+    ...(get ? { get } : {}),
+    signals: collectStoreSignals(tables, tableNames),
+    tables: Object.freeze(tables),
+  }) as TStore;
+};
+
+export type { StoreSignalChange };

package/src/crud-doctrine.ts

@@ -0,0 +1,43 @@
+export const crudOperations = [
+  'create',
+  'read',
+  'update',
+  'delete',
+  'list',
+] as const;
+
+export type CrudOperation = (typeof crudOperations)[number];
+
+export interface CrudAccessorExpectation {
+  readonly fallback?: string | undefined;
+  readonly preferred: string;
+  readonly severityWhenNoFallback: 'error';
+  readonly severityWhenPreferredMissingWithFallback?: 'warn' | undefined;
+}
+
+export const crudAccessorExpectations = {
+  create: {
+    fallback: 'upsert',
+    preferred: 'insert',
+    severityWhenNoFallback: 'error',
+    severityWhenPreferredMissingWithFallback: 'warn',
+  },
+  delete: {
+    preferred: 'remove',
+    severityWhenNoFallback: 'error',
+  },
+  list: {
+    preferred: 'list',
+    severityWhenNoFallback: 'error',
+  },
+  read: {
+    preferred: 'get',
+    severityWhenNoFallback: 'error',
+  },
+  update: {
+    fallback: 'upsert',
+    preferred: 'update',
+    severityWhenNoFallback: 'error',
+    severityWhenPreferredMissingWithFallback: 'warn',
+  },
+} as const satisfies Record<CrudOperation, CrudAccessorExpectation>;

package/src/index.ts

@@ -1,10 +1,9 @@
-export {
-  entitySchemaOf,
-  fixtureSchemaOf,
-  insertSchemaOf,
-  store,
-  updateSchemaOf,
-} from './store.js';
+export { crudAccessorExpectations, crudOperations } from './crud-doctrine.js';
+export type {
+  CrudAccessorExpectation,
+  CrudOperation,
+} from './crud-doctrine.js';
+export { store, versionFieldName } from './store.js';
 export type {
   AnyStoreDefinition,
   AnyStoreTable,
@@ -15,25 +14,35 @@ export type {
   FixturesOfInput,
   GeneratedFieldsOfInput,
   GeneratedKeysOf,
+  IdentityFieldOfInput,
+  IdentityOf,
   IndexFieldsOfInput,
+  IndexedFieldsOfInput,
   InsertOf,
-  PrimaryKeyOf,
   ReadOnlyStoreConnection,
+  StoreAccessor,
   ReadOnlyStoreTableAccessor,
   ReferencesOfInput,
   StoreAccessMode,
   StoreConnection,
+  StoreAdapterOptions,
   StoreDefinition,
   StoreFieldKey,
   StoreFixtureInput,
   StoreFixtureRow,
   StoreIdentifierOf,
+  StoreKind,
   StoreListOptions,
+  StoreMockSeed,
   StoreObjectSchema,
+  StoreOptions,
   StoreSearchDefinition,
   StoreTable,
+  StoreTableSignals,
   StoreTableAccessor,
+  StoreTableConnection,
   StoreTableInput,
   StoreTablesInput,
+  UpsertOf,
   UpdateOf,
 } from './types.js';

package/src/jsonfile/index.ts

@@ -0,0 +1,6 @@
+export { connectJsonFile, jsonFile, jsonFile as store } from './runtime.js';
+export type {
+  JsonFileConnection,
+  JsonFileStoreOptions,
+  JsonFileStoreResource,
+} from './types.js';