@ontrails/core 1.0.0-beta.2 → 1.0.0-beta.21

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 {
@@ -8,79 +9,507 @@ export {
   AmbiguousError,
   AssertionError,
   NotFoundError,
+  VersionNotSupportedError,
   AlreadyExistsError,
   ConflictError,
   PermissionError,
+  PermitError,
   TimeoutError,
   RateLimitError,
   NetworkError,
   InternalError,
   AuthError,
   CancelledError,
+  DerivationError,
+  RecoverableCompletionError,
+  codesByCategory,
+  errorClasses,
+  errorCategories,
   exitCodeMap,
   statusCodeMap,
   jsonRpcCodeMap,
   retryableMap,
+  RetryExhaustedError,
   isRetryable,
   isTrailsError,
 } from './errors.js';
-export type { ErrorCategory } from './errors.js';
+export type {
+  DynamicErrorClassRegistryEntry,
+  ErrorCategory,
+  ErrorCategoryCodes,
+  ErrorClassConstructor,
+  ErrorClassRegistryEntry,
+  FixedErrorClassRegistryEntry,
+} from './errors.js';
+export {
+  createSurfaceErrorMapper,
+  mapSurfaceError,
+  projectErrorClassSurface,
+  projectPublicSurfaceError,
+  projectSurfaceError,
+  surfaceErrorMap,
+  surfaceErrorRegistry,
+  surfaceNames,
+} from './transport-error-map.js';
+export type {
+  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 {
+  Detour,
+  DetourAttempt,
   Implementation,
   TrailContext,
-  FollowFn,
+  TrailContextInit,
+  ComposeBatchOptions,
+  ComposeOptions,
+  ComposeFn,
+  FireFn,
+  LogLevel,
+  LogFormatter,
+  LogRecord,
+  LogSink,
+  PermitRequirement,
   ProgressCallback,
   ProgressEvent,
   Logger,
-  Surface,
+  ResourceLookup,
+} 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 } from './context.js';
+export { createTrailContext, passthroughTrace } from './context.js';
+
+// Resource
+export {
+  createResourceLookup,
+  findDuplicateResourceId,
+  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 type { AnyTrail, Trail, TrailSpec, TrailExample } 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 {
+  deriveSupportedTrailVersions,
+  getTrailVersionEntryKind,
+  hasDeprecatedTrailVersionGuidance,
+  intentValues,
+  isArchivedTrailVersionEntry,
+  isDeprecatedTrailVersionEntry,
+  isLiveTrailVersionEntry,
+  trail,
+} from './trail.js';
+export {
+  TRAIL_VERSION_MARKER_LENGTH,
+  TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH,
+  assertTrailVersionMarker,
+  assertUniqueTrailVersionMarkers,
+  canonicalizeTrailVersionMarkerContent,
+  deriveCurrentTrailVersionMarker,
+  deriveCurrentTrailVersionMarkerContent,
+  deriveShortestUnambiguousTrailVersionMarkerPrefix,
+  deriveTrailVersionEntryMarker,
+  deriveTrailVersionEntryMarkerContent,
+  deriveTrailVersionMarker,
+  deriveTrailVersionMarkers,
+  normalizeTrailVersionMarkerPrefix,
+  resolveTrailVersionMarkerPrefix,
+} from './version-marker.js';
+export {
+  parseTrailIdVersionReference,
+  resolveTrailVersion,
+} from './version-resolution.js';
+export type {
+  AnyTrail,
+  BlazeInput,
+  Intent,
+  Trail,
+  TrailVersionEntry,
+  TrailVersionEntryKind,
+  TrailVersionArchivedStatus,
+  TrailVersionDeprecatedStatus,
+  TrailVersionForkEntry,
+  TrailVersionRevisionEntry,
+  TrailVersions,
+  TrailVersionStatus,
+  TrailVersionTranspose,
+  TrailVersionTransposeInput,
+  TrailVersionTransposeOutput,
+  TrailSpec,
+  TrailExample,
+  TrailExampleSignalAssertion,
+  TrailVisibility,
+  VersionContract,
+  VersionEntry,
+} from './trail.js';
+export type {
+  TrailVersionMarkerBinding,
+  TrailVersionMarkerRecord,
+  TrailVersionMarkerResolution,
+} from './version-marker.js';
+export type {
+  ParsedTrailVersionReference,
+  ResolvedTrailVersion,
+  TrailVersionReference,
+} from './version-resolution.js';
+export {
+  filterSurfaceTrails,
+  matchesTrailPattern,
+  shouldIncludeTrailForSurface,
+} from './surface-filter.js';
+export type { SurfaceFilterOptions } from './surface-filter.js';
+export { deriveSurfaceTrailVersionProjections } from './surface-versioning.js';
+export type { SurfaceTrailVersionProjection } from './surface-versioning.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';
 
-// Hike
-export { hike } from './hike.js';
-export type { AnyHike, Hike, HikeSpec } from './hike.js';
+// Type utilities
+export type {
+  ComposeInput,
+  TrailInput,
+  TrailOutput,
+  TrailResult,
+} from './type-utils.js';
+export { inputOf, outputOf } from './type-utils.js';
 
-// Event
-export { event } from './event.js';
-export type { AnyEvent, Event, EventSpec } from './event.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';
+export {
+  CONTOUR_ID_METADATA,
+  getContourIdMetadata,
+  getContourReferences,
+} from './contour.js';
+export type {
+  AnyContour,
+  Contour,
+  ContourIdBrand,
+  ContourIdMetadata,
+  ContourIdSchema,
+  ContourIdValue,
+  ContourOptions,
+  ContourReference,
+} from './contour.js';
 
 // Topo
 export { topo } from './topo.js';
-export type { 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 {
+  deriveTrailsDbPath,
+  deriveTrailsDir,
+  ensureSubsystemSchema,
+  ensureTrailsWorkspace,
+  openReadTrailsDb,
+  openWriteTrailsDb,
+  WORKSPACE_GITIGNORE_CONTENT,
+  WORKSPACE_GITIGNORE_LINES,
+} from './trails-db.js';
+export type {
+  EnsureSubsystemSchemaOptions,
+  TrailsDbLocationOptions,
+} from './trails-db.js';
+
+// Draft state
+export {
+  DRAFT_ID_PREFIX,
+  deriveDraftReport,
+  isDraftId,
+  validateDraftFreeTopo,
+} from './draft.js';
+export type {
+  DraftDependency,
+  DraftDependencyKind,
+  DraftFinding,
+  DraftReport,
+} from './draft.js';
 
 // Topo validation
 export { validateTopo } from './validate-topo.js';
 export type { TopoIssue } from './validate-topo.js';
+export { validateEstablishedTopo } from './validate-established-topo.js';
 
 // Layer
 export { composeLayers } from './layer.js';
-export type { Layer } from './layer.js';
-
-// Health
-export type { HealthStatus, HealthResult } from './health.js';
-
-// Adapters
+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 {
-  IndexAdapter,
-  StorageAdapter,
-  CacheAdapter,
-  SearchOptions,
-  SearchResult,
-  StorageOptions,
-} from './adapters.js';
+  AttachedLayerScope,
+  AttachedTypedLayer,
+  LayerFieldProjection,
+  LayerFieldRenameReason,
+  ProjectedLayerField,
+  RenamedLayerFieldProjection,
+} from './layer-projection.js';
 
 // Derive
-export { deriveFields } from './derive.js';
+export { deriveCliPath, deriveFields } from './derive.js';
 export type { Field, FieldOverride } from './derive.js';
 
+// Compose schema
+export { buildComposeValidationSchema } from './compose-schema.js';
+export {
+  claimNextComposeBatchIndex,
+  createComposeBatchValidationResults,
+  normalizeComposeBatchConcurrency,
+} from './compose-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,
+  traceContextFromRecord,
+  writeActivationTraceRecord,
+} from './tracing.js';
+export type {
+  ActivationTraceRecordName,
+  SignalTraceRecordName,
+  TraceContext,
+  TraceRecord,
+  TraceSink,
+} 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';
+
+// Trail factories
+export { deriveTrail, ingest } from './trails/index.js';
+export type {
+  DeriveTrailInput,
+  DeriveTrailOperation,
+  DeriveTrailOutput,
+  DeriveTrailSpec,
+  IngestOptions,
+  IngestTransform,
+} from './trails/index.js';
+
 // Validation
 export {
   validateInput,
@@ -88,6 +517,10 @@ export {
   formatZodIssues,
   zodToJsonSchema,
 } from './validation.js';
+export {
+  stripDefaultWrappers,
+  stripDefaultsFromShape,
+} from './zod-wrappers.js';
 
 // Serialization
 export { serializeError, deserializeError } from './serialization.js';
@@ -98,7 +531,7 @@ export {
   retry,
   withTimeout,
   shouldRetry,
-  getBackoffDelay,
+  deriveBackoffDelay,
 } from './resilience.js';
 export type { RetryOptions } from './resilience.js';
 
@@ -113,7 +546,7 @@ export {
   nonEmptyString,
   positiveInt,
   shortId,
-  hashId,
+  deriveIdHash,
 } from './branded.js';
 export type {
   Branded,
@@ -124,15 +557,27 @@ export type {
 } from './branded.js';
 
 // Path Security
-export { securePath, isPathSafe, resolveSafePath } from './path-security.js';
+export { securePath, isPathSafe, deriveSafePath } from './path-security.js';
 
 // Workspace
 export {
   findWorkspaceRoot,
   isInsideWorkspace,
-  getRelativePath,
+  deriveRelativePath,
 } from './workspace.js';
 
+// Blob
+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 {
   isDefined,

package/src/internal/fork-ctx.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal helper for "forking" a trail context.
+ *
+ * Several execution sites need to derive a child context from a parent
+ * context while **resetting** a well-known set of bound closures (`compose`,
+ * `fire`, `resource`). Those closures capture the parent scope, so reusing
+ * them on the child would re-enter execution with the wrong attribution,
+ * the wrong resource scope, or the wrong fan-out identity. The reset list
+ * is the same at every fork site.
+ *
+ * Codifying the reset list in one helper keeps that contract in a single
+ * place. Callers supply the overrides they need (typically `env`,
+ * `extensions`, and `logger`) and let the helper handle the reset.
+ *
+ * This module is internal — do not export it from the package entry point.
+ *
+ * @remarks
+ * The helper is intentionally generic over the concrete context shape. Some
+ * callers work with the fully-resolved `TrailContext` produced inside the
+ * executor; others work with `Partial<TrailContextInit>` during consumer
+ * context derivation in `fire.ts`. Both shapes share the same reset keys.
+ */
+
+import type { TrailContext, TrailContextInit } from '../types.js';
+
+/** Keys cleared by default when forking a context. */
+export type ForkCtxResetKey = 'compose' | 'fire' | 'resource';
+
+/** Override fields callers are allowed to apply when forking a context. */
+export type ForkCtxOverrides = Readonly<
+  Partial<Pick<TrailContext, 'env' | 'extensions' | 'logger'>>
+>;
+
+const DEFAULT_RESET_KEYS: readonly ForkCtxResetKey[] = [
+  'compose',
+  'fire',
+  'resource',
+];
+
+/**
+ * Fork a parent context into a child context.
+ *
+ * Spreads the parent, clears each reset key to `undefined`, and applies the
+ * supplied overrides last so callers may replace logger, env, and extensions
+ * with branch-local values.
+ *
+ * The generic parameter is constrained to the minimal shape the helper
+ * reads and writes. This lets the helper serve both `TrailContext`
+ * (executor scope) and `Partial<TrailContextInit>` (fire-consumer scope)
+ * without widening the public surface of either type.
+ */
+export const forkCtx = <
+  TCtx extends Partial<
+    Pick<
+      TrailContextInit,
+      'compose' | 'env' | 'extensions' | 'fire' | 'logger' | 'resource'
+    >
+  >,
+>(
+  parentCtx: TCtx,
+  overrides: ForkCtxOverrides = {},
+  reset: readonly ForkCtxResetKey[] = DEFAULT_RESET_KEYS
+): TCtx => {
+  const forked: TCtx = { ...parentCtx };
+  for (const key of reset) {
+    forked[key as keyof TCtx] = undefined as TCtx[keyof TCtx];
+  }
+  return { ...forked, ...overrides };
+};