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

package/src/activation-source.ts

@@ -0,0 +1,91 @@
+import type { z } from 'zod';
+
+import type { AnySignal } from './signal.js';
+
+export const activationSourceKinds = Object.freeze([
+  'signal',
+  'schedule',
+  'webhook',
+] as const);
+
+export type BuiltinActivationSourceKind =
+  (typeof activationSourceKinds)[number];
+
+export type ActivationSourceKind = string;
+
+export type ActivationSourceMeta = Readonly<Record<string, unknown>>;
+
+export type ActivationSourceParse<TPayload = unknown> =
+  | z.ZodType<TPayload>
+  | {
+      readonly output?: z.ZodType<TPayload> | undefined;
+    };
+
+export interface ActivationSource {
+  readonly id: string;
+  readonly kind: ActivationSourceKind;
+  readonly cron?: string | undefined;
+  readonly input?: unknown;
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly method?: string | undefined;
+  readonly parse?: ActivationSourceParse | undefined;
+  readonly path?: string | undefined;
+  readonly payload?: z.ZodType<unknown> | undefined;
+  readonly timezone?: string | undefined;
+  readonly verify?: unknown;
+}
+
+export interface ActivationWhereExample {
+  readonly input?: unknown;
+  readonly on: boolean;
+  readonly payload?: unknown;
+}
+
+/* oxlint-disable no-explicit-any -- contextual predicate authoring needs source-specific payload inference; unknown would make inline predicates unusable until a helper API exists. */
+export type ActivationWherePredicate<TPayload = any> = (
+  payload: TPayload
+) => boolean | Promise<boolean>;
+
+export interface ActivationWhere<TPayload = any> {
+  readonly examples?: readonly ActivationWhereExample[] | undefined;
+  readonly predicate: ActivationWherePredicate<TPayload>;
+}
+
+export type ActivationWhereSpec<TPayload = any> =
+  | ActivationWhere<TPayload>
+  | ActivationWherePredicate<TPayload>;
+
+export type ActivationSourceRef = string | AnySignal | ActivationSource;
+
+export interface ActivationEntrySpec {
+  readonly source: ActivationSourceRef;
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly where?: ActivationWhereSpec | undefined;
+}
+
+export interface ActivationEntry {
+  readonly source: ActivationSource;
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly where?: ActivationWhereSpec | undefined;
+}
+
+export const getActivationWherePredicate = (
+  where: ActivationWhereSpec | undefined
+): ActivationWherePredicate | undefined =>
+  typeof where === 'function' ? where : where?.predicate;
+
+export const isKnownActivationSourceKind = (
+  kind: string
+): kind is BuiltinActivationSourceKind =>
+  (activationSourceKinds as readonly string[]).includes(kind);
+
+export const isActivationEntrySpec = (
+  value: unknown
+): value is ActivationEntrySpec =>
+  typeof value === 'object' && value !== null && 'source' in value;
+
+export const isActivationSource = (value: unknown): value is ActivationSource =>
+  typeof value === 'object' &&
+  value !== null &&
+  'id' in value &&
+  'kind' in value;

package/src/blob-ref.ts

@@ -2,6 +2,11 @@
  * BlobRef — a frozen reference to binary data for @ontrails/core.
  */
 
+import { z } from 'zod';
+
+/** Metadata key used to recognize BlobRef schemas during JSON Schema projection. */
+export const BLOB_REF_SCHEMA_META_KEY = 'ontrails/blob-ref';
+
 /** Immutable reference to a blob of binary data. */
 export interface BlobRef {
   readonly name: string;
@@ -10,6 +15,37 @@ export interface BlobRef {
   readonly data: Uint8Array | ReadableStream<Uint8Array>;
 }
 
+/** Schema-projected metadata for a BlobRef value. */
+export interface BlobRefDescriptor {
+  readonly kind: 'blob';
+  readonly mimeType: string;
+  readonly name: string;
+  readonly size: number;
+  readonly uri: string;
+}
+
+/** Public descriptor schema emitted to transport clients instead of raw bytes. */
+export const blobRefDescriptorSchema = z.object({
+  kind: z.literal('blob'),
+  mimeType: z.string(),
+  name: z.string(),
+  size: z.number(),
+  uri: z.string(),
+});
+
+/** Canonical JSON Schema for BlobRef descriptors across derived surfaces. */
+export const blobRefJsonSchema = Object.freeze({
+  properties: Object.freeze({
+    kind: Object.freeze({ const: 'blob' }),
+    mimeType: Object.freeze({ type: 'string' }),
+    name: Object.freeze({ type: 'string' }),
+    size: Object.freeze({ type: 'number' }),
+    uri: Object.freeze({ type: 'string' }),
+  }),
+  required: Object.freeze(['kind', 'mimeType', 'name', 'size', 'uri']),
+  type: 'object',
+});
+
 /** Creates a frozen BlobRef. */
 export const createBlobRef = (options: {
   name: string;
@@ -37,3 +73,18 @@ export const isBlobRef = (value: unknown): value is BlobRef => {
     (obj['data'] instanceof Uint8Array || obj['data'] instanceof ReadableStream)
   );
 };
+
+/** Zod schema for runtime BlobRef values with metadata for descriptor projection. */
+export const blobRefSchema = z
+  .custom<BlobRef>(isBlobRef, { error: 'Expected BlobRef' })
+  .meta({ [BLOB_REF_SCHEMA_META_KEY]: true });
+
+/** Convert a runtime BlobRef into its schema-aware transport descriptor. */
+export const toBlobRefDescriptor = (blob: BlobRef): BlobRefDescriptor =>
+  Object.freeze({
+    kind: 'blob',
+    mimeType: blob.mimeType,
+    name: blob.name,
+    size: blob.size,
+    uri: `blob://${blob.name}`,
+  });

package/src/branded.ts

@@ -120,7 +120,7 @@ export const shortId = (length = 8): string => {
  * Produce a deterministic hex hash from an input string.
  * Uses a simple FNV-1a 32-bit hash — good enough for non-cryptographic IDs.
  */
-export const hashId = (input: string): string => {
+export const deriveIdHash = (input: string): string => {
   // FNV offset basis
   let hash = 2_166_136_261;
   for (let i = 0; i < input.length; i += 1) {

package/src/context.ts

@@ -1,10 +1,26 @@
-import { createProvisionLookup } from './provision.js';
-import type { TrailContext, TrailContextInit } from './types.js';
+import { createResourceLookup } from './resource.js';
+import type { TrailContext, TrailContextInit, TraceFn } from './types.js';
 
 type MutableTrailContext = {
   -readonly [K in keyof TrailContext]: TrailContext[K];
 };
 
+/**
+ * Default passthrough `trace` used when a context is built outside
+ * `executeTrail`. `executeTrail` replaces this with a real sink-writing
+ * implementation. The passthrough runs `fn` without recording anything so
+ * direct `createTrailContext()` callers (tests, ad-hoc compositions) don't
+ * crash when invoking `ctx.trace(...)`.
+ *
+ * Declared `async` so both synchronous throws and async rejections from `fn`
+ * propagate as a rejected promise to the caller — matching the real
+ * sink-writing implementation's error semantics.
+ */
+export const passthroughTrace: TraceFn = async <T>(
+  _label: string,
+  fn: () => T | Promise<T>
+): Promise<T> => await fn();
+
 /**
  * Create a TrailContext with sensible defaults.
  *
@@ -18,11 +34,19 @@ export const createTrailContext = (
   const ctx = {
     abortSignal: new AbortController().signal,
     cwd: process.cwd(),
+    dryRun: false,
     env: process.env as Record<string, string | undefined>,
     requestId: Bun.randomUUIDv7(),
+    trace: passthroughTrace,
     ...overrides,
   } as MutableTrailContext;
-  const lookup = overrides?.provision ?? createProvisionLookup(() => ctx);
-  ctx.provision = lookup;
+  const lookup = overrides?.resource ?? createResourceLookup(() => ctx);
+  ctx.resource = lookup;
+  if (ctx.trace === undefined) {
+    ctx.trace = passthroughTrace;
+  }
+  if (ctx.dryRun === undefined) {
+    ctx.dryRun = false;
+  }
   return ctx;
 };

package/src/contour.ts

@@ -0,0 +1,344 @@
+import { z } from 'zod';
+
+import type { Branded } from './branded.js';
+
+/**
+ * Runtime options for a contour declaration.
+ */
+export interface ContourOptions<
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+> {
+  /** Field name that acts as the contour's primary identity. */
+  readonly identity: TIdentity;
+  /** Example instances validated against the contour schema at declaration time. */
+  readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+}
+
+/** Type-level brand name applied to a contour's identity schema. */
+export type ContourIdBrand<TName extends string> = `${Capitalize<TName>}Id`;
+
+type BrandedSchema<
+  TSchema extends z.core.$ZodType,
+  TBrand extends string,
+> = TSchema & z.ZodType<Branded<z.output<TSchema>, TBrand>>;
+
+type BrandableSchema<TSchema extends z.core.$ZodType> = TSchema & {
+  brand<TBrand extends string>(): BrandedSchema<TSchema, TBrand>;
+};
+
+/** Output value of a branded contour identity schema. */
+export type ContourIdValue<
+  TSchema extends z.core.$ZodType,
+  TName extends string,
+> = Branded<z.output<TSchema>, ContourIdBrand<TName>>;
+
+/** Runtime metadata attached to schemas returned from `contour.id()`. */
+export interface ContourIdMetadata<
+  TName extends string = string,
+  TIdentity extends string = string,
+> {
+  readonly contour: TName;
+  readonly identity: TIdentity;
+}
+
+/** A structural contour reference declared by another contour field schema. */
+export interface ContourReference<
+  TName extends string = string,
+  TIdentity extends string = string,
+> extends ContourIdMetadata<TName, TIdentity> {
+  readonly field: string;
+}
+
+/** Symbol used to tag branded contour reference schemas at runtime. */
+export const CONTOUR_ID_METADATA = Symbol.for('@ontrails/core/contour-id');
+
+/**
+ * Module-level WeakMap storing contour identity metadata keyed by schema object.
+ *
+ * First-write-wins: when multiple contours share the same underlying schema
+ * (e.g. `contour('admin', { id: user.shape.id }, ...)`), the first contour to
+ * brand the schema claims it. Subsequent calls skip the write to prevent
+ * silent metadata corruption.
+ */
+const contourIdMetadata = new WeakMap<object, ContourIdMetadata>();
+
+/**
+ * A contour identity schema branded for one contour and tagged with runtime
+ * metadata so the topo layer can recognize declared references later on.
+ */
+export type ContourIdSchema<
+  TSchema extends z.core.$ZodType = z.core.$ZodType,
+  TName extends string = string,
+  TIdentity extends string = string,
+> = BrandedSchema<TSchema, ContourIdBrand<TName>> & {
+  /** @deprecated Use `getContourIdMetadata()` — metadata lives in a WeakMap, not on the schema. */
+  readonly [CONTOUR_ID_METADATA]?: ContourIdMetadata<TName, TIdentity>;
+};
+
+/**
+ * A first-class domain object with schema, identity metadata, and examples.
+ *
+ * A contour behaves like the `ZodObject` it wraps, so standard Zod composition
+ * helpers such as `.pick()`, `.extend()`, and `.array()` continue to work.
+ */
+export type Contour<
+  TName extends string = string,
+  TShape extends z.ZodRawShape = z.ZodRawShape,
+  TIdentity extends keyof TShape & string = keyof TShape & string,
+> = z.ZodObject<TShape> & {
+  readonly kind: 'contour';
+  readonly name: TName;
+  readonly identity: TIdentity;
+  readonly identitySchema: TShape[TIdentity];
+  readonly id: () => ContourIdSchema<TShape[TIdentity], TName, TIdentity>;
+  readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+};
+
+const formatExampleIssues = (issues: readonly z.core.$ZodIssue[]): string =>
+  issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+      return `${path}: ${issue.message}`;
+    })
+    .join('; ');
+
+const assertIdentityField = <
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  name: string,
+  shape: TShape,
+  identity: TIdentity
+): void => {
+  if (!Object.hasOwn(shape, identity)) {
+    throw new TypeError(
+      `contour("${name}") identity "${identity}" must match a declared field`
+    );
+  }
+};
+
+const assertExamples = <TShape extends z.ZodRawShape>(
+  name: string,
+  schema: z.ZodObject<TShape>,
+  examples: readonly z.output<z.ZodObject<TShape>>[]
+): void => {
+  for (const [index, example] of examples.entries()) {
+    const parsed = schema.safeParse(example);
+    if (!parsed.success) {
+      throw new TypeError(
+        `contour("${name}") example ${index} is invalid: ${formatExampleIssues(parsed.error.issues)}`
+      );
+    }
+  }
+};
+
+const validateExamples = <TShape extends z.ZodRawShape>(
+  name: string,
+  schema: z.ZodObject<TShape>,
+  examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined
+): void => {
+  if (examples) {
+    assertExamples(name, schema, examples);
+  }
+};
+
+const brandIdentitySchema = <
+  TSchema extends z.core.$ZodType,
+  TName extends string,
+  TIdentity extends string,
+>(
+  contour: TName,
+  identity: TIdentity,
+  schema: TSchema
+): ContourIdSchema<TSchema, TName, TIdentity> => {
+  const branded = (schema as BrandableSchema<TSchema>).brand<
+    ContourIdBrand<TName>
+  >();
+
+  // First-write-wins: if another contour already claimed this schema object
+  // (possible when Zod v4 brand() returns `this`), preserve the original
+  // metadata rather than silently overwriting it.
+  if (!contourIdMetadata.has(branded)) {
+    contourIdMetadata.set(branded, {
+      contour,
+      identity,
+    } satisfies ContourIdMetadata<TName, TIdentity>);
+  }
+
+  return branded as ContourIdSchema<TSchema, TName, TIdentity>;
+};
+
+const attachContourMetadata = <
+  TName extends string,
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  schema: z.ZodObject<TShape>,
+  metadata: {
+    readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+    readonly idSchema: ContourIdSchema<TShape[TIdentity], TName, TIdentity>;
+    readonly identity: TIdentity;
+    readonly identitySchema: TShape[TIdentity];
+    readonly name: TName;
+  }
+): void => {
+  Object.defineProperties(schema, {
+    examples: {
+      enumerable: true,
+      value: metadata.examples,
+      writable: false,
+    },
+    id: {
+      enumerable: true,
+      value: () => metadata.idSchema,
+      writable: false,
+    },
+    identity: {
+      enumerable: true,
+      value: metadata.identity,
+      writable: false,
+    },
+    identitySchema: {
+      enumerable: true,
+      value: metadata.identitySchema,
+      writable: false,
+    },
+    kind: {
+      enumerable: true,
+      value: 'contour',
+      writable: false,
+    },
+    name: {
+      enumerable: true,
+      value: metadata.name,
+      writable: false,
+    },
+  });
+};
+
+/** Read contour identity metadata from the module-level WeakMap, if present. */
+const readMetadata = (schema: unknown): ContourIdMetadata | undefined =>
+  typeof schema === 'object' && schema !== null
+    ? contourIdMetadata.get(schema)
+    : undefined;
+
+/** Resolve the inner schema from a Zod wrapper (ZodOptional, ZodNullable, etc.). */
+const unwrapInner = (schema: unknown): unknown => {
+  const def = (schema as { _def?: Record<string, unknown> })._def;
+  return (def?.['innerType'] ?? def?.['schema']) as unknown;
+};
+
+/**
+ * Walk through Zod wrapper layers searching for `CONTOUR_ID_METADATA`.
+ *
+ * `.nullish()` produces `ZodOptional<ZodNullable<T>>` — two wrapper levels —
+ * so a single-step unwrap is insufficient. This iterates until it finds the
+ * metadata or exhausts all wrapper layers.
+ */
+const unwrapToMetadata = (schema: unknown): ContourIdMetadata | undefined => {
+  let current: unknown = schema;
+  while (typeof current === 'object' && current !== null) {
+    const inner = unwrapInner(current);
+    if (typeof inner !== 'object' || inner === null) {
+      return undefined;
+    }
+    const metadata = readMetadata(inner);
+    if (metadata !== undefined) {
+      return metadata;
+    }
+    current = inner;
+  }
+  return undefined;
+};
+
+/**
+ * Read contour-reference metadata from a schema returned by `contour.id()`.
+ *
+ * When the schema is wrapped by Zod combinators (`.optional()`, `.nullable()`,
+ * `.default()`, `.nullish()`, etc.) the `CONTOUR_ID_METADATA` symbol lives on
+ * the inner schema, not on the wrapper. The unwrap handles arbitrarily nested
+ * wrapper levels.
+ */
+export const getContourIdMetadata = (
+  schema: unknown
+): ContourIdMetadata | undefined =>
+  readMetadata(schema) ?? unwrapToMetadata(schema);
+
+/** Inspect a contour schema for fields that reference other contours via `.id()`. */
+export const getContourReferences = (
+  contour: AnyContour
+): readonly ContourReference[] =>
+  Object.entries(contour.shape)
+    .flatMap(([field, schema]) => {
+      if (field === contour.identity) {
+        return [];
+      }
+      const metadata = getContourIdMetadata(schema);
+      if (metadata === undefined) {
+        return [];
+      }
+
+      return [{ field, ...metadata }];
+    })
+    .toSorted((left, right) =>
+      left.field === right.field
+        ? left.contour.localeCompare(right.contour)
+        : left.field.localeCompare(right.field)
+    );
+
+/**
+ * Create a contour definition from a raw Zod object shape.
+ *
+ * @example
+ * ```typescript
+ * const user = contour(
+ *   'user',
+ *   {
+ *     id: z.string().uuid(),
+ *     email: z.string().email(),
+ *     name: z.string(),
+ *   },
+ *   { identity: 'id' }
+ * );
+ * ```
+ */
+export const contour = <
+  TName extends string,
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  name: TName,
+  shape: TShape,
+  options: ContourOptions<TShape, TIdentity>
+): Contour<TName, TShape, TIdentity> => {
+  assertIdentityField(name, shape, options.identity);
+
+  const schema = z.object(shape);
+  validateExamples(name, schema, options.examples);
+
+  const identitySchema = shape[options.identity];
+  if (!identitySchema) {
+    throw new TypeError(
+      `contour("${name}") identity "${options.identity}" must resolve to a schema`
+    );
+  }
+
+  const idSchema = brandIdentitySchema(name, options.identity, identitySchema);
+  const examples = options.examples
+    ? Object.freeze([...options.examples])
+    : undefined;
+
+  attachContourMetadata(schema, {
+    examples,
+    idSchema,
+    identity: options.identity,
+    identitySchema,
+    name,
+  });
+
+  return schema as Contour<TName, TShape, TIdentity>;
+};
+
+/** Existential type for heterogeneous contour collections. */
+export type AnyContour = Contour<string, z.ZodRawShape, string>;

package/src/cross-batch.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared helpers for `ctx.cross([...])` batch execution.
+ *
+ * These helpers normalize batch options, produce validation results, and
+ * implement the unlimited/limited worker-pool execution strategies used by
+ * both the real executor (`packages/core/src/execute.ts`) and the scenario
+ * runner in `@ontrails/testing`. Extracting them here keeps the validation
+ * rule, error message, and worker-pool semantics authored in one place so
+ * the two call sites cannot drift.
+ */
+
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { CrossBatchOptions } from './types.js';
+
+/**
+ * Validate the `concurrency` option on a batch `ctx.cross()` call.
+ *
+ * Returns `Ok(undefined)` when no limit is requested, `Ok(n)` when a
+ * positive integer is supplied, and `Err(ValidationError)` for any other
+ * value. The error message is load-bearing: callers and tests depend on
+ * the exact string.
+ */
+export const normalizeCrossBatchConcurrency = (
+  options: CrossBatchOptions | undefined
+): Result<number | undefined, Error> => {
+  const concurrency = options?.concurrency;
+  if (concurrency === undefined) {
+    return Result.ok();
+  }
+
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    return Result.err(
+      new ValidationError(
+        'ctx.cross() batch concurrency must be a positive integer'
+      )
+    );
+  }
+
+  return Result.ok(concurrency);
+};
+
+/**
+ * Produce one validation-error result per call, preserving the original
+ * call order. Used when `normalizeCrossBatchConcurrency` fails so the caller
+ * can surface a uniform batch shape to the trail implementation.
+ */
+export const createCrossBatchValidationResults = <TCall>(
+  calls: readonly TCall[],
+  error: Error
+): Result<unknown, Error>[] => calls.map(() => Result.err(error));
+
+/**
+ * Claim the next branch index from a shared counter. Safe to call from
+ * multiple worker coroutines because JavaScript is single-threaded between
+ * awaits — the read/increment pair runs without interleaving.
+ */
+export const claimNextCrossBatchIndex = <TCall>(
+  nextIndex: { value: number },
+  calls: readonly TCall[]
+): number | undefined => {
+  if (nextIndex.value >= calls.length) {
+    return undefined;
+  }
+
+  const branchIndex = nextIndex.value;
+  nextIndex.value += 1;
+  return branchIndex;
+};

package/src/cross-schema.ts

@@ -0,0 +1,36 @@
+/**
+ * Cross-invocation schema merging for trails with `crossInput`.
+ *
+ * When a trail declares `crossInput`, callers via `ctx.cross()` pass both
+ * public input and composition-only fields. The merged schema validates the
+ * combined shape so `executeTrail` doesn't reject the extra fields.
+ */
+
+import { z } from 'zod';
+
+import type { AnyTrail } from './trail.js';
+
+/**
+ * Build the validation schema for a cross-invoked trail.
+ *
+ * When the target trail declares `crossInput`, returns the intersection of
+ * `trail.input` and `trail.crossInput`. Returns `undefined` when no
+ * `crossInput` is declared, signaling that normal input validation suffices.
+ */
+export const buildCrossValidationSchema = (
+  trailDef: AnyTrail
+): z.ZodType | undefined => {
+  if (!trailDef.crossInput) {
+    return undefined;
+  }
+  // Prefer .merge() for ZodObject pairs — produces a proper merged object
+  // schema that strips unknown keys and exposes .shape. Fall back to
+  // z.intersection for non-object schemas.
+  if (
+    trailDef.input instanceof z.ZodObject &&
+    trailDef.crossInput instanceof z.ZodObject
+  ) {
+    return trailDef.input.merge(trailDef.crossInput);
+  }
+  return z.intersection(trailDef.input, trailDef.crossInput);
+};

package/src/detours.ts

@@ -0,0 +1,8 @@
+/**
+ * Hard upper bound for detour recovery attempts.
+ *
+ * Execution and derived surface/topo projections both clamp declared detour
+ * attempts to this value so runtime behavior and inspectable contracts stay in
+ * lockstep.
+ */
+export const DETOUR_MAX_ATTEMPTS_CAP = 5;