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

package/src/__tests__/validate-topo.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, test } from 'bun:test';
 
 import { z } from 'zod';
 
+import { analyzeDraftState, isDraftId } from '../draft.js';
+import { validateEstablishedTopo } from '../validate-established-topo.js';
 import { provision } from '../provision.js';
 import { Result } from '../result.js';
 import { topo } from '../topo.js';
@@ -78,6 +80,17 @@ describe('validateTopo', () => {
   });
 
   describe('trail crossing', () => {
+    test('draft crossings are allowed in the authored graph', () => {
+      const app = topo('app', {
+        exportTrail: mockTrail('entity.export', {
+          crosses: ['_draft.entity.prepare'],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
     test('trail crossing a non-existent trail fails', () => {
       const app = topo('app', {
         onboard: mockTrail('entity.onboard', {
@@ -150,6 +163,18 @@ describe('validateTopo', () => {
   });
 
   describe('provision declarations', () => {
+    test('draft provision references are allowed in the authored graph', () => {
+      const db = mockProvision('_draft.db.main');
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          provisions: [db],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
     test('trail declaring a registered provision passes', () => {
       const db = mockProvision('db.main');
       const app = topo('app', {
@@ -319,4 +344,146 @@ describe('validateTopo', () => {
     const issues = extractIssues(result);
     expect(issues).toHaveLength(4);
   });
+
+  describe('signal origins', () => {
+    test('draft signal origins are allowed in the authored graph', () => {
+      const app = topo('app', {
+        updated: mockEvent('entity.updated', ['_draft.entity.prepare']),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+  });
+});
+
+describe('draft state analysis', () => {
+  test('detects declared draft ids', () => {
+    const app = topo('app', {
+      draftTrail: mockTrail('_draft.entity.prepare'),
+    });
+
+    const analysis = analyzeDraftState(app);
+
+    expect(analysis.declaredDraftIds.has('_draft.entity.prepare')).toBe(true);
+    expect(analysis.contaminatedIds.has('_draft.entity.prepare')).toBe(true);
+    expect(analysis.findings.map((finding) => finding.rule)).toContain(
+      'draft-id'
+    );
+  });
+
+  test('propagates contamination through dependencies', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['entity.prepare'],
+      }),
+      prepareTrail: mockTrail('entity.prepare', {
+        crosses: ['_draft.entity.store'],
+      }),
+    });
+
+    const analysis = analyzeDraftState(app);
+    const exportFinding = analysis.findings.find(
+      (finding) => finding.id === 'entity.export'
+    );
+
+    expect(analysis.contaminatedIds.has('entity.prepare')).toBe(true);
+    expect(analysis.contaminatedIds.has('entity.export')).toBe(true);
+    expect(exportFinding).toBeDefined();
+    expect(exportFinding?.rule).toBe('draft-contamination');
+  });
+});
+
+describe('validateEstablishedTopo', () => {
+  test('passes for an established topo', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show'),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isOk()).toBe(true);
+  });
+
+  test('fails when draft declarations remain', () => {
+    const app = topo('app', {
+      draftTrail: mockTrail('_draft.entity.prepare'),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('draft-id');
+  });
+
+  test('fails when established trails depend on draft state', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['_draft.entity.prepare'],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('draft-contamination');
+    expect(issues[0]?.message).toContain('entity.export');
+  });
+
+  test('fails when authored structural validation still fails', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['entity.missing'],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('cross-exists');
+  });
+
+  test('fails when provision declarations are not established in the topo', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show', {
+        provisions: [mockProvision('db.main')],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('provision-exists');
+  });
+
+  test('allows authoring-only example issues outside projection checks', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show', {
+        examples: [
+          {
+            expected: { ok: true },
+            input: { name: 'test' },
+            name: 'Has expected',
+          },
+        ],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isOk()).toBe(true);
+  });
+});
+
+describe('isDraftId', () => {
+  test('recognizes the reserved draft prefix', () => {
+    expect(isDraftId('_draft.entity.show')).toBe(true);
+    expect(isDraftId('entity.show')).toBe(false);
+  });
 });

package/src/derive.ts

@@ -7,6 +7,8 @@
 
 import type { z } from 'zod';
 
+import { ValidationError } from './errors.js';
+
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
@@ -140,14 +142,21 @@ interface DerivedFieldType {
   type: Field['type'];
 }
 
-const fieldTypeByDef: Record<string, (s: ZodInternals) => DerivedFieldType> = {
+const fieldTypeByDef: Record<
+  string,
+  (s: ZodInternals) => DerivedFieldType | null
+> = {
   array: (s) => {
     const element = s._zod.def['element'] as unknown as ZodInternals;
-    const elementType = element._zod.def['type'] as string;
+    const { inner } = unwrap(element);
+    const elementType = inner._zod.def['type'] as string;
     if (elementType === 'enum') {
-      const entries = element._zod.def['entries'] as Record<string, string>;
+      const entries = inner._zod.def['entries'] as Record<string, string>;
       return { options: Object.values(entries), type: 'multiselect' };
     }
+    if (elementType !== 'number' && elementType !== 'string') {
+      return null;
+    }
     return {
       options: undefined,
       type: elementType === 'number' ? 'number[]' : 'string[]',
@@ -163,10 +172,10 @@ const fieldTypeByDef: Record<string, (s: ZodInternals) => DerivedFieldType> = {
 };
 
 /** Derive field type and raw options from the unwrapped Zod def. */
-const deriveFieldType = (s: ZodInternals): DerivedFieldType => {
+const deriveFieldType = (s: ZodInternals): DerivedFieldType | null => {
   const defType = s._zod.def['type'] as string;
   const derive = fieldTypeByDef[defType];
-  return derive ? derive(s) : { options: undefined, type: 'string' };
+  return derive ? derive(s) : null;
 };
 
 /** Build options array, merging with overrides when present. */
@@ -189,6 +198,22 @@ const buildOptions = (
   });
 };
 
+/**
+ * Derive the canonical ordered CLI path from a trail ID.
+ *
+ * @throws {ValidationError} if the trail ID contains empty segments (e.g. consecutive dots).
+ */
+export const deriveCliPath = (trailId: string): string[] => {
+  const segments = trailId.split('.');
+  const emptyIndex = segments.findIndex((s) => s.length === 0);
+  if (emptyIndex !== -1) {
+    throw new ValidationError(
+      `Trail ID "${trailId}" contains an empty segment at position ${emptyIndex}`
+    );
+  }
+  return segments;
+};
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -198,9 +223,13 @@ const deriveField = (
   key: string,
   value: ZodInternals,
   overrides?: Record<string, FieldOverride>
-): Field => {
+): Field | null => {
   const { inner, required, defaultValue, description } = unwrap(value);
-  const { type, options: rawOptions } = deriveFieldType(inner);
+  const derived = deriveFieldType(inner);
+  if (!derived) {
+    return null;
+  }
+  const { type, options: rawOptions } = derived;
   const override = overrides?.[key];
   const label = override?.label ?? description ?? humanize(key);
   const options = buildOptions(rawOptions, override?.options);
@@ -229,5 +258,7 @@ export const deriveFields = (
   const fields = Object.entries(shape).map(([key, value]) =>
     deriveField(key, value, overrides)
   );
-  return fields.toSorted((a, b) => a.name.localeCompare(b.name));
+  return fields
+    .filter((field): field is Field => field !== null)
+    .toSorted((a, b) => a.name.localeCompare(b.name));
 };

package/src/draft.ts

@@ -0,0 +1,334 @@
+import { ValidationError } from './errors.js';
+import type { AnySignal } from './event.js';
+import type { AnyProvision } from './provision.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'
+  | 'detour'
+  | 'provision'
+  | 'replaced-by'
+  | 'signal-from';
+
+export interface DraftDependency {
+  readonly fromId: string;
+  readonly kind: DraftDependencyKind;
+  readonly toId: string;
+}
+
+export interface DraftFinding {
+  readonly id: string;
+  readonly kind: 'provision' | 'signal' | 'trail' | 'unknown';
+  readonly message: string;
+  readonly rule: 'draft-contamination' | 'draft-id';
+  readonly via?: DraftDependencyKind | undefined;
+  readonly dependsOn?: string | undefined;
+}
+
+export interface DraftStateAnalysis {
+  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 = AnyProvision | 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 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[]>;
+  };
+
+  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 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 nodeKind = (
+  id: string,
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>,
+  provisions: ReadonlyMap<string, AnyProvision>
+): DraftFinding['kind'] => {
+  if (trails.has(id)) {
+    return 'trail';
+  }
+  if (signals.has(id)) {
+    return 'signal';
+  }
+  if (provisions.has(id)) {
+    return 'provision';
+  }
+  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.trails.keys()),
+    ...draftIdsFromKeys(topo.signals.keys()),
+    ...draftIdsFromKeys(topo.provisions.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>,
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>,
+  provisions: ReadonlyMap<string, AnyProvision>
+): DraftFinding | undefined => {
+  if (declaredDraftIds.has(id)) {
+    return undefined;
+  }
+
+  const reason = reasons.get(id);
+  if (reason === undefined) {
+    return undefined;
+  }
+
+  return findingForContamination(
+    id,
+    nodeKind(id, trails, signals, provisions),
+    reason
+  );
+};
+
+const collectFindings = (
+  declaredDraftIds: ReadonlySet<string>,
+  contaminatedIds: ReadonlySet<string>,
+  reasons: ReadonlyMap<string, DraftReason>,
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>,
+  provisions: ReadonlyMap<string, AnyProvision>
+): DraftFinding[] => [
+  ...[...declaredDraftIds]
+    .toSorted()
+    .map((id) =>
+      findingForDraftId(id, nodeKind(id, trails, signals, provisions))
+    ),
+  ...[...contaminatedIds].toSorted().flatMap((id) => {
+    const finding = contaminationFindingForId(
+      id,
+      declaredDraftIds,
+      reasons,
+      trails,
+      signals,
+      provisions
+    );
+
+    return finding === undefined ? [] : [finding];
+  }),
+];
+
+const collectDependencies = (topo: Topo): DraftDependency[] => [
+  ...[...topo.trails.values()].flatMap(trailDependencies),
+  ...[...topo.signals.values()].flatMap(signalDependencies),
+  ...[...topo.provisions.values()].flatMap(provisionDependencies),
+];
+
+export const analyzeDraftState = (topo: Topo): DraftStateAnalysis => {
+  const declaredDraftIds = collectDeclaredDraftIds(topo);
+  const dependencies = collectDependencies(topo);
+  const { contaminatedIds, reasons } = propagateContaminatedIds(
+    declaredDraftIds,
+    dependencies
+  );
+  const findings = collectFindings(
+    declaredDraftIds,
+    contaminatedIds,
+    reasons,
+    topo.trails,
+    topo.signals,
+    topo.provisions
+  );
+
+  return {
+    contaminatedIds,
+    declaredDraftIds,
+    dependencies,
+    findings,
+  };
+};
+
+export const validateEstablishedTopo = (
+  topo: Topo
+): Result<void, ValidationError> => {
+  const analysis = analyzeDraftState(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/index.ts

@@ -82,17 +82,46 @@ export type { AnyEvent, Event, EventSpec } from './event.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';
+
+// Draft state
+export {
+  DRAFT_ID_PREFIX,
+  analyzeDraftState,
+  isDraftId,
+  validateEstablishedTopo as validateDraftFreeTopo,
+} from './draft.js';
+export type {
+  DraftDependency,
+  DraftDependencyKind,
+  DraftFinding,
+  DraftStateAnalysis,
+} from './draft.js';
 
 // Topo validation
 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';
 
 // Derive
-export { deriveFields } from './derive.js';
+export { deriveCliPath, deriveFields } from './derive.js';
 export type { Field, FieldOverride } from './derive.js';
 
 // Execute