@ontrails/core 0.2.0

package/src/activation-source.ts

@@ -0,0 +1,93 @@
+import type { z } from 'zod';
+
+import type { AnySignal } from './signal.js';
+
+export const activationSourceKinds = Object.freeze([
+  'queue',
+  '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 queue?: string | 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

@@ -0,0 +1,90 @@
+/**
+ * BlobRef — a frozen reference to binary data for @ontrails/core.
+ */
+
+import { z } from 'zod';
+
+/** Metadata key used to recognize BlobRef schemas during JSON Schema derivation. */
+export const BLOB_REF_SCHEMA_META_KEY = 'ontrails/blob-ref';
+
+/** Immutable reference to a blob of binary data. */
+export interface BlobRef {
+  readonly name: string;
+  readonly mimeType: string;
+  readonly size: number;
+  readonly data: Uint8Array | ReadableStream<Uint8Array>;
+}
+
+/** Schema-derived 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;
+  mimeType: string;
+  size: number;
+  data: Uint8Array | ReadableStream<Uint8Array>;
+}): BlobRef =>
+  Object.freeze({
+    data: options.data,
+    mimeType: options.mimeType,
+    name: options.name,
+    size: options.size,
+  });
+
+/** Type guard for BlobRef-shaped values. */
+export const isBlobRef = (value: unknown): value is BlobRef => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj['name'] === 'string' &&
+    typeof obj['mimeType'] === 'string' &&
+    typeof obj['size'] === 'number' &&
+    (obj['data'] instanceof Uint8Array || obj['data'] instanceof ReadableStream)
+  );
+};
+
+/** Zod schema for runtime BlobRef values with metadata for descriptor derivation. */
+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

@@ -0,0 +1,135 @@
+/**
+ * Branded types and validated constructors for @ontrails/core.
+ *
+ * Branded types enforce domain constraints at the type level while remaining
+ * plain primitives at runtime. Factory functions return Result so callers
+ * handle validation failures explicitly.
+ */
+
+import { ValidationError } from './errors.js';
+import type { Result } from './result.js';
+import { Result as R } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Branding primitive
+// ---------------------------------------------------------------------------
+
+/** Attach a phantom tag to a base type. */
+export type Branded<T, Tag extends string> = T & { readonly __brand: Tag };
+
+/** Brand a value. No validation — use factory functions for safe construction. */
+export const brand = <T, Tag extends string>(
+  _tag: Tag,
+  value: T
+): Branded<T, Tag> => value as Branded<T, Tag>;
+
+/** Strip the brand and recover the underlying value. */
+export const unbrand = <T>(value: Branded<T, string>): T => value as T;
+
+// ---------------------------------------------------------------------------
+// Built-in branded types
+// ---------------------------------------------------------------------------
+
+export type UUID = Branded<string, 'UUID'>;
+export type Email = Branded<string, 'Email'>;
+export type NonEmptyString = Branded<string, 'NonEmptyString'>;
+export type PositiveInt = Branded<number, 'PositiveInt'>;
+
+// ---------------------------------------------------------------------------
+// Validation patterns
+// ---------------------------------------------------------------------------
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// ---------------------------------------------------------------------------
+// Factory functions — each returns Result<BrandedType, ValidationError>
+// ---------------------------------------------------------------------------
+
+export const uuid = (value: string): Result<UUID, ValidationError> => {
+  if (!UUID_RE.test(value)) {
+    return R.err(
+      new ValidationError(`Invalid UUID: "${value}"`, {
+        context: { value },
+      })
+    );
+  }
+  return R.ok(value as UUID);
+};
+
+export const email = (value: string): Result<Email, ValidationError> => {
+  if (!EMAIL_RE.test(value)) {
+    return R.err(
+      new ValidationError(`Invalid email: "${value}"`, {
+        context: { value },
+      })
+    );
+  }
+  return R.ok(value as Email);
+};
+
+export const nonEmptyString = (
+  value: string
+): Result<NonEmptyString, ValidationError> => {
+  if (value.length === 0) {
+    return R.err(new ValidationError('String must not be empty'));
+  }
+  return R.ok(value as NonEmptyString);
+};
+
+export const positiveInt = (
+  value: number
+): Result<PositiveInt, ValidationError> => {
+  if (!Number.isInteger(value) || value <= 0) {
+    return R.err(
+      new ValidationError(`Expected positive integer, got ${value}`, {
+        context: { value },
+      })
+    );
+  }
+  return R.ok(value as PositiveInt);
+};
+
+// ---------------------------------------------------------------------------
+// ID utilities
+// ---------------------------------------------------------------------------
+
+const ALPHANUMERIC =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+/**
+ * Generate a random alphanumeric ID.
+ * Runtime-agnostic: uses `crypto.getRandomValues`.
+ */
+export const shortId = (length = 8): string => {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  let id = '';
+  for (let i = 0; i < length; i += 1) {
+    const byte = bytes[i];
+    if (byte !== undefined) {
+      id += ALPHANUMERIC[byte % ALPHANUMERIC.length];
+    }
+  }
+  return id;
+};
+
+/**
+ * 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 deriveIdHash = (input: string): string => {
+  // FNV offset basis
+  let hash = 2_166_136_261;
+  for (let i = 0; i < input.length; i += 1) {
+    // oxlint-disable-next-line no-bitwise -- FNV-1a hash requires XOR
+    hash ^= input.codePointAt(i) ?? 0;
+    // FNV prime
+    hash = Math.imul(hash, 0x01_00_01_93);
+  }
+  // Convert to unsigned 32-bit then hex
+  // oxlint-disable-next-line no-bitwise, prefer-math-trunc -- unsigned right shift needed for u32 conversion (Math.trunc differs semantically)
+  return (hash >>> 0).toString(16).padStart(8, '0');
+};

package/src/collections.ts

@@ -0,0 +1,99 @@
+/**
+ * Collection utilities and type helpers for @ontrails/core.
+ */
+
+// ---------------------------------------------------------------------------
+// Type utilities
+// ---------------------------------------------------------------------------
+
+/** Recursively make every property optional. */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/** Flatten an intersection into a single object type for better IDE display. */
+// oxlint-disable-next-line ban-types -- `& {}` is a standard TypeScript idiom to force type expansion in IDE tooltips
+export type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Require at least one property from T. */
+export type AtLeastOne<T> = {
+  [K in keyof T]-?: Pick<T, K> & Partial<Omit<T, K>>;
+}[keyof T];
+
+/** A tuple with at least one element. */
+export type NonEmptyArray<T> = [T, ...T[]];
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+/** Narrows a readonly array to a NonEmptyArray. */
+export const isNonEmptyArray = <T>(
+  array: readonly T[]
+): array is NonEmptyArray<T> => array.length > 0;
+
+// ---------------------------------------------------------------------------
+// Collection functions
+// ---------------------------------------------------------------------------
+
+/** Split an array into chunks of at most `size` elements. */
+export const chunk = <T>(array: readonly T[], size: number): T[][] => {
+  if (size < 1) {
+    throw new RangeError('chunk size must be >= 1');
+  }
+  const result: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    result.push(array.slice(i, i + size));
+  }
+  return result;
+};
+
+/**
+ * Remove duplicate items. When `key` is provided, uniqueness is determined
+ * by the return value of the key function; otherwise strict equality is used.
+ */
+export const dedupe = <T>(
+  array: readonly T[],
+  key?: (item: T) => unknown
+): T[] => {
+  if (!key) {
+    return [...new Set(array)];
+  }
+  const seen = new Set<unknown>();
+  const result: T[] = [];
+  for (const item of array) {
+    const k = key(item);
+    if (!seen.has(k)) {
+      seen.add(k);
+      result.push(item);
+    }
+  }
+  return result;
+};
+
+/** Group items by a string key. */
+export const groupBy = <T>(
+  array: readonly T[],
+  key: (item: T) => string
+): Record<string, T[]> => {
+  const groups: Record<string, T[]> = {};
+  for (const item of array) {
+    const k = key(item);
+    (groups[k] ??= []).push(item);
+  }
+  return groups;
+};
+
+/** Return a new sorted array based on a key function (ascending). */
+export const sortBy = <T>(
+  array: readonly T[],
+  key: (item: T) => string | number
+): T[] =>
+  [...array].toSorted((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    if (typeof ka === 'number' && typeof kb === 'number') {
+      return ka - kb;
+    }
+    return String(ka).localeCompare(String(kb));
+  });

package/src/compose-batch.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared helpers for `ctx.compose([...])` 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 { ComposeBatchOptions } from './types.js';
+
+/**
+ * Validate the `concurrency` option on a batch `ctx.compose()` 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 normalizeComposeBatchConcurrency = (
+  options: ComposeBatchOptions | 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.compose() 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 `normalizeComposeBatchConcurrency` fails so the caller
+ * can surface a uniform batch shape to the implementation.
+ */
+export const createComposeBatchValidationResults = <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 claimNextComposeBatchIndex = <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/compose-schema.ts

@@ -0,0 +1,36 @@
+/**
+ * Compose-invocation schema merging for trails with `composeInput`.
+ *
+ * When a trail declares `composeInput`, callers via `ctx.compose()` 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 compose-invoked trail.
+ *
+ * When the target trail declares `composeInput`, returns the intersection of
+ * `trail.input` and `trail.composeInput`. Returns `undefined` when no
+ * `composeInput` is declared, signaling that normal input validation suffices.
+ */
+export const buildComposeValidationSchema = (
+  trailDef: AnyTrail
+): z.ZodType | undefined => {
+  if (!trailDef.composeInput) {
+    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.composeInput instanceof z.ZodObject
+  ) {
+    return trailDef.input.merge(trailDef.composeInput);
+  }
+  return z.intersection(trailDef.input, trailDef.composeInput);
+};

package/src/context.ts

@@ -0,0 +1,66 @@
+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();
+
+const defaultCwd = (): string =>
+  typeof process === 'undefined' ? '/' : process.cwd();
+
+const defaultEnv = (): Record<string, string | undefined> =>
+  typeof process === 'undefined'
+    ? {}
+    : (process.env as Record<string, string | undefined>);
+
+const defaultRequestId = (): string =>
+  typeof Bun === 'undefined' ? crypto.randomUUID() : Bun.randomUUIDv7();
+
+/**
+ * Create a TrailContext with sensible defaults.
+ *
+ * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID), falling
+ *   back to `crypto.randomUUID()` on runtimes without the `Bun` global
+ * - `abortSignal` defaults to a fresh, non-aborted `AbortSignal`
+ * - `cwd`/`env` default to the `process` globals when available, and to
+ *   `'/'`/`{}` on runtimes without `process` (for example Cloudflare Workers)
+ * - All other fields come from `overrides`
+ */
+export const createTrailContext = (
+  overrides?: Partial<TrailContextInit>
+): TrailContext => {
+  const ctx = {
+    abortSignal: new AbortController().signal,
+    cwd: defaultCwd(),
+    dryRun: false,
+    env: defaultEnv(),
+    requestId: defaultRequestId(),
+    trace: passthroughTrace,
+    ...overrides,
+  } as MutableTrailContext;
+  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;
+};