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

package/dist/derive.js

@@ -4,6 +4,7 @@
  * Introspects Zod v4 schemas to produce a runtime-agnostic Field[] descriptor
  * that UI consumers (CLI prompts, web forms, etc.) can consume.
  */
+import { ValidationError } from './errors.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -55,11 +56,15 @@ const unwrap = (s) => {
 const fieldTypeByDef = {
     array: (s) => {
         const element = s._zod.def['element'];
-        const elementType = element._zod.def['type'];
+        const { inner } = unwrap(element);
+        const elementType = inner._zod.def['type'];
         if (elementType === 'enum') {
-            const entries = element._zod.def['entries'];
+            const entries = inner._zod.def['entries'];
             return { options: Object.values(entries), type: 'multiselect' };
         }
+        if (elementType !== 'number' && elementType !== 'string') {
+            return null;
+        }
         return {
             options: undefined,
             type: elementType === 'number' ? 'number[]' : 'string[]',
@@ -77,7 +82,7 @@ const fieldTypeByDef = {
 const deriveFieldType = (s) => {
     const defType = s._zod.def['type'];
     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. */
 const buildOptions = (rawOptions, overrideOptions) => {
@@ -93,13 +98,30 @@ const buildOptions = (rawOptions, overrideOptions) => {
         return ov ? { hint: ov.hint, label: ov.label, value: v } : { value: v };
     });
 };
+/**
+ * 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) => {
+    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
 // ---------------------------------------------------------------------------
 /** Derive a single field from a shape entry. */
 const deriveField = (key, value, overrides) => {
     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);
@@ -120,6 +142,8 @@ export const deriveFields = (schema, overrides) => {
         return [];
     }
     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 !== null)
+        .toSorted((a, b) => a.name.localeCompare(b.name));
 };
 //# sourceMappingURL=derive.js.map

package/dist/derive.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAuD9C,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,4DAA4D;AAC5D,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE,CACvC,GAAG;KACA,UAAU,CAAC,iBAAiB,EAAE,OAAO,CAAC;KACtC,UAAU,CAAC,uBAAuB,EAAE,OAAO,CAAC;KAC5C,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAS7C,8DAA8D;AAC9D,MAAM,YAAY,GAAG,CAAC,OAAqB,EAAgB,EAAE,CAC3D,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAiB,CAAC;AAEhD,4DAA4D;AAC5D,MAAM,oBAAoB,GAAG,CAC3B,KAAmB,EACnB,KAA0C,EACpC,EAAE;IACR,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IACxC,CAAC;AACH,CAAC,CAAC;AAEF,yFAAyF;AACzF,MAAM,UAAU,GAAG,CACjB,OAAqB,EACrB,KAIC,EACoB,EAAE;IACvB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAW,CAAC;IACnD,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,oBAAoB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACnC,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,GAAG,CAAC,CAAe,EAAgB,EAAE;IAC/C,MAAM,KAAK,GAAG;QACZ,YAAY,EAAE,SAAoB;QAClC,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,iDAAiD;IACjD,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM;QACR,CAAC;QACD,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACtC,CAAC,CAAC;AAOF,MAAM,cAAc,GAGhB;IACF,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE;QACX,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAA4B,CAAC;QACjE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAW,CAAC;QACrD,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAA2B,CAAC;YACpE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QAClE,CAAC;QACD,IAAI,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;YACzD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,OAAO,EAAE,SAAS;YAClB,IAAI,EAAE,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU;SACzD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACxD,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE;QACV,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAA2B,CAAC;QAChE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC3D,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACtD,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;CACvD,CAAC;AAEF,oEAAoE;AACpE,MAAM,eAAe,GAAG,CAAC,CAAe,EAA2B,EAAE;IACnE,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAW,CAAC;IAC7C,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACnC,CAAC,CAAC;AAEF,gEAAgE;AAChE,MAAM,YAAY,GAAG,CACnB,UAAgC,EAChC,eAAqD,EACvB,EAAE;IAChC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC1B,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAe,EAAY,EAAE;IACzD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;IAC7D,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,eAAe,CACvB,aAAa,OAAO,2CAA2C,UAAU,EAAE,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAEF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,gDAAgD;AAChD,MAAM,WAAW,GAAG,CAClB,GAAW,EACX,KAAmB,EACnB,SAAyC,EAC3B,EAAE;IAChB,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC9C,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,QAAQ,EAAE,KAAK,IAAI,WAAW,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC9E,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,MAAiB,EACjB,SAAyC,EAChC,EAAE;IACX,MAAM,CAAC,GAAG,MAAiC,CAAC;IAC5C,IAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAY,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAA6C,CAAC;IAC9E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CACxD,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,CACnC,CAAC;IACF,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,KAAK,EAAkB,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC;SACjD,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACtD,CAAC,CAAC"}

package/dist/draft.d.ts

@@ -0,0 +1,28 @@
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+export declare 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[];
+}
+export declare const isDraftId: (id: string) => boolean;
+export declare const deriveDraftReport: (topo: Topo) => DraftReport;
+export declare const validateDraftFreeTopo: (topo: Topo) => Result<void, ValidationError>;
+//# sourceMappingURL=draft.d.ts.map

package/dist/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGtC,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC,MAAM,MAAM,mBAAmB,GAC3B,OAAO,GACP,SAAS,GACT,UAAU,GACV,aAAa,GACb,kBAAkB,GAClB,aAAa,CAAC;AAElB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,GAAG,UAAU,CAAC;IAClD,QAAQ,CAAC,GAAG,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAcD,eAAO,MAAM,SAAS,GAAI,IAAI,MAAM,KAAG,OACP,CAAC;AAiPjC,eAAO,MAAM,iBAAiB,GAAI,MAAM,IAAI,KAAG,WAuB9C,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,MAAM,IAAI,KACT,MAAM,CAAC,IAAI,EAAE,eAAe,CAe9B,CAAC"}

package/dist/draft.js

@@ -0,0 +1,157 @@
+import { getContourReferences } from './contour.js';
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+export const DRAFT_ID_PREFIX = '_draft.';
+const replacedByTarget = (value) => {
+    const raw = value;
+    return typeof raw.replacedBy === 'string' ? raw.replacedBy : undefined;
+};
+export const isDraftId = (id) => id.startsWith(DRAFT_ID_PREFIX);
+const dependenciesFromIds = (fromId, toIds, kind) => toIds.map((toId) => ({
+    fromId,
+    kind,
+    toId,
+}));
+const dependencyFromTarget = (fromId, toId, kind) => toId === undefined
+    ? []
+    : [
+        {
+            fromId,
+            kind,
+            toId,
+        },
+    ];
+const trailDependencies = (trail) => [
+    ...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) => dependenciesFromIds(contour.name, getContourReferences(contour).map((reference) => reference.contour), 'schema-reference');
+const signalDependencies = (signal) => [
+    ...dependenciesFromIds(signal.id, signal.from ?? [], 'signal-from'),
+    ...dependencyFromTarget(signal.id, replacedByTarget(signal), 'replaced-by'),
+];
+const resourceDependencies = (resource) => dependencyFromTarget(resource.id, replacedByTarget(resource), 'replaced-by');
+const nodeKind = (id, contours, trails, signals, resources) => {
+    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) => kind === 'unknown' ? 'Node' : kind[0]?.toUpperCase() + kind.slice(1);
+const draftIdsFromKeys = (keys) => [...keys].filter(isDraftId);
+const collectDeclaredDraftIds = (topo) => new Set([
+    ...draftIdsFromKeys(topo.contours.keys()),
+    ...draftIdsFromKeys(topo.trails.keys()),
+    ...draftIdsFromKeys(topo.signals.keys()),
+    ...draftIdsFromKeys(topo.resources.keys()),
+]);
+const findingForDraftId = (id, kind) => ({
+    id,
+    kind,
+    message: `${displayKind(id ? kind : 'unknown')} "${id}" is draft and cannot appear in the established graph.`,
+    rule: 'draft-id',
+});
+const findingForContamination = (id, kind, reason) => {
+    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, contaminatedIds) => {
+    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, contaminatedIds, reasons) => {
+    const reason = contaminationReason(dependency, contaminatedIds);
+    if (reason === undefined) {
+        return false;
+    }
+    contaminatedIds.add(dependency.fromId);
+    reasons.set(dependency.fromId, reason);
+    return true;
+};
+const propagateContaminatedIds = (declaredDraftIds, dependencies) => {
+    const contaminatedIds = new Set(declaredDraftIds);
+    const reasons = new Map();
+    const visit = () => {
+        if (dependencies.some((dependency) => markContaminatedDependency(dependency, contaminatedIds, reasons))) {
+            visit();
+        }
+    };
+    visit();
+    return { contaminatedIds, reasons };
+};
+const contaminationFindingForId = (id, declaredDraftIds, reasons, contours, trails, signals, resources) => {
+    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, contaminatedIds, reasons, contours, trails, signals, resources) => [
+    ...[...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.contours.values()].flatMap(contourDependencies),
+    ...[...topo.trails.values()].flatMap(trailDependencies),
+    ...[...topo.signals.values()].flatMap(signalDependencies),
+    ...[...topo.resources.values()].flatMap(resourceDependencies),
+];
+export const deriveDraftReport = (topo) => {
+    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) => {
+    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 },
+    }));
+};
+//# sourceMappingURL=draft.js.map

package/dist/draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.js","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -4,7 +4,8 @@
  * Provides a structured error hierarchy with category-based mapping
  * to exit codes, HTTP status codes, and JSON-RPC error codes.
  */
-export type ErrorCategory = 'validation' | 'not_found' | 'conflict' | 'permission' | 'timeout' | 'rate_limit' | 'network' | 'internal' | 'auth' | 'cancelled';
+export declare const errorCategories: readonly ["validation", "not_found", "conflict", "permission", "timeout", "rate_limit", "network", "internal", "auth", "cancelled"];
+export type ErrorCategory = (typeof errorCategories)[number];
 export declare abstract class TrailsError extends Error {
     abstract readonly category: ErrorCategory;
     abstract readonly retryable: boolean;
@@ -61,6 +62,10 @@ export declare class NetworkError extends TrailsError {
     readonly retryable: true;
 }
 export declare class InternalError extends TrailsError {
+    readonly category: ErrorCategory;
+    readonly retryable: false;
+}
+export declare class DerivationError extends TrailsError {
     readonly category: "internal";
     readonly retryable: false;
 }
@@ -72,9 +77,62 @@ export declare class CancelledError extends TrailsError {
     readonly category: "cancelled";
     readonly retryable: false;
 }
-export declare const exitCodeMap: Record<ErrorCategory, number>;
-export declare const statusCodeMap: Record<ErrorCategory, number>;
-export declare const jsonRpcCodeMap: Record<ErrorCategory, number>;
+/**
+ * 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 declare 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;
+    });
+}
+export declare const exitCodeMap: {
+    readonly auth: 9;
+    readonly cancelled: 130;
+    readonly conflict: 3;
+    readonly internal: 8;
+    readonly network: 7;
+    readonly not_found: 2;
+    readonly permission: 4;
+    readonly rate_limit: 6;
+    readonly timeout: 5;
+    readonly validation: 1;
+};
+export declare const statusCodeMap: {
+    readonly auth: 401;
+    readonly cancelled: 499;
+    readonly conflict: 409;
+    readonly internal: 500;
+    readonly network: 502;
+    readonly not_found: 404;
+    readonly permission: 403;
+    readonly rate_limit: 429;
+    readonly timeout: 504;
+    readonly validation: 400;
+};
+export declare const jsonRpcCodeMap: {
+    readonly auth: -32600;
+    readonly cancelled: -32603;
+    readonly conflict: -32603;
+    readonly internal: -32603;
+    readonly network: -32603;
+    readonly not_found: -32601;
+    readonly permission: -32600;
+    readonly rate_limit: -32603;
+    readonly timeout: -32603;
+    readonly validation: -32602;
+};
 export declare const retryableMap: Record<ErrorCategory, boolean>;
 /** Type guard: narrows unknown to TrailsError */
 export declare const isTrailsError: (error?: unknown) => error is TrailsError;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -6,6 +6,21 @@
  * to exit codes, HTTP status codes, and JSON-RPC error codes.
  */
 // ---------------------------------------------------------------------------
+// Category
+// ---------------------------------------------------------------------------
+export const errorCategories = [
+    'validation',
+    'not_found',
+    'conflict',
+    'permission',
+    'timeout',
+    'rate_limit',
+    'network',
+    'internal',
+    'auth',
+    'cancelled',
+];
+// ---------------------------------------------------------------------------
 // Base class
 // ---------------------------------------------------------------------------
 export class TrailsError extends Error {
@@ -68,6 +83,10 @@ export class InternalError extends TrailsError {
     category = 'internal';
     retryable = false;
 }
+export class DerivationError extends TrailsError {
+    category = 'internal';
+    retryable = false;
+}
 export class AuthError extends TrailsError {
     category = 'auth';
     retryable = false;
@@ -76,6 +95,30 @@ export class CancelledError extends TrailsError {
     category = 'cancelled';
     retryable = false;
 }
+/**
+ * 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 extends InternalError {
+    category;
+    cause;
+    /** Number of recovery attempts made before exhaustion. */
+    attempts;
+    /** Name of the detour whose recovery was exhausted. */
+    detour;
+    constructor(wrapped, metadata) {
+        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
 // ---------------------------------------------------------------------------
@@ -135,7 +178,7 @@ export const isTrailsError = (error) => error instanceof TrailsError;
 /** Returns true if the error is retryable (TrailsError with retryable category). */
 export const isRetryable = (error) => {
     if (isTrailsError(error)) {
-        return retryableMap[error.category];
+        return error.retryable;
     }
     return false;
 };

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/execute.d.ts

@@ -1,13 +1,15 @@
 /**
  * Centralized trail execution pipeline.
  *
- * Validates input, builds context, composes gates, and runs the
+ * Validates input, builds context, composes layers, and runs the
  * implementation. Surfaces (CLI, MCP, HTTP) delegate here instead
  * of reimplementing the pipeline.
  */
+import type { z } from 'zod';
 import type { AnyTrail } from './trail.js';
-import type { Gate } from './gate.js';
-import type { ProvisionOverrideMap } from './provision.js';
+import type { Layer } from './layer.js';
+import type { ResourceOverrideMap } from './resource.js';
+import type { Topo } from './topo.js';
 import type { TrailContextInit } from './types.js';
 import { Result } from './result.js';
 /** Options for executeTrail. */
@@ -16,17 +18,32 @@ export interface ExecuteTrailOptions {
     readonly ctx?: Partial<TrailContextInit> | undefined;
     /** AbortSignal override (takes final precedence over ctx and factory). */
     readonly abortSignal?: AbortSignal | undefined;
-    /** Gates to compose around the implementation. */
-    readonly gates?: readonly Gate[] | undefined;
+    /** Layers to compose around the implementation. */
+    readonly layers?: readonly Layer[] | undefined;
     /** Factory that produces a base TrailContext (takes precedence over defaults). */
     readonly createContext?: (() => TrailContextInit | Promise<TrailContextInit>) | undefined;
-    /** Explicit provision instance overrides keyed by provision ID. */
-    readonly provisions?: ProvisionOverrideMap | undefined;
-    /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
+    /** Explicit resource instance overrides keyed by resource ID. */
+    readonly resources?: ResourceOverrideMap | undefined;
+    /** Config values for resources that declare a `config` schema, keyed by resource ID. */
     readonly configValues?: Readonly<Record<string, Record<string, unknown>>> | undefined;
+    /** Topo used for signal-driven activation; required for `ctx.fire()` to work. */
+    readonly topo?: Topo | undefined;
+    /**
+     * Override the validation schema used for input validation.
+     *
+     * When a trail is invoked via `ctx.cross()` and the target declares
+     * `crossInput`, the cross function merges `trail.input` with
+     * `trail.crossInput` and passes the merged schema here so validation
+     * accepts both public and composition-only fields.
+     *
+     * Used by the cross execution path; not part of the public API.
+     *
+     * @internal
+     */
+    readonly validationSchema?: z.ZodType | undefined;
 }
 /**
- * Execute a trail through the standard validate-context-gates-run pipeline.
+ * Execute a trail through the standard validate-context-layers-run pipeline.
  *
  * The function never throws -- unexpected exceptions are caught and
  * returned as `Result.err(InternalError)`.

package/dist/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKjE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAarC,gCAAgC;AAChC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;IACrD,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/C,kDAAkD;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,CAAC;IAC7C,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACvD,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,CAAC,EAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjD,SAAS,CAAC;CACf;AAsFD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,QAAQ,EACf,UAAU,OAAO,EACjB,UAAU,mBAAmB,KAC5B,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAsBhC,CAAC"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,KAAK,EAOV,gBAAgB,EACjB,MAAM,YAAY,CAAC;AA0BpB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAcrC,gCAAgC;AAChC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;IACrD,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/C,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACrD,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjD,SAAS,CAAC;IACd,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACjC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,CAAC;CACnD;AAy0BD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,QAAQ,EACf,UAAU,OAAO,EACjB,UAAU,mBAAmB,KAC5B,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CA2BhC,CAAC"}