@ontrails/store 1.0.0-beta.32 → 1.0.0-beta.41

package/CHANGELOG.md

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

package/README.md

@@ -69,7 +69,7 @@ The bound store is a resource. Use it directly in trails:
 export const list = trail('gist.list', {
   resources: [db],
   intent: 'read',
-  blaze: async (_input, ctx) => {
+  implementation: async (_input, ctx) => {
     const conn = db.from(ctx);
     const gists = await conn.gists.list();
     return Result.ok(gists);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/store",
-  "version": "1.0.0-beta.32",
+  "version": "1.0.0-beta.41",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -26,12 +26,17 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.32"
+    "@ontrails/core": "^1.0.0-beta.41"
   },
   "peerDependencies": {
     "zod": "^4.3.5"
   },
   "trails": {
+    "adapters": {
+      "./jsonfile": {
+        "target": "store"
+      }
+    },
     "adapterTargets": {
       "store": {
         "placements": [

package/src/adapter-support.ts

@@ -19,6 +19,21 @@ type MutableTables<TStore extends AnyStoreDefinition> = {
 
 type StoreSignalChange = 'created' | 'removed' | 'updated';
 
+const storeSignalTokenCounter = Symbol.for(
+  '@ontrails/store.late-bound-signal-counter'
+);
+
+const takeStoreSignalTokenCounter = (): number => {
+  const globals = globalThis as Record<PropertyKey, unknown>;
+  const current = globals[storeSignalTokenCounter];
+  const next = typeof current === 'number' ? current : 0;
+  globals[storeSignalTokenCounter] = next + 1;
+  return next;
+};
+
+const createStoreSignalToken = (change: StoreSignalChange): string =>
+  `store-${change}-${takeStoreSignalTokenCounter()}`;
+
 const createStoreSignalDescription = (
   tableName: string,
   change: StoreSignalChange
@@ -51,7 +66,7 @@ const createStoreSignal = <TPayload>(
     }),
     {
       kind: 'store-derived',
-      token: Bun.randomUUIDv7(),
+      token: createStoreSignalToken(change),
     }
   );
 

package/src/trails/crud.ts

@@ -1,4 +1,9 @@
-import type { Implementation, Resource, Trail } from '@ontrails/core';
+import type {
+  Implementation,
+  PermitRequirement,
+  Resource,
+  Trail,
+} from '@ontrails/core';
 import { deriveTrail } from '@ontrails/core/trails';
 import type {
   DeriveTrailInput,
@@ -16,8 +21,8 @@ import type {
   UpdateOf,
 } from '../types.js';
 import type { CrudOperation } from '../crud-doctrine.js';
-import { createTableContour } from './utils.js';
-import type { TableContour } from './utils.js';
+import { assertCurrentEntityOption, createTableEntity } from './utils.js';
+import type { TableEntity } from './utils.js';
 
 type IdentityInputOf<TTable extends AnyStoreTable> = Readonly<
   Record<Extract<TTable['identity'], string>, StoreIdentifierOf<TTable>>
@@ -27,27 +32,27 @@ type CrudConnection<TTable extends AnyStoreTable> = Readonly<
   Record<TTable['name'], StoreAccessor<TTable>>
 >;
 
-type TableContourFieldKey<TTable extends AnyStoreTable> = Extract<
-  keyof z.output<TableContour<TTable>>,
+type TableEntityFieldKey<TTable extends AnyStoreTable> = Extract<
+  keyof z.output<TableEntity<TTable>>,
   string
 >;
 
 type GeneratedFieldsOf<TTable extends AnyStoreTable> =
-  TTable['generated'] extends readonly TableContourFieldKey<TTable>[]
+  TTable['generated'] extends readonly TableEntityFieldKey<TTable>[]
     ? TTable['generated']
     : readonly [];
 
 /**
  * Input type `deriveTrail` projects for a given CRUD operation against a
- * store table. Uses `TableContour<TTable>` so the projected input
- * structurally matches the contour-backed derivation path in
+ * store table. Uses `TableEntity<TTable>` so the projected input
+ * structurally matches the entity-backed derivation path in
  * `@ontrails/core`'s `deriveTrail`.
  */
 type DerivedInput<
   TTable extends AnyStoreTable,
   TOperation extends CrudOperation,
 > = DeriveTrailInput<
-  TableContour<TTable>,
+  TableEntity<TTable>,
   TOperation,
   GeneratedFieldsOf<TTable>
 >;
@@ -59,7 +64,7 @@ type DerivedInput<
 type DerivedOutput<
   TTable extends AnyStoreTable,
   TOperation extends CrudOperation,
-> = DeriveTrailOutput<TableContour<TTable>, TOperation>;
+> = DeriveTrailOutput<TableEntity<TTable>, TOperation>;
 
 type InternalCreateTrailOf<TTable extends AnyStoreTable> = Trail<
   DerivedInput<TTable, 'create'>,
@@ -137,9 +142,17 @@ export type CrudTrails<TTable extends AnyStoreTable> = readonly [
   update: UpdateTrailOf<TTable>,
   remove: DeleteTrailOf<TTable>,
   list: ListTrailOf<TTable>,
-];
+] & {
+  /**
+   * The table entity the factory registered on its trails. Pass it to
+   * `reconcile({ entity })` (or other factories over the same table) so
+   * the topo sees one shared entity instance instead of rejecting two
+   * same-named rebuilds as duplicates.
+   */
+  readonly entity: TableEntity<TTable>;
+};
 
-export interface CrudBlazeOverrides<TTable extends AnyStoreTable> {
+export interface CrudImplementationOverrides<TTable extends AnyStoreTable> {
   readonly create?: Implementation<InsertOf<TTable>, EntityOf<TTable>>;
   readonly read?: Implementation<IdentityInputOf<TTable>, EntityOf<TTable>>;
   readonly update?: Implementation<
@@ -151,10 +164,28 @@ export interface CrudBlazeOverrides<TTable extends AnyStoreTable> {
 }
 
 export interface CrudOptions<TTable extends AnyStoreTable> {
-  readonly blaze?: CrudBlazeOverrides<TTable>;
+  readonly implementation?: CrudImplementationOverrides<TTable>;
+  /**
+   * Existing table entity to register on the produced trails. When
+   * omitted, the factory builds one from the table. Pass a shared
+   * instance when another factory (e.g. `reconcile()`) covers the same
+   * table so `topo()` sees a single entity registration.
+   */
+  readonly entity?: TableEntity<TTable>;
+  /**
+   * Permit requirement declared on every produced trail. Factory trails
+   * carry authored defaults like any hand-written trail; per-operation
+   * entries in `permits` override this baseline.
+   */
+  readonly permit?: PermitRequirement;
+  /**
+   * Per-operation permit overrides. At minimum, destroy-intent trails
+   * (`delete`) need a declaration to satisfy permit governance.
+   */
+  readonly permits?: Partial<Record<CrudOperation, PermitRequirement>>;
 }
 
-interface InternalCrudBlazeOverrides<TTable extends AnyStoreTable> {
+interface InternalCrudImplementationOverrides<TTable extends AnyStoreTable> {
   readonly create?: Implementation<
     DerivedInput<TTable, 'create'>,
     DerivedOutput<TTable, 'create'>
@@ -178,7 +209,10 @@ interface InternalCrudBlazeOverrides<TTable extends AnyStoreTable> {
 }
 
 interface InternalCrudOptions<TTable extends AnyStoreTable> {
-  readonly blaze?: InternalCrudBlazeOverrides<TTable>;
+  readonly implementation?: InternalCrudImplementationOverrides<TTable>;
+  readonly entity?: TableEntity<TTable>;
+  readonly permit?: PermitRequirement;
+  readonly permits?: Partial<Record<CrudOperation, PermitRequirement>>;
 }
 
 const normalizeExampleForOutput = <TInput, TOutput>(
@@ -222,14 +256,17 @@ const normalizeExamplesForOutput = <TInput, TOutput>(
 const finalizeTrail = <TInput, TOutput>(
   base: Trail<TInput, TOutput>,
   options: {
-    readonly blaze?: Implementation<TInput, TOutput> | undefined;
+    readonly implementation?: Implementation<TInput, TOutput> | undefined;
     readonly output?: z.ZodType<TOutput> | undefined;
     readonly pattern?: string | undefined;
+    readonly permit?: PermitRequirement | undefined;
   } = {}
 ): Trail<TInput, TOutput> =>
   Object.freeze({
     ...base,
-    ...(options.blaze === undefined ? {} : { blaze: options.blaze }),
+    ...(options.implementation === undefined
+      ? {}
+      : { implementation: options.implementation }),
     ...(options.output === undefined
       ? {}
       : {
@@ -237,6 +274,7 @@ const finalizeTrail = <TInput, TOutput>(
           output: options.output,
         }),
     ...(options.pattern === undefined ? {} : { pattern: options.pattern }),
+    ...(options.permit === undefined ? {} : { permit: options.permit }),
   }) as Trail<TInput, TOutput>;
 
 const deriveCrudBaseTrails = <
@@ -244,36 +282,36 @@ const deriveCrudBaseTrails = <
   TConnection extends CrudConnection<TTable>,
 >(
   table: TTable,
-  resource: Resource<TConnection>
+  resource: Resource<TConnection>,
+  tableEntity: TableEntity<TTable>
 ): InternalCrudBaseTrails<TTable> => {
-  const entityContour = createTableContour(table);
-  // Narrow the store's `readonly string[]` to the contour's typed field-key
+  // Narrow the store's `readonly string[]` to the entity's typed field-key
   // array so `deriveTrail`'s `TGenerated` generic picks up the precise
-  // key-of shape that `CreateInputOf<Contour, TGenerated>` expects. The
+  // key-of shape that `CreateInputOf<Entity, TGenerated>` expects. The
   // runtime value is unchanged — the names in `table.generated` are already
   // keys of `table.schema.shape` by construction in `store()`.
   const generated = table.generated as GeneratedFieldsOf<TTable>;
 
   return {
-    createBase: deriveTrail(entityContour, 'create', {
+    createBase: deriveTrail(tableEntity, 'create', {
       generated,
       resource,
     }),
-    deleteBase: deriveTrail(entityContour, 'delete', {
+    deleteBase: deriveTrail(tableEntity, 'delete', {
       resource,
     }),
-    listBase: deriveTrail(entityContour, 'list', {
+    listBase: deriveTrail(tableEntity, 'list', {
       resource,
     }),
-    readBase: deriveTrail(entityContour, 'read', {
+    readBase: deriveTrail(tableEntity, 'read', {
       resource,
     }),
-    // The `update` blaze synthesized by `deriveTrail` handles the partial-patch
+    // The `update` implementation synthesized by `deriveTrail` handles the partial-patch
     // concern: when the accessor lacks a native `update`, the fallback path in
     // `derive-trail.ts` (`updateViaReadAndUpsert`) reads the current entity,
     // merges the patch, strips the `version` field, then calls `upsert` with
     // the full merged payload — so no fields are silently lost.
-    updateBase: deriveTrail(entityContour, 'update', {
+    updateBase: deriveTrail(tableEntity, 'update', {
       generated,
       resource,
     }),
@@ -282,46 +320,67 @@ const deriveCrudBaseTrails = <
 
 const buildCrudTrails = <TTable extends AnyStoreTable>(
   baseTrails: InternalCrudBaseTrails<TTable>,
-  overrides: InternalCrudBlazeOverrides<TTable>,
+  options: InternalCrudOptions<TTable>,
   entityOutput: z.ZodType<DerivedOutput<TTable, 'create'>>,
   listOutput: z.ZodType<DerivedOutput<TTable, 'list'>>
-): InternalCrudTrails<TTable> =>
-  Object.freeze([
+): InternalCrudTrails<TTable> => {
+  const overrides = options.implementation ?? {};
+  const permitFor = (operation: CrudOperation): PermitRequirement | undefined =>
+    options.permits?.[operation] ?? options.permit;
+
+  return Object.freeze([
     finalizeTrail(baseTrails.createBase, {
-      ...(overrides.create === undefined ? {} : { blaze: overrides.create }),
+      ...(overrides.create === undefined
+        ? {}
+        : { implementation: overrides.create }),
       output: entityOutput,
       pattern: 'crud',
+      permit: permitFor('create'),
     }),
     finalizeTrail(baseTrails.readBase, {
-      ...(overrides.read === undefined ? {} : { blaze: overrides.read }),
+      ...(overrides.read === undefined
+        ? {}
+        : { implementation: overrides.read }),
       output: entityOutput,
       pattern: 'crud',
+      permit: permitFor('read'),
     }),
     finalizeTrail(baseTrails.updateBase, {
-      ...(overrides.update === undefined ? {} : { blaze: overrides.update }),
+      ...(overrides.update === undefined
+        ? {}
+        : { implementation: overrides.update }),
       output: entityOutput,
       pattern: 'crud',
+      permit: permitFor('update'),
     }),
     overrides.delete === undefined
-      ? finalizeTrail(baseTrails.deleteBase, { pattern: 'crud' })
+      ? finalizeTrail(baseTrails.deleteBase, {
+          pattern: 'crud',
+          permit: permitFor('delete'),
+        })
       : finalizeTrail(baseTrails.deleteBase, {
-          blaze: overrides.delete,
+          implementation: overrides.delete,
           pattern: 'crud',
+          permit: permitFor('delete'),
         }),
     finalizeTrail(baseTrails.listBase, {
-      ...(overrides.list === undefined ? {} : { blaze: overrides.list }),
+      ...(overrides.list === undefined
+        ? {}
+        : { implementation: overrides.list }),
       output: listOutput,
       pattern: 'crud',
+      permit: permitFor('list'),
     }),
   ]) as InternalCrudTrails<TTable>;
+};
 
 /**
  * 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 backend-agnostic store accessor
+ * The factory derives schemas, examples, resources, and entity linkage from
+ * the table metadata. Implementations 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
+ * implementation overrides stay available for callers that need custom persistence
  * behavior and are layered onto the derived trails in a single pass.
  */
 export function crud<
@@ -340,11 +399,12 @@ export function crud<
   resource: Resource<TConnection>,
   options: InternalCrudOptions<TTable> = {}
 ) {
-  const overrides = options.blaze ?? {};
-  const baseTrails = deriveCrudBaseTrails(table, resource);
+  assertCurrentEntityOption(options, 'crud() options');
+  const tableEntity = options.entity ?? createTableEntity(table);
+  const baseTrails = deriveCrudBaseTrails(table, resource, tableEntity);
   // Narrow `table.schema` (typed `StoreObjectSchema`, which is
   // `z.ZodObject<Record<string, z.ZodType>>`) to a ZodObject keyed by the
-  // concrete shape so its `z.output` unifies with the contour-derived
+  // concrete shape so its `z.output` unifies with the entity-derived
   // output. Structurally `table.schema` already has `shape:
   // TTable['schema']['shape']` — this only refines the generic parameter.
   const entitySchema = table.schema as z.ZodObject<TTable['schema']['shape']>;
@@ -352,5 +412,12 @@ export function crud<
   const listOutput: z.ZodType<DerivedOutput<TTable, 'list'>> =
     entitySchema.array();
 
-  return buildCrudTrails(baseTrails, overrides, entityOutput, listOutput);
+  const trails = buildCrudTrails(baseTrails, options, entityOutput, listOutput);
+  // Expose the registered entity so other factories over the same table
+  // (reconcile, sync) can share the instance instead of rebuilding it.
+  return Object.freeze(
+    Object.assign([...trails], { entity: tableEntity })
+  ) as unknown as InternalCrudTrails<TTable> & {
+    readonly entity: TableEntity<TTable>;
+  };
 }

package/src/trails/index.ts

@@ -4,7 +4,11 @@ export type {
   CrudOperation,
 } from '../crud-doctrine.js';
 export { crud } from './crud.js';
-export type { CrudBlazeOverrides, CrudOptions, CrudTrails } from './crud.js';
+export type {
+  CrudImplementationOverrides,
+  CrudOptions,
+  CrudTrails,
+} from './crud.js';
 export { reconcile } from './reconcile.js';
 export type {
   ReconcileConflict,
@@ -13,3 +17,4 @@ export type {
 } from './reconcile.js';
 export { sync } from './sync.js';
 export type { SyncEndpoint, SyncOptions, SyncTransform } from './sync.js';
+export type { TableEntity } from './utils.js';

package/src/trails/reconcile.ts

@@ -2,6 +2,7 @@ import { ConflictError, Result, ValidationError, trail } from '@ontrails/core';
 import type {
   AnySignal,
   Detour,
+  PermitRequirement,
   Resource,
   Trail,
   TrailContext,
@@ -17,7 +18,12 @@ import type {
   UpsertOf,
 } from '../types.js';
 import { versionFieldName } from '../store.js';
-import { createTableContour, mapStoreTrailError } from './utils.js';
+import {
+  assertCurrentEntityOption,
+  createTableEntity,
+  mapStoreTrailError,
+} from './utils.js';
+import type { TableEntity } from './utils.js';
 
 type ReconcileConnection<TTable extends AnyStoreTable> = Readonly<
   Record<TTable['name'], StoreAccessor<TTable>>
@@ -39,9 +45,19 @@ export interface ReconcileOptions<
   TTable extends AnyStoreTable,
   TConnection extends ReconcileConnection<TTable>,
 > {
+  /**
+   * Existing table entity to register on the reconcile trail. Pass the
+   * entity a `crud()` call over the same table exposes (its `entity`
+   * property) so `topo()` sees one shared instance instead of rejecting
+   * two same-named rebuilds as duplicates. When omitted, the factory
+   * builds its own.
+   */
+  readonly entity?: TableEntity<TTable>;
   readonly description?: string;
   readonly id?: string;
   readonly on?: readonly (AnySignal | string)[];
+  /** Permit requirement declared on the reconcile trail. */
+  readonly permit?: PermitRequirement;
   readonly resource: Resource<TConnection>;
   readonly strategy?: ReconcileStrategy<TTable>;
   readonly table: TTable;
@@ -177,8 +193,8 @@ const buildReconcileInputSchema = <TTable extends AnyStoreTable>(
     [versionFieldName]: z.number().int(),
   }) as unknown as z.ZodType<UpsertOf<TTable>>;
 
-/** The blaze performs only the initial upsert; conflict recovery is handled by the detour. */
-const createReconcileBlaze =
+/** The implementation performs only the initial upsert; conflict recovery is handled by the detour. */
+const createReconcileImplementation =
   <
     TTable extends AnyStoreTable,
     TConnection extends ReconcileConnection<TTable>,
@@ -253,6 +269,7 @@ export const reconcile = <
 >(
   options: ReconcileOptions<TTable, TConnection>
 ): Trail<UpsertOf<TTable>, EntityOf<TTable>> => {
+  assertCurrentEntityOption(options, 'reconcile() options');
   if (!options.table.versioned) {
     throw new ValidationError(
       `reconcile("${options.table.name}") requires a versioned store table.`
@@ -260,22 +277,23 @@ export const reconcile = <
   }
 
   const id = options.id ?? `${options.table.name}.reconcile`;
-  const entityContour = createTableContour(options.table);
+  const tableEntity = options.entity ?? createTableEntity(options.table);
   const strategy = options.strategy ?? 'last-write-wins';
 
   return trail(id, {
-    blaze: createReconcileBlaze(options, id),
-    contours: [entityContour],
     description:
       options.description ??
       `Reconcile version conflicts for "${options.table.name}" entities.`,
     detours: [createReconcileDetour(options, id, strategy)],
+    entities: [tableEntity],
     examples: deriveExamples(options.table),
+    implementation: createReconcileImplementation(options, id),
     input: buildReconcileInputSchema(options.table),
     intent: 'write',
     on: options.on,
     output: options.table.schema as unknown as z.ZodType<EntityOf<TTable>>,
     pattern: 'reconcile',
+    ...(options.permit === undefined ? {} : { permit: options.permit }),
     resources: [options.resource],
   });
 };

package/src/trails/sync.ts

@@ -1,6 +1,7 @@
 import { InternalError, NotFoundError, Result, trail } from '@ontrails/core';
 import type {
   AnySignal,
+  PermitRequirement,
   Resource,
   Trail,
   TrailContext,
@@ -16,7 +17,12 @@ import type {
   StoreIdentifierOf,
   UpsertOf,
 } from '../types.js';
-import { createTableContour, mapStoreTrailError } from './utils.js';
+import {
+  assertCurrentEntityOption,
+  createTableEntity,
+  mapStoreTrailError,
+} from './utils.js';
+import type { TableEntity } from './utils.js';
 
 type IdentityInputOf<TTable extends AnyStoreTable> = Readonly<
   Record<Extract<TTable['identity'], string>, StoreIdentifierOf<TTable>>
@@ -34,6 +40,14 @@ export interface SyncEndpoint<
   TTable extends AnyStoreTable,
   TConnection extends SourceConnection<TTable> | TargetConnection<TTable>,
 > {
+  /**
+   * Existing table entity to register on the produced trail for this
+   * endpoint. Pass the entity a `crud()` bundle over the same table
+   * exposes (its `entity` property) so `topo()` sees one shared
+   * instance instead of rejecting two same-named rebuilds as
+   * duplicates. When omitted, the factory builds one from the table.
+   */
+  readonly entity?: TableEntity<TTable>;
   readonly resource: Resource<TConnection>;
   readonly table: TTable;
 }
@@ -56,6 +70,11 @@ export interface SyncOptions<
   readonly from: SyncEndpoint<TSourceTable, TSourceConnection>;
   readonly id?: string;
   readonly on?: readonly (AnySignal | string)[];
+  /**
+   * Permit requirement declared on the produced trail. Factory trails
+   * carry authored defaults like any hand-written trail.
+   */
+  readonly permit?: PermitRequirement;
   readonly to: SyncEndpoint<TTargetTable, TTargetConnection>;
   readonly transform?: SyncTransform<TSourceTable, TTargetTable>;
 }
@@ -174,22 +193,39 @@ export const sync = <
     TTargetConnection
   >
 ): Trail<IdentityInputOf<TSourceTable>, EntityOf<TTargetTable>> => {
+  assertCurrentEntityOption(options.from, 'sync() from options');
+  assertCurrentEntityOption(options.to, 'sync() to options');
   const id = options.id ?? `${options.to.table.name}.sync`;
-  const sourceContour = createTableContour(options.from.table);
-  const targetContour = createTableContour(options.to.table);
+  const sourceEntity =
+    options.from.entity ?? createTableEntity(options.from.table);
+  const targetEntity = options.to.entity ?? createTableEntity(options.to.table);
 
   return trail(id, {
-    // oxlint-disable-next-line max-statements -- sync blaze reads more clearly as one try/catch with schema validation, transform, and accessor call inline
-    blaze: async (input, ctx) => {
+    description:
+      options.description ??
+      `Sync one "${options.from.table.name}" entity into "${options.to.table.name}".`,
+    entities: [sourceEntity, targetEntity],
+    examples: deriveExamples(
+      options.from.table,
+      options.to.table,
+      options.transform
+    ) as
+      | readonly TrailExample<
+          IdentityInputOf<TSourceTable>,
+          EntityOf<TTargetTable>
+        >[]
+      | undefined,
+    // oxlint-disable-next-line max-statements -- sync implementation reads more clearly as one try/catch with schema validation, transform, and accessor call inline
+    implementation: async (input, ctx) => {
       try {
         const identifier = input[
           options.from.table.identity as keyof typeof input
         ] as StoreIdentifierOf<TSourceTable>;
-        const sourceEntity = await resolveSourceAccessor(options.from, ctx).get(
+        const sourceRecord = await resolveSourceAccessor(options.from, ctx).get(
           identifier
         );
 
-        if (sourceEntity === null) {
+        if (sourceRecord === null) {
           return Result.err(sourceMissingError(options.from.table, identifier));
         }
 
@@ -201,7 +237,7 @@ export const sync = <
         // a mismatched payload.
         const next =
           options.transform === undefined
-            ? options.to.table.fixtureSchema.safeParse(sourceEntity)
+            ? options.to.table.fixtureSchema.safeParse(sourceRecord)
             : undefined;
 
         if (next !== undefined && !next.success) {
@@ -215,7 +251,7 @@ export const sync = <
         const payload =
           options.transform === undefined
             ? (next?.data as unknown as UpsertOf<TTargetTable>)
-            : await options.transform(sourceEntity, ctx);
+            : await options.transform(sourceRecord, ctx);
 
         const synced = await resolveTargetAccessor(options.to, ctx).upsert(
           payload
@@ -225,20 +261,6 @@ export const sync = <
         return Result.err(mapStoreTrailError(id, error));
       }
     },
-    contours: [sourceContour, targetContour],
-    description:
-      options.description ??
-      `Sync one "${options.from.table.name}" entity into "${options.to.table.name}".`,
-    examples: deriveExamples(
-      options.from.table,
-      options.to.table,
-      options.transform
-    ) as
-      | readonly TrailExample<
-          IdentityInputOf<TSourceTable>,
-          EntityOf<TTargetTable>
-        >[]
-      | undefined,
     input: identityInputSchema(options.from.table),
     intent: 'write',
     on: options.on,
@@ -246,6 +268,7 @@ export const sync = <
       EntityOf<TTargetTable>
     >,
     pattern: 'sync',
+    ...(options.permit === undefined ? {} : { permit: options.permit }),
     resources: [options.from.resource, options.to.resource],
   });
 };

package/src/trails/utils.ts

@@ -1,26 +1,31 @@
-import { InternalError, contour, isTrailsError } from '@ontrails/core';
-import type { Contour } from '@ontrails/core';
+import {
+  InternalError,
+  ValidationError,
+  entity,
+  isTrailsError,
+} from '@ontrails/core';
+import type { Entity } from '@ontrails/core';
 import type { z } from 'zod';
 
 import type { AnyStoreTable } from '../types.js';
 
 /**
- * The contour type produced by {@link createTableContour} for a given store
+ * The entity type produced by {@link createTableEntity} for a given store
  * table. Threads the table's name, schema shape, and identity through the
- * contour generics so downstream `deriveTrail()` calls project concrete
+ * entity generics so downstream `deriveTrail()` calls project concrete
  * input/output types instead of widening back to
- * `Contour<string, z.ZodRawShape, string>` (the `AnyContour` alias).
+ * `Entity<string, z.ZodRawShape, string>` (the `AnyEntity` alias).
  */
-export type TableContour<TTable extends AnyStoreTable> = Contour<
+export type TableEntity<TTable extends AnyStoreTable> = Entity<
   TTable['name'],
   TTable['schema']['shape'],
   Extract<TTable['identity'], keyof TTable['schema']['shape'] & string>
 >;
 
 /**
- * Build the shape used when deriving a contour view of a store table.
+ * Build the shape used when deriving an entity view of a store table.
  *
- * Contour validates every example against the shape passed in, so the shape
+ * Entity 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
  * adapter populates them, so we mirror `fixtureSchema`'s treatment of
@@ -30,7 +35,7 @@ export type TableContour<TTable extends AnyStoreTable> = Contour<
  * `table.schema.shape` directly and crashed when a fixture omitted
  * `createdAt` or another generated field.
  */
-export const buildContourShape = (
+export const buildEntityShape = (
   table: AnyStoreTable
 ): Record<string, z.ZodType> => {
   const shape = table.schema.shape as unknown as Record<string, z.ZodType>;
@@ -52,25 +57,41 @@ export const buildContourShape = (
 };
 
 /**
- * Derive a contour view of a store table.
+ * Derive an entity view of a store table.
  *
  * Both `sync` and `reconcile` use this helper so they pick up the
  * fixture-shape treatment (generated fields optional).
  *
  * @remarks
- * Intentionally not cached. `contour()` brands the identity schema via
+ * Intentionally not cached. `entity()` brands the identity schema via
  * `Object.defineProperty(..., { writable: false })`, and re-invoking on a
  * schema that's already been branded throws TypeError. Factory call sites
- * already build the contour once per trail instance, so rebuilding on a
+ * already build the entity once per trail instance, so rebuilding on a
  * warm call is cheap and side-effect-free.
  */
-export const createTableContour = <TTable extends AnyStoreTable>(
+export const createTableEntity = <TTable extends AnyStoreTable>(
   table: TTable
-): TableContour<TTable> =>
-  contour(table.name, buildContourShape(table), {
+): TableEntity<TTable> =>
+  entity(table.name, buildEntityShape(table), {
     examples: table.fixtures as readonly Record<string, unknown>[],
     identity: table.identity,
-  }) as TableContour<TTable>;
+  }) as TableEntity<TTable>;
+
+/** Reject the retired store-factory option instead of silently ignoring it. */
+export const assertCurrentEntityOption = (
+  value: unknown,
+  owner: string
+): void => {
+  if (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.hasOwn(value, 'contour')
+  ) {
+    throw new ValidationError(
+      `${owner} uses retired "contour"; use "entity" instead`
+    );
+  }
+};
 
 /**
  * Coerce an unknown thrown value into an Error instance, preserving the

package/src/types.ts

@@ -70,7 +70,7 @@ type ObjectOutputOf<TShape extends z.ZodRawShape> = z.core.$InferObjectOutput<
  * create/upsert inputs they meet at store/core trail boundaries.
  *
  * This is not the same type-level path core's `deriveTrail()` uses — core
- * still goes through `z.input<TContour>` / `z.output<TContour>` — but at
+ * still goes through `z.input<TEntity>` / `z.output<TEntity>` — but at
  * concrete instantiations it collapses to the same structural fixture shape
  * while preserving generic equality across the store/core seam.
  */
@@ -103,7 +103,7 @@ export type StoreFixtureInput<
  *
  * Mirror of {@link StoreFixtureInput} on the output side — computed through
  * `$InferObjectOutput<TShape, Record<never, never>>` so row types stay
- * structurally aligned with the contour output shapes they compose against.
+ * structurally aligned with the entity output shapes they compose against.
  *
  * As with {@link StoreFixtureInput}, this is a shape-based equivalent rather
  * than the identical `z.output<TSchema>` inference path core uses directly.
@@ -433,7 +433,7 @@ export type GeneratedKeysOf<TTable extends AnyStoreTable> = Extract<
  * this collapses to the same structural shape as
  * `Omit<z.input<TTable['schema']>, GeneratedKeysOf<TTable>>`, but the
  * shape-based form lets TypeScript prove structural equality with
- * `CreateInputOf<Contour, ...>` at trail boundaries without widening
+ * `CreateInputOf<Entity, ...>` at trail boundaries without widening
  * generic call sites to `Record<string, unknown>`.
  *
  * Defaulted fields remain optional because `$InferObjectInput` honors
@@ -532,7 +532,7 @@ export interface StoreAccessor<
 // Compile-time assertion: StoreAccessor satisfies the core accessor protocol.
 //
 // `@ontrails/core/store` declares a structural protocol that `deriveTrail()`
-// uses to synthesize default blazes without importing `@ontrails/store`. We
+// uses to synthesize default implementations without importing `@ontrails/store`. We
 // pin the relationship here rather than in core so that any drift between
 // the two shapes fails the store build immediately. If this check fails, the
 // protocol in core has diverged from the store accessor contract — fix the