@ontrails/core 0.2.0

package/src/index.ts

@@ -0,0 +1,704 @@
+// Result
+export { Result, resultAccessorNames } from './result.js';
+export type { ResultAccessorName } from './result.js';
+
+// Errors
+export {
+  TrailsError,
+  ValidationError,
+  AmbiguousError,
+  AssertionError,
+  NotFoundError,
+  VersionNotSupportedError,
+  AlreadyExistsError,
+  ConflictError,
+  PermissionError,
+  PermitError,
+  TimeoutError,
+  RateLimitError,
+  NetworkError,
+  WorkspaceShiftError,
+  InternalError,
+  AuthError,
+  CancelledError,
+  DerivationError,
+  RecoverableCompletionError,
+  codesByCategory,
+  errorClasses,
+  errorCategories,
+  exitCodeMap,
+  statusCodeMap,
+  jsonRpcCodeMap,
+  retryableMap,
+  RetryExhaustedError,
+  isRetryable,
+  isTrailsError,
+} from './errors.js';
+export type {
+  DynamicErrorClassRegistryEntry,
+  ErrorCategory,
+  ErrorCategoryCodes,
+  ErrorClassConstructor,
+  ErrorClassRegistryEntry,
+  FixedErrorClassRegistryEntry,
+} from './errors.js';
+export {
+  createSurfaceErrorMapper,
+  mapSurfaceError,
+  renderErrorClassSurface,
+  renderPublicSurfaceError,
+  renderSurfaceError,
+  surfaceErrorMap,
+  surfaceErrorRegistry,
+  surfaceNames,
+} from './transport-error-map.js';
+export type {
+  ErrorClassSurfaceRendering,
+  SurfaceErrorCode,
+  SurfaceErrorMapper,
+  SurfaceErrorMappings,
+  SurfaceErrorRendering,
+  SurfaceName,
+} from './transport-error-map.js';
+export {
+  INTERNAL_ERROR_PUBLIC_MESSAGE,
+  renderErrorDiagnostics,
+  renderPublicError,
+  redactErrorContext,
+  redactErrorStack,
+  redactErrorString,
+} from './error-rendering.js';
+export type {
+  ErrorDiagnosticsRendering,
+  PublicErrorRendering,
+} from './error-rendering.js';
+export type {
+  DiagnosticBase,
+  DiagnosticSeverity,
+  RuleDiagnosticBase,
+} from './diagnostics.js';
+
+// Types
+export type {
+  Detour,
+  DetourAttempt,
+  Implementation,
+  TrailContext,
+  TrailContextInit,
+  ComposeBatchOptions,
+  ComposeOptions,
+  ComposeFn,
+  FireFn,
+  LogLevel,
+  LogFormatter,
+  LogRecord,
+  LogSink,
+  PermitRequirement,
+  ProgressCallback,
+  ProgressEvent,
+  Logger,
+  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, passthroughTrace } from './context.js';
+
+// Glob and path scope
+export {
+  escapeRegExp,
+  globToRegExp,
+  matchesAnyGlob,
+  matchesGlob,
+} from './glob.js';
+export type { GlobConfig } from './glob.js';
+export {
+  includedByPathScope,
+  matchesAnyPathGlob,
+  matchesPathGlob,
+  normalizePathScopePath,
+  pathScopeSchema,
+} from './path-scope.js';
+export type { PathGlob, PathScope, ScanTargets } from './path-scope.js';
+export { matchesAnyTrailIdGlob, matchesTrailIdGlob } from './trail-id-glob.js';
+export type { TrailIdGlob } from './trail-id-glob.js';
+
+// Resource
+export {
+  createResourceLookup,
+  findDuplicateResourceId,
+  isResource,
+  resource,
+} from './resource.js';
+export {
+  createResources,
+  drainResources,
+  resolveResourceConfig,
+} from './resource-config.js';
+export type {
+  ResolvedResourceScope,
+  ResourceConfigValues,
+  ResourceDrainReport,
+} from './resource-config.js';
+export type {
+  AnyResource,
+  Resource,
+  ResourceContext,
+  ResourceOverrideMap,
+  ResourceSpec,
+  ResourceUnmockable,
+} from './resource.js';
+
+// Trail
+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,
+  deriveActivationSourceFacts,
+} from './activation-source-derivation.js';
+export type { ActivationSourceFacts } from './activation-source-derivation.js';
+export {
+  deriveSupportedTrailVersions,
+  forkVersion,
+  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,
+  ImplementationInput,
+  Intent,
+  Trail,
+  TrailVersionEntry,
+  TrailVersionEntryKind,
+  TrailVersionArchivedStatus,
+  TrailVersionDeprecatedStatus,
+  TrailVersionForkEntry,
+  TrailVersionForkSpec,
+  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 { deriveSurfaceTrailVersionRenderings } from './surface-versioning.js';
+export type { SurfaceTrailVersionRendering } 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';
+
+// Type utilities
+export type {
+  ComposeInput,
+  TrailInput,
+  TrailOutput,
+  TrailResult,
+} from './type-utils.js';
+export { inputOf, outputOf } from './type-utils.js';
+
+// Signal
+export { signal } from './signal.js';
+export type { AnySignal, Signal, SignalSpec } from './signal.js';
+export { queue, validateQueueSource } from './queue.js';
+export type { QueueSource, QueueSpec, QueueValidationIssue } from './queue.js';
+export { schedule, validateScheduleSource } from './schedule.js';
+export type {
+  ScheduleSource,
+  ScheduleSpec,
+  ScheduleValidationIssue,
+} from './schedule.js';
+export {
+  getWebhookHeader,
+  getWebhookHeaders,
+  matchWebhookPath,
+  parseWebhookPathParams,
+  validateWebhookSource,
+  verifyWebhookRequest,
+  webhook,
+  webhookMethods,
+  webhookPathPatternsOverlap,
+} 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';
+
+// Entity
+export { entity } from './entity.js';
+export {
+  ENTITY_ID_METADATA,
+  getEntityIdMetadata,
+  getEntityReferences,
+} from './entity.js';
+export type {
+  AnyEntity,
+  Entity,
+  EntityIdBrand,
+  EntityIdMetadata,
+  EntityIdSchema,
+  EntityIdValue,
+  EntityOptions,
+  EntityReference,
+} from './entity.js';
+
+// Topo
+export { topo } from './topo.js';
+export type { Topo, TopoIdentity } from './topo.js';
+
+// Surface overlay
+export {
+  SURFACES_OVERLAY_NAMESPACE,
+  classifySurfaceBinding,
+  deriveMcpTrailheadDescription,
+  expandCliSurfaceBindings,
+  expandMcpSurfaceBindings,
+  resolveSurfaceOverlayBindings,
+  surfaceBindingsFromLockOverlays,
+  surfaceOverlay,
+  surfaceOverlayBindingsSchema,
+} from './surface-overlay.js';
+export type {
+  CliSurfaceBindingAliases,
+  McpSurfaceBindingExpansion,
+  OverlayEnvelopeLike,
+  OverlayProvenance,
+  SurfaceBindingRef,
+  SurfaceBindingShape,
+  SurfaceBindingValue,
+  SurfaceBindings,
+  SurfaceOverlay,
+  SurfaceOverlayBindings,
+} from './surface-overlay.js';
+
+// Generic trails-db helpers (shared framework infrastructure per ADR-0014).
+// The topo-store public API that previously lived here moved to
+// `@ontrails/topography` per ADR-0042.
+export {
+  deriveTrailsDbPath,
+  deriveTrailsDir,
+  deriveTrailsProjectKey,
+  deriveTrailsStateDir,
+  deriveTrailsStateHome,
+  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,
+  DraftDiagnostic,
+  DraftFinding,
+  DraftReport,
+} from './draft.js';
+
+// Topo validation
+export { getTopoDiagnostics, validateTopo } from './validate-topo.js';
+export type {
+  TopoDiagnostic,
+  TopoDiagnosticCode,
+  TopoIssue,
+  TopoMissingReference,
+  TopoReferenceKind,
+  TopoReferenceOwnerKind,
+} from './validate-topo.js';
+export { validateEstablishedTopo } from './validate-established-topo.js';
+
+// Layer
+export { composeLayers } from './layer.js';
+export type { Layer, LayerInputSchema } from './layer.js';
+export {
+  collectAttachedTypedLayers,
+  LAYER_FIELD_RESERVED_NAMES,
+  LAYER_FIELD_RESERVED_NAMES_KEBAB,
+  renderLayerFieldName,
+} from './layer-field-rendering.js';
+export type {
+  AttachedLayerScope,
+  AttachedTypedLayer,
+  LayerFieldRendering,
+  LayerFieldRenameReason,
+  RenderedLayerField,
+  RenamedLayerFieldRendering,
+} from './layer-field-rendering.js';
+
+// Derive
+export {
+  deriveCliPath,
+  deriveFields,
+  deriveMcpToolName,
+  deriveTrailCliCommandRendering,
+  normalizeCliCommandPath,
+} from './derive.js';
+export type {
+  CliCommandAliasInput,
+  CliCommandPathInput,
+  CliCommandRoute,
+  CliCommandRouteKind,
+  CliCommandRouteSource,
+  DeriveTrailCliCommandOptions,
+  Field,
+  FieldOverride,
+  TrailCliCommandRendering,
+  TrailCliRendering,
+} 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,
+  createSignalTraceRecord,
+  createTraceRecord,
+  getTraceContext,
+  getTraceSink,
+  NOOP_SINK,
+  registerTraceSink,
+  TRACE_CONTEXT_KEY,
+  traceContextFromRecord,
+  writeActivationTraceRecord,
+  writeSignalTraceRecord,
+} 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,
+  validateOutput,
+  formatZodIssues,
+  zodToJsonSchema,
+} from './validation.js';
+export {
+  stripDefaultWrappers,
+  stripDefaultsFromShape,
+} from './zod-wrappers.js';
+
+// Serialization
+export { serializeError, deserializeError } from './serialization.js';
+export type { SerializedError } from './serialization.js';
+
+// Resilience
+export {
+  retry,
+  withTimeout,
+  shouldRetry,
+  deriveBackoffDelay,
+} from './resilience.js';
+export type { RetryOptions } from './resilience.js';
+
+// Fetch — fromFetch is available as Result.fromFetch()
+
+// Branded types
+export {
+  brand,
+  unbrand,
+  uuid,
+  email,
+  nonEmptyString,
+  positiveInt,
+  shortId,
+  deriveIdHash,
+} from './branded.js';
+export type {
+  Branded,
+  UUID,
+  Email,
+  NonEmptyString,
+  PositiveInt,
+} from './branded.js';
+
+// Path Security
+export { securePath, isPathSafe, deriveSafePath } from './path-security.js';
+
+// Workspace
+export {
+  deriveRelativePath,
+  findWorkspacePackage,
+  findWorkspaceRoot,
+  isInsideWorkspace,
+  listWorkspacePackageDirs,
+  listWorkspacePackages,
+  listWorkspacePatterns,
+} from './workspace.js';
+export type { WorkspacePackage, WorkspaceRootManifest } 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,
+  isNonEmptyString,
+  isPlainObject,
+  hasProperty,
+  assertNever,
+} from './guards.js';
+
+// Collections
+export {
+  chunk,
+  dedupe,
+  groupBy,
+  sortBy,
+  isNonEmptyArray,
+} from './collections.js';
+export type {
+  NonEmptyArray,
+  DeepPartial,
+  Prettify,
+  AtLeastOne,
+} from './collections.js';