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

package/dist/trails/crud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crud.js","sourceRoot":"","sources":["../../src/trails/crud.ts"],"names":[],"mappings":"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"}

package/dist/trails/index.d.ts

@@ -0,0 +1,7 @@
+export { crud } from './crud.js';
+export type { CrudBlazeOverrides, CrudOptions, CrudTrails } from './crud.js';
+export { reconcile } from './reconcile.js';
+export type { ReconcileConflict, ReconcileOptions, ReconcileStrategy, } from './reconcile.js';
+export { sync } from './sync.js';
+export type { SyncEndpoint, SyncOptions, SyncTransform } from './sync.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/trails/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/trails/index.js

@@ -0,0 +1,4 @@
+export { crud } from './crud.js';
+export { reconcile } from './reconcile.js';
+export { sync } from './sync.js';
+//# sourceMappingURL=index.js.map

package/dist/trails/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/trails/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAM3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}

package/dist/trails/reconcile.d.ts

@@ -0,0 +1,36 @@
+import type { AnySignal, Resource, Trail, TrailContext } from '@ontrails/core';
+import type { AnyStoreTable, EntityOf, StoreAccessor, UpsertOf } from '../types.js';
+type ReconcileConnection<TTable extends AnyStoreTable> = Readonly<Record<TTable['name'], StoreAccessor<TTable>>>;
+export interface ReconcileConflict<TTable extends AnyStoreTable> {
+    readonly current: EntityOf<TTable>;
+    readonly incoming: UpsertOf<TTable>;
+}
+export type ReconcileStrategy<TTable extends AnyStoreTable> = 'last-write-wins' | ((conflict: ReconcileConflict<TTable>, ctx: TrailContext) => Promise<UpsertOf<TTable>> | UpsertOf<TTable>);
+export interface ReconcileOptions<TTable extends AnyStoreTable, TConnection extends ReconcileConnection<TTable>> {
+    readonly description?: string;
+    readonly id?: string;
+    readonly on?: readonly (AnySignal | string)[];
+    readonly resource: Resource<TConnection>;
+    readonly strategy?: ReconcileStrategy<TTable>;
+    readonly table: TTable;
+}
+/**
+ * Produce one trail that retries a versioned upsert with a conflict strategy
+ * when the incoming entity is stale.
+ *
+ * Reconcile is bounded to a single retry via a declarative `detour`. If a
+ * concurrent writer races the retry and produces a second `ConflictError`,
+ * the detour loop wraps it in `RetryExhaustedError<ConflictError>` so
+ * callers can distinguish "retry reconcile at a higher level" from
+ * "reconcile tried and lost the race".
+ *
+ * @remarks
+ * 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
+ * shape.
+ */
+export declare const reconcile: <TTable extends AnyStoreTable, TConnection extends ReconcileConnection<TTable>>(options: ReconcileOptions<TTable, TConnection>) => Trail<UpsertOf<TTable>, EntityOf<TTable>>;
+export {};
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/trails/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/trails/reconcile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EAET,QAAQ,EACR,KAAK,EACL,YAAY,EAGb,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,aAAa,EACb,QAAQ,EACT,MAAM,aAAa,CAAC;AAIrB,KAAK,mBAAmB,CAAC,MAAM,SAAS,aAAa,IAAI,QAAQ,CAC/D,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAC9C,CAAC;AAEF,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,aAAa;IAC7D,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,MAAM,iBAAiB,CAAC,MAAM,SAAS,aAAa,IACtD,iBAAiB,GACjB,CAAC,CACC,QAAQ,EAAE,iBAAiB,CAAC,MAAM,CAAC,EACnC,GAAG,EAAE,YAAY,KACd,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAEvD,MAAM,WAAW,gBAAgB,CAC/B,MAAM,SAAS,aAAa,EAC5B,WAAW,SAAS,mBAAmB,CAAC,MAAM,CAAC;IAE/C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAyLD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,GACpB,MAAM,SAAS,aAAa,EAC5B,WAAW,SAAS,mBAAmB,CAAC,MAAM,CAAC,EAE/C,SAAS,gBAAgB,CAAC,MAAM,EAAE,WAAW,CAAC,KAC7C,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CA0B1C,CAAC"}

package/dist/trails/reconcile.js

@@ -0,0 +1,142 @@
+import { ConflictError, Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+import { versionFieldName } from '../store.js';
+import { createTableContour, mapStoreTrailError } from './utils.js';
+const resolveAccessor = (table, resource, ctx) => {
+    const connection = resource.from(ctx);
+    return connection[table.name];
+};
+const omitUndefined = (value) => Object.fromEntries(Object.entries(value).filter(([, candidate]) => candidate !== undefined));
+const currentVersion = (current) => current[versionFieldName];
+const lastWriteWins = (conflict) => ({
+    ...conflict.current,
+    ...omitUndefined(conflict.incoming),
+    [versionFieldName]: currentVersion(conflict.current),
+});
+const normalizeResolvedInput = (table, current, resolved) => ({
+    ...current,
+    ...omitUndefined(resolved),
+    [table.identity]: current[table.identity],
+    [versionFieldName]: currentVersion(current),
+});
+const deriveExamples = (table) => {
+    const examples = table.fixtures.flatMap((fixture) => {
+        const parsed = table.schema.safeParse(fixture);
+        if (!parsed.success) {
+            return [];
+        }
+        return [
+            {
+                expected: parsed.data,
+                input: fixture,
+                name: `Reconcile ${table.name} ${String(fixture[table.identity])}`,
+            },
+        ];
+    });
+    return examples.length === 0 ? undefined : Object.freeze(examples);
+};
+const buildConflict = async (table, input, accessor, error) => {
+    const identifier = input[table.identity];
+    if (identifier === undefined) {
+        return error;
+    }
+    const current = await accessor.get(identifier);
+    return current === null ? error : { current, incoming: input };
+};
+const resolveStrategy = async (strategy, conflict, ctx) => strategy === 'last-write-wins'
+    ? lastWriteWins(conflict)
+    : await strategy(conflict, ctx);
+/** Resolve a version conflict through the configured strategy and retry the upsert. */
+const recoverConflict = async (table, input, accessor, error, strategy, ctx) => {
+    const conflict = await buildConflict(table, input, accessor, error);
+    if (conflict instanceof ConflictError) {
+        return Result.err(conflict);
+    }
+    const resolved = await resolveStrategy(strategy, conflict, ctx);
+    const normalized = normalizeResolvedInput(table, conflict.current, resolved);
+    return Result.ok(await accessor.upsert(normalized));
+};
+/**
+ * Build the input schema for a reconcile trail.
+ *
+ * `fixtureSchema` makes generated fields (including `version` on versioned
+ * tables) optional because connectors 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
+ * callers cannot sidestep optimistic concurrency at the input boundary.
+ */
+const buildReconcileInputSchema = (table) => table.fixtureSchema.extend({
+    [versionFieldName]: z.number().int(),
+});
+/** The blaze performs only the initial upsert; conflict recovery is handled by the detour. */
+const createReconcileBlaze = (options, id) => async (input, ctx) => {
+    try {
+        const accessor = resolveAccessor(options.table, options.resource, ctx);
+        return Result.ok(await accessor.upsert(input));
+    }
+    catch (error) {
+        if (error instanceof ConflictError) {
+            return Result.err(error);
+        }
+        return Result.err(mapStoreTrailError(id, error));
+    }
+};
+/** Build the detour that handles ConflictError recovery via the configured strategy. */
+const createReconcileDetour = (options, id, strategy) => ({
+    maxAttempts: 1,
+    on: ConflictError,
+    recover: async (attempt, ctx) => {
+        const conflictError = attempt.error;
+        try {
+            const accessor = resolveAccessor(options.table, options.resource, ctx);
+            return await recoverConflict(options.table, attempt.input, accessor, conflictError, strategy, ctx);
+        }
+        catch (error) {
+            if (error instanceof ConflictError) {
+                return Result.err(error);
+            }
+            return Result.err(mapStoreTrailError(id, error));
+        }
+    },
+});
+/**
+ * Produce one trail that retries a versioned upsert with a conflict strategy
+ * when the incoming entity is stale.
+ *
+ * Reconcile is bounded to a single retry via a declarative `detour`. If a
+ * concurrent writer races the retry and produces a second `ConflictError`,
+ * the detour loop wraps it in `RetryExhaustedError<ConflictError>` so
+ * callers can distinguish "retry reconcile at a higher level" from
+ * "reconcile tried and lost the race".
+ *
+ * @remarks
+ * 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
+ * shape.
+ */
+export const reconcile = (options) => {
+    if (!options.table.versioned) {
+        throw new ValidationError(`reconcile("${options.table.name}") requires a versioned store table.`);
+    }
+    const id = options.id ?? `${options.table.name}.reconcile`;
+    const entityContour = createTableContour(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)],
+        examples: deriveExamples(options.table),
+        input: buildReconcileInputSchema(options.table),
+        intent: 'write',
+        on: options.on,
+        output: options.table.schema,
+        pattern: 'reconcile',
+        resources: [options.resource],
+    });
+};
+//# sourceMappingURL=reconcile.js.map

package/dist/trails/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../src/trails/reconcile.ts"],"names":[],"mappings":"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"}

package/dist/trails/sync.d.ts

@@ -0,0 +1,25 @@
+import type { AnySignal, Resource, Trail, TrailContext } from '@ontrails/core';
+import type { AnyStoreTable, EntityOf, ReadOnlyStoreTableAccessor, StoreAccessor, StoreIdentifierOf, UpsertOf } from '../types.js';
+type IdentityInputOf<TTable extends AnyStoreTable> = Readonly<Record<Extract<TTable['identity'], string>, StoreIdentifierOf<TTable>>>;
+type SourceConnection<TTable extends AnyStoreTable> = Readonly<Record<TTable['name'], ReadOnlyStoreTableAccessor<TTable>>>;
+type TargetConnection<TTable extends AnyStoreTable> = Readonly<Record<TTable['name'], StoreAccessor<TTable>>>;
+export interface SyncEndpoint<TTable extends AnyStoreTable, TConnection extends SourceConnection<TTable> | TargetConnection<TTable>> {
+    readonly resource: Resource<TConnection>;
+    readonly table: TTable;
+}
+export type SyncTransform<TSourceTable extends AnyStoreTable, TTargetTable extends AnyStoreTable> = (entity: EntityOf<TSourceTable>, ctx: TrailContext) => Promise<UpsertOf<TTargetTable>> | UpsertOf<TTargetTable>;
+export interface SyncOptions<TSourceTable extends AnyStoreTable, TTargetTable extends AnyStoreTable, TSourceConnection extends SourceConnection<TSourceTable>, TTargetConnection extends TargetConnection<TTargetTable>> {
+    readonly description?: string;
+    readonly from: SyncEndpoint<TSourceTable, TSourceConnection>;
+    readonly id?: string;
+    readonly on?: readonly (AnySignal | string)[];
+    readonly to: SyncEndpoint<TTargetTable, TTargetConnection>;
+    readonly transform?: SyncTransform<TSourceTable, TTargetTable>;
+}
+/**
+ * Produce one trail that reads one source entity and writes the transformed
+ * result into a target store resource.
+ */
+export declare const sync: <TSourceTable extends AnyStoreTable, TTargetTable extends AnyStoreTable, TSourceConnection extends SourceConnection<TSourceTable>, TTargetConnection extends TargetConnection<TTargetTable>>(options: SyncOptions<TSourceTable, TTargetTable, TSourceConnection, TTargetConnection>) => Trail<IdentityInputOf<TSourceTable>, EntityOf<TTargetTable>>;
+export {};
+//# sourceMappingURL=sync.d.ts.map

package/dist/trails/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/trails/sync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,QAAQ,EACR,KAAK,EACL,YAAY,EAEb,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,0BAA0B,EAC1B,aAAa,EACb,iBAAiB,EACjB,QAAQ,EACT,MAAM,aAAa,CAAC;AAGrB,KAAK,eAAe,CAAC,MAAM,SAAS,aAAa,IAAI,QAAQ,CAC3D,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC,CACvE,CAAC;AAEF,KAAK,gBAAgB,CAAC,MAAM,SAAS,aAAa,IAAI,QAAQ,CAC5D,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAC3D,CAAC;AAEF,KAAK,gBAAgB,CAAC,MAAM,SAAS,aAAa,IAAI,QAAQ,CAC5D,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAC9C,CAAC;AAEF,MAAM,WAAW,YAAY,CAC3B,MAAM,SAAS,aAAa,EAC5B,WAAW,SAAS,gBAAgB,CAAC,MAAM,CAAC,GAAG,gBAAgB,CAAC,MAAM,CAAC;IAEvE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,aAAa,CACvB,YAAY,SAAS,aAAa,EAClC,YAAY,SAAS,aAAa,IAChC,CACF,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,GAAG,EAAE,YAAY,KACd,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;AAE9D,MAAM,WAAW,WAAW,CAC1B,YAAY,SAAS,aAAa,EAClC,YAAY,SAAS,aAAa,EAClC,iBAAiB,SAAS,gBAAgB,CAAC,YAAY,CAAC,EACxD,iBAAiB,SAAS,gBAAgB,CAAC,YAAY,CAAC;IAExD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;IAC7D,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC;IAC9C,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;CAChE;AAmGD;;;GAGG;AACH,eAAO,MAAM,IAAI,GACf,YAAY,SAAS,aAAa,EAClC,YAAY,SAAS,aAAa,EAClC,iBAAiB,SAAS,gBAAgB,CAAC,YAAY,CAAC,EACxD,iBAAiB,SAAS,gBAAgB,CAAC,YAAY,CAAC,EAExD,SAAS,WAAW,CAClB,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,CAClB,KACA,KAAK,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CA2E7D,CAAC"}

package/dist/trails/sync.js

@@ -0,0 +1,96 @@
+import { InternalError, NotFoundError, Result, trail } from '@ontrails/core';
+import { createTableContour, mapStoreTrailError } from './utils.js';
+const resolveSourceAccessor = (endpoint, ctx) => {
+    const connection = endpoint.resource.from(ctx);
+    return connection[endpoint.table.name];
+};
+const resolveTargetAccessor = (endpoint, ctx) => {
+    const connection = endpoint.resource.from(ctx);
+    return connection[endpoint.table.name];
+};
+const sourceMissingError = (table, id) => new NotFoundError(`Store table "${table.name}" could not find source entity "${String(id)}"`);
+const identityInputSchema = (table) => table.schema.pick({
+    [table.identity]: true,
+});
+const deriveExamples = (sourceTable, targetTable, transform) => {
+    const targetById = new Map();
+    for (const fixture of targetTable.fixtures) {
+        const id = fixture[targetTable.identity];
+        if (id !== undefined) {
+            targetById.set(id, fixture);
+        }
+    }
+    const examples = sourceTable.fixtures.flatMap((fixture) => {
+        const id = fixture[sourceTable.identity];
+        if (id === undefined) {
+            return [];
+        }
+        const targetFixture = targetById.get(id) ??
+            (transform === undefined && targetTable.schema.safeParse(fixture).success
+                ? fixture
+                : undefined);
+        if (targetFixture === undefined) {
+            return [];
+        }
+        return [
+            {
+                expected: targetFixture,
+                input: { [sourceTable.identity]: id },
+                name: `Sync ${targetTable.name} ${String(id)}`,
+            },
+        ];
+    });
+    return examples.length === 0 ? undefined : Object.freeze(examples);
+};
+/**
+ * Produce one trail that reads one source entity and writes the transformed
+ * result into a target store resource.
+ */
+export const sync = (options) => {
+    const id = options.id ?? `${options.to.table.name}.sync`;
+    const sourceContour = createTableContour(options.from.table);
+    const targetContour = 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
+        blaze: async (input, ctx) => {
+            try {
+                const identifier = input[options.from.table.identity];
+                const sourceEntity = await resolveSourceAccessor(options.from, ctx).get(identifier);
+                if (sourceEntity === null) {
+                    return Result.err(sourceMissingError(options.from.table, identifier));
+                }
+                // No-transform path: the source entity is upserted directly into
+                // the target table. The generic signature does not require the two
+                // tables to be structurally compatible, so validate `next` against
+                // the target table's fixture schema at runtime. This catches
+                // accidentally omitted transforms before the underlying store sees
+                // a mismatched payload.
+                const next = options.transform === undefined
+                    ? options.to.table.fixtureSchema.safeParse(sourceEntity)
+                    : undefined;
+                if (next !== undefined && !next.success) {
+                    return Result.err(new InternalError(`${id} produced an invalid target entity: ${next.error.message}`));
+                }
+                const payload = options.transform === undefined
+                    ? next?.data
+                    : await options.transform(sourceEntity, ctx);
+                const synced = await resolveTargetAccessor(options.to, ctx).upsert(payload);
+                return Result.ok(synced);
+            }
+            catch (error) {
+                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),
+        input: identityInputSchema(options.from.table),
+        intent: 'write',
+        on: options.on,
+        output: options.to.table.schema,
+        pattern: 'sync',
+        resources: [options.from.resource, options.to.resource],
+    });
+};
+//# sourceMappingURL=sync.js.map

package/dist/trails/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../src/trails/sync.ts"],"names":[],"mappings":"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"}

package/dist/trails/utils.d.ts

@@ -0,0 +1,51 @@
+import type { Contour } 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
+ * table. Threads the table's name, schema shape, and identity through the
+ * contour generics so downstream `deriveTrail()` calls project concrete
+ * input/output types instead of widening back to
+ * `Contour<string, z.ZodRawShape, string>` (the `AnyContour` alias).
+ */
+export type TableContour<TTable extends AnyStoreTable> = Contour<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.
+ *
+ * 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
+ * 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
+ * `table.schema.shape` directly and crashed when a fixture omitted
+ * `createdAt` or another generated field.
+ */
+export declare const buildContourShape: (table: AnyStoreTable) => Record<string, z.ZodType>;
+/**
+ * Derive a contour 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
+ * `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
+ * warm call is cheap and side-effect-free.
+ */
+export declare const createTableContour: <TTable extends AnyStoreTable>(table: TTable) => TableContour<TTable>;
+/**
+ * Coerce an unknown thrown value into an Error instance, preserving the
+ * original when possible.
+ */
+export declare const asError: (error: unknown) => Error;
+/**
+ * Map a caught error into a `TrailsError` suitable for surfacing from a store
+ * trail factory. Pass-through for errors already in the taxonomy; otherwise
+ * wrap in an `InternalError` keyed by the trail id.
+ */
+export declare const mapStoreTrailError: (trailId: string, error: unknown) => Error;
+//# sourceMappingURL=utils.d.ts.map

package/dist/trails/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/trails/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,aAAa,IAAI,OAAO,CAC9D,MAAM,CAAC,MAAM,CAAC,EACd,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACzB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,CACtE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,aAAa,KACnB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAiB1B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,SAAS,aAAa,EAC7D,OAAO,MAAM,KACZ,YAAY,CAAC,MAAM,CAIM,CAAC;AAE7B;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,KACkB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,EAAE,OAAO,OAAO,KAAG,KASpE,CAAC"}

package/dist/trails/utils.js

@@ -0,0 +1,65 @@
+import { InternalError, contour, isTrailsError } from '@ontrails/core';
+/**
+ * Build the shape used when deriving a contour view of a store table.
+ *
+ * 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
+ * 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
+ * `table.schema.shape` directly and crashed when a fixture omitted
+ * `createdAt` or another generated field.
+ */
+export const buildContourShape = (table) => {
+    const shape = table.schema.shape;
+    const generatedNonIdentity = new Set(table.generated.filter((field) => field !== table.identity));
+    if (generatedNonIdentity.size === 0) {
+        return shape;
+    }
+    const next = {};
+    for (const [field, fieldSchema] of Object.entries(shape)) {
+        next[field] = generatedNonIdentity.has(field)
+            ? fieldSchema.optional()
+            : fieldSchema;
+    }
+    return next;
+};
+/**
+ * Derive a contour 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
+ * `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
+ * warm call is cheap and side-effect-free.
+ */
+export const createTableContour = (table) => contour(table.name, buildContourShape(table), {
+    examples: table.fixtures,
+    identity: table.identity,
+});
+/**
+ * Coerce an unknown thrown value into an Error instance, preserving the
+ * original when possible.
+ */
+export const asError = (error) => error instanceof Error ? error : new Error(String(error));
+/**
+ * Map a caught error into a `TrailsError` suitable for surfacing from a store
+ * trail factory. Pass-through for errors already in the taxonomy; otherwise
+ * wrap in an `InternalError` keyed by the trail id.
+ */
+export const mapStoreTrailError = (trailId, error) => {
+    if (isTrailsError(error)) {
+        return error;
+    }
+    const resolved = asError(error);
+    return new InternalError(`${trailId} failed: ${resolved.message}`, {
+        cause: resolved,
+    });
+};
+//# sourceMappingURL=utils.js.map

package/dist/trails/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/trails/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAmBvE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,KAAoB,EACO,EAAE;IAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,KAA6C,CAAC;IACzE,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAClC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,KAAK,CAAC,QAAQ,CAAC,CAC5D,CAAC;IAEF,IAAI,oBAAoB,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAA8B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,IAAI,CAAC,KAAK,CAAC,GAAG,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC;YAC3C,CAAC,CAAC,WAAW,CAAC,QAAQ,EAAE;YACxB,CAAC,CAAC,WAAW,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAa,EACS,EAAE,CACxB,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE;IAC5C,QAAQ,EAAE,KAAK,CAAC,QAA8C;IAC9D,QAAQ,EAAE,KAAK,CAAC,QAAQ;CACzB,CAAyB,CAAC;AAE7B;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAc,EAAS,EAAE,CAC/C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAe,EAAE,KAAc,EAAS,EAAE;IAC3E,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,OAAO,IAAI,aAAa,CAAC,GAAG,OAAO,YAAY,QAAQ,CAAC,OAAO,EAAE,EAAE;QACjE,KAAK,EAAE,QAAQ;KAChB,CAAC,CAAC;AACL,CAAC,CAAC"}