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

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @ontrails/store
 
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/store",
-  "version": "1.0.0-beta.32",
+  "version": "1.0.0-beta.39",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -26,7 +26,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.32"
+    "@ontrails/core": "^1.0.0-beta.39"
   },
   "peerDependencies": {
     "zod": "^4.3.5"

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,
@@ -137,7 +142,15 @@ export type CrudTrails<TTable extends AnyStoreTable> = readonly [
   update: UpdateTrailOf<TTable>,
   remove: DeleteTrailOf<TTable>,
   list: ListTrailOf<TTable>,
-];
+] & {
+  /**
+   * The table contour the factory registered on its trails. Pass it to
+   * `reconcile({ contour })` (or other factories over the same table) so
+   * the topo sees one shared contour instance instead of rejecting two
+   * same-named rebuilds as duplicates.
+   */
+  readonly contour: TableContour<TTable>;
+};
 
 export interface CrudBlazeOverrides<TTable extends AnyStoreTable> {
   readonly create?: Implementation<InsertOf<TTable>, EntityOf<TTable>>;
@@ -152,6 +165,24 @@ export interface CrudBlazeOverrides<TTable extends AnyStoreTable> {
 
 export interface CrudOptions<TTable extends AnyStoreTable> {
   readonly blaze?: CrudBlazeOverrides<TTable>;
+  /**
+   * Existing table contour 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 contour registration.
+   */
+  readonly contour?: TableContour<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> {
@@ -179,6 +210,9 @@ interface InternalCrudBlazeOverrides<TTable extends AnyStoreTable> {
 
 interface InternalCrudOptions<TTable extends AnyStoreTable> {
   readonly blaze?: InternalCrudBlazeOverrides<TTable>;
+  readonly contour?: TableContour<TTable>;
+  readonly permit?: PermitRequirement;
+  readonly permits?: Partial<Record<CrudOperation, PermitRequirement>>;
 }
 
 const normalizeExampleForOutput = <TInput, TOutput>(
@@ -225,6 +259,7 @@ const finalizeTrail = <TInput, TOutput>(
     readonly blaze?: Implementation<TInput, TOutput> | undefined;
     readonly output?: z.ZodType<TOutput> | undefined;
     readonly pattern?: string | undefined;
+    readonly permit?: PermitRequirement | undefined;
   } = {}
 ): Trail<TInput, TOutput> =>
   Object.freeze({
@@ -237,6 +272,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,9 +280,9 @@ const deriveCrudBaseTrails = <
   TConnection extends CrudConnection<TTable>,
 >(
   table: TTable,
-  resource: Resource<TConnection>
+  resource: Resource<TConnection>,
+  entityContour: TableContour<TTable>
 ): InternalCrudBaseTrails<TTable> => {
-  const entityContour = createTableContour(table);
   // Narrow the store's `readonly string[]` to the contour's typed field-key
   // array so `deriveTrail`'s `TGenerated` generic picks up the precise
   // key-of shape that `CreateInputOf<Contour, TGenerated>` expects. The
@@ -282,38 +318,51 @@ 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.blaze ?? {};
+  const permitFor = (operation: CrudOperation): PermitRequirement | undefined =>
+    options.permits?.[operation] ?? options.permit;
+
+  return Object.freeze([
     finalizeTrail(baseTrails.createBase, {
       ...(overrides.create === undefined ? {} : { blaze: overrides.create }),
       output: entityOutput,
       pattern: 'crud',
+      permit: permitFor('create'),
     }),
     finalizeTrail(baseTrails.readBase, {
       ...(overrides.read === undefined ? {} : { blaze: overrides.read }),
       output: entityOutput,
       pattern: 'crud',
+      permit: permitFor('read'),
     }),
     finalizeTrail(baseTrails.updateBase, {
       ...(overrides.update === undefined ? {} : { blaze: 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,
           pattern: 'crud',
+          permit: permitFor('delete'),
         }),
     finalizeTrail(baseTrails.listBase, {
       ...(overrides.list === undefined ? {} : { blaze: overrides.list }),
       output: listOutput,
       pattern: 'crud',
+      permit: permitFor('list'),
     }),
   ]) as InternalCrudTrails<TTable>;
+};
 
 /**
  * Produce the standard CRUD trail tuple for one normalized store table.
@@ -340,8 +389,8 @@ export function crud<
   resource: Resource<TConnection>,
   options: InternalCrudOptions<TTable> = {}
 ) {
-  const overrides = options.blaze ?? {};
-  const baseTrails = deriveCrudBaseTrails(table, resource);
+  const entityContour = options.contour ?? createTableContour(table);
+  const baseTrails = deriveCrudBaseTrails(table, resource, entityContour);
   // 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
@@ -352,5 +401,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 contour so other factories over the same table
+  // (reconcile, sync) can share the instance instead of rebuilding it.
+  return Object.freeze(
+    Object.assign([...trails], { contour: entityContour })
+  ) as unknown as InternalCrudTrails<TTable> & {
+    readonly contour: TableContour<TTable>;
+  };
 }

package/src/trails/index.ts

@@ -13,3 +13,4 @@ export type {
 } from './reconcile.js';
 export { sync } from './sync.js';
 export type { SyncEndpoint, SyncOptions, SyncTransform } from './sync.js';
+export type { TableContour } 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,
@@ -18,6 +19,7 @@ import type {
 } from '../types.js';
 import { versionFieldName } from '../store.js';
 import { createTableContour, mapStoreTrailError } from './utils.js';
+import type { TableContour } from './utils.js';
 
 type ReconcileConnection<TTable extends AnyStoreTable> = Readonly<
   Record<TTable['name'], StoreAccessor<TTable>>
@@ -39,9 +41,19 @@ export interface ReconcileOptions<
   TTable extends AnyStoreTable,
   TConnection extends ReconcileConnection<TTable>,
 > {
+  /**
+   * Existing table contour to register on the reconcile trail. Pass the
+   * contour a `crud()` call over the same table exposes (its `contour`
+   * property) so `topo()` sees one shared instance instead of rejecting
+   * two same-named rebuilds as duplicates. When omitted, the factory
+   * builds its own.
+   */
+  readonly contour?: TableContour<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;
@@ -260,7 +272,7 @@ export const reconcile = <
   }
 
   const id = options.id ?? `${options.table.name}.reconcile`;
-  const entityContour = createTableContour(options.table);
+  const entityContour = options.contour ?? createTableContour(options.table);
   const strategy = options.strategy ?? 'last-write-wins';
 
   return trail(id, {
@@ -276,6 +288,7 @@ export const reconcile = <
     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,
@@ -17,6 +18,7 @@ import type {
   UpsertOf,
 } from '../types.js';
 import { createTableContour, mapStoreTrailError } from './utils.js';
+import type { TableContour } from './utils.js';
 
 type IdentityInputOf<TTable extends AnyStoreTable> = Readonly<
   Record<Extract<TTable['identity'], string>, StoreIdentifierOf<TTable>>
@@ -34,6 +36,14 @@ export interface SyncEndpoint<
   TTable extends AnyStoreTable,
   TConnection extends SourceConnection<TTable> | TargetConnection<TTable>,
 > {
+  /**
+   * Existing table contour to register on the produced trail for this
+   * endpoint. Pass the contour a `crud()` bundle over the same table
+   * exposes (its `contour` 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 contour?: TableContour<TTable>;
   readonly resource: Resource<TConnection>;
   readonly table: TTable;
 }
@@ -56,6 +66,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>;
 }
@@ -175,8 +190,10 @@ export const sync = <
   >
 ): Trail<IdentityInputOf<TSourceTable>, EntityOf<TTargetTable>> => {
   const id = options.id ?? `${options.to.table.name}.sync`;
-  const sourceContour = createTableContour(options.from.table);
-  const targetContour = createTableContour(options.to.table);
+  const sourceContour =
+    options.from.contour ?? createTableContour(options.from.table);
+  const targetContour =
+    options.to.contour ?? createTableContour(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
@@ -246,6 +263,7 @@ export const sync = <
       EntityOf<TTargetTable>
     >,
     pattern: 'sync',
+    ...(options.permit === undefined ? {} : { permit: options.permit }),
     resources: [options.from.resource, options.to.resource],
   });
 };