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

package/src/contour.ts

@@ -0,0 +1,344 @@
+import { z } from 'zod';
+
+import type { Branded } from './branded.js';
+
+/**
+ * Runtime options for a contour declaration.
+ */
+export interface ContourOptions<
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+> {
+  /** Field name that acts as the contour's primary identity. */
+  readonly identity: TIdentity;
+  /** Example instances validated against the contour schema at declaration time. */
+  readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+}
+
+/** Type-level brand name applied to a contour's identity schema. */
+export type ContourIdBrand<TName extends string> = `${Capitalize<TName>}Id`;
+
+type BrandedSchema<
+  TSchema extends z.core.$ZodType,
+  TBrand extends string,
+> = TSchema & z.ZodType<Branded<z.output<TSchema>, TBrand>>;
+
+type BrandableSchema<TSchema extends z.core.$ZodType> = TSchema & {
+  brand<TBrand extends string>(): BrandedSchema<TSchema, TBrand>;
+};
+
+/** Output value of a branded contour identity schema. */
+export type ContourIdValue<
+  TSchema extends z.core.$ZodType,
+  TName extends string,
+> = Branded<z.output<TSchema>, ContourIdBrand<TName>>;
+
+/** Runtime metadata attached to schemas returned from `contour.id()`. */
+export interface ContourIdMetadata<
+  TName extends string = string,
+  TIdentity extends string = string,
+> {
+  readonly contour: TName;
+  readonly identity: TIdentity;
+}
+
+/** A structural contour reference declared by another contour field schema. */
+export interface ContourReference<
+  TName extends string = string,
+  TIdentity extends string = string,
+> extends ContourIdMetadata<TName, TIdentity> {
+  readonly field: string;
+}
+
+/** Symbol used to tag branded contour reference schemas at runtime. */
+export const CONTOUR_ID_METADATA = Symbol.for('@ontrails/core/contour-id');
+
+/**
+ * Module-level WeakMap storing contour identity metadata keyed by schema object.
+ *
+ * First-write-wins: when multiple contours share the same underlying schema
+ * (e.g. `contour('admin', { id: user.shape.id }, ...)`), the first contour to
+ * brand the schema claims it. Subsequent calls skip the write to prevent
+ * silent metadata corruption.
+ */
+const contourIdMetadata = new WeakMap<object, ContourIdMetadata>();
+
+/**
+ * A contour identity schema branded for one contour and tagged with runtime
+ * metadata so the topo layer can recognize declared references later on.
+ */
+export type ContourIdSchema<
+  TSchema extends z.core.$ZodType = z.core.$ZodType,
+  TName extends string = string,
+  TIdentity extends string = string,
+> = BrandedSchema<TSchema, ContourIdBrand<TName>> & {
+  /** @deprecated Use `getContourIdMetadata()` — metadata lives in a WeakMap, not on the schema. */
+  readonly [CONTOUR_ID_METADATA]?: ContourIdMetadata<TName, TIdentity>;
+};
+
+/**
+ * A first-class domain object with schema, identity metadata, and examples.
+ *
+ * A contour behaves like the `ZodObject` it wraps, so standard Zod composition
+ * helpers such as `.pick()`, `.extend()`, and `.array()` continue to work.
+ */
+export type Contour<
+  TName extends string = string,
+  TShape extends z.ZodRawShape = z.ZodRawShape,
+  TIdentity extends keyof TShape & string = keyof TShape & string,
+> = z.ZodObject<TShape> & {
+  readonly kind: 'contour';
+  readonly name: TName;
+  readonly identity: TIdentity;
+  readonly identitySchema: TShape[TIdentity];
+  readonly id: () => ContourIdSchema<TShape[TIdentity], TName, TIdentity>;
+  readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+};
+
+const formatExampleIssues = (issues: readonly z.core.$ZodIssue[]): string =>
+  issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+      return `${path}: ${issue.message}`;
+    })
+    .join('; ');
+
+const assertIdentityField = <
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  name: string,
+  shape: TShape,
+  identity: TIdentity
+): void => {
+  if (!Object.hasOwn(shape, identity)) {
+    throw new TypeError(
+      `contour("${name}") identity "${identity}" must match a declared field`
+    );
+  }
+};
+
+const assertExamples = <TShape extends z.ZodRawShape>(
+  name: string,
+  schema: z.ZodObject<TShape>,
+  examples: readonly z.output<z.ZodObject<TShape>>[]
+): void => {
+  for (const [index, example] of examples.entries()) {
+    const parsed = schema.safeParse(example);
+    if (!parsed.success) {
+      throw new TypeError(
+        `contour("${name}") example ${index} is invalid: ${formatExampleIssues(parsed.error.issues)}`
+      );
+    }
+  }
+};
+
+const validateExamples = <TShape extends z.ZodRawShape>(
+  name: string,
+  schema: z.ZodObject<TShape>,
+  examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined
+): void => {
+  if (examples) {
+    assertExamples(name, schema, examples);
+  }
+};
+
+const brandIdentitySchema = <
+  TSchema extends z.core.$ZodType,
+  TName extends string,
+  TIdentity extends string,
+>(
+  contour: TName,
+  identity: TIdentity,
+  schema: TSchema
+): ContourIdSchema<TSchema, TName, TIdentity> => {
+  const branded = (schema as BrandableSchema<TSchema>).brand<
+    ContourIdBrand<TName>
+  >();
+
+  // First-write-wins: if another contour already claimed this schema object
+  // (possible when Zod v4 brand() returns `this`), preserve the original
+  // metadata rather than silently overwriting it.
+  if (!contourIdMetadata.has(branded)) {
+    contourIdMetadata.set(branded, {
+      contour,
+      identity,
+    } satisfies ContourIdMetadata<TName, TIdentity>);
+  }
+
+  return branded as ContourIdSchema<TSchema, TName, TIdentity>;
+};
+
+const attachContourMetadata = <
+  TName extends string,
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  schema: z.ZodObject<TShape>,
+  metadata: {
+    readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+    readonly idSchema: ContourIdSchema<TShape[TIdentity], TName, TIdentity>;
+    readonly identity: TIdentity;
+    readonly identitySchema: TShape[TIdentity];
+    readonly name: TName;
+  }
+): void => {
+  Object.defineProperties(schema, {
+    examples: {
+      enumerable: true,
+      value: metadata.examples,
+      writable: false,
+    },
+    id: {
+      enumerable: true,
+      value: () => metadata.idSchema,
+      writable: false,
+    },
+    identity: {
+      enumerable: true,
+      value: metadata.identity,
+      writable: false,
+    },
+    identitySchema: {
+      enumerable: true,
+      value: metadata.identitySchema,
+      writable: false,
+    },
+    kind: {
+      enumerable: true,
+      value: 'contour',
+      writable: false,
+    },
+    name: {
+      enumerable: true,
+      value: metadata.name,
+      writable: false,
+    },
+  });
+};
+
+/** Read contour identity metadata from the module-level WeakMap, if present. */
+const readMetadata = (schema: unknown): ContourIdMetadata | undefined =>
+  typeof schema === 'object' && schema !== null
+    ? contourIdMetadata.get(schema)
+    : undefined;
+
+/** Resolve the inner schema from a Zod wrapper (ZodOptional, ZodNullable, etc.). */
+const unwrapInner = (schema: unknown): unknown => {
+  const def = (schema as { _def?: Record<string, unknown> })._def;
+  return (def?.['innerType'] ?? def?.['schema']) as unknown;
+};
+
+/**
+ * Walk through Zod wrapper layers searching for `CONTOUR_ID_METADATA`.
+ *
+ * `.nullish()` produces `ZodOptional<ZodNullable<T>>` — two wrapper levels —
+ * so a single-step unwrap is insufficient. This iterates until it finds the
+ * metadata or exhausts all wrapper layers.
+ */
+const unwrapToMetadata = (schema: unknown): ContourIdMetadata | undefined => {
+  let current: unknown = schema;
+  while (typeof current === 'object' && current !== null) {
+    const inner = unwrapInner(current);
+    if (typeof inner !== 'object' || inner === null) {
+      return undefined;
+    }
+    const metadata = readMetadata(inner);
+    if (metadata !== undefined) {
+      return metadata;
+    }
+    current = inner;
+  }
+  return undefined;
+};
+
+/**
+ * Read contour-reference metadata from a schema returned by `contour.id()`.
+ *
+ * When the schema is wrapped by Zod combinators (`.optional()`, `.nullable()`,
+ * `.default()`, `.nullish()`, etc.) the `CONTOUR_ID_METADATA` symbol lives on
+ * the inner schema, not on the wrapper. The unwrap handles arbitrarily nested
+ * wrapper levels.
+ */
+export const getContourIdMetadata = (
+  schema: unknown
+): ContourIdMetadata | undefined =>
+  readMetadata(schema) ?? unwrapToMetadata(schema);
+
+/** Inspect a contour schema for fields that reference other contours via `.id()`. */
+export const getContourReferences = (
+  contour: AnyContour
+): readonly ContourReference[] =>
+  Object.entries(contour.shape)
+    .flatMap(([field, schema]) => {
+      if (field === contour.identity) {
+        return [];
+      }
+      const metadata = getContourIdMetadata(schema);
+      if (metadata === undefined) {
+        return [];
+      }
+
+      return [{ field, ...metadata }];
+    })
+    .toSorted((left, right) =>
+      left.field === right.field
+        ? left.contour.localeCompare(right.contour)
+        : left.field.localeCompare(right.field)
+    );
+
+/**
+ * Create a contour definition from a raw Zod object shape.
+ *
+ * @example
+ * ```typescript
+ * const user = contour(
+ *   'user',
+ *   {
+ *     id: z.string().uuid(),
+ *     email: z.string().email(),
+ *     name: z.string(),
+ *   },
+ *   { identity: 'id' }
+ * );
+ * ```
+ */
+export const contour = <
+  TName extends string,
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  name: TName,
+  shape: TShape,
+  options: ContourOptions<TShape, TIdentity>
+): Contour<TName, TShape, TIdentity> => {
+  assertIdentityField(name, shape, options.identity);
+
+  const schema = z.object(shape);
+  validateExamples(name, schema, options.examples);
+
+  const identitySchema = shape[options.identity];
+  if (!identitySchema) {
+    throw new TypeError(
+      `contour("${name}") identity "${options.identity}" must resolve to a schema`
+    );
+  }
+
+  const idSchema = brandIdentitySchema(name, options.identity, identitySchema);
+  const examples = options.examples
+    ? Object.freeze([...options.examples])
+    : undefined;
+
+  attachContourMetadata(schema, {
+    examples,
+    idSchema,
+    identity: options.identity,
+    identitySchema,
+    name,
+  });
+
+  return schema as Contour<TName, TShape, TIdentity>;
+};
+
+/** Existential type for heterogeneous contour collections. */
+export type AnyContour = Contour<string, z.ZodRawShape, string>;

package/src/cross-schema.ts

@@ -0,0 +1,36 @@
+/**
+ * Cross-invocation schema merging for trails with `crossInput`.
+ *
+ * When a trail declares `crossInput`, callers via `ctx.cross()` pass both
+ * public input and composition-only fields. The merged schema validates the
+ * combined shape so `executeTrail` doesn't reject the extra fields.
+ */
+
+import { z } from 'zod';
+
+import type { AnyTrail } from './trail.js';
+
+/**
+ * Build the validation schema for a cross-invoked trail.
+ *
+ * When the target trail declares `crossInput`, returns the intersection of
+ * `trail.input` and `trail.crossInput`. Returns `undefined` when no
+ * `crossInput` is declared, signaling that normal input validation suffices.
+ */
+export const buildCrossValidationSchema = (
+  trailDef: AnyTrail
+): z.ZodType | undefined => {
+  if (!trailDef.crossInput) {
+    return undefined;
+  }
+  // Prefer .merge() for ZodObject pairs — produces a proper merged object
+  // schema that strips unknown keys and exposes .shape. Fall back to
+  // z.intersection for non-object schemas.
+  if (
+    trailDef.input instanceof z.ZodObject &&
+    trailDef.crossInput instanceof z.ZodObject
+  ) {
+    return trailDef.input.merge(trailDef.crossInput);
+  }
+  return z.intersection(trailDef.input, trailDef.crossInput);
+};

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,10 @@ export const DRAFT_ID_PREFIX = '_draft.';
 
 export type DraftDependencyKind =
   | 'cross'
-  | 'detour'
-  | 'provision'
+  | 'contour'
+  | 'resource'
   | 'replaced-by'
+  | 'schema-reference'
   | 'signal-from';
 
 export interface DraftDependency {
@@ -22,14 +25,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 +44,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 +80,54 @@ 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'
+  ),
+  ...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 +140,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 +236,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 +252,7 @@ const contaminationFindingForId = (
 
   return findingForContamination(
     id,
-    nodeKind(id, trails, signals, provisions),
+    nodeKind(id, contours, trails, signals, resources),
     reason
   );
 };
@@ -261,23 +261,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 +287,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 +304,10 @@ export const analyzeDraftState = (topo: Topo): DraftStateAnalysis => {
     declaredDraftIds,
     contaminatedIds,
     reasons,
+    topo.contours,
     topo.trails,
     topo.signals,
-    topo.provisions
+    topo.resources
   );
 
   return {
@@ -314,10 +318,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();