@ontrails/core 1.0.0-beta.13 → 1.0.0-beta.15

package/src/draft.ts

@@ -0,0 +1,338 @@
+import type { AnyContour } from './contour.js';
+import { getContourReferences } from './contour.js';
+import { ValidationError } from './errors.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';
+
+export const DRAFT_ID_PREFIX = '_draft.';
+
+export type DraftDependencyKind =
+  | 'cross'
+  | 'contour'
+  | 'resource'
+  | 'replaced-by'
+  | 'schema-reference'
+  | 'signal-from';
+
+export interface DraftDependency {
+  readonly fromId: string;
+  readonly kind: DraftDependencyKind;
+  readonly toId: string;
+}
+
+export interface DraftFinding {
+  readonly id: string;
+  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 DraftReport {
+  readonly contaminatedIds: ReadonlySet<string>;
+  readonly declaredDraftIds: ReadonlySet<string>;
+  readonly dependencies: readonly DraftDependency[];
+  readonly findings: readonly DraftFinding[];
+}
+
+interface DraftReason {
+  readonly dependsOn: string;
+  readonly via: DraftDependencyKind;
+}
+
+type TopoNode = AnyContour | AnyResource | AnySignal | AnyTrail;
+
+const replacedByTarget = (value: TopoNode): string | undefined => {
+  const raw = value as unknown as { replacedBy?: unknown };
+  return typeof raw.replacedBy === 'string' ? raw.replacedBy : undefined;
+};
+
+export const isDraftId = (id: string): boolean =>
+  id.startsWith(DRAFT_ID_PREFIX);
+
+const dependenciesFromIds = (
+  fromId: string,
+  toIds: readonly string[],
+  kind: DraftDependencyKind
+): DraftDependency[] =>
+  toIds.map((toId) => ({
+    fromId,
+    kind,
+    toId,
+  }));
+
+const dependencyFromTarget = (
+  fromId: string,
+  toId: string | undefined,
+  kind: DraftDependencyKind
+): DraftDependency[] =>
+  toId === undefined
+    ? []
+    : [
+        {
+          fromId,
+          kind,
+          toId,
+        },
+      ];
+
+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'
+  ),
+  ...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 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>,
+  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 (resources.has(id)) {
+    return 'resource';
+  }
+  return 'unknown';
+};
+
+const displayKind = (kind: DraftFinding['kind']): string =>
+  kind === 'unknown' ? 'Node' : kind[0]?.toUpperCase() + kind.slice(1);
+
+const draftIdsFromKeys = (keys: Iterable<string>): string[] =>
+  [...keys].filter(isDraftId);
+
+const collectDeclaredDraftIds = (topo: Topo): ReadonlySet<string> =>
+  new Set([
+    ...draftIdsFromKeys(topo.contours.keys()),
+    ...draftIdsFromKeys(topo.trails.keys()),
+    ...draftIdsFromKeys(topo.signals.keys()),
+    ...draftIdsFromKeys(topo.resources.keys()),
+  ]);
+
+const findingForDraftId = (
+  id: string,
+  kind: DraftFinding['kind']
+): DraftFinding => ({
+  id,
+  kind,
+  message: `${displayKind(id ? kind : 'unknown')} "${id}" is draft and cannot appear in the established graph.`,
+  rule: 'draft-id',
+});
+
+const findingForContamination = (
+  id: string,
+  kind: DraftFinding['kind'],
+  reason: DraftReason
+): DraftFinding => {
+  const dependencyLabel = isDraftId(reason.dependsOn)
+    ? `draft "${reason.dependsOn}"`
+    : `draft-contaminated "${reason.dependsOn}"`;
+
+  return {
+    dependsOn: reason.dependsOn,
+    id,
+    kind,
+    message:
+      `Established ${kind} "${id}" depends on ${dependencyLabel} ` +
+      `via ${reason.via} and cannot appear in the established graph.`,
+    rule: 'draft-contamination',
+    via: reason.via,
+  };
+};
+
+const contaminationReason = (
+  dependency: DraftDependency,
+  contaminatedIds: ReadonlySet<string>
+): DraftReason | undefined => {
+  if (contaminatedIds.has(dependency.fromId)) {
+    return undefined;
+  }
+
+  if (!isDraftId(dependency.toId) && !contaminatedIds.has(dependency.toId)) {
+    return undefined;
+  }
+
+  return {
+    dependsOn: dependency.toId,
+    via: dependency.kind,
+  };
+};
+
+const markContaminatedDependency = (
+  dependency: DraftDependency,
+  contaminatedIds: Set<string>,
+  reasons: Map<string, DraftReason>
+): boolean => {
+  const reason = contaminationReason(dependency, contaminatedIds);
+
+  if (reason === undefined) {
+    return false;
+  }
+
+  contaminatedIds.add(dependency.fromId);
+  reasons.set(dependency.fromId, reason);
+  return true;
+};
+
+const propagateContaminatedIds = (
+  declaredDraftIds: ReadonlySet<string>,
+  dependencies: readonly DraftDependency[]
+): { contaminatedIds: Set<string>; reasons: Map<string, DraftReason> } => {
+  const contaminatedIds = new Set<string>(declaredDraftIds);
+  const reasons = new Map<string, DraftReason>();
+
+  const visit = (): void => {
+    if (
+      dependencies.some((dependency) =>
+        markContaminatedDependency(dependency, contaminatedIds, reasons)
+      )
+    ) {
+      visit();
+    }
+  };
+
+  visit();
+  return { contaminatedIds, reasons };
+};
+
+const contaminationFindingForId = (
+  id: string,
+  declaredDraftIds: ReadonlySet<string>,
+  reasons: ReadonlyMap<string, DraftReason>,
+  contours: ReadonlyMap<string, AnyContour>,
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>,
+  resources: ReadonlyMap<string, AnyResource>
+): DraftFinding | undefined => {
+  if (declaredDraftIds.has(id)) {
+    return undefined;
+  }
+
+  const reason = reasons.get(id);
+  if (reason === undefined) {
+    return undefined;
+  }
+
+  return findingForContamination(
+    id,
+    nodeKind(id, contours, trails, signals, resources),
+    reason
+  );
+};
+
+const collectFindings = (
+  declaredDraftIds: ReadonlySet<string>,
+  contaminatedIds: ReadonlySet<string>,
+  reasons: ReadonlyMap<string, DraftReason>,
+  contours: ReadonlyMap<string, AnyContour>,
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>,
+  resources: ReadonlyMap<string, AnyResource>
+): DraftFinding[] => [
+  ...[...declaredDraftIds]
+    .toSorted()
+    .map((id) =>
+      findingForDraftId(id, nodeKind(id, contours, trails, signals, resources))
+    ),
+  ...[...contaminatedIds].toSorted().flatMap((id) => {
+    const finding = contaminationFindingForId(
+      id,
+      declaredDraftIds,
+      reasons,
+      contours,
+      trails,
+      signals,
+      resources
+    );
+
+    return finding === undefined ? [] : [finding];
+  }),
+];
+
+const collectDependencies = (topo: Topo): DraftDependency[] => [
+  ...[...topo.contours.values()].flatMap(contourDependencies),
+  ...[...topo.trails.values()].flatMap(trailDependencies),
+  ...[...topo.signals.values()].flatMap(signalDependencies),
+  ...[...topo.resources.values()].flatMap(resourceDependencies),
+];
+
+export const deriveDraftReport = (topo: Topo): DraftReport => {
+  const declaredDraftIds = collectDeclaredDraftIds(topo);
+  const dependencies = collectDependencies(topo);
+  const { contaminatedIds, reasons } = propagateContaminatedIds(
+    declaredDraftIds,
+    dependencies
+  );
+  const findings = collectFindings(
+    declaredDraftIds,
+    contaminatedIds,
+    reasons,
+    topo.contours,
+    topo.trails,
+    topo.signals,
+    topo.resources
+  );
+
+  return {
+    contaminatedIds,
+    declaredDraftIds,
+    dependencies,
+    findings,
+  };
+};
+
+export const validateDraftFreeTopo = (
+  topo: Topo
+): Result<void, ValidationError> => {
+  const analysis = deriveDraftReport(topo);
+
+  if (analysis.findings.length === 0) {
+    return Result.ok();
+  }
+
+  return Result.err(
+    new ValidationError(
+      `Established topo validation failed with ${analysis.findings.length} draft issue(s)`,
+      {
+        context: { issues: analysis.findings },
+      }
+    )
+  );
+};

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
@@ -109,6 +112,11 @@ 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;
 }
@@ -123,11 +131,47 @@ 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 trailhead 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;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Taxonomy maps
 // ---------------------------------------------------------------------------
 
-export const exitCodeMap: Record<ErrorCategory, number> = {
+export const exitCodeMap = {
   auth: 9,
   cancelled: 130,
   conflict: 3,
@@ -138,9 +182,9 @@ export const exitCodeMap: Record<ErrorCategory, number> = {
   rate_limit: 6,
   timeout: 5,
   validation: 1,
-} as const;
+} as const satisfies Record<ErrorCategory, number>;
 
-export const statusCodeMap: Record<ErrorCategory, number> = {
+export const statusCodeMap = {
   auth: 401,
   cancelled: 499,
   conflict: 409,
@@ -151,9 +195,9 @@ export const statusCodeMap: Record<ErrorCategory, number> = {
   rate_limit: 429,
   timeout: 504,
   validation: 400,
-} as const;
+} as const satisfies Record<ErrorCategory, number>;
 
-export const jsonRpcCodeMap: Record<ErrorCategory, number> = {
+export const jsonRpcCodeMap = {
   auth: -32_600,
   cancelled: -32_603,
   conflict: -32_603,
@@ -164,7 +208,7 @@ export const jsonRpcCodeMap: Record<ErrorCategory, number> = {
   rate_limit: -32_603,
   timeout: -32_603,
   validation: -32_602,
-} as const;
+} as const satisfies Record<ErrorCategory, number>;
 
 export const retryableMap: Record<ErrorCategory, boolean> = {
   auth: false,
@@ -190,7 +234,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;
 };