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

package/dist/transport-error-map.d.ts

@@ -0,0 +1,106 @@
+import type { ErrorCategory, TrailsError } from './errors.js';
+export declare const transportNames: readonly ["cli", "http", "mcp"];
+export type TransportName = (typeof transportNames)[number];
+export type TransportErrorMapper<T> = (error: TrailsError) => T;
+export type TransportErrorMappings<T> = Record<ErrorCategory, T>;
+/**
+ * Union of every transport-specific error code emitted by {@link transportErrorMap}.
+ *
+ * @remarks
+ * Previously parameterised by transport (`TransportErrorCode<'cli'>` etc.), but
+ * the generic collapsed to `number` because the underlying maps were typed as
+ * `Record<ErrorCategory, number>`. With `as const satisfies` on the maps the
+ * per-transport literals are now observable, but TypeScript cannot narrow
+ * `transportErrorMap[transport][error.category]` through a generic
+ * `TTransport` without an unsound cast. The non-generic union honestly reflects
+ * what `mapTransportError` returns at the call site.
+ */
+export type TransportErrorCode = (typeof transportErrorMap)[TransportName][ErrorCategory];
+export declare const createTransportErrorMapper: <T>(mappings: TransportErrorMappings<T>) => TransportErrorMapper<T>;
+export declare const transportErrorMap: {
+    readonly cli: {
+        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;
+    };
+    readonly http: {
+        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;
+    };
+    readonly mcp: {
+        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 transportErrorRegistry: {
+    readonly cli: {
+        readonly map: TransportErrorMapper<9 | 130 | 3 | 8 | 7 | 2 | 4 | 6 | 5 | 1>;
+        readonly values: {
+            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;
+        };
+    };
+    readonly http: {
+        readonly map: TransportErrorMapper<401 | 499 | 409 | 500 | 502 | 404 | 403 | 429 | 504 | 400>;
+        readonly values: {
+            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;
+        };
+    };
+    readonly mcp: {
+        readonly map: TransportErrorMapper<-32600 | -32603 | -32601 | -32602>;
+        readonly values: {
+            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 mapTransportError: (transport: TransportName, error: TrailsError) => TransportErrorCode;
+//# sourceMappingURL=transport-error-map.d.ts.map

package/dist/transport-error-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-error-map.d.ts","sourceRoot":"","sources":["../src/transport-error-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG9D,eAAO,MAAM,cAAc,iCAAkC,CAAC;AAE9D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,KAAK,CAAC,CAAC;AAEhE,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;AAEjE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAC5B,CAAC,OAAO,iBAAiB,CAAC,CAAC,aAAa,CAAC,CAAC,aAAa,CAAC,CAAC;AAE3D,eAAO,MAAM,0BAA0B,GACpC,CAAC,EAAE,UAAU,sBAAsB,CAAC,CAAC,CAAC,KAAG,oBAAoB,CAAC,CAAC,CAEtC,CAAC;AAE7B,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAI4C,CAAC;AAE3E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAazB,CAAC;AAEX,eAAO,MAAM,iBAAiB,GAC5B,WAAW,aAAa,EACxB,OAAO,WAAW,KACjB,kBAAkE,CAAC"}

package/dist/transport-error-map.js

@@ -0,0 +1,24 @@
+import { exitCodeMap, jsonRpcCodeMap, statusCodeMap } from './errors.js';
+export const transportNames = ['cli', 'http', 'mcp'];
+export const createTransportErrorMapper = (mappings) => (error) => mappings[error.category];
+export const transportErrorMap = {
+    cli: exitCodeMap,
+    http: statusCodeMap,
+    mcp: jsonRpcCodeMap,
+};
+export const transportErrorRegistry = {
+    cli: {
+        map: createTransportErrorMapper(transportErrorMap.cli),
+        values: transportErrorMap.cli,
+    },
+    http: {
+        map: createTransportErrorMapper(transportErrorMap.http),
+        values: transportErrorMap.http,
+    },
+    mcp: {
+        map: createTransportErrorMapper(transportErrorMap.mcp),
+        values: transportErrorMap.mcp,
+    },
+};
+export const mapTransportError = (transport, error) => transportErrorMap[transport][error.category];
+//# sourceMappingURL=transport-error-map.js.map

package/dist/transport-error-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-error-map.js","sourceRoot":"","sources":["../src/transport-error-map.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AAuB9D,MAAM,CAAC,MAAM,0BAA0B,GACrC,CAAI,QAAmC,EAA2B,EAAE,CACpE,CAAC,KAAK,EAAE,EAAE,CACR,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAE7B,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,aAAa;IACnB,GAAG,EAAE,cAAc;CACqD,CAAC;AAE3E,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,GAAG,EAAE;QACH,GAAG,EAAE,0BAA0B,CAAC,iBAAiB,CAAC,GAAG,CAAC;QACtD,MAAM,EAAE,iBAAiB,CAAC,GAAG;KAC9B;IACD,IAAI,EAAE;QACJ,GAAG,EAAE,0BAA0B,CAAC,iBAAiB,CAAC,IAAI,CAAC;QACvD,MAAM,EAAE,iBAAiB,CAAC,IAAI;KAC/B;IACD,GAAG,EAAE;QACH,GAAG,EAAE,0BAA0B,CAAC,iBAAiB,CAAC,GAAG,CAAC;QACtD,MAAM,EAAE,iBAAiB,CAAC,GAAG;KAC9B;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,SAAwB,EACxB,KAAkB,EACE,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC"}

package/dist/type-checks.test-d.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Compile-time type assertions for type-utils.
+ *
+ * This file lives in src/ (not __tests__/) so it is included in the
+ * typecheck pass. It contains no runtime code — only type-level
+ * assertions that fail the build when type inference regresses.
+ *
+ * Assertion types are exported to satisfy `noUnusedLocals` but are not
+ * re-exported from the package index.
+ */
+import type { Trail } from './trail.js';
+import type { CrossInput, TrailInput } from './type-utils.js';
+/** A trail with crossInput declared. */
+type CrossTrail = Trail<{
+    name: string;
+}, {
+    id: string;
+}, {
+    forkedFrom: string;
+}>;
+/** A trail without crossInput. */
+type PlainTrail = Trail<{
+    name: string;
+}, {
+    id: string;
+}>;
+type WithCrossInput = CrossInput<CrossTrail>;
+type AssertMerged = WithCrossInput extends {
+    name: string;
+    forkedFrom: string;
+} ? true : false;
+export type Merged = [AssertMerged] extends [true] ? 'pass' : never;
+type WithoutCrossInput = CrossInput<PlainTrail>;
+type BaseInput = TrailInput<PlainTrail>;
+type AssertFallback1 = WithoutCrossInput extends BaseInput ? true : false;
+type AssertFallback2 = BaseInput extends WithoutCrossInput ? true : false;
+export type Fallback = [AssertFallback1, AssertFallback2] extends [true, true] ? 'pass' : never;
+/**
+ * When a trail has crossInput, the blaze's first parameter must include
+ * both the public input fields AND the crossInput fields. Before the fix,
+ * blaze was typed as Implementation<I, O>, losing the CI fields.
+ */
+type CrossBlazeParam = Parameters<CrossTrail['blaze']>[0];
+type AssertBlazeHasCrossFields = CrossBlazeParam extends {
+    name: string;
+    forkedFrom: string;
+} ? true : false;
+export type BlazeWithCross = [AssertBlazeHasCrossFields] extends [true] ? 'pass' : never;
+type PlainBlazeParam = Parameters<PlainTrail['blaze']>[0];
+type AssertPlainBlazeIsInput = PlainBlazeParam extends {
+    name: string;
+} ? true : false;
+type AssertPlainBlazeNoExtra = {
+    name: string;
+} extends PlainBlazeParam ? true : false;
+export type BlazeWithoutCross = [
+    AssertPlainBlazeIsInput,
+    AssertPlainBlazeNoExtra
+] extends [true, true] ? 'pass' : never;
+type AssertDefault = Trail<{
+    x: number;
+}, {
+    y: number;
+}> extends Trail<{
+    x: number;
+}, {
+    y: number;
+}, never> ? true : false;
+export type Default = [AssertDefault] extends [true] ? 'pass' : never;
+export {};
+//# sourceMappingURL=type-checks.test-d.d.ts.map

package/dist/type-checks.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-checks.test-d.d.ts","sourceRoot":"","sources":["../src/type-checks.test-d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAM9D,wCAAwC;AACxC,KAAK,UAAU,GAAG,KAAK,CACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAChB;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACd;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CACvB,CAAC;AAEF,kCAAkC;AAClC,KAAK,UAAU,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAM1D,KAAK,cAAc,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;AAI7C,KAAK,YAAY,GAAG,cAAc,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3E,IAAI,GACJ,KAAK,CAAC;AACV,MAAM,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAMpE,KAAK,iBAAiB,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;AAChD,KAAK,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;AAGxC,KAAK,eAAe,GAAG,iBAAiB,SAAS,SAAS,GAAG,IAAI,GAAG,KAAK,CAAC;AAC1E,KAAK,eAAe,GAAG,SAAS,SAAS,iBAAiB,GAAG,IAAI,GAAG,KAAK,CAAC;AAC1E,MAAM,MAAM,QAAQ,GAAG,CAAC,eAAe,EAAE,eAAe,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,GAC1E,MAAM,GACN,KAAK,CAAC;AAMV;;;;GAIG;AACH,KAAK,eAAe,GAAG,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1D,KAAK,yBAAyB,GAAG,eAAe,SAAS;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB,GACG,IAAI,GACJ,KAAK,CAAC;AACV,MAAM,MAAM,cAAc,GAAG,CAAC,yBAAyB,CAAC,SAAS,CAAC,IAAI,CAAC,GACnE,MAAM,GACN,KAAK,CAAC;AAGV,KAAK,eAAe,GAAG,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1D,KAAK,uBAAuB,GAAG,eAAe,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GACnE,IAAI,GACJ,KAAK,CAAC;AACV,KAAK,uBAAuB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,SAAS,eAAe,GACnE,IAAI,GACJ,KAAK,CAAC;AACV,MAAM,MAAM,iBAAiB,GAAG;IAC9B,uBAAuB;IACvB,uBAAuB;CACxB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,GAClB,MAAM,GACN,KAAK,CAAC;AAOV,KAAK,aAAa,GAChB,KAAK,CAAC;IAAE,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE;IAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,SAAS,KAAK,CAC/C;IAAE,CAAC,EAAE,MAAM,CAAA;CAAE,EACb;IAAE,CAAC,EAAE,MAAM,CAAA;CAAE,EACb,KAAK,CACN,GACG,IAAI,GACJ,KAAK,CAAC;AACZ,MAAM,MAAM,OAAO,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC"}

package/dist/type-checks.test-d.js

@@ -0,0 +1,12 @@
+/**
+ * Compile-time type assertions for type-utils.
+ *
+ * This file lives in src/ (not __tests__/) so it is included in the
+ * typecheck pass. It contains no runtime code — only type-level
+ * assertions that fail the build when type inference regresses.
+ *
+ * Assertion types are exported to satisfy `noUnusedLocals` but are not
+ * re-exported from the package index.
+ */
+export {};
+//# sourceMappingURL=type-checks.test-d.js.map

package/dist/type-checks.test-d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-checks.test-d.js","sourceRoot":"","sources":["../src/type-checks.test-d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/type-utils.d.ts

@@ -4,9 +4,18 @@
 import type { Result } from './result.js';
 import type { AnyTrail, Trail } from './trail.js';
 /** Extract the input type from a Trail. */
-export type TrailInput<T extends AnyTrail> = T extends Trail<infer I, any> ? I : never;
+export type TrailInput<T extends AnyTrail> = T extends Trail<infer I, any, any> ? I : never;
 /** Extract the output type from a Trail. */
-export type TrailOutput<T extends AnyTrail> = T extends Trail<any, infer O> ? O : never;
+export type TrailOutput<T extends AnyTrail> = T extends Trail<any, infer O, any> ? O : never;
+/**
+ * Extract the cross-callable input type from a trail.
+ *
+ * When a trail declares `crossInput`, callers via `ctx.cross()` must pass
+ * both the public input fields and the composition-only fields. This type
+ * merges both schemas so the compiler enforces the full shape at the call
+ * site. Falls back to plain `TrailInput<T>` when no `crossInput` exists.
+ */
+export type CrossInput<T extends AnyTrail> = T extends Trail<infer I, any, infer CI> ? [CI] extends [never] ? I : I & CI : never;
 /**
  * Extracts the full `Result<Output, Error>` type from a trail definition.
  *

package/dist/type-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-utils.d.ts","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAQlD,2CAA2C;AAC3C,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IACvC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C,4CAA4C;AAC5C,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IACxC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAQ5E,kFAAkF;AAClF,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,OAAO,CACnD,CAAC;AAEd,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,QAAQ,CACpD,CAAC"}
+{"version":3,"file":"type-utils.d.ts","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAQlD,2CAA2C;AAC3C,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IACvC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEjD,4CAA4C;AAC5C,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IACxC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IACvC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,GACnC,CAAC,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,GAClB,CAAC,GACD,CAAC,GAAG,EAAE,GACR,KAAK,CAAC;AAEZ;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAQ5E,kFAAkF;AAClF,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,OAAO,CACnD,CAAC;AAEd,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,QAAQ,CACpD,CAAC"}

package/dist/type-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"type-utils.js","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8BH,mCAAmC;AAEnC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,kFAAkF;AAClF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAqB,KAAQ,EAAc,EAAE,CAClE,KAAK,CAAC,KAAK,CAAC;AAEd,+FAA+F;AAC/F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAqB,KAAQ,EAAe,EAAE,CACpE,KAAK,CAAC,MAAM,CAAC"}
+{"version":3,"file":"type-utils.js","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AA6CH,mCAAmC;AAEnC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,kFAAkF;AAClF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAqB,KAAQ,EAAc,EAAE,CAClE,KAAK,CAAC,KAAK,CAAC;AAEd,+FAA+F;AAC/F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAqB,KAAQ,EAAe,EAAE,CACpE,KAAK,CAAC,MAAM,CAAC"}

package/dist/types.d.ts

@@ -1,4 +1,40 @@
+import type { TrailsError } from './errors.js';
 import type { Result } from './result.js';
+import type { Signal } from './signal.js';
+import type { AnyTrail } from './trail.js';
+import type { CrossInput, TrailOutput } from './type-utils.js';
+/** A recovery path that activates when a trail's blaze fails with a matching error. */
+export interface Detour<Input, Output, TErr extends TrailsError = TrailsError> {
+    readonly on: abstract new (...args: any[]) => TErr;
+    readonly maxAttempts?: number | undefined;
+    readonly recover: (attempt: DetourAttempt<Input, TErr>, ctx: TrailContext) => Promise<Result<Output, TrailsError>>;
+}
+/** Context passed to a detour's recover function on each attempt. */
+export interface DetourAttempt<Input, TErr extends TrailsError = TrailsError> {
+    /** 1-indexed attempt number */
+    readonly attempt: number;
+    /** The matched error */
+    readonly error: TErr;
+    /** Original trail input */
+    readonly input: Input;
+}
+type CrossBatchCall<TTarget extends AnyTrail | string = AnyTrail | string> = TTarget extends AnyTrail ? readonly [trail: TTarget, input: CrossInput<TTarget>] : readonly [id: string, input: unknown];
+type CrossBatchResult<TTarget extends AnyTrail | string> = TTarget extends AnyTrail ? Result<TrailOutput<TTarget>, Error> : Result<unknown, Error>;
+type CrossBatchResults<TCalls extends readonly CrossBatchCall[]> = {
+    readonly [K in keyof TCalls]: TCalls[K] extends readonly [
+        infer TTarget,
+        unknown
+    ] ? TTarget extends AnyTrail | string ? CrossBatchResult<TTarget> : never : never;
+};
+/** Runtime options for batch `ctx.cross([...])` calls. */
+export interface CrossBatchOptions {
+    /**
+     * Maximum number of branches to execute concurrently.
+     *
+     * Omit for unbounded concurrency. `1` is equivalent to sequential execution.
+     */
+    readonly concurrency?: number | undefined;
+}
 /**
  * Trail implementation — sync or async.
  *
@@ -6,12 +42,65 @@ import type { Result } from './result.js';
  * normalizes with `await` at every call site, so both forms work transparently.
  */
 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 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: {
+/**
+ * Invoke another trail — used for trail composition.
+ *
+ * Two call shapes:
+ *
+ * - **By trail object** (typed): `ctx.cross(showGist, { id })` — the compiler
+ *   infers `I` and `O` from the trail's schemas, so the result is fully typed.
+ * - **By string id** (untyped escape hatch): `ctx.cross('gist.show', { id })`
+ *   — returns `Result<O, Error>` where `O` defaults to `unknown`.
+ * - **By batch**: `ctx.cross([[showGist, { id }], ['audit.log', payload]])`
+ *   — executes every crossing concurrently and resolves once all results are
+ *   available. Result ordering always matches the input tuple ordering. Pass
+ *   `{ concurrency: N }` as the second argument to limit how many branches
+ *   run at once.
+ */
+export interface CrossFn {
+    <const TCalls extends readonly CrossBatchCall[]>(calls: TCalls, options?: CrossBatchOptions): Promise<CrossBatchResults<TCalls>>;
+    <T extends AnyTrail>(trail: T, input: CrossInput<T>): Promise<Result<TrailOutput<T>, Error>>;
+    <O = unknown>(id: string, input: unknown): Promise<Result<O, Error>>;
+}
+/**
+ * Emit a signal — used for signal-driven activation.
+ *
+ * Fan-out to consumer trails (those with the signal in their `on:` array) is
+ * the framework's responsibility. Producers get `Result.ok(undefined)` unless
+ * the signal id is unknown or the payload fails schema validation. Consumer
+ * errors are logged but do not propagate back to the producer. Consumers fan
+ * out in parallel, each with its own derived context. Runtime cycle
+ * suppression is still signal-id-based against the current fire stack: it
+ * prevents re-entrant loops but can over-suppress legitimate diamond
+ * re-fires, with a debug breadcrumb and a warn emitted when suppression happens.
+ *
+ * Two call shapes are supported:
+ *
+ * - **By id** (base shape): `ctx.fire('order.placed', { ... })`. Matches
+ *   the shape of `ctx.cross`; payload is typed as `unknown` and validated
+ *   against the signal's schema at the fire boundary.
+ * - **By signal value** (progressive disclosure): `ctx.fire(orderPlaced, payload)`
+ *   where `orderPlaced` is a `Signal<T>`. The compiler enforces that
+ *   `payload` matches the signal's declared schema type at the call site,
+ *   on top of the runtime validation.
+ */
+export interface FireFn {
+    <T>(signal: Signal<T>, payload: T): Promise<Result<void, Error>>;
+    (signalId: string, payload: unknown): Promise<Result<void, Error>>;
+}
+/** Resolve a resource instance from the current trail context. */
+export type ResourceLookup = <T = unknown>(resourceOrId: {
     readonly id: string;
 } | string) => T;
+/**
+ * Wrap the execution of `fn` in a child trace span.
+ *
+ * Creates a nested span under the current trail's root trace record, times
+ * the callback, records success or failure (including error category), and
+ * writes the completed span to the registered sink. Errors thrown by `fn`
+ * are recorded on the span and then rethrown — tracing never swallows them.
+ */
+export type TraceFn = <T>(label: string, fn: () => T | Promise<T>) => Promise<T>;
 /** Callback for reporting progress from long-running trails */
 export type ProgressCallback = (event: ProgressEvent) => void;
 /** Structured progress event emitted during trail execution */
@@ -45,6 +134,12 @@ export interface TrailContext {
     readonly requestId: string;
     readonly abortSignal: AbortSignal;
     readonly cross?: CrossFn | undefined;
+    /**
+     * Emit a signal by id. Fans out to every trail with the signal in its
+     * `on:` declaration. Bound by the runner that holds the topo (typically
+     * `run()`); undefined when a context is constructed without topo access.
+     */
+    readonly fire?: FireFn | undefined;
     readonly permit?: BasePermit;
     readonly workspaceRoot?: string | undefined;
     readonly logger?: Logger | undefined;
@@ -52,7 +147,16 @@ export interface TrailContext {
     readonly cwd?: string | undefined;
     readonly env?: Record<string, string | undefined> | undefined;
     readonly extensions?: Readonly<Record<string, unknown>> | undefined;
-    readonly provision?: ProvisionLookup | undefined;
+    readonly resource?: ResourceLookup | undefined;
+    /**
+     * Wrap a callback in a child trace span.
+     *
+     * Always present on contexts produced by `executeTrail` or
+     * `createTrailContext`. Optional on the interface so manually constructed
+     * contexts (tests, ad-hoc compositions) don't have to supply one — call
+     * sites tolerate `undefined` by falling back to a no-op passthrough.
+     */
+    readonly trace?: TraceFn | undefined;
 }
 /**
  * Permit requirement declared on a trail spec.
@@ -65,7 +169,9 @@ export type PermitRequirement = {
     readonly scopes: readonly string[];
 } | 'public';
 /** Input shape used to seed a runtime TrailContext before resolution. */
-export type TrailContextInit = Omit<TrailContext, 'provision'> & {
-    readonly provision?: ProvisionLookup | undefined;
+export type TrailContextInit = Omit<TrailContext, 'resource' | 'trace'> & {
+    readonly resource?: ResourceLookup | undefined;
+    readonly trace?: TraceFn | undefined;
 };
+export {};
 //# 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":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,IAAI,CACjC,KAAK,EAAE,CAAC,EACR,GAAG,EAAE,YAAY,KACd,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AAElD,8DAA8D;AAC9D,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,EACtB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,KACX,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AAE/B,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,GAAG,OAAO,EACxC,aAAa,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,KAC5C,CAAC,CAAC;AAEP,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE9D,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,mFAAmF;AACnF,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CACjD;AAED,6DAA6D;AAC7D,eAAO,MAAM,aAAa,EAAG,oBAA6B,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACtC,QAAQ,CAAC;AAEb,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CAClD,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAM/D,uFAAuF;AACvF,MAAM,WAAW,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAS,WAAW,GAAG,WAAW;IAE3E,QAAQ,CAAC,EAAE,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,CAChB,OAAO,EAAE,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,EACnC,GAAG,EAAE,YAAY,KACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;CAC3C;AAED,qEAAqE;AACrE,MAAM,WAAW,aAAa,CAAC,KAAK,EAAE,IAAI,SAAS,WAAW,GAAG,WAAW;IAC1E,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,KAAK,cAAc,CAAC,OAAO,SAAS,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,IACvE,OAAO,SAAS,QAAQ,GACpB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,GACrD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAE5C,KAAK,gBAAgB,CAAC,OAAO,SAAS,QAAQ,GAAG,MAAM,IACrD,OAAO,SAAS,QAAQ,GACpB,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GACnC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAE7B,KAAK,iBAAiB,CAAC,MAAM,SAAS,SAAS,cAAc,EAAE,IAAI;IACjE,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,SAAS;QACvD,MAAM,OAAO;QACb,OAAO;KACR,GACG,OAAO,SAAS,QAAQ,GAAG,MAAM,GAC/B,gBAAgB,CAAC,OAAO,CAAC,GACzB,KAAK,GACP,KAAK;CACV,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,IAAI,CACjC,KAAK,EAAE,CAAC,EACR,GAAG,EAAE,YAAY,KACd,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,OAAO;IACtB,CAAC,KAAK,CAAC,MAAM,SAAS,SAAS,cAAc,EAAE,EAC7C,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,SAAS,QAAQ,EACjB,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;CACtE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,MAAM;IACrB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IACjE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;CACpE;AAED,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,GAAG,OAAO,EACvC,YAAY,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,KAC3C,CAAC,CAAC;AAEP;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,EACtB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KACrB,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE9D,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,mFAAmF;AACnF,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CACjD;AAED,6DAA6D;AAC7D,eAAO,MAAM,aAAa,EAAG,oBAA6B,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACtC,QAAQ,CAAC;AAEb,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO,CAAC,GAAG;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC,CAAC"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAgDA,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAG,oBAA6B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAyKA,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 { validateDraftFreeTopo } from './draft.js';
+import { validateTopo } from './validate-topo.js';
+const PROJECTION_BLOCKING_RULES = new Set([
+    'cross-cycle',
+    'cross-exists',
+    'no-self-cross',
+    'resource-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,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;IACxC,aAAa;IACb,cAAc;IACd,eAAe;IACf,iBAAiB;IACjB,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.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;AAIH,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;AA8MD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,MAAM,CAAC,IAAI,EAAE,eAAe,CAqBrE,CAAC"}