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

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 52ms on 65 files with 93 rules using 24 threads.
+Finished in 66ms on 99 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @ontrails/core
 
+## 1.0.0-beta.15
+
+### Minor Changes
+
+- 4ad6b25: Lexicon rename cleanup (ADR-0023). Breaking for `@ontrails/core`, `@ontrails/cli`, and `@ontrails/tracing` at the boundary; internal-only churn for `@ontrails/warden`.
+
+  - **core**: the topo store schema renames `topo_provisions` / `topo_trail_provisions` → `topo_resources` / `topo_trail_resources` and `provision_count` → `resource_count`. Schema version bumped v4→v5. Stores still carrying the legacy schema are detected on open, dropped, and recreated from the new DDL — previous topo saves are cleared. Stored-data helpers `listTopoStoreProvisions` / `getTopoStoreProvision` / `readProvisionUsage` / `mapProvisionRow` renamed to their `resource` counterparts. TS row types `TopoTrailProvisionRow` / `TopoProvisionRow` renamed to `TopoTrailResourceRow` / `TopoResourceRow`.
+  - **cli**: CLI output mode env vars are now derived from the topo name per ADR-0023. Legacy globals `TRAILS_JSON` / `TRAILS_JSONL` are no longer honored — a topo named `stash` reads `STASH_JSON` / `STASH_JSONL`. `ActionResultContext` gains a `topoName: string` field; `resolveOutputMode(flags, topoName)` takes a topo name argument.
+  - **tracing**: legacy `.trails/dev/tracker.db` migration path removed. Any user still running a pre-rename beta build with a `tracker.db` should delete it or migrate before upgrading.
+  - **warden**: internal-only rename of `provisionDeclarations` / `provisionExists` rules and their trails to `resourceDeclarations` / `resourceExists`. No behavior change.
+
+## 1.0.0-beta.14
+
+### Minor Changes
+
+- 69057e9: Add hierarchical CLI command trees and structured input, enforce established-only topo exports across trailheads, move developer topo and tracker state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+
 ## 1.0.0-beta.13
 
 ### Minor Changes

package/README.md

@@ -18,7 +18,7 @@ const greet = trail('greet', {
   blaze: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
 });
 
-const app = topo('myapp', { greet });
+const graph = topo('myapp', { greet });
 ```
 
 Trails compose other trails through `crosses` and `ctx.cross()`:
@@ -43,23 +43,24 @@ const onboard = trail('entity.onboard', {
 | --- | --- |
 | `trail(id, spec)` | Define a unit of work with typed input and `Result` output; use `crosses` for composition |
 | `signal(id, spec)` | Define a server-originated notification with a typed data schema |
-| `provision(id, spec)` | Define an infrastructure dependency with `create`, `dispose`, and optional `mock` |
+| `resource(id, spec)` | Define an infrastructure dependency with `create`, `dispose`, and optional `mock` |
 | `topo(name, ...modules)` | Collect trail modules into a queryable topology |
+| `deriveTrail(contour, operation, spec)` | Derive CRUD-shaped trail contracts from a contour on the `@ontrails/core/trails` subpath |
 | `validateTopo(topo)` | Structural validation: cross targets exist, no cycles, examples parse, output schemas present |
 
 ### Execution
 
 | Export | What it does |
 | --- | --- |
-| `executeTrail(trail, rawInput, options?)` | Centralized execution pipeline: validates input, builds context, composes gates, runs the implementation. Never throws -- exceptions become `Result.err(InternalError)`. |
+| `executeTrail(trail, rawInput, options?)` | Centralized execution pipeline: validates input, builds context, composes layers, runs the implementation. Never throws -- exceptions become `Result.err(InternalError)`. |
 | `run(topo, id, input, options?)` | Headless trail execution by ID. Looks up the trail in the topo, then delegates to `executeTrail`. Returns `Result.err(NotFoundError)` if the ID is not registered. |
 
 ```typescript
-// executeTrail — trailheads use this directly
+// executeTrail — surfaces use this directly
 const result = await executeTrail(greet, { name: 'Alice' });
 
-// run — no-trailhead execution by trail ID
-const result = await run(app, 'greet', { name: 'Alice' });
+// run — headless execution by trail ID
+const result = await run(graph, 'greet', { name: 'Alice' });
 if (result.isOk()) console.log(result.value);
 ```
 
@@ -89,7 +90,7 @@ Beyond the `trail(id, spec)` builder, `Topo` exposes these accessors:
 
 | Type | What it describes |
 | --- | --- |
-| `ExecuteTrailOptions` | Options for `executeTrail`: `ctx`, `abortSignal`, `gates`, `createContext` |
+| `ExecuteTrailOptions` | Options for `executeTrail`: `ctx`, `abortSignal`, `layers`, `createContext` |
 | `RunOptions` | Same shape as `ExecuteTrailOptions`; forwarded by `run` |
 
 ### Result
@@ -112,33 +113,37 @@ result.unwrapOr(fallback);   // Value or fallback
 
 ### Error taxonomy
 
-13 error classes across 10 categories. Each maps deterministically to exit codes, HTTP status, and JSON-RPC codes on every trailhead.
+15 error classes across 10 categories. Each maps deterministically to exit codes, HTTP status, and JSON-RPC codes on every surface.
 
 | Category | Classes | HTTP | Retryable |
 | --- | --- | --- | --- |
-| `validation` | `ValidationError`, `AmbiguousError`, `AssertionError` | 400 | No |
+| `validation` | `ValidationError`, `AmbiguousError` | 400 | No |
 | `not_found` | `NotFoundError` | 404 | No |
 | `conflict` | `AlreadyExistsError`, `ConflictError` | 409 | No |
 | `permission` | `PermissionError` | 403 | No |
 | `timeout` | `TimeoutError` | 504 | Yes |
 | `rate_limit` | `RateLimitError` | 429 | Yes |
 | `network` | `NetworkError` | 502 | Yes |
-| `internal` | `InternalError` | 500 | No |
+| `internal` | `InternalError`, `DerivationError`, `AssertionError` | 500 | No |
 | `auth` | `AuthError` | 401 | No |
 | `cancelled` | `CancelledError` | 499 | No |
 
-The developer returns `Result.err(new NotFoundError(...))`. The framework maps it to the right code on every trailhead.
+`RetryExhaustedError` wraps another `TrailsError`, inherits the wrapped error's category for surface mappings, and always reports `retryable: false`.
+
+The developer returns `Result.err(new NotFoundError(...))`. The framework maps it to the right code on every surface.
 
 ### Other exports
 
-- **Schema derivation** -- `deriveFields(schema)` extracts field metadata from Zod for prompts and forms
+- **Schema derivation** -- `deriveFields(schema)` extracts faithfully
+  representable field metadata from Zod for prompts and forms
 - **Validation** -- `validateInput`, `formatZodIssues`, `zodToJsonSchema`
-- **Resilience** -- `retry`, `withTimeout`, `shouldRetry`, `getBackoffDelay`
+- **Resilience** -- `retry`, `withTimeout`, `shouldRetry`, `deriveBackoffDelay`
 - **Serialization** -- `serializeError`, `deserializeError`
 - **Branded types** -- `uuid`, `email`, `nonEmptyString`, `positiveInt`
-- **Gates** -- cross-cutting gates via `composeGates`
+- **Layers** -- cross-cutting layers via `composeLayers`
 - **Guards and collections** -- `isDefined`, `chunk`, `dedupe`, `groupBy`, `sortBy`
 - **Patterns** (`@ontrails/core/patterns`) -- reusable Zod schemas for pagination, bulk ops, timestamps, sorting
+- **Trail factories** (`@ontrails/core/trails`) -- derive CRUD-shaped trail contracts from contours without re-authoring IDs, schemas, examples, or intents
 - **Redaction** (`@ontrails/core/redaction`) -- strip sensitive data before logging
 
 See the [API Reference](../../docs/api-reference.md) for the full list.

package/dist/branded.d.ts

@@ -32,5 +32,5 @@ export declare const shortId: (length?: number) => string;
  * Produce a deterministic hex hash from an input string.
  * Uses a simple FNV-1a 32-bit hash — good enough for non-cryptographic IDs.
  */
-export declare const hashId: (input: string) => string;
+export declare const deriveIdHash: (input: string) => string;
 //# sourceMappingURL=branded.d.ts.map

package/dist/branded.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branded.d.ts","sourceRoot":"","sources":["../src/branded.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAO1C,2CAA2C;AAC3C,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,GAAG,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAA;CAAE,CAAC;AAE3E,kFAAkF;AAClF,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,GAAG,SAAS,MAAM,EACzC,MAAM,GAAG,EACT,OAAO,CAAC,KACP,OAAO,CAAC,CAAC,EAAE,GAAG,CAA6B,CAAC;AAE/C,wDAAwD;AACxD,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,KAAG,CAAe,CAAC;AAMvE,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC3C,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC7C,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAezD,eAAO,MAAM,IAAI,GAAI,OAAO,MAAM,KAAG,MAAM,CAAC,IAAI,EAAE,eAAe,CAShE,CAAC;AAEF,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,MAAM,CAAC,KAAK,EAAE,eAAe,CASlE,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,KACZ,MAAM,CAAC,cAAc,EAAE,eAAe,CAKxC,CAAC;AAEF,eAAO,MAAM,WAAW,GACtB,OAAO,MAAM,KACZ,MAAM,CAAC,WAAW,EAAE,eAAe,CASrC,CAAC;AASF;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,eAAU,KAAG,MAWpC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,KAAG,MAYtC,CAAC"}
+{"version":3,"file":"branded.d.ts","sourceRoot":"","sources":["../src/branded.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAO1C,2CAA2C;AAC3C,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,GAAG,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAA;CAAE,CAAC;AAE3E,kFAAkF;AAClF,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,GAAG,SAAS,MAAM,EACzC,MAAM,GAAG,EACT,OAAO,CAAC,KACP,OAAO,CAAC,CAAC,EAAE,GAAG,CAA6B,CAAC;AAE/C,wDAAwD;AACxD,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,KAAG,CAAe,CAAC;AAMvE,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC3C,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC7C,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAezD,eAAO,MAAM,IAAI,GAAI,OAAO,MAAM,KAAG,MAAM,CAAC,IAAI,EAAE,eAAe,CAShE,CAAC;AAEF,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,MAAM,CAAC,KAAK,EAAE,eAAe,CASlE,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,KACZ,MAAM,CAAC,cAAc,EAAE,eAAe,CAKxC,CAAC;AAEF,eAAO,MAAM,WAAW,GACtB,OAAO,MAAM,KACZ,MAAM,CAAC,WAAW,EAAE,eAAe,CASrC,CAAC;AASF;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,eAAU,KAAG,MAWpC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAY5C,CAAC"}

package/dist/branded.js

@@ -73,7 +73,7 @@ export const shortId = (length = 8) => {
  * Produce a deterministic hex hash from an input string.
  * Uses a simple FNV-1a 32-bit hash — good enough for non-cryptographic IDs.
  */
-export const hashId = (input) => {
+export const deriveIdHash = (input) => {
     // FNV offset basis
     let hash = 2_166_136_261;
     for (let i = 0; i < input.length; i += 1) {

package/dist/branded.js.map

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

package/dist/context.d.ts

@@ -1,4 +1,16 @@
-import type { TrailContext, TrailContextInit } from './types.js';
+import type { TrailContext, TrailContextInit, TraceFn } from './types.js';
+/**
+ * Default passthrough `trace` used when a context is built outside
+ * `executeTrail`. `executeTrail` replaces this with a real sink-writing
+ * implementation. The passthrough runs `fn` without recording anything so
+ * direct `createTrailContext()` callers (tests, ad-hoc compositions) don't
+ * crash when invoking `ctx.trace(...)`.
+ *
+ * Declared `async` so both synchronous throws and async rejections from `fn`
+ * propagate as a rejected promise to the caller — matching the real
+ * sink-writing implementation's error semantics.
+ */
+export declare const passthroughTrace: TraceFn;
 /**
  * Create a TrailContext with sensible defaults.
  *

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMjE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,OAAO,CAAC,gBAAgB,CAAC,KACpC,YAWF,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAM1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAGJ,CAAC;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,OAAO,CAAC,gBAAgB,CAAC,KACpC,YAeF,CAAC"}

package/dist/context.js

@@ -1,4 +1,16 @@
-import { createProvisionLookup } from './provision.js';
+import { createResourceLookup } from './resource.js';
+/**
+ * Default passthrough `trace` used when a context is built outside
+ * `executeTrail`. `executeTrail` replaces this with a real sink-writing
+ * implementation. The passthrough runs `fn` without recording anything so
+ * direct `createTrailContext()` callers (tests, ad-hoc compositions) don't
+ * crash when invoking `ctx.trace(...)`.
+ *
+ * Declared `async` so both synchronous throws and async rejections from `fn`
+ * propagate as a rejected promise to the caller — matching the real
+ * sink-writing implementation's error semantics.
+ */
+export const passthroughTrace = async (_label, fn) => await fn();
 /**
  * Create a TrailContext with sensible defaults.
  *
@@ -12,10 +24,14 @@ export const createTrailContext = (overrides) => {
         cwd: process.cwd(),
         env: process.env,
         requestId: Bun.randomUUIDv7(),
+        trace: passthroughTrace,
         ...overrides,
     };
-    const lookup = overrides?.provision ?? createProvisionLookup(() => ctx);
-    ctx.provision = lookup;
+    const lookup = overrides?.resource ?? createResourceLookup(() => ctx);
+    ctx.resource = lookup;
+    if (ctx.trace === undefined) {
+        ctx.trace = passthroughTrace;
+    }
     return ctx;
 };
 //# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAOvD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,SAAqC,EACvB,EAAE;IAChB,MAAM,GAAG,GAAG;QACV,WAAW,EAAE,IAAI,eAAe,EAAE,CAAC,MAAM;QACzC,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,GAAG,EAAE,OAAO,CAAC,GAAyC;QACtD,SAAS,EAAE,GAAG,CAAC,YAAY,EAAE;QAC7B,GAAG,SAAS;KACU,CAAC;IACzB,MAAM,MAAM,GAAG,SAAS,EAAE,SAAS,IAAI,qBAAqB,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IACxE,GAAG,CAAC,SAAS,GAAG,MAAM,CAAC;IACvB,OAAO,GAAG,CAAC;AACb,CAAC,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAOrD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAY,KAAK,EAC5C,MAAc,EACd,EAAwB,EACZ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,SAAqC,EACvB,EAAE;IAChB,MAAM,GAAG,GAAG;QACV,WAAW,EAAE,IAAI,eAAe,EAAE,CAAC,MAAM;QACzC,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,GAAG,EAAE,OAAO,CAAC,GAAyC;QACtD,SAAS,EAAE,GAAG,CAAC,YAAY,EAAE;QAC7B,KAAK,EAAE,gBAAgB;QACvB,GAAG,SAAS;KACU,CAAC;IACzB,MAAM,MAAM,GAAG,SAAS,EAAE,QAAQ,IAAI,oBAAoB,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IACtE,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC;IACtB,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5B,GAAG,CAAC,KAAK,GAAG,gBAAgB,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC"}

package/dist/contour.d.ts

@@ -0,0 +1,81 @@
+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>>;
+/** 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 declare const CONTOUR_ID_METADATA: unique symbol;
+/**
+ * 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;
+};
+/**
+ * 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 declare const getContourIdMetadata: (schema: unknown) => ContourIdMetadata | undefined;
+/** Inspect a contour schema for fields that reference other contours via `.id()`. */
+export declare const getContourReferences: (contour: AnyContour) => readonly ContourReference[];
+/**
+ * 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 declare 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>;
+/** Existential type for heterogeneous contour collections. */
+export type AnyContour = Contour<string, z.ZodRawShape, string>;
+export {};
+//# sourceMappingURL=contour.d.ts.map

package/dist/contour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contour.d.ts","sourceRoot":"","sources":["../src/contour.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,CAAC,CAAC,WAAW,EAC5B,SAAS,SAAS,MAAM,MAAM,GAAG,MAAM;IAEvC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC;CAC1E;AAED,oEAAoE;AACpE,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;AAE5E,KAAK,aAAa,CAChB,OAAO,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,EAC/B,MAAM,SAAS,MAAM,IACnB,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAM5D,yDAAyD;AACzD,MAAM,MAAM,cAAc,CACxB,OAAO,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,EAC/B,KAAK,SAAS,MAAM,IAClB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AAEtD,yEAAyE;AACzE,MAAM,WAAW,iBAAiB,CAChC,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,SAAS,SAAS,MAAM,GAAG,MAAM;IAEjC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB,CAC/B,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,SAAS,SAAS,MAAM,GAAG,MAAM,CACjC,SAAQ,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,eAA0C,CAAC;AAY3E;;;GAGG;AACH,MAAM,MAAM,eAAe,CACzB,OAAO,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,EACjD,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,SAAS,SAAS,MAAM,GAAG,MAAM,IAC/B,aAAa,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,GAAG;IAClD,iGAAiG;IACjG,QAAQ,CAAC,CAAC,mBAAmB,CAAC,CAAC,EAAE,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;CACtE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CACjB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,MAAM,SAAS,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,EAC5C,SAAS,SAAS,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,IAC7D,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC;CAC1E,CAAC;AA+JF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,OAAO,KACd,iBAAiB,GAAG,SAC2B,CAAC;AAEnD,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,UAAU,KAClB,SAAS,gBAAgB,EAiBvB,CAAC;AAEN;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,GAClB,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,CAAC,CAAC,WAAW,EAC5B,SAAS,SAAS,MAAM,MAAM,GAAG,MAAM,EAEvC,MAAM,KAAK,EACX,OAAO,MAAM,EACb,SAAS,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,KACzC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CA2BlC,CAAC;AAEF,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC"}

package/dist/contour.js

@@ -0,0 +1,176 @@
+import { z } from 'zod';
+/** 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();
+const formatExampleIssues = (issues) => issues
+    .map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+    return `${path}: ${issue.message}`;
+})
+    .join('; ');
+const assertIdentityField = (name, shape, identity) => {
+    if (!Object.hasOwn(shape, identity)) {
+        throw new TypeError(`contour("${name}") identity "${identity}" must match a declared field`);
+    }
+};
+const assertExamples = (name, schema, examples) => {
+    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 = (name, schema, examples) => {
+    if (examples) {
+        assertExamples(name, schema, examples);
+    }
+};
+const brandIdentitySchema = (contour, identity, schema) => {
+    const branded = schema.brand();
+    // 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,
+        });
+    }
+    return branded;
+};
+const attachContourMetadata = (schema, metadata) => {
+    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) => typeof schema === 'object' && schema !== null
+    ? contourIdMetadata.get(schema)
+    : undefined;
+/** Resolve the inner schema from a Zod wrapper (ZodOptional, ZodNullable, etc.). */
+const unwrapInner = (schema) => {
+    const def = schema._def;
+    return (def?.['innerType'] ?? def?.['schema']);
+};
+/**
+ * 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) => {
+    let current = 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) => readMetadata(schema) ?? unwrapToMetadata(schema);
+/** Inspect a contour schema for fields that reference other contours via `.id()`. */
+export const getContourReferences = (contour) => 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 = (name, shape, options) => {
+    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;
+};
+//# sourceMappingURL=contour.js.map

package/dist/contour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contour.js","sourceRoot":"","sources":["../src/contour.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoDxB,uEAAuE;AACvE,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAE3E;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAG,IAAI,OAAO,EAA6B,CAAC;AAkCnE,MAAM,mBAAmB,GAAG,CAAC,MAAmC,EAAU,EAAE,CAC1E,MAAM;KACH,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;IACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACrE,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;AACrC,CAAC,CAAC;KACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAEhB,MAAM,mBAAmB,GAAG,CAI1B,IAAY,EACZ,KAAa,EACb,QAAmB,EACb,EAAE;IACR,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CACjB,YAAY,IAAI,gBAAgB,QAAQ,+BAA+B,CACxE,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CACrB,IAAY,EACZ,MAA2B,EAC3B,QAAkD,EAC5C,EAAE;IACR,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,SAAS,CACjB,YAAY,IAAI,cAAc,KAAK,gBAAgB,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAC9F,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,CACvB,IAAY,EACZ,MAA2B,EAC3B,QAA+D,EACzD,EAAE;IACR,IAAI,QAAQ,EAAE,CAAC;QACb,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAK1B,OAAc,EACd,QAAmB,EACnB,MAAe,EAC6B,EAAE;IAC9C,MAAM,OAAO,GAAI,MAAmC,CAAC,KAAK,EAEvD,CAAC;IAEJ,0EAA0E;IAC1E,uEAAuE;IACvE,gDAAgD;IAChD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE;YAC7B,OAAO;YACP,QAAQ;SACqC,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,OAAqD,CAAC;AAC/D,CAAC,CAAC;AAEF,MAAM,qBAAqB,GAAG,CAK5B,MAA2B,EAC3B,QAMC,EACK,EAAE;IACR,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE;QAC9B,QAAQ,EAAE;YACR,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,QAAQ,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK;SAChB;QACD,EAAE,EAAE;YACF,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ;YAC9B,QAAQ,EAAE,KAAK;SAChB;QACD,QAAQ,EAAE;YACR,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,QAAQ,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK;SAChB;QACD,cAAc,EAAE;YACd,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,QAAQ,CAAC,cAAc;YAC9B,QAAQ,EAAE,KAAK;SAChB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,KAAK;SAChB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,QAAQ,CAAC,IAAI;YACpB,QAAQ,EAAE,KAAK;SAChB;KACF,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,gFAAgF;AAChF,MAAM,YAAY,GAAG,CAAC,MAAe,EAAiC,EAAE,CACtE,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;IAC3C,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC;IAC/B,CAAC,CAAC,SAAS,CAAC;AAEhB,oFAAoF;AACpF,MAAM,WAAW,GAAG,CAAC,MAAe,EAAW,EAAE;IAC/C,MAAM,GAAG,GAAI,MAA6C,CAAC,IAAI,CAAC;IAChE,OAAO,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAY,CAAC;AAC5D,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAG,CAAC,MAAe,EAAiC,EAAE;IAC1E,IAAI,OAAO,GAAY,MAAM,CAAC;IAC9B,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,OAAO,GAAG,KAAK,CAAC;IAClB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,MAAe,EACgB,EAAE,CACjC,YAAY,CAAC,MAAM,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAEnD,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,OAAmB,EACU,EAAE,CAC/B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;KAC1B,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE;IAC3B,IAAI,KAAK,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC/B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,CAAC,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;AAClC,CAAC,CAAC;KACD,QAAQ,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACxB,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;IACxB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC;IAC3C,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAC1C,CAAC;AAEN;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAKrB,IAAW,EACX,KAAa,EACb,OAA0C,EACP,EAAE;IACrC,mBAAmB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEnD,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjD,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CACjB,YAAY,IAAI,gBAAgB,OAAO,CAAC,QAAQ,4BAA4B,CAC7E,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC7E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ;QAC/B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtC,CAAC,CAAC,SAAS,CAAC;IAEd,qBAAqB,CAAC,MAAM,EAAE;QAC5B,QAAQ;QACR,QAAQ;QACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,cAAc;QACd,IAAI;KACL,CAAC,CAAC;IAEH,OAAO,MAA2C,CAAC;AACrD,CAAC,CAAC"}

package/dist/cross-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare const buildCrossValidationSchema: (trailDef: AnyTrail) => z.ZodType | undefined;
+//# sourceMappingURL=cross-schema.d.ts.map

package/dist/cross-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-schema.d.ts","sourceRoot":"","sources":["../src/cross-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GACrC,UAAU,QAAQ,KACjB,CAAC,CAAC,OAAO,GAAG,SAcd,CAAC"}

package/dist/cross-schema.js

@@ -0,0 +1,29 @@
+/**
+ * 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';
+/**
+ * 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) => {
+    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);
+};
+//# sourceMappingURL=cross-schema.js.map

package/dist/cross-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-schema.js","sourceRoot":"","sources":["../src/cross-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CACxC,QAAkB,EACK,EAAE;IACzB,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;QACzB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,wEAAwE;IACxE,mEAAmE;IACnE,yCAAyC;IACzC,IACE,QAAQ,CAAC,KAAK,YAAY,CAAC,CAAC,SAAS;QACrC,QAAQ,CAAC,UAAU,YAAY,CAAC,CAAC,SAAS,EAC1C,CAAC;QACD,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC7D,CAAC,CAAC"}

package/dist/derive.d.ts

@@ -29,6 +29,12 @@ export interface FieldOverride {
         hint?: string | undefined;
     }[] | undefined;
 }
+/**
+ * Derive the canonical ordered CLI path from a trail ID.
+ *
+ * @throws {ValidationError} if the trail ID contains empty segments (e.g. consecutive dots).
+ */
+export declare const deriveCliPath: (trailId: string) => string[];
 /**
  * Derive a runtime-agnostic Field[] from a Zod object schema.
  *

package/dist/derive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAM7B,qEAAqE;AACrE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EACT,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,MAAM,GACN,aAAa,GACb,UAAU,GACV,UAAU,CAAC;IACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EACb,SAAS;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,EAAE,GACH,SAAS,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EACb,SAAS;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,EAAE,GACH,SAAS,CAAC;CACf;AAiKD;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,CAAC,CAAC,OAAO,EACjB,YAAY,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KACxC,KAAK,EAeP,CAAC"}
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQ7B,qEAAqE;AACrE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EACT,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,MAAM,GACN,aAAa,GACb,UAAU,GACV,UAAU,CAAC;IACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EACb,SAAS;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,EAAE,GACH,SAAS,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EACb,SAAS;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,EAAE,GACH,SAAS,CAAC;CACf;AAsJD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,KAAG,MAAM,EASrD,CAAC;AAwBF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,CAAC,CAAC,OAAO,EACjB,YAAY,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KACxC,KAAK,EAiBP,CAAC"}