@ontrails/core 1.0.0-beta.14 → 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,104 +12,353 @@ export {
   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,
   TrailContextInit,
+  CrossBatchOptions,
   CrossFn,
-  BasePermit,
+  FireFn,
+  LogLevel,
+  LogFormatter,
+  LogRecord,
+  LogSink,
   PermitRequirement,
   ProgressCallback,
   ProgressEvent,
   Logger,
-  ProvisionLookup,
+  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 { TRAILHEAD_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';
 
-// Provision
+// Resource
 export {
-  createProvisionLookup,
-  findDuplicateProvisionId,
-  isProvision,
-  provision,
-} from './provision.js';
+  createResourceLookup,
+  findDuplicateResourceId,
+  isResource,
+  resource,
+} from './resource.js';
+export { drainResources, resolveResourceConfig } from './resource-config.js';
 export type {
-  AnyProvision,
-  Provision,
-  ProvisionContext,
-  ProvisionOverrideMap,
-  ProvisionSpec,
-} from './provision.js';
+  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,
   Intent,
   Trail,
   TrailSpec,
   TrailExample,
+  TrailExampleSignalAssertion,
+  TrailVisibility,
 } from './trail.js';
+export {
+  filterSurfaceTrails,
+  matchesTrailPattern,
+  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 { TrailInput, TrailOutput, TrailResult } from './type-utils.js';
+export type {
+  CrossInput,
+  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 { event } from './event.js';
-export type { AnyEvent, Event, EventSpec } from './event.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 {
-  createMockTopoStore,
-  createTopoStore,
-  topoStore,
-} from './topo-store.js';
-export type {
-  MockTopoStoreSeed,
-  ReadOnlyTopoStore,
-  TopoStoreExportRecord,
-  TopoStoreProvisionRecord,
-  TopoStoreRef,
-  TopoStoreTrailDetailRecord,
-  TopoStoreTrailRecord,
-} from './topo-store.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,
-  analyzeDraftState,
+  deriveDraftReport,
   isDraftId,
-  validateEstablishedTopo as validateDraftFreeTopo,
+  validateDraftFreeTopo,
 } from './draft.js';
 export type {
   DraftDependency,
   DraftDependencyKind,
   DraftFinding,
-  DraftStateAnalysis,
+  DraftReport,
 } from './draft.js';
 
 // Topo validation
@@ -116,22 +366,94 @@ export { validateTopo } from './validate-topo.js';
 export type { TopoIssue } from './validate-topo.js';
 export { validateEstablishedTopo } from './validate-established-topo.js';
 
-// Gate
-export { composeGates } from './gate.js';
-export type { Gate } from './gate.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,
+  projectLayerFieldName,
+} from './layer-projection.js';
+export type {
+  AttachedLayerScope,
+  AttachedTypedLayer,
+  LayerFieldProjection,
+  LayerFieldRenameReason,
+  ProjectedLayerField,
+  RenamedLayerFieldProjection,
+} from './layer-projection.js';
 
 // Derive
 export { deriveCliPath, deriveFields } from './derive.js';
 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,
+  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,
@@ -139,6 +461,10 @@ export {
   formatZodIssues,
   zodToJsonSchema,
 } from './validation.js';
+export {
+  stripDefaultWrappers,
+  stripDefaultsFromShape,
+} from './zod-wrappers.js';
 
 // Serialization
 export { serializeError, deserializeError } from './serialization.js';
@@ -149,7 +475,7 @@ export {
   retry,
   withTimeout,
   shouldRetry,
-  getBackoffDelay,
+  deriveBackoffDelay,
 } from './resilience.js';
 export type { RetryOptions } from './resilience.js';
 
@@ -164,7 +490,7 @@ export {
   nonEmptyString,
   positiveInt,
   shortId,
-  hashId,
+  deriveIdHash,
 } from './branded.js';
 export type {
   Branded,
@@ -175,18 +501,26 @@ 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 { 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/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 (`cross`,
+ * `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 = 'cross' | '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[] = [
+  'cross',
+  '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,
+      'cross' | '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 };
+};