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

package/src/index.ts

@@ -1,5 +1,6 @@
 // Result
-export { Result } from './result.js';
+export { Result, resultAccessorNames } from './result.js';
+export type { ResultAccessorName } from './result.js';
 
 // Errors
 export {
@@ -11,6 +12,7 @@ export {
   AlreadyExistsError,
   ConflictError,
   PermissionError,
+  PermitError,
   TimeoutError,
   RateLimitError,
   NetworkError,
@@ -18,6 +20,9 @@ export {
   AuthError,
   CancelledError,
   DerivationError,
+  RecoverableCompletionError,
+  codesByCategory,
+  errorClasses,
   errorCategories,
   exitCodeMap,
   statusCodeMap,
@@ -27,20 +32,40 @@ export {
   isRetryable,
   isTrailsError,
 } from './errors.js';
-export type { ErrorCategory } from './errors.js';
+export type {
+  DynamicErrorClassRegistryEntry,
+  ErrorCategory,
+  ErrorCategoryCodes,
+  ErrorClassConstructor,
+  ErrorClassRegistryEntry,
+  FixedErrorClassRegistryEntry,
+} from './errors.js';
 export {
-  createTransportErrorMapper,
-  mapTransportError,
-  transportErrorMap,
-  transportErrorRegistry,
-  transportNames,
+  createSurfaceErrorMapper,
+  mapSurfaceError,
+  projectErrorClassSurface,
+  projectPublicSurfaceError,
+  projectSurfaceError,
+  surfaceErrorMap,
+  surfaceErrorRegistry,
+  surfaceNames,
 } from './transport-error-map.js';
 export type {
-  TransportErrorCode,
-  TransportErrorMapper,
-  TransportErrorMappings,
-  TransportName,
+  ErrorClassSurfaceProjection,
+  SurfaceErrorCode,
+  SurfaceErrorMapper,
+  SurfaceErrorMappings,
+  SurfaceErrorProjection,
+  SurfaceName,
 } from './transport-error-map.js';
+export {
+  INTERNAL_ERROR_PUBLIC_MESSAGE,
+  projectErrorDiagnostics,
+  redactErrorContext,
+  redactErrorStack,
+  redactErrorString,
+} from './error-projection.js';
+export type { ErrorDiagnosticsProjection } from './error-projection.js';
 
 // Types
 export type {
@@ -52,14 +77,34 @@ export type {
   CrossBatchOptions,
   CrossFn,
   FireFn,
-  BasePermit,
+  LogLevel,
+  LogFormatter,
+  LogRecord,
+  LogSink,
   PermitRequirement,
   ProgressCallback,
   ProgressEvent,
   Logger,
   ResourceLookup,
 } from './types.js';
-export { TRAILHEAD_KEY } from './types.js';
+export { basePermitSchema } from './permits.js';
+export type { BasePermit } from './permits.js';
+export {
+  LAYER_INPUTS_KEY,
+  SURFACE_KEY,
+  SURFACE_LAYER_NAMES_KEY,
+} from './types.js';
+export {
+  ACTIVATION_PROVENANCE_KEY,
+  buildActivationProvenanceTraceAttrs,
+  getActivationProvenance,
+  withActivationProvenance,
+} from './activation-provenance.js';
+export type {
+  ActivationProvenance,
+  ActivationProvenanceCarrier,
+  ActivationProvenanceSource,
+} from './activation-provenance.js';
 
 // Context factory
 export { createTrailContext, passthroughTrace } from './context.js';
@@ -71,16 +116,48 @@ export {
   isResource,
   resource,
 } from './resource.js';
+export { drainResources, resolveResourceConfig } from './resource-config.js';
+export type {
+  ResourceConfigValues,
+  ResourceDrainReport,
+} from './resource-config.js';
 export type {
   AnyResource,
   Resource,
   ResourceContext,
   ResourceOverrideMap,
   ResourceSpec,
+  ResourceUnmockable,
 } from './resource.js';
 
 // Trail
-export { trail } from './trail.js';
+export {
+  activationSourceKinds,
+  getActivationWherePredicate,
+  isActivationEntrySpec,
+  isActivationSource,
+  isKnownActivationSourceKind,
+} from './activation-source.js';
+export type {
+  ActivationEntry,
+  ActivationEntrySpec,
+  ActivationSource,
+  ActivationSourceKind,
+  ActivationSourceMeta,
+  ActivationSourceRef,
+  ActivationWhere,
+  ActivationWhereExample,
+  ActivationWherePredicate,
+  ActivationWhereSpec,
+  BuiltinActivationSourceKind,
+} from './activation-source.js';
+export {
+  activationSourceDeclarationSignature,
+  activationSourceKey,
+  projectActivationSourceDeclaration,
+} from './activation-source-projection.js';
+export type { ActivationSourceProjection } from './activation-source-projection.js';
+export { intentValues, trail } from './trail.js';
 export type {
   AnyTrail,
   BlazeInput,
@@ -88,6 +165,7 @@ export type {
   Trail,
   TrailSpec,
   TrailExample,
+  TrailExampleSignalAssertion,
   TrailVisibility,
 } from './trail.js';
 export {
@@ -96,6 +174,31 @@ export {
   shouldIncludeTrailForSurface,
 } from './surface-filter.js';
 export type { SurfaceFilterOptions } from './surface-filter.js';
+export {
+  shouldValidateSurfaceTopo,
+  validateSurfaceTopo,
+  withSurfaceLayerNames,
+  withSurfaceMarker,
+} from './surface-derivation.js';
+export type {
+  BaseSurfaceOptions,
+  SurfaceConfigValues,
+  SurfaceSelectionOptions,
+  SurfaceMarkedContext,
+  SurfaceValidationOptions,
+} from './surface-derivation.js';
+export {
+  deriveStructuredSignalExamples,
+  deriveStructuredTrailExamples,
+} from './structured-examples.js';
+export type {
+  StructuredSignalExample,
+  StructuredSignalExampleProvenance,
+  StructuredTrailExample,
+  StructuredTrailExampleKind,
+  StructuredTrailExampleProvenance,
+  StructuredTrailExampleSignalAssertion,
+} from './structured-examples.js';
 
 // Type utilities
 export type {
@@ -109,6 +212,100 @@ export { inputOf, outputOf } from './type-utils.js';
 // Signal
 export { signal } from './signal.js';
 export type { AnySignal, Signal, SignalSpec } from './signal.js';
+export { schedule, validateScheduleSource } from './schedule.js';
+export type {
+  ScheduleSource,
+  ScheduleSpec,
+  ScheduleValidationIssue,
+} from './schedule.js';
+export {
+  getWebhookHeader,
+  getWebhookHeaders,
+  validateWebhookSource,
+  verifyWebhookRequest,
+  webhook,
+  webhookMethods,
+} from './webhook.js';
+export type {
+  WebhookMethod,
+  WebhookMethodInput,
+  WebhookSource,
+  WebhookSpec,
+  WebhookValidationIssue,
+  WebhookVerify,
+  WebhookVerifyHeaders,
+  WebhookVerifyRequest,
+} from './webhook.js';
+export { createScheduleRuntime } from './schedule-runtime.js';
+export type {
+  ScheduleCronFactory,
+  ScheduleCronHandler,
+  ScheduleCronJob,
+  ScheduleRuntime,
+  ScheduleRuntimeLogger,
+  ScheduleRuntimeOptions,
+  ScheduleRuntimeRegistrationReport,
+  ScheduleRuntimeRunRecord,
+  ScheduleRuntimeRunStatus,
+  ScheduleRuntimeSkipReason,
+  ScheduleRuntimeStartReport,
+  ScheduleRuntimeState,
+  ScheduleRuntimeStopReport,
+  ScheduleRuntimeWarning,
+  ScheduleRuntimeWarningCode,
+} from './schedule-runtime.js';
+export {
+  SIGNAL_DIAGNOSTICS_SINK_KEY,
+  SIGNAL_DIAGNOSTICS_STRICT_MODE_KEY,
+  createSignalFireSuppressedDiagnostic,
+  createSignalHandlerFailedDiagnostic,
+  createSignalHandlerRejectedDiagnostic,
+  createSignalInvalidDiagnostic,
+  createSignalPredicateFailedDiagnostic,
+  createSignalUnknownDiagnostic,
+  recordSignalDiagnostic,
+  shouldPromoteSignalDiagnostic,
+  signalDiagnosticDefinitions,
+  summarizeSignalPayload,
+} from './signal-diagnostics.js';
+export type {
+  CreateSignalFireSuppressedDiagnosticInput,
+  CreateSignalHandlerDiagnosticInput,
+  CreateSignalInvalidDiagnosticInput,
+  SignalDiagnostic,
+  SignalDiagnosticCategory,
+  SignalDiagnosticCause,
+  SignalDiagnosticCode,
+  SignalDiagnosticCommonInput,
+  SignalDiagnosticContext,
+  SignalDiagnosticLevel,
+  SignalDiagnosticPathSegment,
+  SignalDiagnosticRecordResult,
+  SignalDiagnosticSchemaIssue,
+  SignalDiagnosticSink,
+  SignalDiagnosticOrigin,
+  SignalDiagnosticSourceLocation,
+  SignalDiagnosticStrictMode,
+  SignalFireSuppressedDiagnostic,
+  SignalHandlerFailedDiagnostic,
+  SignalHandlerRejectedDiagnostic,
+  SignalInvalidDiagnostic,
+  SignalPredicateFailedDiagnostic,
+  SignalPayloadShape,
+  SignalPayloadSummary,
+  SignalUnknownDiagnostic,
+} from './signal-diagnostics.js';
+export {
+  attachLateBoundSignalRef,
+  cloneSignalWithId,
+  createLateBoundSignalMarker,
+  getLateBoundSignalRef,
+  parseLateBoundSignalMarker,
+} from './signal-ref.js';
+export type {
+  LateBoundSignalMarker,
+  LateBoundSignalRef,
+} from './signal-ref.js';
 
 // Contour
 export { contour } from './contour.js';
@@ -131,27 +328,24 @@ export type {
 // Topo
 export { topo } from './topo.js';
 export type { Topo, TopoIdentity } from './topo.js';
+
+// Generic trails-db helpers (shared framework infrastructure per ADR-0014).
+// The topo-store public API that previously lived here moved to
+// `@ontrails/topographer` per ADR-0042.
 export {
-  createTopoSnapshot,
-  createMockTopoStore,
-  createTopoStore,
-  listTopoSnapshots,
-  pinTopoSnapshot,
-  topoStore,
-  unpinTopoSnapshot,
-} from './topo-store.js';
+  deriveTrailsDbPath,
+  deriveTrailsDir,
+  ensureSubsystemSchema,
+  ensureTrailsWorkspace,
+  openReadTrailsDb,
+  openWriteTrailsDb,
+  WORKSPACE_GITIGNORE_CONTENT,
+  WORKSPACE_GITIGNORE_LINES,
+} from './trails-db.js';
 export type {
-  CreateTopoSnapshotInput,
-  ListTopoSnapshotsOptions,
-  MockTopoStoreSeed,
-  ReadOnlyTopoStore,
-  TopoSnapshot,
-  TopoStoreExportRecord,
-  TopoStoreResourceRecord,
-  TopoStoreRef,
-  TopoStoreTrailDetailRecord,
-  TopoStoreTrailRecord,
-} from './topo-store.js';
+  EnsureSubsystemSchemaOptions,
+  TrailsDbLocationOptions,
+} from './trails-db.js';
 
 // Draft state
 export {
@@ -174,7 +368,21 @@ export { validateEstablishedTopo } from './validate-established-topo.js';
 
 // Layer
 export { composeLayers } from './layer.js';
-export type { Layer } from './layer.js';
+export type { Layer, LayerInputSchema } from './layer.js';
+export {
+  collectAttachedTypedLayers,
+  LAYER_FIELD_RESERVED_NAMES,
+  LAYER_FIELD_RESERVED_NAMES_KEBAB,
+  projectLayerFieldName,
+} from './layer-projection.js';
+export type {
+  AttachedLayerScope,
+  AttachedTypedLayer,
+  LayerFieldProjection,
+  LayerFieldRenameReason,
+  ProjectedLayerField,
+  RenamedLayerFieldProjection,
+} from './layer-projection.js';
 
 // Derive
 export { deriveCliPath, deriveFields } from './derive.js';
@@ -182,28 +390,55 @@ export type { Field, FieldOverride } from './derive.js';
 
 // Cross schema
 export { buildCrossValidationSchema } from './cross-schema.js';
+export {
+  claimNextCrossBatchIndex,
+  createCrossBatchValidationResults,
+  normalizeCrossBatchConcurrency,
+} from './cross-batch.js';
 
 // Execute
+export { DETOUR_MAX_ATTEMPTS_CAP } from './detours.js';
 export { executeTrail } from './execute.js';
 export type { ExecuteTrailOptions } from './execute.js';
 
 // Intrinsic tracing
 export {
   clearTraceSink,
+  createActivationTraceRecord,
   createTraceRecord,
   getTraceContext,
   getTraceSink,
   NOOP_SINK,
   registerTraceSink,
   TRACE_CONTEXT_KEY,
-} from './internal/tracing.js';
+  traceContextFromRecord,
+  writeActivationTraceRecord,
+} from './tracing.js';
 export type {
+  ActivationTraceRecordName,
+  SignalTraceRecordName,
   TraceContext,
   TraceRecord,
   TraceSink,
-} from './internal/tracing.js';
+} from './tracing.js';
 export type { TraceFn } from './types.js';
 
+// Observe
+export {
+  createObserveLogger,
+  isLogSink,
+  isLogger,
+  isObserveInput,
+  isTraceSink,
+  normalizeObserve,
+} from './observe.js';
+export type {
+  ObserveCapabilities,
+  ObserveConfig,
+  ObserveInput,
+  TopoOptions,
+} from './observe.js';
+
 // Run
 export { run } from './run.js';
 export type { RunOptions } from './run.js';
@@ -226,6 +461,10 @@ export {
   formatZodIssues,
   zodToJsonSchema,
 } from './validation.js';
+export {
+  stripDefaultWrappers,
+  stripDefaultsFromShape,
+} from './zod-wrappers.js';
 
 // Serialization
 export { serializeError, deserializeError } from './serialization.js';
@@ -272,8 +511,16 @@ export {
 } from './workspace.js';
 
 // Blob
-export { createBlobRef, isBlobRef } from './blob-ref.js';
-export type { BlobRef } from './blob-ref.js';
+export {
+  BLOB_REF_SCHEMA_META_KEY,
+  blobRefDescriptorSchema,
+  blobRefJsonSchema,
+  blobRefSchema,
+  createBlobRef,
+  isBlobRef,
+  toBlobRefDescriptor,
+} from './blob-ref.js';
+export type { BlobRef, BlobRefDescriptor } from './blob-ref.js';
 
 // Guards
 export {

package/src/layer-projection.ts

@@ -0,0 +1,192 @@
+/**
+ * Shared, surface-agnostic helpers for projecting typed layer `input` schemas
+ * onto a surface's native idiom.
+ *
+ * Layer projection has two halves:
+ *   1. **Collection** — walk the trail's effective layers (topo → surface →
+ *      trail) and keep only the ones that declare an `input` schema. These
+ *      are the layers a surface needs to project.
+ *   2. **Naming/collision policy** — when a layer field's projected name
+ *      collides with a name already claimed by the trail, by another layer,
+ *      or by a surface-reserved name, the field is renamed using the
+ *      deterministic `<layerName>-<originalField>` rule. The collision-detection
+ *      logic itself is surface-agnostic; the *shape* of the projected name
+ *      (kebab-case CLI flag, camelCase MCP parameter, HTTP request field)
+ *      stays per-surface.
+ *
+ * This module owns the surface-agnostic half. CLI/MCP/HTTP each layer their
+ * own projection on top: see `@ontrails/cli/build`, `@ontrails/mcp/build`,
+ * and `@ontrails/http/build`.
+ *
+ * @see TRL-473 for the CLI projection that introduced this contract.
+ * @see TRL-474 for the MCP and HTTP projections that lifted these helpers.
+ */
+
+import type { Layer } from './layer.js';
+import type { Topo } from './topo.js';
+import type { AnyTrail } from './trail.js';
+
+export const LAYER_FIELD_RESERVED_NAMES: ReadonlySet<string> = new Set([
+  'all',
+  'devPermit',
+  'dryRun',
+  'input',
+  'inputJson',
+  'json',
+  'jsonl',
+  'output',
+  'permit',
+  'quiet',
+  'token',
+  'trace',
+  'watch',
+]);
+
+const toKebabCase = (name: string): string =>
+  name.replaceAll(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`);
+
+export const LAYER_FIELD_RESERVED_NAMES_KEBAB: ReadonlySet<string> = new Set(
+  [...LAYER_FIELD_RESERVED_NAMES].map(toKebabCase)
+);
+
+// ---------------------------------------------------------------------------
+// Collection
+// ---------------------------------------------------------------------------
+
+/**
+ * Source of a typed layer attached to a trail.
+ *
+ * Surfaces may want to know whether a layer came from topo-, surface-, or
+ * trail-scope (e.g. for descriptive errors). The collection helper preserves
+ * this information so callers don't have to recompute it.
+ */
+export type AttachedLayerScope = 'topo' | 'surface' | 'trail';
+
+export interface AttachedTypedLayer {
+  readonly layer: Layer;
+  readonly scope: AttachedLayerScope;
+}
+
+/**
+ * Collect every typed layer attached to a trail in the same composition order
+ * the executor uses (topo → surface → trail). Layers without an `input`
+ * schema are skipped — they have nothing to project onto a surface.
+ *
+ * @param graph - The topo carrying topo-scope layers.
+ * @param trail - The trail whose effective layers we are projecting.
+ * @param surfaceLayers - Layers attached at surface scope (`options.layers`
+ *   on the surface builder).
+ */
+export const collectAttachedTypedLayers = (
+  graph: Topo,
+  trail: AnyTrail,
+  surfaceLayers?: readonly Layer[] | undefined
+): readonly AttachedTypedLayer[] => {
+  const layers: AttachedTypedLayer[] = [];
+  for (const layer of graph.layers) {
+    if (layer.input !== undefined) {
+      layers.push({ layer, scope: 'topo' });
+    }
+  }
+  if (surfaceLayers !== undefined) {
+    for (const layer of surfaceLayers) {
+      if (layer.input !== undefined) {
+        layers.push({ layer, scope: 'surface' });
+      }
+    }
+  }
+  for (const layer of trail.layers) {
+    if (layer.input !== undefined) {
+      layers.push({ layer, scope: 'trail' });
+    }
+  }
+  return layers;
+};
+
+// ---------------------------------------------------------------------------
+// Collision rename rule
+// ---------------------------------------------------------------------------
+
+/**
+ * Reason a layer field was renamed during projection.
+ *
+ * Surfaces map this onto their own warning/error idiom. CLI emits a stderr
+ * warning, while MCP/HTTP rely on the projected schema as the source of truth.
+ */
+export type LayerFieldRenameReason = 'reserved-name' | 'flag-collision';
+
+/**
+ * Outcome of projecting a single layer field's name.
+ *
+ * `claimedName` is the name the surface will publish to consumers; it is the
+ * field name when no collision was detected, or `<layerName>-<fieldName>` (or
+ * an analogous transformed form, depending on the surface's convention) when
+ * a collision required a rename. `routingTarget` is the original field name
+ * the value should be assigned back to inside the layer's runtime input.
+ */
+export interface LayerFieldProjection {
+  readonly claimedName: string;
+  readonly routingTarget: string;
+  readonly renamed: false;
+}
+
+export interface RenamedLayerFieldProjection {
+  readonly claimedName: string;
+  readonly routingTarget: string;
+  readonly renamed: true;
+  readonly originalName: string;
+  readonly reason: LayerFieldRenameReason;
+}
+
+export type ProjectedLayerField =
+  | LayerFieldProjection
+  | RenamedLayerFieldProjection;
+
+/**
+ * Apply the deterministic collision rename rule to a single projected layer
+ * field name.
+ *
+ * @param layerName - The layer's logical name (used as the rename prefix).
+ * @param originalName - The layer field's name as authored on its schema.
+ * @param projectedName - The candidate name in the surface's native idiom
+ *   (e.g. kebab-case for CLI, camelCase for MCP, request field for HTTP).
+ * @param renamedName - The fallback name applied when a collision is detected.
+ *   Surfaces compute this with their own casing rule.
+ * @param claimedNames - Names already taken by the trail's input or by
+ *   previous layer projections. Updated in place when a name is claimed.
+ * @param reservedNames - Framework-owned names that force a rename across
+ *   surface projections.
+ */
+export const projectLayerFieldName = (
+  _layerName: string,
+  originalName: string,
+  projectedName: string,
+  renamedName: string,
+  claimedNames: Set<string>,
+  reservedNames: ReadonlySet<string>
+): ProjectedLayerField => {
+  const collidesWithClaimed = claimedNames.has(projectedName);
+  const collidesWithReserved = reservedNames.has(projectedName);
+
+  if (!collidesWithClaimed && !collidesWithReserved) {
+    claimedNames.add(projectedName);
+    return {
+      claimedName: projectedName,
+      renamed: false,
+      routingTarget: originalName,
+    };
+  }
+
+  let claimedName = renamedName;
+  for (let suffix = 2; claimedNames.has(claimedName); suffix += 1) {
+    claimedName = `${renamedName}${suffix}`;
+  }
+  claimedNames.add(claimedName);
+  return {
+    claimedName,
+    originalName: projectedName,
+    reason: collidesWithReserved ? 'reserved-name' : 'flag-collision',
+    renamed: true,
+    routingTarget: originalName,
+  };
+};

package/src/layer.ts

@@ -1,3 +1,5 @@
+import type { z } from 'zod';
+
 import type { AnyTrail } from './trail.js';
 import type { Implementation } from './types.js';
 
@@ -5,11 +7,40 @@ import type { Implementation } from './types.js';
 // Layer interface
 // ---------------------------------------------------------------------------
 
-/** A composable layer that wraps trail implementations. */
+/**
+ * A composable, named layer that wraps trail implementations.
+ *
+ * Layers attach at trail, surface, or topo scope and may declare an object
+ * `input` schema describing the configuration they need from the surrounding
+ * surface. Surface packages (CLI, MCP, HTTP) project this schema onto their
+ * native idioms — flags, tool parameters, query strings — alongside the
+ * trail's own input schema.
+ *
+ * @remarks
+ * The `input` schema is metadata for surface projection. It must be an object
+ * schema so every surface can project named fields consistently. It is
+ * optional; layers without an `input` schema behave as plain wrappers. The
+ * layer's `wrap` function is the runtime contract.
+ */
+export type LayerInputSchema = z.ZodObject<z.ZodRawShape>;
+
 export interface Layer {
   readonly name: string;
   readonly description?: string | undefined;
 
+  /**
+   * Authored configuration the layer needs from the surrounding surface.
+   *
+   * Surface packages project this schema onto their native idioms (CLI flags,
+   * MCP tool parameters, HTTP query strings) so a layer's input fields appear
+   * alongside the trail's own input fields. Optional — layers that wrap purely
+   * by behavior, with no surface-visible inputs, may omit it.
+   *
+   * @see TRL-473 for CLI flag projection.
+   * @see TRL-474 for MCP and HTTP projection.
+   */
+  readonly input?: LayerInputSchema | undefined;
+
   /**
    * Wrap a trail's implementation, returning a new implementation.
    *