@proposit/proposit-core 1.9.0 → 1.11.0

package/dist/lib/index.js.map

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

package/dist/lib/llm/index.d.ts

@@ -1,2 +1,2 @@
-export type { TLlmModel, TReasoningEffort, TToolSpec, TLlmRequest, TLlmResponse, TLlmProvider, TLlmTokenUsage, } from "./types.js";
+export type { TLlmModel, TReasoningEffort, TToolSpec, TLlmRequest, TLlmResponse, TLlmProvider, TLlmTokenUsage, TResponseStatus, TRetrievedResponse, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/llm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/llm/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACR,SAAS,EACT,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,cAAc,GACjB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/llm/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACR,SAAS,EACT,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,eAAe,EACf,kBAAkB,GACrB,MAAM,YAAY,CAAA"}

package/dist/lib/llm/types.d.ts

@@ -27,6 +27,21 @@ export type TLlmRequest<T> = {
     tools?: readonly TToolSpec[];
     maxOutputTokens?: number;
     signal?: AbortSignal;
+    /**
+     * Optional callback fired by a provider **as soon as the upstream
+     * response id is known — before the call resolves**. Lets a caller
+     * persist the id mid-flight so an interrupted in-flight call can be
+     * recovered from the upstream's stored copy.
+     *
+     * Only providers that can surface an id mid-flight invoke it (the
+     * OpenAI provider in background-stream mode, from the first
+     * `response.created` SSE event). Synchronous providers leave it
+     * uncalled and surface the id only at completion via
+     * {@link TLlmResponse.rawResponseId}. Optional + backward-compatible:
+     * callers that don't set it are unaffected. Invoked at most once per
+     * provider call (per attempt).
+     */
+    onResponseCreated?: (responseId: string) => void;
     /**
      * Phantom field that carries the structured-output type `T` from
      * `outputSchema` into the response. Always `undefined` at runtime.
@@ -46,4 +61,44 @@ export type TLlmResponse<T> = {
 export type TLlmProvider = {
     respond<T>(req: TLlmRequest<T>): Promise<TLlmResponse<T>>;
 };
+/**
+ * Lifecycle status of a stored/background LLM response. `completed` /
+ * `failed` / `incomplete` / `cancelled` are terminal; `queued` /
+ * `in_progress` are transient.
+ *
+ * This is the framework-side mirror of the concrete provider's status
+ * union (the OpenAI extension exports a structurally-identical
+ * `TResponseStatus`). It lives here, in the SDK-free layer, so the
+ * pipeline's launch/complete entry points can reference a response
+ * status by its function/value type without importing the OpenAI
+ * extension — keeping `src/lib/` free of third-party SDK imports.
+ */
+export type TResponseStatus = "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
+/**
+ * Framework-side structural mirror of a retrieved background-response
+ * shape, consumed by `completeStage`. The OpenAI extension's
+ * `retrieveResponse` returns a structurally-compatible object (it
+ * carries every field below), so a consumer can pass its result
+ * straight into `completeStage` — without `src/lib/` importing the
+ * extension type. `output` is the **raw assistant text** (not a parsed
+ * object); `completeStage` parses it against the stage's schema.
+ */
+export type TRetrievedResponse = {
+    /** Current status of the stored response. */
+    status: TResponseStatus;
+    /** Raw assistant text output, present when `status === "completed"`. */
+    output?: string;
+    /** Token usage reported by the provider, when available. */
+    tokenUsage?: TLlmTokenUsage;
+    /** The provider response id that was retrieved. */
+    rawResponseId: string;
+    /**
+     * The provider's `incomplete_details.reason`, present when
+     * `status === "incomplete"` (e.g. `max_output_tokens`,
+     * `content_filter`). Drives `completeStage`'s classification.
+     */
+    incompleteReason?: string;
+    /** The provider's error message, present when `status === "failed"`. */
+    errorMessage?: string;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/lib/llm/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/llm/types.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAEtC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,cAAc,CAAA;AAE/E,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpE,MAAM,MAAM,SAAS,GACf;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD;IACI,IAAI,EAAE,UAAU,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/C,CAAA;AAEP,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IACzB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,CAAC,EAAE,gBAAgB,CAAA;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,OAAO,CAAA;IACrB,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;OAGG;IAEH,WAAW,CAAC,EAAE,CAAC,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC1B,MAAM,EAAE,CAAC,CAAA;IACT,UAAU,EAAE,cAAc,CAAA;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACvB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;CAC5D,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/llm/types.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAEtC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,cAAc,CAAA;AAE/E,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpE,MAAM,MAAM,SAAS,GACf;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD;IACI,IAAI,EAAE,UAAU,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/C,CAAA;AAEP,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IACzB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,CAAC,EAAE,gBAAgB,CAAA;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,OAAO,CAAA;IACrB,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD;;;OAGG;IAEH,WAAW,CAAC,EAAE,CAAC,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC1B,MAAM,EAAE,CAAC,CAAA;IACT,UAAU,EAAE,cAAc,CAAA;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACvB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;CAC5D,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GACrB,QAAQ,GACR,aAAa,GACb,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,WAAW,CAAA;AAEjB;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,6CAA6C;IAC7C,MAAM,EAAE,eAAe,CAAA;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA"}

package/dist/lib/pipelines/execute.d.ts

@@ -1,5 +1,6 @@
-import type { TPipeline, TPipelineEvent, TPipelineResult } from "./types.js";
-import type { TLlmProvider } from "../llm/types.js";
+import type { TPipeline, TPipelineEvent, TPipelineResult, TProcessingFailure, TStageStatus } from "./types.js";
+import type { TRetryReason } from "./stage-helpers.js";
+import type { TLlmProvider, TLlmRequest, TLlmTokenUsage, TResponseStatus, TRetrievedResponse } from "../llm/types.js";
 export type TExecutePipelineDeps = {
     llm: TLlmProvider;
     generateId?: () => string;
@@ -9,7 +10,7 @@ export type TExecutePipelineDeps = {
     concurrencyLimit?: number;
 };
 export declare class PipelineConfigurationError extends Error {
-    readonly code: "DAG_CYCLE" | "SELF_DEP" | "UNKNOWN_DEP" | "DUPLICATE_STAGE_ID" | "GET_OUTSIDE_DEPS" | "STATUS_OUTSIDE_DEPS";
+    readonly code: "DAG_CYCLE" | "SELF_DEP" | "UNKNOWN_DEP" | "UNKNOWN_STAGE" | "DUPLICATE_STAGE_ID" | "GET_OUTSIDE_DEPS" | "STATUS_OUTSIDE_DEPS";
     readonly stageId?: string;
     readonly depId?: string;
     constructor(args: {
@@ -20,4 +21,175 @@ export declare class PipelineConfigurationError extends Error {
     });
 }
 export declare function executePipeline<TInput, TOutput>(pipeline: TPipeline<TInput, TOutput>, input: TInput, deps: TExecutePipelineDeps): Promise<TPipelineResult<TOutput>>;
+/**
+ * The rehydration unit for one upstream stage. Carries both the outcome
+ * AND the output so a single-stage run reproduces the monolithic run's
+ * semantics exactly: `ctx.get(stageId)` returns the output only for a
+ * `completed` upstream, and `ctx.stageStatus(stageId)` returns the
+ * outcome. The serialized form of one stage is `{ outcome, output? }`
+ * where `output` is the value the stage's `outputSchema` accepts (JSON
+ * round-trippable) and is present iff `outcome === "completed"`.
+ */
+export type TStageOutcomeRecord = {
+    outcome: TStageStatus;
+    /**
+     * The stage's validated output. Present only for
+     * `outcome === "completed"` — `executeStage` / `executeFinalize`
+     * defensively drop it for `skipped` / `failed` records, so a stale
+     * persisted output can never leak into a non-completed dependency.
+     */
+    output?: unknown;
+};
+/**
+ * Dependencies for a single-stage / single-finalize / launch / complete
+ * run. A subset of `TExecutePipelineDeps`: no `concurrencyLimit` (one unit
+ * runs at a time) and no run-level bookends.
+ */
+export type TExecuteStageDeps = {
+    llm: TLlmProvider;
+    generateId?: () => string;
+    signal?: AbortSignal;
+    onEvent?: (event: TPipelineEvent) => void;
+    /**
+     * Submit-only background-response capability — required by
+     * `launchStage`, ignored by `executeStage` / `executeFinalize` /
+     * `completeStage`. Referenced by **function type only** so `src/lib/`
+     * takes no OpenAI-extension import (the zero-SDK-import boundary
+     * holds); the consumer supplies the concrete
+     * `extensions/openai`#`submitBackgroundResponse` (apiKey-bound). It
+     * submits a background response and resolves with `{ responseId,
+     * status }` WITHOUT awaiting completion.
+     */
+    submitBackgroundResponse?: (req: TLlmRequest<unknown>, opts: {
+        apiKey: string;
+        baseUrl?: string;
+        signal?: AbortSignal;
+    }) => Promise<{
+        responseId: string;
+        status: TResponseStatus;
+    }>;
+};
+/**
+ * The result of running one stage via `executeStage` (run-to-completion)
+ * or `completeStage` (the completion side of the launch/complete split).
+ */
+export type TExecuteStageResult = {
+    /** The stage's own outcome after this single execution. */
+    outcome: TStageStatus;
+    /** The validated output when `outcome === "completed"`; else undefined. */
+    output?: unknown;
+    /** Any ProcessingFailure(s) the stage produced. */
+    failures: TProcessingFailure[];
+    /** Per-stage token usage, when the stage made an LLM call. */
+    tokenUsage?: TLlmTokenUsage;
+    /**
+     * The retry CLASSIFICATION when a `completeStage` result is `failed`
+     * for a RETRYABLE reason — a reason code, not a bare boolean, so a
+     * durable orchestrator can apply the same `retryOn` + bounded-attempt
+     * decision core would. Absent when `completed`, when the failure is
+     * non-retryable / fail-fast (`failed` envelope, `content_filter`), or
+     * when the outcome is `skipped` (a cancelled response). **Run-to-
+     * completion `executeStage` never sets this** (it owns its own retry
+     * loop); only `completeStage` does.
+     */
+    retryReason?: TRetryReason;
+};
+/**
+ * The result of `launchStage`: the submitted background response's id +
+ * its submit-time status. The caller persists `responseId` and builds the
+ * durable hook token before suspending; `status` may already be terminal
+ * on a small/cached submit (the caller then proceeds straight to
+ * `completeStage` via `retrieveResponse`).
+ */
+export type TLaunchStageResult = {
+    responseId: string;
+    status: TResponseStatus;
+};
+/** The result of running the finalize via `executeFinalize`. */
+export type TExecuteFinalizeResult<TOutput> = {
+    /**
+     * The pipeline output finalize produced; `null` when a required
+     * finalize dep was not `completed` (the same gate `executePipeline`
+     * applies) or when finalize itself threw (a `FINALIZE_UNCAUGHT_ERROR`
+     * failure).
+     */
+    output: TOutput | null;
+    failures: TProcessingFailure[];
+};
+/**
+ * Run a single stage of `pipeline` against the caller-supplied upstream
+ * records, without re-running the whole DAG. The upstream map carries
+ * each dependency's `{ outcome, output? }` so `ctx.get` / `ctx.stageStatus`
+ * reproduce monolithic-run semantics exactly. `input` is validated +
+ * transformed via `Value.Parse(pipeline.inputSchema, input)` (a schema
+ * mismatch throws, same as `executePipeline`) and the PARSED value seeds
+ * `ctx.input`.
+ *
+ * Emits the per-stage events only (`stage:start`, `stage:llm-request`,
+ * `stage:llm-response-created`, `stage:llm-call`, `stage:retry`,
+ * `stage:end`) — no `pipeline:*` bookends. Throws `PipelineConfigurationError`
+ * (`UNKNOWN_STAGE`) when `stageId` is not in `pipeline.stages`, and throws a
+ * `PipelineConfigurationError` (`GET_OUTSIDE_DEPS` / `STATUS_OUTSIDE_DEPS`)
+ * out directly when the stage reads a non-dependency — both are caller
+ * bugs, surfaced rather than swallowed into the result.
+ *
+ * The caller may pass a superset of `upstream` records; `executeStage`
+ * uses the stage's own `dependsOn` to pick the relevant ones. It does NOT
+ * decide whether the stage SHOULD run given its upstream outcomes — a
+ * required-failed upstream just means `ctx.get` returns `undefined`; the
+ * skip decision belongs to the caller's scheduler.
+ */
+export declare function executeStage(pipeline: TPipeline<unknown, unknown>, stageId: string, upstream: Readonly<Record<string, TStageOutcomeRecord>>, input: unknown, deps: TExecuteStageDeps): Promise<TExecuteStageResult>;
+/**
+ * Run `pipeline.finalize` against the caller-supplied upstream records,
+ * without re-running the whole DAG. Symmetric with `executeStage`:
+ * `input` is parsed via `Value.Parse(pipeline.inputSchema, input)` and the
+ * PARSED value seeds the finalize `ctx.input`; the finalize `ctx` is built
+ * with `pipeline.finalize.dependsOn` as its allowed-dep set; the
+ * required-finalize-dep gate (`output` stays `null` if any required dep is
+ * not `completed`) and the `FINALIZE_UNCAUGHT_ERROR` capture match
+ * `executePipeline`.
+ *
+ * Emits NO events (finalize is not a stage — it has no `stage:*`
+ * lifecycle — and there are no `pipeline:*` bookends). `async` purely for
+ * signature symmetry with `executeStage`; `TPipelineFinalize.run` stays
+ * synchronous and the `async` wrapper just resolves its result.
+ */
+export declare function executeFinalize<TOutput>(pipeline: TPipeline<unknown, TOutput>, upstream: Readonly<Record<string, TStageOutcomeRecord>>, input: unknown, deps: TExecuteStageDeps): Promise<TExecuteFinalizeResult<TOutput>>;
+/**
+ * Launch an LLM-background stage: rehydrate `ctx` from `upstream` +
+ * parsed input, build the request via the shared seam, submit it via the
+ * injected `deps.submitBackgroundResponse`, and return
+ * `{ responseId, status }` WITHOUT awaiting completion.
+ *
+ * Emits `stage:start`, `stage:llm-request`, and `stage:llm-response-created`
+ * (from the submit's returned id) — but NO `stage:llm-call` / `stage:end`
+ * (the completion side emits those, in a later invocation). The
+ * per-stage event pair therefore spans two invocations; an `onEvent`
+ * consumer must NOT assume a balanced start↔end per call.
+ *
+ * `deps.submitBackgroundResponse` is REQUIRED; `launchStage` throws if it
+ * is absent. `stageId` must name an LLM stage (built by `llmStage`);
+ * a non-LLM stage throws. `attempt` (default 1) lets a re-launch rebuild
+ * the retry-suffixed user message for attempt 2+.
+ */
+export declare function launchStage(pipeline: TPipeline<unknown, unknown>, stageId: string, upstream: Readonly<Record<string, TStageOutcomeRecord>>, input: unknown, deps: TExecuteStageDeps, attempt?: number): Promise<TLaunchStageResult>;
+/**
+ * Complete an LLM-background stage from its retrieved response. Recovers
+ * the stage's LLM config, parses the RAW assistant text in
+ * `retrieved.output` against the stage's schema (via the shared seam),
+ * classifies a non-`completed` status per the launch/complete table, and
+ * returns the standard `TExecuteStageResult`.
+ *
+ * Emits `stage:llm-call` + `stage:end` (NO `stage:start` — that fired in
+ * the launch invocation). `tokenUsage` is taken directly from
+ * `retrieved.tokenUsage` (the per-`ctx` WeakMap cannot bridge the two
+ * invocations). On a RETRYABLE failure the result carries `retryReason`
+ * (the reason code); a fail-fast failure (`failed` envelope,
+ * `content_filter`) carries none; a `cancelled` response settles as
+ * `outcome: "skipped"` with no `ProcessingFailure`.
+ *
+ * `stageId` must name an LLM stage; a non-LLM stage throws.
+ */
+export declare function completeStage(pipeline: TPipeline<unknown, unknown>, stageId: string, retrieved: TRetrievedResponse, deps: TExecuteStageDeps, attempt?: number): Promise<TExecuteStageResult>;
 //# sourceMappingURL=execute.d.ts.map

package/dist/lib/pipelines/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/lib/pipelines/execute.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAER,SAAS,EACT,cAAc,EACd,eAAe,EAKlB,MAAM,YAAY,CAAA;AAcnB,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,iBAAiB,CAAA;AAEnE,MAAM,MAAM,oBAAoB,GAAG;IAC/B,GAAG,EAAE,YAAY,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,MAAM,CAAA;IACzB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACzC,iBAAiB;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IACjD,SAAgB,IAAI,EACd,WAAW,GACX,UAAU,GACV,aAAa,GACb,oBAAoB,GACpB,kBAAkB,GAClB,qBAAqB,CAAA;IAC3B,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChC,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAA;gBAElB,IAAI,EAAE;QACd,IAAI,EAAE,0BAA0B,CAAC,MAAM,CAAC,CAAA;QACxC,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,KAAK,CAAC,EAAE,MAAM,CAAA;KACjB;CAOJ;AAmHD,wBAAsB,eAAe,CAAC,MAAM,EAAE,OAAO,EACjD,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,oBAAoB,GAC3B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CA+dnC"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/lib/pipelines/execute.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAER,SAAS,EACT,cAAc,EACd,eAAe,EACf,kBAAkB,EAGlB,YAAY,EACf,MAAM,YAAY,CAAA;AAanB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAOtD,OAAO,KAAK,EACR,YAAY,EACZ,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EACrB,MAAM,iBAAiB,CAAA;AAExB,MAAM,MAAM,oBAAoB,GAAG;IAC/B,GAAG,EAAE,YAAY,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,MAAM,CAAA;IACzB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACzC,iBAAiB;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IACjD,SAAgB,IAAI,EACd,WAAW,GACX,UAAU,GACV,aAAa,GACb,eAAe,GACf,oBAAoB,GACpB,kBAAkB,GAClB,qBAAqB,CAAA;IAC3B,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChC,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAA;gBAElB,IAAI,EAAE;QACd,IAAI,EAAE,0BAA0B,CAAC,MAAM,CAAC,CAAA;QACxC,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,KAAK,CAAC,EAAE,MAAM,CAAA;KACjB;CAOJ;AAqZD,wBAAsB,eAAe,CAAC,MAAM,EAAE,OAAO,EACjD,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,oBAAoB,GAC3B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CA0RnC;AAYD;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,OAAO,EAAE,YAAY,CAAA;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B,GAAG,EAAE,YAAY,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,MAAM,CAAA;IACzB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACzC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,CACvB,GAAG,EAAE,WAAW,CAAC,OAAO,CAAC,EACzB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAC/D,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAC,CAAA;CAChE,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,2DAA2D;IAC3D,OAAO,EAAE,YAAY,CAAA;IACrB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,mDAAmD;IACnD,QAAQ,EAAE,kBAAkB,EAAE,CAAA;IAC9B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;CAC7B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,eAAe,CAAA;CAC1B,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,sBAAsB,CAAC,OAAO,IAAI;IAC1C;;;;;OAKG;IACH,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IACtB,QAAQ,EAAE,kBAAkB,EAAE,CAAA;CACjC,CAAA;AAsDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,YAAY,CAC9B,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,EACvD,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,iBAAiB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAiC9B;AAED;;;;;;;;;;;;;;GAcG;AAMH,wBAAsB,eAAe,CAAC,OAAO,EACzC,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,EACvD,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,iBAAiB,GACxB,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAc1C;AA0CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC7B,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,EACvD,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,iBAAiB,EACvB,OAAO,SAAI,GACZ,OAAO,CAAC,kBAAkB,CAAC,CA+D7B;AAED;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAsB,aAAa,CAC/B,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,kBAAkB,EAC7B,IAAI,EAAE,iBAAiB,EACvB,OAAO,SAAI,GACZ,OAAO,CAAC,mBAAmB,CAAC,CA0E9B"}