@ontrails/core 1.0.0-beta.15 → 1.0.0-beta.17

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/context.ts

@@ -34,6 +34,7 @@ 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,
@@ -44,5 +45,8 @@ export const createTrailContext = (
   if (ctx.trace === undefined) {
     ctx.trace = passthroughTrace;
   }
+  if (ctx.dryRun === undefined) {
+    ctx.dryRun = false;
+  }
   return ctx;
 };

package/src/{internal/cross-batch.ts → cross-batch.ts}

@@ -7,13 +7,11 @@
  * 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.
- *
- * @internal
  */
 
-import { ValidationError } from '../errors.js';
-import { Result } from '../result.js';
-import type { CrossBatchOptions } from '../types.js';
+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.
@@ -22,8 +20,6 @@ import type { CrossBatchOptions } from '../types.js';
  * 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.
- *
- * @internal
  */
 export const normalizeCrossBatchConcurrency = (
   options: CrossBatchOptions | undefined
@@ -48,8 +44,6 @@ export const normalizeCrossBatchConcurrency = (
  * 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.
- *
- * @internal
  */
 export const createCrossBatchValidationResults = <TCall>(
   calls: readonly TCall[],
@@ -60,8 +54,6 @@ export const createCrossBatchValidationResults = <TCall>(
  * 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.
- *
- * @internal
  */
 export const claimNextCrossBatchIndex = <TCall>(
   nextIndex: { value: number },

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;

package/src/draft.ts

@@ -15,6 +15,8 @@ export type DraftDependencyKind =
   | 'resource'
   | 'replaced-by'
   | 'schema-reference'
+  | 'signal-fire'
+  | 'signal-on'
   | 'signal-from';
 
 export interface DraftDependency {
@@ -92,6 +94,8 @@ const trailDependencies = (trail: AnyTrail): DraftDependency[] => [
     trail.resources.map(({ id }) => id),
     'resource'
   ),
+  ...dependenciesFromIds(trail.id, trail.fires ?? [], 'signal-fire'),
+  ...dependenciesFromIds(trail.id, trail.on ?? [], 'signal-on'),
   ...dependencyFromTarget(trail.id, replacedByTarget(trail), 'replaced-by'),
 ];
 

package/src/error-projection.ts

@@ -0,0 +1,51 @@
+import type { ErrorCategory } from './errors.js';
+import { isTrailsError } from './errors.js';
+import { createRedactor } from './redaction/index.js';
+
+const errorRedactor = createRedactor();
+
+export const INTERNAL_ERROR_PUBLIC_MESSAGE = 'Internal server error';
+
+export interface ErrorDiagnosticsProjection {
+  readonly category?: ErrorCategory | undefined;
+  readonly context?: Record<string, unknown> | undefined;
+  readonly message: string;
+  readonly name: string;
+  readonly retryable?: boolean | undefined;
+  readonly stack?: string | undefined;
+}
+
+export const redactErrorString = (value: string): string =>
+  errorRedactor.redact(value);
+
+export const redactErrorContext = (
+  context: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined =>
+  context === undefined ? undefined : errorRedactor.redactObject(context);
+
+export const redactErrorStack = (
+  stack: string | undefined
+): string | undefined =>
+  stack === undefined ? undefined : redactErrorString(stack);
+
+export const projectErrorDiagnostics = (
+  error: Error
+): ErrorDiagnosticsProjection => {
+  const context = isTrailsError(error)
+    ? redactErrorContext(error.context)
+    : undefined;
+  const stack = redactErrorStack(error.stack);
+
+  return {
+    ...(isTrailsError(error)
+      ? {
+          category: error.category,
+          retryable: error.retryable,
+        }
+      : {}),
+    ...(context === undefined ? {} : { context }),
+    message: redactErrorString(error.message),
+    name: error.name || error.constructor.name || 'Error',
+    ...(stack === undefined ? {} : { stack }),
+  };
+};

package/src/errors.ts

@@ -83,6 +83,16 @@ export class PermissionError extends TrailsError {
   readonly retryable = false as const;
 }
 
+export class PermitError extends PermissionError {
+  constructor(
+    message: string,
+    options?: { cause?: Error; context?: Record<string, unknown> }
+  ) {
+    super(message, options);
+    this.name = 'PermitError';
+  }
+}
+
 export class TimeoutError extends TrailsError {
   readonly category = 'timeout' as const;
   readonly retryable = true as const;
@@ -121,6 +131,8 @@ export class DerivationError extends TrailsError {
   readonly retryable = false as const;
 }
 
+export class RecoverableCompletionError extends InternalError {}
+
 export class AuthError extends TrailsError {
   readonly category = 'auth' as const;
   readonly retryable = false as const;
@@ -134,7 +146,7 @@ export class CancelledError extends TrailsError {
 /**
  * Returned when a detour exhausts all recovery attempts.
  *
- * Inherits the wrapped error's category for trailhead mapping (e.g. a
+ * Inherits the wrapped error's category for surface mapping (e.g. a
  * `RetryExhaustedError<ConflictError>` maps to HTTP 409), but always
  * sets `retryable = false` to prevent amplification across `ctx.cross()`
  * boundaries or stacked layers.
@@ -167,48 +179,189 @@ export class RetryExhaustedError<
   }
 }
 
+// ---------------------------------------------------------------------------
+// Class registry
+// ---------------------------------------------------------------------------
+
+export type ErrorClassConstructor = new (...args: never[]) => TrailsError;
+
+export interface FixedErrorClassRegistryEntry {
+  readonly category: ErrorCategory;
+  readonly ctor: ErrorClassConstructor;
+  readonly name: string;
+  readonly retryable: boolean;
+}
+
+export interface DynamicErrorClassRegistryEntry {
+  readonly category: 'dynamic';
+  readonly ctor: ErrorClassConstructor;
+  readonly inheritsCategoryFrom: 'wrapped-error';
+  readonly name: string;
+  readonly retryable: false;
+}
+
+export type ErrorClassRegistryEntry =
+  | DynamicErrorClassRegistryEntry
+  | FixedErrorClassRegistryEntry;
+
+/**
+ * Authored registry of concrete TrailsError classes.
+ *
+ * JavaScript cannot enumerate subclasses at runtime, so rule and projection
+ * tooling should walk this owner-held list instead of hardcoding parallel
+ * class-name tables. `RetryExhaustedError` is marked dynamic because it
+ * inherits its runtime category from the wrapped error rather than always
+ * mapping as `internal`.
+ */
+export const errorClasses = [
+  {
+    category: 'validation',
+    ctor: ValidationError,
+    name: 'ValidationError',
+    retryable: false,
+  },
+  {
+    category: 'validation',
+    ctor: AmbiguousError,
+    name: 'AmbiguousError',
+    retryable: false,
+  },
+  {
+    category: 'internal',
+    ctor: AssertionError,
+    name: 'AssertionError',
+    retryable: false,
+  },
+  {
+    category: 'not_found',
+    ctor: NotFoundError,
+    name: 'NotFoundError',
+    retryable: false,
+  },
+  {
+    category: 'conflict',
+    ctor: AlreadyExistsError,
+    name: 'AlreadyExistsError',
+    retryable: false,
+  },
+  {
+    category: 'conflict',
+    ctor: ConflictError,
+    name: 'ConflictError',
+    retryable: false,
+  },
+  {
+    category: 'permission',
+    ctor: PermissionError,
+    name: 'PermissionError',
+    retryable: false,
+  },
+  {
+    category: 'permission',
+    ctor: PermitError,
+    name: 'PermitError',
+    retryable: false,
+  },
+  {
+    category: 'timeout',
+    ctor: TimeoutError,
+    name: 'TimeoutError',
+    retryable: true,
+  },
+  {
+    category: 'rate_limit',
+    ctor: RateLimitError,
+    name: 'RateLimitError',
+    retryable: true,
+  },
+  {
+    category: 'network',
+    ctor: NetworkError,
+    name: 'NetworkError',
+    retryable: true,
+  },
+  {
+    category: 'internal',
+    ctor: InternalError,
+    name: 'InternalError',
+    retryable: false,
+  },
+  {
+    category: 'internal',
+    ctor: DerivationError,
+    name: 'DerivationError',
+    retryable: false,
+  },
+  {
+    category: 'internal',
+    ctor: RecoverableCompletionError,
+    name: 'RecoverableCompletionError',
+    retryable: false,
+  },
+  { category: 'auth', ctor: AuthError, name: 'AuthError', retryable: false },
+  {
+    category: 'cancelled',
+    ctor: CancelledError,
+    name: 'CancelledError',
+    retryable: false,
+  },
+  {
+    category: 'dynamic',
+    ctor: RetryExhaustedError,
+    inheritsCategoryFrom: 'wrapped-error',
+    name: 'RetryExhaustedError',
+    retryable: false,
+  },
+] as const satisfies readonly ErrorClassRegistryEntry[];
+
 // ---------------------------------------------------------------------------
 // Taxonomy maps
 // ---------------------------------------------------------------------------
 
-export const exitCodeMap = {
-  auth: 9,
-  cancelled: 130,
-  conflict: 3,
-  internal: 8,
-  network: 7,
-  not_found: 2,
-  permission: 4,
-  rate_limit: 6,
-  timeout: 5,
-  validation: 1,
-} as const satisfies Record<ErrorCategory, number>;
-
-export const statusCodeMap = {
-  auth: 401,
-  cancelled: 499,
-  conflict: 409,
-  internal: 500,
-  network: 502,
-  not_found: 404,
-  permission: 403,
-  rate_limit: 429,
-  timeout: 504,
-  validation: 400,
-} as const satisfies Record<ErrorCategory, number>;
-
-export const jsonRpcCodeMap = {
-  auth: -32_600,
-  cancelled: -32_603,
-  conflict: -32_603,
-  internal: -32_603,
-  network: -32_603,
-  not_found: -32_601,
-  permission: -32_600,
-  rate_limit: -32_603,
-  timeout: -32_603,
-  validation: -32_602,
-} as const satisfies Record<ErrorCategory, number>;
+export interface ErrorCategoryCodes {
+  readonly exit: number;
+  readonly http: number;
+  readonly jsonRpc: number;
+}
+
+export const codesByCategory = {
+  auth: { exit: 9, http: 401, jsonRpc: -32_600 },
+  cancelled: { exit: 130, http: 499, jsonRpc: -32_603 },
+  conflict: { exit: 3, http: 409, jsonRpc: -32_603 },
+  internal: { exit: 8, http: 500, jsonRpc: -32_603 },
+  network: { exit: 7, http: 502, jsonRpc: -32_603 },
+  not_found: { exit: 2, http: 404, jsonRpc: -32_601 },
+  permission: { exit: 4, http: 403, jsonRpc: -32_600 },
+  rate_limit: { exit: 6, http: 429, jsonRpc: -32_603 },
+  timeout: { exit: 5, http: 504, jsonRpc: -32_603 },
+  validation: { exit: 1, http: 400, jsonRpc: -32_602 },
+} as const satisfies Record<ErrorCategory, ErrorCategoryCodes>;
+
+const deriveCodeMap = <TCode extends keyof ErrorCategoryCodes>(
+  code: TCode
+): {
+  readonly [TCategory in ErrorCategory]: (typeof codesByCategory)[TCategory][TCode];
+} => ({
+  auth: codesByCategory.auth[code],
+  cancelled: codesByCategory.cancelled[code],
+  conflict: codesByCategory.conflict[code],
+  internal: codesByCategory.internal[code],
+  network: codesByCategory.network[code],
+  not_found: codesByCategory.not_found[code],
+  permission: codesByCategory.permission[code],
+  rate_limit: codesByCategory.rate_limit[code],
+  timeout: codesByCategory.timeout[code],
+  validation: codesByCategory.validation[code],
+});
+
+/** @deprecated Prefer `codesByCategory[category].exit`. */
+export const exitCodeMap = deriveCodeMap('exit');
+
+/** @deprecated Prefer `codesByCategory[category].http`. */
+export const statusCodeMap = deriveCodeMap('http');
+
+/** @deprecated Prefer `codesByCategory[category].jsonRpc`. */
+export const jsonRpcCodeMap = deriveCodeMap('jsonRpc');
 
 export const retryableMap: Record<ErrorCategory, boolean> = {
   auth: false,