@ontrails/core 1.0.0-beta.4 → 1.0.0-beta.41

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

@@ -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/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

@@ -1,18 +1,66 @@
-import type { TrailContext } 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();
+
+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)
- * - `signal` defaults to a fresh, non-aborted `AbortSignal`
+ * - `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<TrailContext>
-): TrailContext => ({
-  cwd: process.cwd(),
-  env: process.env as Record<string, string | undefined>,
-  requestId: Bun.randomUUIDv7(),
-  signal: new AbortController().signal,
-  ...overrides,
-});
+  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;
+};