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

package/src/draft.ts

@@ -1,6 +1,8 @@
+import type { AnyContour } from './contour.js';
+import { getContourReferences } from './contour.js';
 import { ValidationError } from './errors.js';
-import type { AnySignal } from './event.js';
-import type { AnyProvision } from './provision.js';
+import type { AnySignal } from './signal.js';
+import type { AnyResource } from './resource.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
 import type { AnyTrail } from './trail.js';
@@ -9,9 +11,12 @@ export const DRAFT_ID_PREFIX = '_draft.';
 
 export type DraftDependencyKind =
   | 'cross'
-  | 'detour'
-  | 'provision'
+  | 'contour'
+  | 'resource'
   | 'replaced-by'
+  | 'schema-reference'
+  | 'signal-fire'
+  | 'signal-on'
   | 'signal-from';
 
 export interface DraftDependency {
@@ -22,14 +27,14 @@ export interface DraftDependency {
 
 export interface DraftFinding {
   readonly id: string;
-  readonly kind: 'provision' | 'signal' | 'trail' | 'unknown';
+  readonly kind: 'contour' | 'resource' | 'signal' | 'trail' | 'unknown';
   readonly message: string;
   readonly rule: 'draft-contamination' | 'draft-id';
   readonly via?: DraftDependencyKind | undefined;
   readonly dependsOn?: string | undefined;
 }
 
-export interface DraftStateAnalysis {
+export interface DraftReport {
   readonly contaminatedIds: ReadonlySet<string>;
   readonly declaredDraftIds: ReadonlySet<string>;
   readonly dependencies: readonly DraftDependency[];
@@ -41,7 +46,7 @@ interface DraftReason {
   readonly via: DraftDependencyKind;
 }
 
-type TopoNode = AnyProvision | AnySignal | AnyTrail;
+type TopoNode = AnyContour | AnyResource | AnySignal | AnyTrail;
 
 const replacedByTarget = (value: TopoNode): string | undefined => {
   const raw = value as unknown as { replacedBy?: unknown };
@@ -77,59 +82,56 @@ const dependencyFromTarget = (
         },
       ];
 
-const dependenciesFromDetours = (
-  fromId: string,
-  detours: Record<string, string[]>
-): DraftDependency[] =>
-  Object.values(detours).flatMap((targets) =>
-    dependenciesFromIds(fromId, targets, 'detour')
-  );
-
-const trailDependencies = (trail: AnyTrail): DraftDependency[] => {
-  const { detours } = trail as unknown as {
-    detours?: Record<string, string[]>;
-  };
+const trailDependencies = (trail: AnyTrail): DraftDependency[] => [
+  ...dependenciesFromIds(
+    trail.id,
+    (trail.contours ?? []).map((contour) => contour.name),
+    'contour'
+  ),
+  ...dependenciesFromIds(trail.id, trail.crosses, 'cross'),
+  ...dependenciesFromIds(
+    trail.id,
+    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'),
+];
 
-  return [
-    ...dependenciesFromIds(trail.id, trail.crosses, 'cross'),
-    ...dependenciesFromIds(
-      trail.id,
-      trail.provisions.map(({ id }) => id),
-      'provision'
-    ),
-    ...(detours === undefined
-      ? []
-      : dependenciesFromDetours(trail.id, detours)),
-    ...dependencyFromTarget(trail.id, replacedByTarget(trail), 'replaced-by'),
-  ];
-};
+const contourDependencies = (contour: AnyContour): DraftDependency[] =>
+  dependenciesFromIds(
+    contour.name,
+    getContourReferences(contour).map((reference) => reference.contour),
+    'schema-reference'
+  );
 
 const signalDependencies = (signal: AnySignal): DraftDependency[] => [
   ...dependenciesFromIds(signal.id, signal.from ?? [], 'signal-from'),
   ...dependencyFromTarget(signal.id, replacedByTarget(signal), 'replaced-by'),
 ];
 
-const provisionDependencies = (provision: AnyProvision): DraftDependency[] =>
-  dependencyFromTarget(
-    provision.id,
-    replacedByTarget(provision),
-    'replaced-by'
-  );
+const resourceDependencies = (resource: AnyResource): DraftDependency[] =>
+  dependencyFromTarget(resource.id, replacedByTarget(resource), 'replaced-by');
 
 const nodeKind = (
   id: string,
+  contours: ReadonlyMap<string, AnyContour>,
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
-  provisions: ReadonlyMap<string, AnyProvision>
+  resources: ReadonlyMap<string, AnyResource>
 ): DraftFinding['kind'] => {
+  if (contours.has(id)) {
+    return 'contour';
+  }
   if (trails.has(id)) {
     return 'trail';
   }
   if (signals.has(id)) {
     return 'signal';
   }
-  if (provisions.has(id)) {
-    return 'provision';
+  if (resources.has(id)) {
+    return 'resource';
   }
   return 'unknown';
 };
@@ -142,9 +144,10 @@ const draftIdsFromKeys = (keys: Iterable<string>): string[] =>
 
 const collectDeclaredDraftIds = (topo: Topo): ReadonlySet<string> =>
   new Set([
+    ...draftIdsFromKeys(topo.contours.keys()),
     ...draftIdsFromKeys(topo.trails.keys()),
     ...draftIdsFromKeys(topo.signals.keys()),
-    ...draftIdsFromKeys(topo.provisions.keys()),
+    ...draftIdsFromKeys(topo.resources.keys()),
   ]);
 
 const findingForDraftId = (
@@ -237,9 +240,10 @@ const contaminationFindingForId = (
   id: string,
   declaredDraftIds: ReadonlySet<string>,
   reasons: ReadonlyMap<string, DraftReason>,
+  contours: ReadonlyMap<string, AnyContour>,
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
-  provisions: ReadonlyMap<string, AnyProvision>
+  resources: ReadonlyMap<string, AnyResource>
 ): DraftFinding | undefined => {
   if (declaredDraftIds.has(id)) {
     return undefined;
@@ -252,7 +256,7 @@ const contaminationFindingForId = (
 
   return findingForContamination(
     id,
-    nodeKind(id, trails, signals, provisions),
+    nodeKind(id, contours, trails, signals, resources),
     reason
   );
 };
@@ -261,23 +265,25 @@ const collectFindings = (
   declaredDraftIds: ReadonlySet<string>,
   contaminatedIds: ReadonlySet<string>,
   reasons: ReadonlyMap<string, DraftReason>,
+  contours: ReadonlyMap<string, AnyContour>,
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
-  provisions: ReadonlyMap<string, AnyProvision>
+  resources: ReadonlyMap<string, AnyResource>
 ): DraftFinding[] => [
   ...[...declaredDraftIds]
     .toSorted()
     .map((id) =>
-      findingForDraftId(id, nodeKind(id, trails, signals, provisions))
+      findingForDraftId(id, nodeKind(id, contours, trails, signals, resources))
     ),
   ...[...contaminatedIds].toSorted().flatMap((id) => {
     const finding = contaminationFindingForId(
       id,
       declaredDraftIds,
       reasons,
+      contours,
       trails,
       signals,
-      provisions
+      resources
     );
 
     return finding === undefined ? [] : [finding];
@@ -285,12 +291,13 @@ const collectFindings = (
 ];
 
 const collectDependencies = (topo: Topo): DraftDependency[] => [
+  ...[...topo.contours.values()].flatMap(contourDependencies),
   ...[...topo.trails.values()].flatMap(trailDependencies),
   ...[...topo.signals.values()].flatMap(signalDependencies),
-  ...[...topo.provisions.values()].flatMap(provisionDependencies),
+  ...[...topo.resources.values()].flatMap(resourceDependencies),
 ];
 
-export const analyzeDraftState = (topo: Topo): DraftStateAnalysis => {
+export const deriveDraftReport = (topo: Topo): DraftReport => {
   const declaredDraftIds = collectDeclaredDraftIds(topo);
   const dependencies = collectDependencies(topo);
   const { contaminatedIds, reasons } = propagateContaminatedIds(
@@ -301,9 +308,10 @@ export const analyzeDraftState = (topo: Topo): DraftStateAnalysis => {
     declaredDraftIds,
     contaminatedIds,
     reasons,
+    topo.contours,
     topo.trails,
     topo.signals,
-    topo.provisions
+    topo.resources
   );
 
   return {
@@ -314,10 +322,10 @@ export const analyzeDraftState = (topo: Topo): DraftStateAnalysis => {
   };
 };
 
-export const validateEstablishedTopo = (
+export const validateDraftFreeTopo = (
   topo: Topo
 ): Result<void, ValidationError> => {
-  const analysis = analyzeDraftState(topo);
+  const analysis = deriveDraftReport(topo);
 
   if (analysis.findings.length === 0) {
     return Result.ok();

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

@@ -10,17 +10,20 @@
 // Category
 // ---------------------------------------------------------------------------
 
-export type ErrorCategory =
-  | 'validation'
-  | 'not_found'
-  | 'conflict'
-  | 'permission'
-  | 'timeout'
-  | 'rate_limit'
-  | 'network'
-  | 'internal'
-  | 'auth'
-  | 'cancelled';
+export const errorCategories = [
+  'validation',
+  'not_found',
+  'conflict',
+  'permission',
+  'timeout',
+  'rate_limit',
+  'network',
+  'internal',
+  'auth',
+  'cancelled',
+] as const;
+
+export type ErrorCategory = (typeof errorCategories)[number];
 
 // ---------------------------------------------------------------------------
 // Base class
@@ -80,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;
@@ -109,10 +122,17 @@ export class NetworkError extends TrailsError {
 }
 
 export class InternalError extends TrailsError {
+  readonly category: ErrorCategory = 'internal';
+  readonly retryable = false as const;
+}
+
+export class DerivationError extends TrailsError {
   readonly category = 'internal' as const;
   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;
@@ -123,48 +143,225 @@ export class CancelledError extends TrailsError {
   readonly retryable = false as const;
 }
 
+/**
+ * Returned when a detour exhausts all recovery attempts.
+ *
+ * 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.
+ */
+export class RetryExhaustedError<
+  TErr extends TrailsError = TrailsError,
+> extends InternalError {
+  readonly category: ErrorCategory;
+  readonly cause: TErr;
+
+  /** Number of recovery attempts made before exhaustion. */
+  readonly attempts: number;
+
+  /** Name of the detour whose recovery was exhausted. */
+  readonly detour: string;
+
+  constructor(
+    wrapped: TErr,
+    metadata: { readonly attempts: number; readonly detour: string }
+  ) {
+    super(
+      `Recovery exhausted after ${metadata.attempts} attempts: ${wrapped.message}`,
+      { cause: wrapped }
+    );
+    this.cause = wrapped;
+    this.attempts = metadata.attempts;
+    this.detour = metadata.detour;
+    // Dynamic — inherited from wrapped error at construction time.
+    this.category = wrapped.category;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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: Record<ErrorCategory, number> = {
-  auth: 9,
-  cancelled: 130,
-  conflict: 3,
-  internal: 8,
-  network: 7,
-  not_found: 2,
-  permission: 4,
-  rate_limit: 6,
-  timeout: 5,
-  validation: 1,
-} as const;
+export interface ErrorCategoryCodes {
+  readonly exit: number;
+  readonly http: number;
+  readonly jsonRpc: number;
+}
 
-export const statusCodeMap: Record<ErrorCategory, number> = {
-  auth: 401,
-  cancelled: 499,
-  conflict: 409,
-  internal: 500,
-  network: 502,
-  not_found: 404,
-  permission: 403,
-  rate_limit: 429,
-  timeout: 504,
-  validation: 400,
-} as const;
+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>;
 
-export const jsonRpcCodeMap: Record<ErrorCategory, number> = {
-  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;
+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,
@@ -190,7 +387,7 @@ export const isTrailsError = (error?: unknown): error is TrailsError =>
 /** Returns true if the error is retryable (TrailsError with retryable category). */
 export const isRetryable = (error: Error): boolean => {
   if (isTrailsError(error)) {
-    return retryableMap[error.category];
+    return error.retryable;
   }
   return false;
 };