@ontrails/core 1.0.0-beta.4 → 1.0.0-beta.41

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,21 @@
 // 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',
+  'shift',
+  'internal',
+  'auth',
+  'cancelled',
+] as const;
+
+export type ErrorCategory = (typeof errorCategories)[number];
 
 // ---------------------------------------------------------------------------
 // Base class
@@ -65,6 +69,64 @@ export class NotFoundError extends TrailsError {
   readonly retryable = false as const;
 }
 
+export class VersionNotSupportedError extends NotFoundError {
+  readonly reason?: string | undefined;
+  readonly requested?: number | string | undefined;
+  readonly supported?: readonly number[] | undefined;
+  readonly trailId?: string | undefined;
+
+  constructor(
+    message: string,
+    options?: { cause?: Error; context?: Record<string, unknown> }
+  );
+  constructor(
+    trailId: string,
+    requested: number | string,
+    supported: readonly number[],
+    reason?: string | undefined
+  );
+  constructor(
+    messageOrTrailId: string,
+    optionsOrRequested?:
+      | { cause?: Error; context?: Record<string, unknown> }
+      | number
+      | string,
+    supported?: readonly number[],
+    reason?: string | undefined
+  ) {
+    if (supported === undefined) {
+      super(
+        messageOrTrailId,
+        optionsOrRequested as
+          | { cause?: Error; context?: Record<string, unknown> }
+          | undefined
+      );
+      this.name = 'VersionNotSupportedError';
+      return;
+    }
+
+    const requested = optionsOrRequested as number | string;
+    const supportedLabel =
+      supported.length === 0 ? 'none' : supported.join(', ');
+    super(
+      `Trail "${messageOrTrailId}" version ${String(requested)} is not supported (supported: ${supportedLabel})`,
+      {
+        context: {
+          ...(reason === undefined ? {} : { reason }),
+          requested,
+          supported,
+          trailId: messageOrTrailId,
+        },
+      }
+    );
+    this.name = 'VersionNotSupportedError';
+    this.reason = reason;
+    this.requested = requested;
+    this.supported = supported;
+    this.trailId = messageOrTrailId;
+  }
+}
+
 export class AlreadyExistsError extends TrailsError {
   readonly category = 'conflict' as const;
   readonly retryable = false as const;
@@ -80,6 +142,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;
@@ -108,11 +180,34 @@ export class NetworkError extends TrailsError {
   readonly retryable = true as const;
 }
 
+/**
+ * @example
+ * ```ts
+ * return Result.err(new WorkspaceShiftError('workspace changed during check'));
+ * ```
+ *
+ * Raised when the observed workspace substrate moves during one run.
+ *
+ * A shift voids the run's verdict, including passes. Callers can retry on
+ * stable ground without changing their request.
+ */
+export class WorkspaceShiftError extends TrailsError {
+  readonly category = 'shift' as const;
+  readonly retryable = true as const;
+}
+
 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 +218,239 @@ 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.compose()`
+ * 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: 'not_found',
+    ctor: VersionNotSupportedError,
+    name: 'VersionNotSupportedError',
+    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: 'shift',
+    ctor: WorkspaceShiftError,
+    name: 'WorkspaceShiftError',
+    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 },
+  shift: { exit: 10, http: 503, 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],
+  shift: codesByCategory.shift[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,
@@ -175,6 +461,7 @@ export const retryableMap: Record<ErrorCategory, boolean> = {
   not_found: false,
   permission: false,
   rate_limit: true,
+  shift: true,
   timeout: true,
   validation: false,
 } as const;
@@ -190,7 +477,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;
 };