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

package/dist/types.d.ts

@@ -7,9 +7,9 @@ import type { Result } from './result.js';
  */
 export type Implementation<I, O> = (input: I, ctx: TrailContext) => Result<O, Error> | Promise<Result<O, Error>>;
 /** Invoke another trail by id — used for trail composition */
-export type FollowFn = <O>(id: string, input: unknown) => Promise<Result<O, Error>>;
-/** Resolve a service instance from the current trail context. */
-export type ServiceLookup = <T = unknown>(serviceOrId: {
+export type CrossFn = <O>(id: string, input: unknown) => Promise<Result<O, Error>>;
+/** Resolve a provision instance from the current trail context. */
+export type ProvisionLookup = <T = unknown>(provisionOrId: {
     readonly id: string;
 } | string) => T;
 /** Callback for reporting progress from long-running trails */
@@ -33,8 +33,8 @@ export interface Logger {
     fatal(message: string, data?: Record<string, unknown>): void;
     child(context: Record<string, unknown>): Logger;
 }
-/** Context extension key for the invoking surface name. */
-export declare const SURFACE_KEY: "__trails_surface";
+/** Context extension key for the invoking trailhead name. */
+export declare const TRAILHEAD_KEY: "__trails_trailhead";
 /** Minimal permit shape available on TrailContext. Permits extends this. */
 export interface BasePermit {
     readonly id: string;
@@ -43,8 +43,8 @@ export interface BasePermit {
 /** Runtime context threaded through every trail execution */
 export interface TrailContext {
     readonly requestId: string;
-    readonly signal: AbortSignal;
-    readonly follow?: FollowFn | undefined;
+    readonly abortSignal: AbortSignal;
+    readonly cross?: CrossFn | undefined;
     readonly permit?: BasePermit;
     readonly workspaceRoot?: string | undefined;
     readonly logger?: Logger | undefined;
@@ -52,7 +52,7 @@ export interface TrailContext {
     readonly cwd?: string | undefined;
     readonly env?: Record<string, string | undefined> | undefined;
     readonly extensions?: Readonly<Record<string, unknown>> | undefined;
-    readonly service?: ServiceLookup | undefined;
+    readonly provision?: ProvisionLookup | undefined;
 }
 /**
  * Permit requirement declared on a trail spec.
@@ -65,7 +65,7 @@ export type PermitRequirement = {
     readonly scopes: readonly string[];
 } | 'public';
 /** Input shape used to seed a runtime TrailContext before resolution. */
-export type TrailContextInit = Omit<TrailContext, 'service'> & {
-    readonly service?: ServiceLookup | undefined;
+export type TrailContextInit = Omit<TrailContext, 'provision'> & {
+    readonly provision?: ProvisionLookup | undefined;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -1,3 +1,3 @@
-/** Context extension key for the invoking surface name. */
-export const SURFACE_KEY = '__trails_surface';
+/** Context extension key for the invoking trailhead name. */
+export const TRAILHEAD_KEY = '__trails_trailhead';
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAgDA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAG,kBAA2B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAgDA,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAG,oBAA6B,CAAC"}

package/dist/validate-established-topo.d.ts

@@ -0,0 +1,76 @@
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+/**
+ * Validate that a topo is ready for established outputs.
+ *
+ * Established surfaces still require the authored graph to be structurally
+ * valid, and they must also reject any remaining draft state.
+ */
+export declare const validateEstablishedTopo: (topo: Topo) => {
+    readonly error: ValidationError;
+    isOk(): this is {
+        readonly value: never;
+        isOk(): this is /*elided*/ any;
+        isErr(): this is /*elided*/ any;
+        map<U>(fn: (value: never) => U): Result<U, ValidationError>;
+        flatMap<U, F = ValidationError>(fn: (value: never) => Result<U, F>): Result<U, ValidationError | F>;
+        mapErr<F>(_fn: (error: ValidationError) => F): Result<never, F>;
+        match<U>(handlers: {
+            ok: (value: never) => U;
+            err: (error: ValidationError) => U;
+        }): U;
+        unwrap(): never;
+        unwrapOr(_fallback: never): never;
+    };
+    isErr(): this is /*elided*/ any;
+    map<U>(_fn: (value: never) => U): Result<U, ValidationError>;
+    flatMap<U, F = ValidationError>(_fn: (value: never) => Result<U, F>): Result<U, ValidationError | F>;
+    mapErr<F>(fn: (error: ValidationError) => F): Result<never, F>;
+    match<U>(handlers: {
+        ok: (value: never) => U;
+        err: (error: ValidationError) => U;
+    }): U;
+    unwrap(): never;
+    unwrapOr<T>(fallback: T): T;
+} | {
+    readonly value: void;
+    isOk(): this is /*elided*/ any;
+    isErr(): this is {
+        readonly error: never;
+        isOk(): this is {
+            readonly value: never;
+            isOk(): this is /*elided*/ any;
+            isErr(): this is /*elided*/ any;
+            map<U>(fn: (value: never) => U): Result<U, never>;
+            flatMap<U, F = never>(fn: (value: never) => Result<U, F>): Result<U, F>;
+            mapErr<F>(_fn: (error: never) => F): Result<never, F>;
+            match<U>(handlers: {
+                ok: (value: never) => U;
+                err: (error: never) => U;
+            }): U;
+            unwrap(): never;
+            unwrapOr(_fallback: never): never;
+        };
+        isErr(): this is /*elided*/ any;
+        map<U>(_fn: (value: never) => U): Result<U, never>;
+        flatMap<U, F = never>(_fn: (value: never) => Result<U, F>): Result<U, F>;
+        mapErr<F>(fn: (error: never) => F): Result<never, F>;
+        match<U>(handlers: {
+            ok: (value: never) => U;
+            err: (error: never) => U;
+        }): U;
+        unwrap(): never;
+        unwrapOr<T>(fallback: T): T;
+    };
+    map<U>(fn: (value: void) => U): Result<U, never>;
+    flatMap<U, F = never>(fn: (value: void) => Result<U, F>): Result<U, F>;
+    mapErr<F>(_fn: (error: never) => F): Result<void, F>;
+    match<U>(handlers: {
+        ok: (value: void) => U;
+        err: (error: never) => U;
+    }): U;
+    unwrap(): void;
+    unwrapOr(_fallback: void): void;
+};
+//# sourceMappingURL=validate-established-topo.d.ts.map

package/dist/validate-established-topo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-established-topo.d.ts","sourceRoot":"","sources":["../src/validate-established-topo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA0CtC;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYjD,CAAC"}

package/dist/validate-established-topo.js

@@ -0,0 +1,43 @@
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import { validateEstablishedTopo as validateDraftFreeTopo } from './draft.js';
+import { validateTopo } from './validate-topo.js';
+const PROJECTION_BLOCKING_RULES = new Set([
+    'cross-cycle',
+    'cross-exists',
+    'no-self-cross',
+    'provision-exists',
+    'signal-origin-exists',
+]);
+const keepProjectionBlockingIssues = (result) => {
+    if (result.isOk()) {
+        return result;
+    }
+    const issues = result.error.context?.issues;
+    const remainingIssues = issues?.filter((issue) => PROJECTION_BLOCKING_RULES.has(issue.rule));
+    if (remainingIssues === undefined || remainingIssues.length === 0) {
+        return Result.ok();
+    }
+    return Result.err(new ValidationError(`Topo validation failed with ${remainingIssues.length} issue(s)`, {
+        cause: result.error,
+        context: { issues: remainingIssues },
+    }));
+};
+/**
+ * Validate that a topo is ready for established outputs.
+ *
+ * Established surfaces still require the authored graph to be structurally
+ * valid, and they must also reject any remaining draft state.
+ */
+export const validateEstablishedTopo = (topo) => {
+    const structural = keepProjectionBlockingIssues(validateTopo(topo));
+    if (structural.isErr()) {
+        return structural;
+    }
+    const established = validateDraftFreeTopo(topo);
+    if (established.isErr()) {
+        return established;
+    }
+    return Result.ok();
+};
+//# sourceMappingURL=validate-established-topo.js.map

package/dist/validate-established-topo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-established-topo.js","sourceRoot":"","sources":["../src/validate-established-topo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,uBAAuB,IAAI,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE9E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;IACxC,aAAa;IACb,cAAc;IACd,eAAe;IACf,kBAAkB;IAClB,sBAAsB;CACvB,CAAC,CAAC;AAEH,MAAM,4BAA4B,GAAG,CACnC,MAAuC,EACvC,EAAE;IACF,IAAI,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,MAAM,GACV,MAAM,CAAC,KAAK,CAAC,OACd,EAAE,MAAM,CAAC;IACV,MAAM,eAAe,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAC/C,yBAAyB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAC1C,CAAC;IAEF,IAAI,eAAe,KAAK,SAAS,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClE,OAAO,MAAM,CAAC,EAAE,EAAE,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CACf,IAAI,eAAe,CACjB,+BAA+B,eAAe,CAAC,MAAM,WAAW,EAChE;QACE,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE;KACrC,CACF,CACF,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,IAAU,EAAE,EAAE;IACpD,MAAM,UAAU,GAAG,4BAA4B,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,IAAI,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;QACvB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,WAAW,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;QACxB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC,EAAE,EAAE,CAAC;AACrB,CAAC,CAAC"}

package/dist/validate-topo.d.ts

@@ -1,7 +1,7 @@
 /**
  * Structural validation for a Topo graph.
  *
- * Checks trail follow references, example input validity, event origin
+ * Checks trail crossing references, example input validity, event origin
  * references, and output schema completeness. Returns a Result with all
  * issues collected into a single ValidationError.
  */
@@ -16,7 +16,7 @@ export interface TopoIssue {
 /**
  * Validate the structural integrity of a Topo graph.
  *
- * Checks follow references, example inputs, event origins, and output
+ * Checks crossing references, example inputs, event origins, and output
  * schema presence. Returns `Result.ok()` when no issues are found, or
  * `Result.err(ValidationError)` with all issues in the error context.
  */

package/dist/validate-topo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-topo.d.ts","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQtC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAsLD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,MAAM,CAAC,IAAI,EAAE,eAAe,CAoBrE,CAAC"}
+{"version":3,"file":"validate-topo.d.ts","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQtC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAyLD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,MAAM,CAAC,IAAI,EAAE,eAAe,CAoBrE,CAAC"}

package/dist/validate-topo.js

@@ -1,11 +1,12 @@
 /**
  * Structural validation for a Topo graph.
  *
- * Checks trail follow references, example input validity, event origin
+ * Checks trail crossing references, example input validity, event origin
  * references, and output schema completeness. Returns a Result with all
  * issues collected into a single ValidationError.
  */
 import { ValidationError } from './errors.js';
+import { isDraftId } from './draft.js';
 import { Result } from './result.js';
 import { validateInput } from './validation.js';
 // ---------------------------------------------------------------------------
@@ -14,12 +15,12 @@ import { validateInput } from './validation.js';
 const WHITE = 0;
 const GRAY = 1;
 const BLACK = 2;
-/** Build an adjacency list and initial color map from trails with follow. */
-const buildFollowGraph = (trails) => {
+/** Build an adjacency list and initial color map from trails with crossings. */
+const buildCrossGraph = (trails) => {
     const graph = new Map();
     for (const [id, t] of trails) {
-        if (t.follow.length > 0) {
-            graph.set(id, t.follow);
+        if (t.crosses.length > 0) {
+            graph.set(id, t.crosses);
         }
     }
     const color = new Map();
@@ -28,10 +29,10 @@ const buildFollowGraph = (trails) => {
     }
     return { color, graph };
 };
-/** Detect multi-node cycles in the trail follow graph via DFS. */
-const detectFollowCycles = (trails) => {
+/** Detect multi-node cycles in the trail crossing graph via DFS. */
+const detectCrossCycles = (trails) => {
     const issues = [];
-    const { color, graph } = buildFollowGraph(trails);
+    const { color, graph } = buildCrossGraph(trails);
     const dfs = (node, path) => {
         color.set(node, GRAY);
         for (const next of graph.get(node) ?? []) {
@@ -43,7 +44,7 @@ const detectFollowCycles = (trails) => {
                 const cycle = [...path.slice(path.indexOf(next)), next];
                 issues.push({
                     message: `Cycle detected: ${cycle.join(' → ')}`,
-                    rule: 'follow-cycle',
+                    rule: 'cross-cycle',
                     trailId: next,
                 });
             }
@@ -60,37 +61,38 @@ const detectFollowCycles = (trails) => {
     }
     return issues;
 };
-const checkFollows = (trails, topo) => {
+const checkCrosses = (trails, topo) => {
     const issues = [];
     for (const [id, trail] of trails) {
-        for (const followId of trail.follow) {
-            if (followId === id) {
+        for (const crossedId of trail.crosses) {
+            if (crossedId === id) {
                 issues.push({
-                    message: `Trail follows itself`,
-                    rule: 'no-self-follow',
+                    message: `Trail crosses itself`,
+                    rule: 'no-self-cross',
                     trailId: id,
                 });
             }
-            else if (!topo.has(followId)) {
+            else if (!topo.has(crossedId) && !isDraftId(crossedId)) {
                 issues.push({
-                    message: `Follows "${followId}" which is not in the topo`,
-                    rule: 'follow-exists',
+                    message: `Crosses "${crossedId}" which is not in the topo`,
+                    rule: 'cross-exists',
                     trailId: id,
                 });
             }
         }
     }
-    issues.push(...detectFollowCycles(trails));
+    issues.push(...detectCrossCycles(trails));
     return issues;
 };
-const checkServices = (trails, topo) => {
+const checkProvisions = (trails, topo) => {
     const issues = [];
     for (const [id, trail] of trails) {
-        for (const declaredService of trail.services) {
-            if (!topo.hasService(declaredService.id)) {
+        for (const declaredProvision of trail.provisions) {
+            if (!topo.hasProvision(declaredProvision.id) &&
+                !isDraftId(declaredProvision.id)) {
                 issues.push({
-                    message: `Service "${declaredService.id}" is not in the topo`,
-                    rule: 'service-exists',
+                    message: `Provision "${declaredProvision.id}" is not in the topo`,
+                    rule: 'provision-exists',
                     trailId: id,
                 });
             }
@@ -129,17 +131,17 @@ const checkExamples = (trails) => {
     }
     return issues;
 };
-const checkEventOrigins = (events, topo) => {
+const checkSignalOrigins = (signals, topo) => {
     const issues = [];
-    for (const [id, evt] of events) {
+    for (const [id, evt] of signals) {
         if (!evt.from) {
             continue;
         }
         for (const originId of evt.from) {
-            if (!topo.has(originId)) {
+            if (!topo.has(originId) && !isDraftId(originId)) {
                 issues.push({
-                    message: `Event origin "${originId}" is not in the topo`,
-                    rule: 'event-origin-exists',
+                    message: `Signal origin "${originId}" is not in the topo`,
+                    rule: 'signal-origin-exists',
                     trailId: id,
                 });
             }
@@ -153,16 +155,16 @@ const checkEventOrigins = (events, topo) => {
 /**
  * Validate the structural integrity of a Topo graph.
  *
- * Checks follow references, example inputs, event origins, and output
+ * Checks crossing references, example inputs, event origins, and output
  * schema presence. Returns `Result.ok()` when no issues are found, or
  * `Result.err(ValidationError)` with all issues in the error context.
  */
 export const validateTopo = (topo) => {
     const issues = [
-        ...checkFollows(topo.trails, topo),
-        ...checkServices(topo.trails, topo),
+        ...checkCrosses(topo.trails, topo),
+        ...checkProvisions(topo.trails, topo),
         ...checkExamples(topo.trails),
-        ...checkEventOrigins(topo.events, topo),
+        ...checkSignalOrigins(topo.signals, topo),
     ];
     if (issues.length === 0) {
         return Result.ok();

package/dist/validate-topo.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-topo.js","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAYhD,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,MAAM,KAAK,GAAG,CAAC,CAAC;AAChB,MAAM,IAAI,GAAG,CAAC,CAAC;AACf,MAAM,KAAK,GAAG,CAAC,CAAC;AAEhB,6EAA6E;AAC7E,MAAM,gBAAgB,GAAG,CACvB,MAAqC,EAIrC,EAAE;IACF,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;IACnD,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9B,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC,CAAC;AAEF,kEAAkE;AAClE,MAAM,kBAAkB,GAAG,CACzB,MAAqC,EACxB,EAAE;IACf,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAElD,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,IAAc,EAAQ,EAAE;QACjD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACtB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrB,SAAS;YACX,CAAC;YACD,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;YACnC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;gBACf,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;gBACxD,MAAM,CAAC,IAAI,CAAC;oBACV,OAAO,EAAE,mBAAmB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;oBAC/C,IAAI,EAAE,cAAc;oBACpB,OAAO,EAAE,IAAI;iBACd,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;gBACvB,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC,CAAC;IAEF,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC;YAC5B,GAAG,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CACnB,MAAqC,EACrC,IAAU,EACG,EAAE;IACf,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACjC,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACpC,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,CAAC;oBACV,OAAO,EAAE,sBAAsB;oBAC/B,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE,EAAE;iBACZ,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC/B,MAAM,CAAC,IAAI,CAAC;oBACV,OAAO,EAAE,YAAY,QAAQ,4BAA4B;oBACzD,IAAI,EAAE,eAAe;oBACrB,OAAO,EAAE,EAAE;iBACZ,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3C,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,CACpB,MAAqC,EACrC,IAAU,EACG,EAAE;IACf,MAAM,MAAM,GAAgB,EAAE,CAAC;IAE/B,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACjC,KAAK,MAAM,eAAe,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC;gBACzC,MAAM,CAAC,IAAI,CAAC;oBACV,OAAO,EAAE,YAAY,eAAe,CAAC,EAAE,sBAAsB;oBAC7D,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE,EAAE;iBACZ,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CACtB,EAAU,EACV,OAKC,EACD,WAAmE,EACnE,SAAkB,EACL,EAAE;IACf,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,aAAa,CAAC,WAAgC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,OAAO,CAAC,KAAK,KAAK,iBAAiB,EAAE,CAAC;QAC1D,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,YAAY,OAAO,CAAC,IAAI,uCAAuC;YACxE,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,EAAE;SACZ,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,SAAS,EAAE,CAAC;QACjD,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,YAAY,OAAO,CAAC,IAAI,sDAAsD;YACvF,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,EAAE;SACZ,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,CAAC,MAAqC,EAAe,EAAE;IAC3E,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACpB,SAAS;QACX,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,iBAAiB,GAAG,CACxB,MAAqC,EACrC,IAAU,EACG,EAAE;IACf,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YACd,SAAS;QACX,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxB,MAAM,CAAC,IAAI,CAAC;oBACV,OAAO,EAAE,iBAAiB,QAAQ,sBAAsB;oBACxD,IAAI,EAAE,qBAAqB;oBAC3B,OAAO,EAAE,EAAE;iBACZ,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAU,EAAiC,EAAE;IACxE,MAAM,MAAM,GAAG;QACb,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;QAClC,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;QACnC,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC;QAC7B,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;KACxC,CAAC;IAEF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,EAAE,EAAE,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CACf,IAAI,eAAe,CACjB,+BAA+B,MAAM,CAAC,MAAM,WAAW,EACvD;QACE,OAAO,EAAE,EAAE,MAAM,EAAE;KACpB,CACF,CACF,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"validate-topo.js","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./internal/topo-saves": "./src/internal/topo-saves.ts",
+    "./internal/topo-store": "./src/internal/topo-store.ts",
+    "./internal/trails-db": "./src/internal/trails-db.ts",
     "./patterns": "./src/patterns/index.ts",
     "./redaction": "./src/redaction/index.ts",
     "./package.json": "./package.json"

package/src/__tests__/context.test.ts

@@ -23,10 +23,10 @@ describe('createTrailContext', () => {
     expect(ctx.env).toBe(process.env);
   });
 
-  test('provides a non-aborted signal by default', () => {
+  test('provides a non-aborted abortSignal by default', () => {
     const ctx = createTrailContext();
-    expect(ctx.signal).toBeInstanceOf(AbortSignal);
-    expect(ctx.signal.aborted).toBe(false);
+    expect(ctx.abortSignal).toBeInstanceOf(AbortSignal);
+    expect(ctx.abortSignal.aborted).toBe(false);
   });
 
   test('override values take precedence', () => {
@@ -34,17 +34,17 @@ describe('createTrailContext', () => {
     ac.abort();
 
     const ctx = createTrailContext({
+      abortSignal: ac.signal,
       cwd: '/custom/dir',
       env: { CUSTOM: 'yes' },
       requestId: 'custom-id',
-      signal: ac.signal,
       workspaceRoot: '/tmp',
     });
 
     expect(ctx.cwd).toBe('/custom/dir');
     expect(ctx.env).toEqual({ CUSTOM: 'yes' });
     expect(ctx.requestId).toBe('custom-id');
-    expect(ctx.signal.aborted).toBe(true);
+    expect(ctx.abortSignal.aborted).toBe(true);
     expect(ctx.workspaceRoot).toBe('/tmp');
   });
 
@@ -57,14 +57,14 @@ describe('createTrailContext', () => {
     expect(ctx.extensions?.['nested']).toEqual({ key: 'value' });
   });
 
-  test('provides a service accessor backed by extensions', () => {
+  test('provides a provision accessor backed by extensions', () => {
     const widget = { id: 'widget-1' };
     const ctx = createTrailContext({
       extensions: { 'widget.main': widget },
     });
 
-    expect(ctx.service('widget.main')).toBe(widget);
-    expect(ctx.service<{ id: string }>({ id: 'widget.main' }).id).toBe(
+    expect(ctx.provision('widget.main')).toBe(widget);
+    expect(ctx.provision<{ id: string }>({ id: 'widget.main' }).id).toBe(
       'widget-1'
     );
   });

package/src/__tests__/derive.test.ts

@@ -2,13 +2,45 @@ import { describe, test, expect } from 'bun:test';
 
 import { z } from 'zod';
 
-import { deriveFields } from '../derive.js';
+import { deriveCliPath, deriveFields } from '../derive.js';
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
 describe('derive', () => {
+  describe('cli paths', () => {
+    test('top-level trail IDs derive to a one-segment CLI path', () => {
+      expect(deriveCliPath('search')).toEqual(['search']);
+    });
+
+    test('multi-dot trail IDs derive to the full ordered CLI path', () => {
+      expect(deriveCliPath('topo.pin.remove')).toEqual([
+        'topo',
+        'pin',
+        'remove',
+      ]);
+    });
+
+    test('trail IDs with consecutive dots throw a ValidationError', () => {
+      expect(() => deriveCliPath('topo..pin')).toThrow(
+        'Trail ID "topo..pin" contains an empty segment'
+      );
+    });
+
+    test('trail IDs with a leading dot throw a ValidationError', () => {
+      expect(() => deriveCliPath('.pin')).toThrow(
+        'Trail ID ".pin" contains an empty segment'
+      );
+    });
+
+    test('trail IDs with a trailing dot throw a ValidationError', () => {
+      expect(() => deriveCliPath('pin.')).toThrow(
+        'Trail ID "pin." contains an empty segment'
+      );
+    });
+  });
+
   describe('primitive types', () => {
     test('z.string() derives string field', () => {
       const schema = z.object({ name: z.string() });
@@ -119,6 +151,31 @@ describe('derive', () => {
       expect(fields[0]?.type).toBe('string[]');
       expect(fields[0]?.default).toEqual(['a', 'b']);
     });
+
+    test('z.array(z.object(...)) is omitted when it cannot be represented faithfully', () => {
+      const schema = z.object({
+        files: z.array(
+          z.object({
+            content: z.string(),
+            filename: z.string(),
+          })
+        ),
+      });
+
+      expect(deriveFields(schema)).toEqual([]);
+    });
+  });
+
+  describe('unsupported shapes', () => {
+    test('nested objects are omitted when they cannot be represented faithfully', () => {
+      const schema = z.object({
+        filter: z.object({
+          query: z.string(),
+        }),
+      });
+
+      expect(deriveFields(schema)).toEqual([]);
+    });
   });
 
   describe('modifiers', () => {