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

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @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

package/README.md

@@ -2,7 +2,7 @@
 
 Schema-derived persistence for Trails.
 
-The root package owns the connector-agnostic `store(...)` declaration. External connector 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 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
 
@@ -100,7 +100,7 @@ export const db = jsonFile(definition, {
 
 ## Typed accessors
 
-Every writable table on a bound connection exposes the connector-agnostic accessor contract:
+Every writable table on a bound connection exposes the backend-agnostic accessor contract:
 
 ```typescript
 const conn = db.from(ctx);
@@ -135,7 +135,7 @@ 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 a connector binds the store to a resource. The bound form is always `resource:table.event`:
+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;
@@ -144,9 +144,24 @@ 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.
 
-Tabular connectors such as `@ontrails/drizzle` also expose `insert()` and `update()` as convenience methods when the backend natively distinguishes create and patch operations.
+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
 
@@ -165,13 +180,13 @@ export const db = store({
 });
 ```
 
-When a connector binds the store, those fixtures feed the resource 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 resources without extra ceremony, as long as the resource 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 binding 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 } from '@ontrails/drizzle';
@@ -186,17 +201,17 @@ Read-only bindings expose `get()`, `list()`, and `query()`, but not `upsert()`,
 
 ## Accessor contract testing
 
-Connectors can reuse the shared writable-accessor contract tests from `@ontrails/store/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 connector suites only need to wrap them with their normal `test(...)` calls and add backend-specific coverage on top.
+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);
@@ -208,9 +223,9 @@ 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 binding
+## Adapter binding
 
 `@ontrails/drizzle` keeps the durable `store(...)` declaration in
 `@ontrails/store` and binds it to a concrete runtime:
@@ -234,7 +249,7 @@ export const readonly = connectReadOnlyDrizzle(definition, {
 });
 ```
 
-The root package still owns the authored persistence model; connector packages
+The root package still owns the authored persistence model; adapter packages
 project that model into runnable resources.
 
 ## Schema export for external tooling
@@ -264,7 +279,7 @@ const schema = db.tables;
 bun add @ontrails/store zod
 ```
 
-Add Drizzle only when you want the external SQLite/ORM connector:
+Add Drizzle only when you want the external SQLite/ORM adapter:
 
 ```bash
 bun add @ontrails/drizzle
@@ -274,5 +289,6 @@ bun add @ontrails/drizzle
 
 The Drizzle binding now lives in `@ontrails/drizzle`.
 
+<!-- warden-ignore-next-line -->
 - Replace `import { ... } from '@ontrails/store/drizzle'` with `import { ... } from '@ontrails/drizzle'`
-- Keep connector-agnostic store declarations on `@ontrails/store`
+- Keep backend-agnostic store declarations on `@ontrails/store`

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@ontrails/store",
-  "version": "1.0.0-beta.15",
+  "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",
-    "./internal/signal-identity": "./src/internal/signal-identity.ts",
+    "./adapter-support": "./src/adapter-support.ts",
     "./jsonfile": "./src/jsonfile/index.ts",
     "./trails": "./src/trails/index.ts",
     "./testing": "./src/testing.ts",
@@ -18,7 +26,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.14"
+    "@ontrails/core": "^1.0.0-beta.15"
   },
   "peerDependencies": {
     "zod": "^4.3.5"

package/src/{internal/signal-identity.ts → adapter-support.ts}

@@ -1,28 +1,29 @@
-import { signal, ValidationError } from '@ontrails/core';
-import type { Signal } from '@ontrails/core';
 import {
   attachLateBoundSignalRef,
   cloneSignalWithId,
-} from '@ontrails/core/internal/signal-ref';
+  signal,
+  ValidationError,
+} from '@ontrails/core';
+import type { Signal } from '@ontrails/core';
 import type { z } from 'zod';
 
 import type {
   AnyStoreDefinition,
   AnyStoreTable,
   StoreTableSignals,
-} from '../types.js';
+} from './types.js';
 
 type MutableTables<TStore extends AnyStoreDefinition> = {
   -readonly [TName in keyof TStore['tables']]: TStore['tables'][TName];
 };
 
-type StoreSignalEvent = 'created' | 'removed' | 'updated';
+type StoreSignalChange = 'created' | 'removed' | 'updated';
 
 const createStoreSignalDescription = (
   tableName: string,
-  event: StoreSignalEvent
+  change: StoreSignalChange
 ): string => {
-  switch (event) {
+  switch (change) {
     case 'created': {
       return `Fired after a "${tableName}" entity is created.`;
     }
@@ -33,19 +34,19 @@ const createStoreSignalDescription = (
       return `Fired after a "${tableName}" entity is updated.`;
     }
     default: {
-      throw new Error(`Unsupported store signal event: ${event as string}`);
+      throw new Error(`Unsupported store signal change: ${change as string}`);
     }
   }
 };
 
 const createStoreSignal = <TPayload>(
   tableName: string,
-  event: StoreSignalEvent,
+  change: StoreSignalChange,
   payload: z.ZodType<TPayload>
 ): Signal<TPayload> =>
   attachLateBoundSignalRef(
-    signal(`${tableName}.${event}`, {
-      description: createStoreSignalDescription(tableName, event),
+    signal(`${tableName}.${change}`, {
+      description: createStoreSignalDescription(tableName, change),
       payload,
     }),
     {
@@ -67,8 +68,8 @@ export const createStoreTableSignals = <TPayload>(
 export const composeStoreSignalId = (
   scope: string,
   tableName: string,
-  event: StoreSignalEvent
-): string => `${scope}:${tableName}.${event}`;
+  change: StoreSignalChange
+): string => `${scope}:${tableName}.${change}`;
 
 const bindTableSignals = (
   scope: string,
@@ -159,4 +160,4 @@ export const bindStoreDefinition = <TStore extends AnyStoreDefinition>(
   }) as TStore;
 };
 
-export type { StoreSignalEvent };
+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,3 +1,8 @@
+export { crudAccessorExpectations, crudOperations } from './crud-doctrine.js';
+export type {
+  CrudAccessorExpectation,
+  CrudOperation,
+} from './crud-doctrine.js';
 export { store, versionFieldName } from './store.js';
 export type {
   AnyStoreDefinition,
@@ -20,7 +25,7 @@ export type {
   ReferencesOfInput,
   StoreAccessMode,
   StoreConnection,
-  StoreConnectorOptions,
+  StoreAdapterOptions,
   StoreDefinition,
   StoreFieldKey,
   StoreFixtureInput,

package/src/jsonfile/runtime.ts

@@ -10,7 +10,7 @@ import type {
   StoreListOptions,
   UpsertOf,
 } from '../types.js';
-import { bindStoreDefinition } from '../internal/signal-identity.js';
+import { bindStoreDefinition } from '../adapter-support.js';
 import { versionFieldName } from '../store.js';
 
 import type {
@@ -448,7 +448,7 @@ const executeRemove = async <TTable extends AnyStoreTable>(
 
 // Module-level registry: ensures all connections to the same file share one
 // in-memory table instance. Keyed by resolved file path.
-// Note: entries are never evicted. This is acceptable for v1 — the connector
+// Note: entries are never evicted. This is acceptable for v1 — the adapter
 // targets single-process, short-lived servers where the number of distinct
 // table paths is bounded by the store definition.
 interface JsonFileTableRegistration<TTable extends AnyStoreTable> {
@@ -522,7 +522,7 @@ const buildAndRegisterTable = <TTable extends AnyStoreTable>(
  * @remarks
  * Tables are shared per resolved file path so multiple connections stay
  * coherent in-process. Reuse is only allowed when table-affecting config
- * matches exactly; otherwise the connector throws instead of silently
+ * matches exactly; otherwise the adapter throws instead of silently
  * inheriting the first connection's runtime semantics.
  */
 const createJsonFileTable = <TTable extends AnyStoreTable>(
@@ -698,5 +698,3 @@ export const jsonFile = <TStore extends AnyStoreDefinition>(
     signals: store.signals,
   });
 };
-
-export { jsonFile as store };

package/src/jsonfile/types.ts

@@ -3,7 +3,7 @@ import type {
   AnyStoreDefinition,
   AnyStoreTable,
   StoreAccessor,
-  StoreConnectorOptions,
+  StoreAdapterOptions,
 } from '../types.js';
 
 /** Connection shape: one StoreAccessor per table name. */
@@ -13,7 +13,7 @@ export type JsonFileConnection<TStore extends Record<string, AnyStoreTable>> =
 /** Options for creating a jsonfile store. */
 export interface JsonFileStoreOptions<
   TStore extends AnyStoreDefinition = AnyStoreDefinition,
-> extends StoreConnectorOptions<TStore> {
+> extends StoreAdapterOptions<TStore> {
   /** Directory where JSON files are written. One `<tableName>.json` per table. */
   readonly dir: string;
   /**

package/src/store.ts

@@ -1,9 +1,8 @@
-import { ValidationError } from '@ontrails/core';
+import { stripDefaultsFromShape, ValidationError } from '@ontrails/core';
 import type { AnySignal } from '@ontrails/core';
-import { stripDefaultsFromShape } from '@ontrails/core/internal/zod-wrappers';
 import { z } from 'zod';
 
-import { createStoreTableSignals } from './internal/signal-identity.js';
+import { createStoreTableSignals } from './adapter-support.js';
 import type {
   StoreDefinition,
   StoreKind,
@@ -19,7 +18,7 @@ const isStoreObjectSchema = (schema: z.ZodType): schema is StoreObjectSchema =>
 
 /**
  * Name of the framework-managed version column used by versioned tables for
- * optimistic concurrency control. Exported so connectors can gate their own
+ * optimistic concurrency control. Exported so adapters can gate their own
  * version-handling logic without duplicating the literal.
  */
 export const versionFieldName = 'version';
@@ -499,10 +498,10 @@ const collectStoreSignals = <const TTables extends StoreTablesInput>(
   );
 
 /**
- * Declare a connector-agnostic store definition from entity schemas and
+ * Declare a backend-agnostic store definition from entity schemas and
  * persistence metadata.
  *
- * The returned value is a normalized, read-only contract that connectors can
+ * The returned value is a normalized, read-only contract that adapters can
  * bind to a concrete runtime later.
  */
 export const store = <const TTables extends StoreTablesInput>(

package/src/testing.ts

@@ -84,9 +84,9 @@ const seedExistingEntity = async <TTable extends AnyStoreTable>(
 };
 
 /**
- * Shared contract cases for connector-agnostic writable store accessors.
+ * Shared contract cases for backend-agnostic writable store accessors.
  *
- * Connectors can register these with their own `test(...)` wrappers so the
+ * Adapters can register these with their own `test(...)` wrappers so the
  * baseline `get/list/upsert/remove` contract stays aligned across runtimes
  * without fighting repository-specific test-lint rules.
  */

package/src/trails/crud.ts

@@ -15,6 +15,7 @@ import type {
   StoreIdentifierOf,
   UpdateOf,
 } from '../types.js';
+import type { CrudOperation } from '../crud-doctrine.js';
 import { createTableContour } from './utils.js';
 import type { TableContour } from './utils.js';
 
@@ -44,7 +45,7 @@ type GeneratedFieldsOf<TTable extends AnyStoreTable> =
  */
 type DerivedInput<
   TTable extends AnyStoreTable,
-  TOperation extends 'create' | 'read' | 'update' | 'delete' | 'list',
+  TOperation extends CrudOperation,
 > = DeriveTrailInput<
   TableContour<TTable>,
   TOperation,
@@ -57,7 +58,7 @@ type DerivedInput<
  */
 type DerivedOutput<
   TTable extends AnyStoreTable,
-  TOperation extends 'create' | 'read' | 'update' | 'delete' | 'list',
+  TOperation extends CrudOperation,
 > = DeriveTrailOutput<TableContour<TTable>, TOperation>;
 
 type InternalCreateTrailOf<TTable extends AnyStoreTable> = Trail<
@@ -318,7 +319,7 @@ const buildCrudTrails = <TTable extends AnyStoreTable>(
  * Produce the standard CRUD trail tuple for one normalized store table.
  *
  * The factory derives schemas, examples, resources, and contour linkage from
- * the table metadata. Blazes default to the connector-agnostic store accessor
+ * the table metadata. Blazes default to the backend-agnostic store accessor
  * contract via `deriveTrail()`'s single-resource synthesis path. Per-operation
  * blaze overrides stay available for callers that need custom persistence
  * behavior and are layered onto the derived trails in a single pass.

package/src/trails/index.ts

@@ -1,3 +1,8 @@
+export { crudAccessorExpectations, crudOperations } from '../crud-doctrine.js';
+export type {
+  CrudAccessorExpectation,
+  CrudOperation,
+} from '../crud-doctrine.js';
 export { crud } from './crud.js';
 export type { CrudBlazeOverrides, CrudOptions, CrudTrails } from './crud.js';
 export { reconcile } from './reconcile.js';

package/src/trails/reconcile.ts

@@ -164,7 +164,7 @@ const recoverConflict = async <TTable extends AnyStoreTable>(
  * Build the input schema for a reconcile trail.
  *
  * `fixtureSchema` makes generated fields (including `version` on versioned
- * tables) optional because connectors populate them. Reconcile, however,
+ * tables) optional because adapters populate them. Reconcile, however,
  * relies on optimistic concurrency: the caller must pass the expected
  * `version` so `assertExpectedVersionMatch` can detect stale payloads. We
  * therefore extend `fixtureSchema` with a required `version` field so
@@ -244,7 +244,7 @@ const createReconcileDetour = <
  * For versioned tables, the derived input schema requires an explicit
  * `version` field so callers cannot sidestep optimistic concurrency at the
  * input boundary. `fixtureSchema` alone makes `version` optional because
- * connectors populate it for writes; reconcile must reject that relaxed
+ * adapters populate it for writes; reconcile must reject that relaxed
  * shape.
  */
 export const reconcile = <

package/src/trails/utils.ts

@@ -23,7 +23,7 @@ export type TableContour<TTable extends AnyStoreTable> = Contour<
  * Contour validates every example against the shape passed in, so the shape
  * must match how fixtures are actually shaped. Store fixtures may omit
  * framework-generated fields (`createdAt`, `version`, ...) because the
- * connector populates them, so we mirror `fixtureSchema`'s treatment of
+ * adapter populates them, so we mirror `fixtureSchema`'s treatment of
  * generated fields: generated, non-identity fields are made optional; the
  * identity field stays required because read/delete/update all derive their
  * input from it. Previously reconcile.ts and sync.ts passed