@ontrails/core 1.0.0-beta.3 → 1.0.0-beta.30

package/src/activation-source-projection.ts

@@ -0,0 +1,221 @@
+import type { ActivationSource } from './activation-source.js';
+import { zodToJsonSchema } from './validation.js';
+
+type ZodSchemaInput = Parameters<typeof zodToJsonSchema>[0];
+
+export type ActivationSourceProjection = Readonly<Record<string, unknown>> & {
+  readonly id: string;
+  readonly key: string;
+  readonly kind: string;
+};
+
+export const activationSourceKey = (
+  source: Pick<ActivationSource, 'id' | 'kind'>
+): string => `${source.kind}:${source.id}`;
+
+const sortKeys = <T extends Record<string, unknown>>(value: T): T => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    sorted[key] = value[key];
+  }
+  return sorted as T;
+};
+
+const deepSortKeys = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(deepSortKeys);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = deepSortKeys((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+const canonicalLeaf = (value: unknown): unknown => {
+  switch (typeof value) {
+    case 'bigint': {
+      return value.toString();
+    }
+    case 'function': {
+      return `[Function:${value.name || 'anonymous'}]`;
+    }
+    case 'symbol': {
+      return `[Symbol:${value.description ?? ''}]`;
+    }
+    case 'undefined': {
+      return '[Undefined]';
+    }
+    default: {
+      return value;
+    }
+  }
+};
+
+const canonicalObject = (
+  value: Record<string, unknown>,
+  visit: (value: unknown) => unknown
+): Record<string, unknown> => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    const next = value[key];
+    sorted[key] = next === undefined ? '[Undefined]' : visit(next);
+  }
+  return sorted;
+};
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof RegExp) {
+    return value.toString();
+  }
+  if (value !== null && typeof value === 'object') {
+    return canonicalObject(value as Record<string, unknown>, canonicalize);
+  }
+  return canonicalLeaf(value);
+};
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isZodSchema = (value: unknown): value is ZodSchemaInput =>
+  isObjectRecord(value) &&
+  typeof value['safeParse'] === 'function' &&
+  isObjectRecord(value['_zod']);
+
+const toSortedJsonSchema = (
+  schema: ZodSchemaInput
+): Readonly<Record<string, unknown>> =>
+  deepSortKeys(zodToJsonSchema(schema)) as Readonly<Record<string, unknown>>;
+
+const parseOutputSchema = (
+  source: ActivationSource
+): ZodSchemaInput | undefined => {
+  if (isZodSchema(source.parse)) {
+    return source.parse;
+  }
+  if (isObjectRecord(source.parse) && isZodSchema(source.parse['output'])) {
+    return source.parse['output'];
+  }
+  return undefined;
+};
+
+const normalizeWebhookMethod = (method: string | undefined): string =>
+  (method ?? 'POST').trim().toUpperCase();
+
+const normalizeWebhookPath = (path: string): string => path.trim();
+
+export const projectActivationSourceDeclaration = (
+  source: ActivationSource
+): ActivationSourceProjection => {
+  const record: Record<string, unknown> = {
+    id: source.id,
+    key: activationSourceKey(source),
+    kind: source.kind,
+  };
+
+  if (source.cron !== undefined) {
+    record['cron'] = source.cron;
+  }
+  if (Object.hasOwn(source, 'input')) {
+    if (isZodSchema(source.input)) {
+      record['inputSchema'] = toSortedJsonSchema(source.input);
+    } else {
+      record['input'] = canonicalize(source.input);
+    }
+  }
+  if (source.meta !== undefined) {
+    record['meta'] = canonicalize(source.meta);
+  }
+  if (source.kind === 'webhook') {
+    record['method'] = normalizeWebhookMethod(source.method);
+  } else if (source.method !== undefined) {
+    record['method'] = source.method;
+  }
+  if (source.parse !== undefined) {
+    record['hasParse'] = true;
+    const output = parseOutputSchema(source);
+    if (output !== undefined) {
+      record['parseOutputSchema'] = toSortedJsonSchema(output);
+    }
+  }
+  if (source.path !== undefined) {
+    record['path'] =
+      source.kind === 'webhook'
+        ? normalizeWebhookPath(source.path)
+        : source.path;
+  }
+  if (source.payload !== undefined) {
+    record['hasPayloadSchema'] = true;
+    if (isZodSchema(source.payload)) {
+      record['payloadSchema'] = toSortedJsonSchema(source.payload);
+    }
+  }
+  if (source.timezone !== undefined) {
+    record['timezone'] = source.timezone;
+  }
+  if (source.verify !== undefined) {
+    record['hasVerify'] = true;
+  }
+
+  return sortKeys(record) as ActivationSourceProjection;
+};
+
+/**
+ * Identifies the verifier function attached to an activation source, when one
+ * exists. Two declarations sharing the same id/method/path/parse but different
+ * `verify` references must be treated as conflicting source options. The
+ * returned token captures the function's reference identity so it changes when
+ * the verifier function changes.
+ *
+ * The token is intentionally kept out of {@link projectActivationSourceDeclaration}
+ * so that the persisted topo-store projection remains stable and free of
+ * nondeterministic function identity. Use this only for in-memory comparisons
+ * (validation, conflict detection).
+ */
+const verifierIds = new WeakMap<object, number>();
+let verifierIdCounter = 0;
+
+const verifierIdToken = (verify: object): string => {
+  const existing = verifierIds.get(verify);
+  if (existing !== undefined) {
+    return `verify#${existing}`;
+  }
+  verifierIdCounter += 1;
+  verifierIds.set(verify, verifierIdCounter);
+  return `verify#${verifierIdCounter}`;
+};
+
+const verifierIdentityToken = (
+  source: ActivationSource
+): string | undefined => {
+  if (source.kind !== 'webhook') {
+    return undefined;
+  }
+  const { verify } = source as { readonly verify?: unknown };
+  if (typeof verify !== 'function') {
+    return undefined;
+  }
+  // Use a per-process WeakMap-backed counter so two different function
+  // references produce different tokens, even if they share a name.
+  return verifierIdToken(verify);
+};
+
+export const activationSourceDeclarationSignature = (
+  source: ActivationSource
+): string => {
+  const projection = projectActivationSourceDeclaration(source);
+  const verifyToken = verifierIdentityToken(source);
+  if (verifyToken === undefined) {
+    return JSON.stringify(projection);
+  }
+  return JSON.stringify({ projection, verify: verifyToken });
+};

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/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 blaze.
+ */
+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,52 @@
-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();
 
 /**
  * Create a TrailContext with sensible defaults.
  *
  * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID)
- * - `signal` defaults to a fresh, non-aborted `AbortSignal`
+ * - `abortSignal` defaults to a fresh, non-aborted `AbortSignal`
  * - 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: process.cwd(),
+    dryRun: false,
+    env: process.env as Record<string, string | undefined>,
+    requestId: Bun.randomUUIDv7(),
+    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;
+};