@promptbook/documents 0.113.0-8 → 0.113.0-9

package/esm/index.es.js

@@ -25,7 +25,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.113.0-8';
+const PROMPTBOOK_ENGINE_VERSION = '0.113.0-9';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -106,6 +106,127 @@ function take(initialValue) {
     });
 }
 
+/**
+ * Validates that a channel value is a valid number within the range of 0 to 255.
+ * Throws an error if the value is not valid.
+ *
+ * @param channelName - The name of the channel being validated.
+ * @param value - The value of the channel to validate.
+ * @throws Will throw an error if the value is not a valid channel number.
+ *
+ * @private util of `@promptbook/color`
+ */
+function checkChannelValue(channelName, value) {
+    if (typeof value !== 'number') {
+        throw new Error(`${channelName} channel value is not number but ${typeof value}`);
+    }
+    if (isNaN(value)) {
+        throw new Error(`${channelName} channel value is NaN`);
+    }
+    if (Math.round(value) !== value) {
+        throw new Error(`${channelName} channel is not whole number, it is ${value}`);
+    }
+    if (value < 0) {
+        throw new Error(`${channelName} channel is lower than 0, it is ${value}`);
+    }
+    if (value > 255) {
+        throw new Error(`${channelName} channel is greater than 255, it is ${value}`);
+    }
+}
+
+/**
+ * Shared immutable channel storage and serialization helpers for `Color`.
+ *
+ * @private base class of Color
+ */
+class ColorValue {
+    constructor(red, green, blue, alpha = 255) {
+        this.red = red;
+        this.green = green;
+        this.blue = blue;
+        this.alpha = alpha;
+        checkChannelValue('Red', red);
+        checkChannelValue('Green', green);
+        checkChannelValue('Blue', blue);
+        checkChannelValue('Alpha', alpha);
+    }
+    /**
+     * Shortcut for `red` property
+     * Number from 0 to 255
+     * @alias red
+     */
+    get r() {
+        return this.red;
+    }
+    /**
+     * Shortcut for `green` property
+     * Number from 0 to 255
+     * @alias green
+     */
+    get g() {
+        return this.green;
+    }
+    /**
+     * Shortcut for `blue` property
+     * Number from 0 to 255
+     * @alias blue
+     */
+    get b() {
+        return this.blue;
+    }
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get a() {
+        return this.alpha;
+    }
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get opacity() {
+        return this.alpha;
+    }
+    /**
+     * Shortcut for 1-`alpha` property
+     */
+    get transparency() {
+        return 255 - this.alpha;
+    }
+    clone() {
+        return take(this.createColor(this.red, this.green, this.blue, this.alpha));
+    }
+    toString() {
+        return this.toHex();
+    }
+    toHex() {
+        if (this.alpha === 255) {
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}`;
+        }
+        else {
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
+        }
+    }
+    toRgb() {
+        if (this.alpha === 255) {
+            return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+        }
+        else {
+            return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
+        }
+    }
+    toHsl() {
+        throw new Error(`Getting HSL is not implemented`);
+    }
+}
+
 /**
  * 🎨 List of all 140 color names which are supported by CSS
  *
@@ -265,127 +386,6 @@ const CSS_COLORS = {
 };
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * Validates that a channel value is a valid number within the range of 0 to 255.
- * Throws an error if the value is not valid.
- *
- * @param channelName - The name of the channel being validated.
- * @param value - The value of the channel to validate.
- * @throws Will throw an error if the value is not a valid channel number.
- *
- * @private util of `@promptbook/color`
- */
-function checkChannelValue(channelName, value) {
-    if (typeof value !== 'number') {
-        throw new Error(`${channelName} channel value is not number but ${typeof value}`);
-    }
-    if (isNaN(value)) {
-        throw new Error(`${channelName} channel value is NaN`);
-    }
-    if (Math.round(value) !== value) {
-        throw new Error(`${channelName} channel is not whole number, it is ${value}`);
-    }
-    if (value < 0) {
-        throw new Error(`${channelName} channel is lower than 0, it is ${value}`);
-    }
-    if (value > 255) {
-        throw new Error(`${channelName} channel is greater than 255, it is ${value}`);
-    }
-}
-
-/**
- * Shared immutable channel storage and serialization helpers for `Color`.
- *
- * @private base class of Color
- */
-class ColorValue {
-    constructor(red, green, blue, alpha = 255) {
-        this.red = red;
-        this.green = green;
-        this.blue = blue;
-        this.alpha = alpha;
-        checkChannelValue('Red', red);
-        checkChannelValue('Green', green);
-        checkChannelValue('Blue', blue);
-        checkChannelValue('Alpha', alpha);
-    }
-    /**
-     * Shortcut for `red` property
-     * Number from 0 to 255
-     * @alias red
-     */
-    get r() {
-        return this.red;
-    }
-    /**
-     * Shortcut for `green` property
-     * Number from 0 to 255
-     * @alias green
-     */
-    get g() {
-        return this.green;
-    }
-    /**
-     * Shortcut for `blue` property
-     * Number from 0 to 255
-     * @alias blue
-     */
-    get b() {
-        return this.blue;
-    }
-    /**
-     * Shortcut for `alpha` property
-     * Number from 0 (transparent) to 255 (opaque)
-     * @alias alpha
-     */
-    get a() {
-        return this.alpha;
-    }
-    /**
-     * Shortcut for `alpha` property
-     * Number from 0 (transparent) to 255 (opaque)
-     * @alias alpha
-     */
-    get opacity() {
-        return this.alpha;
-    }
-    /**
-     * Shortcut for 1-`alpha` property
-     */
-    get transparency() {
-        return 255 - this.alpha;
-    }
-    clone() {
-        return take(this.createColor(this.red, this.green, this.blue, this.alpha));
-    }
-    toString() {
-        return this.toHex();
-    }
-    toHex() {
-        if (this.alpha === 255) {
-            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}`;
-        }
-        else {
-            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
-        }
-    }
-    toRgb() {
-        if (this.alpha === 255) {
-            return `rgb(${this.red}, ${this.green}, ${this.blue})`;
-        }
-        else {
-            return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
-        }
-    }
-    toHsl() {
-        throw new Error(`Getting HSL is not implemented`);
-    }
-}
-
 /**
  * Checks if the given value is a valid hex color string
  *
@@ -2121,20 +2121,109 @@ function pipelineJsonToString(pipelineJson) {
 // TODO: [🧠] Should be in generated .book.md file GENERATOR_WARNING
 
 /**
- * Orders JSON object by keys
- *
- * @returns The same type of object as the input re-ordered
+ * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function orderJson(options) {
-    const { value, order } = options;
-    const orderedValue = {
-        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
-        ...value,
-    };
-    return orderedValue;
-}
+class PipelineLogicError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineLogicError';
+        Object.setPrototypeOf(this, PipelineLogicError.prototype);
+    }
+}
+
+/**
+ * Creates the shared validation context for one pipeline.
+ *
+ * @private function of `validatePipeline`
+ */
+function createPipelineValidationContext(pipeline) {
+    return {
+        pipeline,
+        pipelineIdentification: getPipelineIdentification(pipeline),
+    };
+}
+/**
+ * Builds a short file/url identification block for validation errors.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function getPipelineIdentification(pipeline) {
+    // Note: This is a 😐 implementation of [🚞]
+    const pipelineIdentificationParts = [];
+    if (pipeline.sourceFile !== undefined) {
+        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
+    }
+    if (pipeline.pipelineUrl !== undefined) {
+        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
+    }
+    return pipelineIdentificationParts.join('\n');
+}
+
+/**
+ * Validates that the expected top-level collections have array structure.
+ *
+ * @private function of `validatePipeline`
+ */
+function validatePipelineCollectionsStructure({ pipeline, pipelineIdentification, }) {
+    validatePipelineParametersCollection(pipeline, pipelineIdentification);
+    validatePipelineTasksCollection(pipeline, pipelineIdentification);
+}
+/**
+ * Validates that `pipeline.parameters` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineParametersCollection(pipeline, pipelineIdentification) {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.parameters)) {
+        return;
+    }
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(spaceTrim$1((block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
+
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates that `pipeline.tasks` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineTasksCollection(pipeline, pipelineIdentification) {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.tasks)) {
+        return;
+    }
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(spaceTrim$1((block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
+
+                ${block(pipelineIdentification)}
+            `));
+}
+
+/**
+ * Orders JSON object by keys
+ *
+ * @returns The same type of object as the input re-ordered
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function orderJson(options) {
+    const { value, order } = options;
+    const orderedValue = {
+        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
+        ...value,
+    };
+    return orderedValue;
+}
 
 /**
  * Freezes the given object and all its nested objects recursively
@@ -2483,16 +2572,137 @@ const RESERVED_PARAMETER_NAMES = exportJson({
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
+ * Validates that task dependencies can be resolved without cycles or missing definitions.
  *
- * @public exported from `@promptbook/core`
+ * @private function of `validatePipeline`
  */
-class PipelineLogicError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'PipelineLogicError';
-        Object.setPrototypeOf(this, PipelineLogicError.prototype);
+function validatePipelineDependencyResolution({ pipeline, pipelineIdentification, }) {
+    let dependencyResolutionState = createInitialDependencyResolutionState(pipeline);
+    let loopLimit = LOOP_LIMIT;
+    while (hasUnresolvedTasks(dependencyResolutionState)) {
+        if (loopLimit-- < 0) {
+            throw createDependencyResolutionLoopLimitError(pipelineIdentification);
+        }
+        dependencyResolutionState = resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification);
+    }
+}
+/**
+ * Collects the parameter names that are already resolvable before dependency traversal starts.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createInitialDependencyResolutionState(pipeline) {
+    return {
+        resolvedParameterNames: createInitiallyResolvedParameterNames(pipeline),
+        unresolvedTasks: [...pipeline.tasks],
+    };
+}
+/**
+ * Checks whether dependency resolution still has tasks left to process.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function hasUnresolvedTasks({ unresolvedTasks }) {
+    return unresolvedTasks.length > 0;
+}
+/**
+ * Resolves the next batch of currently satisfiable tasks.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification) {
+    const currentlyResolvedTasks = getCurrentlyResolvedTasks(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames);
+    if (currentlyResolvedTasks.length === 0) {
+        throw createUnresolvedTasksError(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames, pipelineIdentification);
+    }
+    return {
+        resolvedParameterNames: appendResolvedTaskParameterNames(dependencyResolutionState.resolvedParameterNames, currentlyResolvedTasks),
+        unresolvedTasks: dependencyResolutionState.unresolvedTasks.filter((task) => !currentlyResolvedTasks.includes(task)),
+    };
+}
+/**
+ * Collects the parameter names that are already resolvable before dependency traversal starts.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createInitiallyResolvedParameterNames(pipeline) {
+    let resolvedParameterNames = pipeline.parameters
+        .filter(({ isInput }) => isInput)
+        .map(({ name }) => name);
+    for (const reservedParameterName of RESERVED_PARAMETER_NAMES) {
+        resolvedParameterNames = [...resolvedParameterNames, reservedParameterName];
     }
+    return resolvedParameterNames;
+}
+/**
+ * Adds newly resolved task outputs to the resolved parameter list.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function appendResolvedTaskParameterNames(resolvedParameterNames, currentlyResolvedTasks) {
+    return [
+        ...resolvedParameterNames,
+        ...currentlyResolvedTasks.map(({ resultingParameterName }) => resultingParameterName),
+    ];
+}
+/**
+ * Selects tasks whose dependencies are already resolved.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function getCurrentlyResolvedTasks(unresolvedTasks, resolvedParameterNames) {
+    return unresolvedTasks.filter((task) => task.dependentParameterNames.every((name) => resolvedParameterNames.includes(name)));
+}
+/**
+ * Creates the unexpected loop-limit error for dependency resolution.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createDependencyResolutionLoopLimitError(pipelineIdentification) {
+    // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
+    return new UnexpectedError(spaceTrim$1((block) => `
+                Loop limit reached during detection of circular dependencies in \`validatePipeline\`
+
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Creates the detailed error for unresolved or circular task dependencies.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createUnresolvedTasksError(unresolvedTasks, resolvedParameterNames, pipelineIdentification) {
+    return new PipelineLogicError(
+    // TODO: [🐎] DRY
+    spaceTrim$1((block) => `
+
+                Can not resolve some parameters:
+                Either you are using a parameter that is not defined, or there are some circular dependencies.
+
+                ${block(pipelineIdentification)}
+
+                **Can not resolve:**
+                ${block(unresolvedTasks
+        .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
+        .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
+        .join(' and ')}`)
+        .join('\n'))}
+
+                **Resolved:**
+                ${block(resolvedParameterNames
+        .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
+        .map((name) => `- Parameter \`{${name}}\``)
+        .join('\n'))}
+
+
+                **Reserved (which are available):**
+                ${block(resolvedParameterNames
+        .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
+        .map((name) => `- Parameter \`{${name}}\``)
+        .join('\n'))}
+
+
+            `));
 }
 
 /**
@@ -2570,171 +2780,22 @@ function isValidPipelineUrl(url) {
 // TODO: [🐠] Maybe more info why the URL is invalid
 
 /**
- * Validates PipelineJson if it is logically valid
- *
- * It checks:
- * -   if it has correct parameters dependency
- *
- * It does NOT check:
- * -   if it is valid json
- * -   if it is meaningful
- *
- * Note: [🔂] This function is idempotent.
+ * Validates pipeline-level metadata fields.
  *
- * @param pipeline valid or invalid PipelineJson
- * @returns the same pipeline if it is logically valid
- * @throws {PipelineLogicError} on logical error in the pipeline
+ * @private function of `validatePipeline`
+ */
+function validatePipelineMetadata({ pipeline, pipelineIdentification }) {
+    validatePipelineUrl(pipeline, pipelineIdentification);
+    validatePipelineBookVersion(pipeline, pipelineIdentification);
+}
+/**
+ * Validates the pipeline URL, when present.
  *
- * @public exported from `@promptbook/core`
+ * @private internal utility of `validatePipelineMetadata`
  */
-function validatePipeline(pipeline) {
-    if (IS_PIPELINE_LOGIC_VALIDATED) {
-        validatePipeline_InnerFunction(pipeline);
-    }
-    else {
-        try {
-            validatePipeline_InnerFunction(pipeline);
-        }
-        catch (error) {
-            if (!(error instanceof PipelineLogicError)) {
-                throw error;
-            }
-            console.error(spaceTrim$1((block) => `
-                        Pipeline is not valid but logic errors are temporarily disabled via \`IS_PIPELINE_LOGIC_VALIDATED\`
-
-                        ${block(error.message)}
-                    `));
-        }
-    }
-    return pipeline;
-}
-/**
- * Validates pipeline inner function.
- *
- * @private internal function for `validatePipeline`
- */
-function validatePipeline_InnerFunction(pipeline) {
-    // TODO: [🧠] Maybe test if promptbook is a promise and make specific error case for that
-    const context = createPipelineValidationContext(pipeline);
-    validatePipelineMetadata(context);
-    validatePipelineCollectionsStructure(context);
-    validatePipelineParameters(context);
-    validatePipelineTasks(context);
-    validatePipelineDependencyResolution(context);
-    // Note: Check that formfactor is corresponding to the pipeline interface
-    // TODO: !!6 Implement this
-    // pipeline.formfactorName
-}
-/**
- * Creates the shared validation context for one pipeline.
- *
- * @private internal utility of `validatePipeline`
- */
-function createPipelineValidationContext(pipeline) {
-    return {
-        pipeline,
-        pipelineIdentification: getPipelineIdentification(pipeline),
-    };
-}
-/**
- * Builds a short file/url identification block for validation errors.
- *
- * @private internal utility of `validatePipeline`
- */
-function getPipelineIdentification(pipeline) {
-    // Note: This is a 😐 implementation of [🚞]
-    const pipelineIdentificationParts = [];
-    if (pipeline.sourceFile !== undefined) {
-        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
-    }
-    if (pipeline.pipelineUrl !== undefined) {
-        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
-    }
-    return pipelineIdentificationParts.join('\n');
-}
-/**
- * Validates pipeline-level metadata fields.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineMetadata({ pipeline, pipelineIdentification }) {
-    validatePipelineUrl(pipeline, pipelineIdentification);
-    validatePipelineBookVersion(pipeline, pipelineIdentification);
-}
-/**
- * Validates that the expected top-level collections have array structure.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineCollectionsStructure({ pipeline, pipelineIdentification }) {
-    validatePipelineParametersCollection(pipeline, pipelineIdentification);
-    validatePipelineTasksCollection(pipeline, pipelineIdentification);
-}
-/**
- * Validates all pipeline parameter declarations.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineParameters({ pipeline, pipelineIdentification }) {
-    for (const parameter of pipeline.parameters) {
-        validatePipelineParameter(parameter, pipeline, pipelineIdentification);
-    }
-}
-/**
- * Validates all pipeline tasks and their per-task invariants.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineTasks({ pipeline, pipelineIdentification }) {
-    // Note: All input parameters are defined - so that they can be used as result of some task
-    const definedParameters = createInitiallyDefinedParameters(pipeline);
-    for (const task of pipeline.tasks) {
-        validatePipelineTask(task, definedParameters, pipelineIdentification);
-    }
-}
-/**
- * Validates that task dependencies can be resolved without cycles or missing definitions.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineDependencyResolution({ pipeline, pipelineIdentification }) {
-    let dependencyResolutionState = createInitialDependencyResolutionState(pipeline);
-    let loopLimit = LOOP_LIMIT;
-    while (hasUnresolvedTasks(dependencyResolutionState)) {
-        if (loopLimit-- < 0) {
-            throw createDependencyResolutionLoopLimitError(pipelineIdentification);
-        }
-        dependencyResolutionState = resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification);
-    }
-}
-/**
- * Validates one pipeline parameter declaration.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineParameter(parameter, pipeline, pipelineIdentification) {
-    validateParameterDirection(parameter, pipelineIdentification);
-    validateParameterUsage(parameter, pipeline, pipelineIdentification);
-    validateParameterDefinition(parameter, pipeline, pipelineIdentification);
-}
-/**
- * Validates one pipeline task and its invariants.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineTask(task, definedParameters, pipelineIdentification) {
-    validateTaskResultingParameter(task, definedParameters, pipelineIdentification);
-    validateTaskJokers(task, pipelineIdentification);
-    validateTaskExpectations(task, pipelineIdentification);
-}
-/**
- * Validates the pipeline URL, when present.
- *
- * @private internal utility of `validatePipeline`
- */
-function validatePipelineUrl(pipeline, pipelineIdentification) {
-    if (pipeline.pipelineUrl === undefined || isValidPipelineUrl(pipeline.pipelineUrl)) {
-        return;
+function validatePipelineUrl(pipeline, pipelineIdentification) {
+    if (pipeline.pipelineUrl === undefined || isValidPipelineUrl(pipeline.pipelineUrl)) {
+        return;
     }
     // <- Note: [🚲]
     throw new PipelineLogicError(spaceTrim$1((block) => `
@@ -2746,7 +2807,7 @@ function validatePipelineUrl(pipeline, pipelineIdentification) {
 /**
  * Validates the Promptbook version, when present.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineMetadata`
  */
 function validatePipelineBookVersion(pipeline, pipelineIdentification) {
     if (pipeline.bookVersion === undefined || isValidPromptbookVersion(pipeline.bookVersion)) {
@@ -2759,48 +2820,31 @@ function validatePipelineBookVersion(pipeline, pipelineIdentification) {
                 ${block(pipelineIdentification)}
             `));
 }
+
 /**
- * Validates that `pipeline.parameters` is an array.
+ * Validates all pipeline parameter declarations.
  *
- * @private internal utility of `validatePipeline`
+ * @private function of `validatePipeline`
  */
-function validatePipelineParametersCollection(pipeline, pipelineIdentification) {
-    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
-    if (Array.isArray(pipeline.parameters)) {
-        return;
+function validatePipelineParameters({ pipeline, pipelineIdentification }) {
+    for (const parameter of pipeline.parameters) {
+        validatePipelineParameter(parameter, pipeline, pipelineIdentification);
     }
-    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-    throw new ParseError(spaceTrim$1((block) => `
-                Pipeline is valid JSON but with wrong structure
-
-                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
-
-                ${block(pipelineIdentification)}
-            `));
 }
 /**
- * Validates that `pipeline.tasks` is an array.
+ * Validates one pipeline parameter declaration.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
-function validatePipelineTasksCollection(pipeline, pipelineIdentification) {
-    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
-    if (Array.isArray(pipeline.tasks)) {
-        return;
-    }
-    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-    throw new ParseError(spaceTrim$1((block) => `
-                Pipeline is valid JSON but with wrong structure
-
-                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
-
-                ${block(pipelineIdentification)}
-            `));
+function validatePipelineParameter(parameter, pipeline, pipelineIdentification) {
+    validateParameterDirection(parameter, pipelineIdentification);
+    validateParameterUsage(parameter, pipeline, pipelineIdentification);
+    validateParameterDefinition(parameter, pipeline, pipelineIdentification);
 }
 /**
  * Validates that one parameter does not declare incompatible directions.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterDirection(parameter, pipelineIdentification) {
     if (!parameter.isInput || !parameter.isOutput) {
@@ -2817,7 +2861,7 @@ function validateParameterDirection(parameter, pipelineIdentification) {
 /**
  * Validates that one intermediate parameter is actually consumed by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterUsage(parameter, pipeline, pipelineIdentification) {
     if (parameter.isInput || parameter.isOutput || isParameterUsedByAnyTask(parameter, pipeline.tasks)) {
@@ -2836,7 +2880,7 @@ function validateParameterUsage(parameter, pipeline, pipelineIdentification) {
 /**
  * Validates that one non-input parameter is produced by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterDefinition(parameter, pipeline, pipelineIdentification) {
     if (parameter.isInput || isParameterDefinedByAnyTask(parameter, pipeline.tasks)) {
@@ -2855,7 +2899,7 @@ function validateParameterDefinition(parameter, pipeline, pipelineIdentification
 /**
  * Checks whether one parameter is consumed by at least one task dependency list.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function isParameterUsedByAnyTask(parameter, tasks) {
     return tasks.some((task) => task.dependentParameterNames.includes(parameter.name));
@@ -2863,23 +2907,46 @@ function isParameterUsedByAnyTask(parameter, tasks) {
 /**
  * Checks whether one parameter is produced by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function isParameterDefinedByAnyTask(parameter, tasks) {
     return tasks.some((task) => task.resultingParameterName === parameter.name);
 }
+
+/**
+ * Validates all pipeline tasks and their per-task invariants.
+ *
+ * @private function of `validatePipeline`
+ */
+function validatePipelineTasks({ pipeline, pipelineIdentification }) {
+    // Note: All input parameters are defined - so that they can be used as result of some task
+    const definedParameters = createInitiallyDefinedParameters(pipeline);
+    for (const task of pipeline.tasks) {
+        validatePipelineTask(task, definedParameters, pipelineIdentification);
+    }
+}
 /**
  * Collects the parameter names that are already defined before task validation starts.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function createInitiallyDefinedParameters(pipeline) {
     return new Set(pipeline.parameters.filter(({ isInput }) => isInput).map(({ name }) => name));
 }
+/**
+ * Validates one pipeline task and its invariants.
+ *
+ * @private internal utility of `validatePipelineTasks`
+ */
+function validatePipelineTask(task, definedParameters, pipelineIdentification) {
+    validateTaskResultingParameter(task, definedParameters, pipelineIdentification);
+    validateTaskJokers(task, pipelineIdentification);
+    validateTaskExpectations(task, pipelineIdentification);
+}
 /**
  * Validates one task result parameter declaration and marks it as defined.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskResultingParameter(task, definedParameters, pipelineIdentification) {
     if (definedParameters.has(task.resultingParameterName)) {
@@ -2901,7 +2968,7 @@ function validateTaskResultingParameter(task, definedParameters, pipelineIdentif
 /**
  * Validates joker parameters for one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskJokers(task, pipelineIdentification) {
     if (!hasTaskJokers(task)) {
@@ -2913,7 +2980,7 @@ function validateTaskJokers(task, pipelineIdentification) {
 /**
  * Checks whether one task declares any joker parameters.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function hasTaskJokers(task) {
     return !!task.jokerParameterNames && task.jokerParameterNames.length > 0;
@@ -2921,7 +2988,7 @@ function hasTaskJokers(task) {
 /**
  * Validates that a task has the required supporting features when using jokers.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskSupportsJokers(task, pipelineIdentification) {
     if (task.format || task.expectations /* <- TODO: Require at least 1 -> min <- expectation to use jokers */) {
@@ -2936,7 +3003,7 @@ function validateTaskSupportsJokers(task, pipelineIdentification) {
 /**
  * Validates that every joker parameter is also listed among task dependencies.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskJokerDependencies(task, pipelineIdentification) {
     for (const joker of task.jokerParameterNames) {
@@ -2953,7 +3020,7 @@ function validateTaskJokerDependencies(task, pipelineIdentification) {
 /**
  * Validates all expectation bounds configured on one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectations(task, pipelineIdentification) {
     if (!task.expectations) {
@@ -2968,7 +3035,7 @@ function validateTaskExpectations(task, pipelineIdentification) {
 /**
  * Validates the minimum and maximum expectation ordering for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationRange(unit, min, max, pipelineIdentification) {
     if (min === undefined || max === undefined || min <= max) {
@@ -2983,7 +3050,7 @@ function validateTaskExpectationRange(unit, min, max, pipelineIdentification) {
 /**
  * Validates the minimum expectation bound for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationMin(unit, min, pipelineIdentification) {
     if (min === undefined || min >= 0) {
@@ -2998,7 +3065,7 @@ function validateTaskExpectationMin(unit, min, pipelineIdentification) {
 /**
  * Validates the maximum expectation bound for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationMax(unit, max, pipelineIdentification) {
     if (max === undefined || max > 0) {
@@ -3010,123 +3077,62 @@ function validateTaskExpectationMax(unit, max, pipelineIdentification) {
                 ${block(pipelineIdentification)}
             `));
 }
+
 /**
- * Collects the parameter names that are already resolvable before dependency traversal starts.
- *
- * @private internal utility of `validatePipeline`
- */
-function createInitialDependencyResolutionState(pipeline) {
-    return {
-        resolvedParameterNames: createInitiallyResolvedParameterNames(pipeline),
-        unresolvedTasks: [...pipeline.tasks],
-    };
-}
-/**
- * Checks whether dependency resolution still has tasks left to process.
- *
- * @private internal utility of `validatePipeline`
- */
-function hasUnresolvedTasks({ unresolvedTasks }) {
-    return unresolvedTasks.length > 0;
-}
-/**
- * Resolves the next batch of currently satisfiable tasks.
+ * Validates PipelineJson if it is logically valid
  *
- * @private internal utility of `validatePipeline`
- */
-function resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification) {
-    const currentlyResolvedTasks = getCurrentlyResolvedTasks(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames);
-    if (currentlyResolvedTasks.length === 0) {
-        throw createUnresolvedTasksError(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames, pipelineIdentification);
-    }
-    return {
-        resolvedParameterNames: appendResolvedTaskParameterNames(dependencyResolutionState.resolvedParameterNames, currentlyResolvedTasks),
-        unresolvedTasks: dependencyResolutionState.unresolvedTasks.filter((task) => !currentlyResolvedTasks.includes(task)),
-    };
-}
-/**
- * Collects the parameter names that are already resolvable before dependency traversal starts.
+ * It checks:
+ * -   if it has correct parameters dependency
  *
- * @private internal utility of `validatePipeline`
- */
-function createInitiallyResolvedParameterNames(pipeline) {
-    let resolvedParameterNames = pipeline.parameters
-        .filter(({ isInput }) => isInput)
-        .map(({ name }) => name);
-    for (const reservedParameterName of RESERVED_PARAMETER_NAMES) {
-        resolvedParameterNames = [...resolvedParameterNames, reservedParameterName];
-    }
-    return resolvedParameterNames;
-}
-/**
- * Adds newly resolved task outputs to the resolved parameter list.
+ * It does NOT check:
+ * -   if it is valid json
+ * -   if it is meaningful
  *
- * @private internal utility of `validatePipeline`
- */
-function appendResolvedTaskParameterNames(resolvedParameterNames, currentlyResolvedTasks) {
-    return [
-        ...resolvedParameterNames,
-        ...currentlyResolvedTasks.map(({ resultingParameterName }) => resultingParameterName),
-    ];
-}
-/**
- * Selects tasks whose dependencies are already resolved.
+ * Note: [🔂] This function is idempotent.
  *
- * @private internal utility of `validatePipeline`
- */
-function getCurrentlyResolvedTasks(unresolvedTasks, resolvedParameterNames) {
-    return unresolvedTasks.filter((task) => task.dependentParameterNames.every((name) => resolvedParameterNames.includes(name)));
-}
-/**
- * Creates the unexpected loop-limit error for dependency resolution.
+ * @param pipeline valid or invalid PipelineJson
+ * @returns the same pipeline if it is logically valid
+ * @throws {PipelineLogicError} on logical error in the pipeline
  *
- * @private internal utility of `validatePipeline`
+ * @public exported from `@promptbook/core`
  */
-function createDependencyResolutionLoopLimitError(pipelineIdentification) {
-    // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
-    return new UnexpectedError(spaceTrim$1((block) => `
-                Loop limit reached during detection of circular dependencies in \`validatePipeline\`
+function validatePipeline(pipeline) {
+    if (IS_PIPELINE_LOGIC_VALIDATED) {
+        validatePipeline_InnerFunction(pipeline);
+    }
+    else {
+        try {
+            validatePipeline_InnerFunction(pipeline);
+        }
+        catch (error) {
+            if (!(error instanceof PipelineLogicError)) {
+                throw error;
+            }
+            console.error(spaceTrim$1((block) => `
+                        Pipeline is not valid but logic errors are temporarily disabled via \`IS_PIPELINE_LOGIC_VALIDATED\`
 
-                ${block(pipelineIdentification)}
-            `));
+                        ${block(error.message)}
+                    `));
+        }
+    }
+    return pipeline;
 }
 /**
- * Creates the detailed error for unresolved or circular task dependencies.
+ * Validates pipeline inner function.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal function for `validatePipeline`
  */
-function createUnresolvedTasksError(unresolvedTasks, resolvedParameterNames, pipelineIdentification) {
-    return new PipelineLogicError(
-    // TODO: [🐎] DRY
-    spaceTrim$1((block) => `
-
-                Can not resolve some parameters:
-                Either you are using a parameter that is not defined, or there are some circular dependencies.
-
-                ${block(pipelineIdentification)}
-
-                **Can not resolve:**
-                ${block(unresolvedTasks
-        .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
-        .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
-        .join(' and ')}`)
-        .join('\n'))}
-
-                **Resolved:**
-                ${block(resolvedParameterNames
-        .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
-        .map((name) => `- Parameter \`{${name}}\``)
-        .join('\n'))}
-
-
-                **Reserved (which are available):**
-                ${block(resolvedParameterNames
-        .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
-        .map((name) => `- Parameter \`{${name}}\``)
-        .join('\n'))}
-
-
-            `));
+function validatePipeline_InnerFunction(pipeline) {
+    // TODO: [🧠] Maybe test if promptbook is a promise and make specific error case for that
+    const context = createPipelineValidationContext(pipeline);
+    validatePipelineMetadata(context);
+    validatePipelineCollectionsStructure(context);
+    validatePipelineParameters(context);
+    validatePipelineTasks(context);
+    validatePipelineDependencyResolution(context);
+    // Note: Check that formfactor is corresponding to the pipeline interface
+    // TODO: !!6 Implement this
+    // pipeline.formfactorName
 }
 /**
  * TODO: [🧞‍♀️] Do not allow joker + foreach