@ontrails/core 1.0.0-beta.3 → 1.0.0-beta.32

package/src/contour.ts

@@ -0,0 +1,346 @@
+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;
+  /** Reserved for future contour-specific design; trail versioning is trail-only. */
+  readonly version?: never;
+}
+
+/** 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/derive.ts

@@ -1,17 +1,19 @@
 /**
  * Schema-driven field derivation for @ontrails/core
  *
- * Introspects Zod v4 schemas to produce a surface-agnostic Field[] descriptor
- * that UI layers (CLI prompts, web forms, etc.) can consume.
+ * Introspects Zod v4 schemas to produce a runtime-agnostic Field[] descriptor
+ * that UI consumers (CLI prompts, web forms, etc.) can consume.
  */
 
 import type { z } from 'zod';
 
+import { ValidationError } from './errors.js';
+
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
 
-/** A surface-agnostic field descriptor derived from a Zod schema. */
+/** A runtime-agnostic field descriptor derived from a Zod schema. */
 export interface Field {
   readonly name: string;
   readonly type:
@@ -48,6 +50,57 @@ export interface FieldOverride {
     | undefined;
 }
 
+// ---------------------------------------------------------------------------
+// CLI command route projection
+// ---------------------------------------------------------------------------
+
+/** Authored CLI command path shape. Strings are split on whitespace. */
+export type CliCommandPathInput = string | readonly string[];
+
+/**
+ * Authored CLI command alias shape.
+ *
+ * String aliases are sibling leaf aliases. Array aliases are absolute command
+ * paths.
+ */
+export type CliCommandAliasInput = string | readonly string[];
+
+/** Source that produced a resolved CLI command route. */
+export type CliCommandRouteSource = 'derived' | 'trail' | 'surface';
+
+/** Whether a resolved CLI command route is canonical or an alias. */
+export type CliCommandRouteKind = 'alias' | 'canonical';
+
+/** Trail-authored CLI projection metadata. */
+export interface TrailCliProjection {
+  readonly aliases?: readonly CliCommandAliasInput[] | undefined;
+  readonly path?: CliCommandPathInput | undefined;
+}
+
+/** A resolved command path accepted by a CLI surface for one trail. */
+export interface CliCommandRoute {
+  readonly kind: CliCommandRouteKind;
+  readonly path: readonly string[];
+  readonly source: CliCommandRouteSource;
+  readonly target: string;
+}
+
+/** Resolved CLI projection for one trail. */
+export interface TrailCliCommandProjection {
+  readonly path: readonly string[];
+  readonly routes: readonly CliCommandRoute[];
+}
+
+interface TrailCliProjectionInput {
+  readonly cli?: CliCommandPathInput | TrailCliProjection | undefined;
+  readonly id: string;
+}
+
+export interface DeriveTrailCliCommandProjectionOptions {
+  readonly aliases?: readonly CliCommandAliasInput[] | undefined;
+  readonly aliasSource?: Extract<CliCommandRouteSource, 'surface' | 'trail'>;
+}
+
 // ---------------------------------------------------------------------------
 // Zod v4 internals accessor
 // ---------------------------------------------------------------------------
@@ -92,7 +145,7 @@ const propagateDescription = (
   }
 };
 
-/** Step one level of optional/default unwrapping. Returns null if not a wrapper type. */
+/** Step one level of transparent wrapper unwrapping. Returns null if not a wrapper type. */
 const unwrapStep = (
   current: ZodInternals,
   state: {
@@ -102,10 +155,16 @@ const unwrapStep = (
   }
 ): ZodInternals | null => {
   const defType = current._zod.def['type'] as string;
-  if (defType !== 'optional' && defType !== 'default') {
+  if (
+    defType !== 'optional' &&
+    defType !== 'default' &&
+    defType !== 'readonly'
+  ) {
     return null;
   }
-  state.required = false;
+  if (defType !== 'readonly') {
+    state.required = false;
+  }
   if (defType === 'default') {
     state.defaultValue = current._zod.def['defaultValue'];
   }
@@ -140,14 +199,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 +229,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,29 +255,192 @@ 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;
+};
+
+const hasWhitespace = (value: string): boolean => /\s/.test(value);
+
+const validateCliSegment = (segment: string, context: string): string => {
+  const normalized = segment.trim();
+  if (normalized.length === 0) {
+    throw new ValidationError(`${context} cannot contain empty segments`);
+  }
+  if (hasWhitespace(normalized)) {
+    throw new ValidationError(
+      `${context} segment "${segment}" cannot contain whitespace`
+    );
+  }
+  return normalized;
+};
+
+const splitCliPathString = (value: string, context: string): string[] => {
+  const segments = value
+    .trim()
+    .split(/\s+/)
+    .filter((segment) => segment.length > 0);
+  if (segments.length === 0) {
+    throw new ValidationError(`${context} cannot be empty`);
+  }
+  return segments.map((segment) => validateCliSegment(segment, context));
+};
+
+/** Normalize an authored CLI command path. */
+export const normalizeCliCommandPath = (
+  value: CliCommandPathInput,
+  context = 'CLI command path'
+): readonly string[] =>
+  typeof value === 'string'
+    ? splitCliPathString(value, context)
+    : value.map((segment) => validateCliSegment(segment, context));
+
+const isTrailCliProjection = (
+  value: CliCommandPathInput | TrailCliProjection
+): value is TrailCliProjection =>
+  typeof value !== 'string' &&
+  !Array.isArray(value) &&
+  value !== null &&
+  typeof value === 'object';
+
+const trailCliProjectionFor = (
+  trail: TrailCliProjectionInput
+): TrailCliProjection | undefined => {
+  if (trail.cli === undefined) {
+    return undefined;
+  }
+  return isTrailCliProjection(trail.cli) ? trail.cli : { path: trail.cli };
+};
+
+const deriveCanonicalCliRoute = (
+  trail: TrailCliProjectionInput
+): CliCommandRoute => {
+  const projection = trailCliProjectionFor(trail);
+  const path =
+    projection?.path === undefined
+      ? deriveCliPath(trail.id)
+      : normalizeCliCommandPath(
+          projection.path,
+          `CLI command path for trail "${trail.id}"`
+        );
+  return {
+    kind: 'canonical',
+    path,
+    source: projection?.path === undefined ? 'derived' : 'trail',
+    target: trail.id,
+  };
+};
+
+const normalizeCliAlias = ({
+  alias,
+  canonicalPath,
+  source,
+  target,
+}: {
+  readonly alias: CliCommandAliasInput;
+  readonly canonicalPath: readonly string[];
+  readonly source: Extract<CliCommandRouteSource, 'surface' | 'trail'>;
+  readonly target: string;
+}): CliCommandRoute => {
+  const context = `CLI command alias for trail "${target}"`;
+  if (typeof alias === 'string') {
+    const segment = alias.trim();
+    if (segment.length === 0) {
+      throw new ValidationError(`${context} cannot be empty`);
+    }
+    if (hasWhitespace(segment)) {
+      throw new ValidationError(
+        `${context} must be a single command segment; use a string array for absolute paths`
+      );
+    }
+    return {
+      kind: 'alias',
+      path: [
+        ...canonicalPath.slice(0, -1),
+        validateCliSegment(segment, context),
+      ],
+      source,
+      target,
+    };
+  }
+  return {
+    kind: 'alias',
+    path: normalizeCliCommandPath(alias, context),
+    source,
+    target,
+  };
+};
+
+/** Derive resolved CLI command routes for one trail. */
+export const deriveTrailCliCommandProjection = (
+  trail: TrailCliProjectionInput,
+  options?: DeriveTrailCliCommandProjectionOptions
+): TrailCliCommandProjection => {
+  const canonical = deriveCanonicalCliRoute(trail);
+  const projection = trailCliProjectionFor(trail);
+  const trailAliases =
+    projection?.aliases?.map((alias) =>
+      normalizeCliAlias({
+        alias,
+        canonicalPath: canonical.path,
+        source: 'trail',
+        target: trail.id,
+      })
+    ) ?? [];
+  const surfaceAliases =
+    options?.aliases?.map((alias) =>
+      normalizeCliAlias({
+        alias,
+        canonicalPath: canonical.path,
+        source: options.aliasSource ?? 'surface',
+        target: trail.id,
+      })
+    ) ?? [];
+
+  return {
+    path: canonical.path,
+    routes: [canonical, ...trailAliases, ...surfaceAliases],
+  };
+};
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
-/**
- * Derive a surface-agnostic Field[] from a Zod object schema.
- *
- * Uses Zod v4's `_zod.def` for introspection. Returns fields sorted by name.
- */
 /** Derive a single field from a shape entry. */
 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);
   return { default: defaultValue, label, name: key, options, required, type };
 };
 
+/**
+ * Derive a runtime-agnostic Field[] from a Zod object schema.
+ *
+ * Uses Zod v4's `_zod.def` for introspection. Returns fields sorted by name.
+ */
 export const deriveFields = (
   schema: z.ZodType,
   overrides?: Record<string, FieldOverride>
@@ -229,5 +458,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/detours.ts

@@ -0,0 +1,8 @@
+/**
+ * Hard upper bound for detour recovery attempts.
+ *
+ * Execution and derived surface/topo projections both clamp declared detour
+ * attempts to this value so runtime behavior and inspectable contracts stay in
+ * lockstep.
+ */
+export const DETOUR_MAX_ATTEMPTS_CAP = 5;