@promptbook/documents 0.113.0-1 → 0.113.0-10

package/umd/index.umd.js

@@ -26,7 +26,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-1';
+    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-10';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -107,6 +107,127 @@
         });
     }
 
+    /**
+     * 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
      *
@@ -266,127 +387,6 @@
     };
     // 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
      *
@@ -2122,20 +2122,109 @@
     // 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.spaceTrim((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.spaceTrim((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
@@ -2484,16 +2573,137 @@
     // 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.spaceTrim((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.spaceTrim((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'))}
+
+
+            `));
     }
 
     /**
@@ -2571,171 +2781,22 @@
     // 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.spaceTrim((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.spaceTrim((block) => `
@@ -2747,7 +2808,7 @@
     /**
      * 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)) {
@@ -2760,48 +2821,31 @@
                 ${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.spaceTrim((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.spaceTrim((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) {
@@ -2818,7 +2862,7 @@
     /**
      * 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)) {
@@ -2837,7 +2881,7 @@
     /**
      * 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)) {
@@ -2856,7 +2900,7 @@
     /**
      * 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));
@@ -2864,23 +2908,46 @@
     /**
      * 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)) {
@@ -2902,7 +2969,7 @@
     /**
      * Validates joker parameters for one task.
      *
-     * @private internal utility of `validatePipeline`
+     * @private internal utility of `validatePipelineTasks`
      */
     function validateTaskJokers(task, pipelineIdentification) {
         if (!hasTaskJokers(task)) {
@@ -2914,7 +2981,7 @@
     /**
      * 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;
@@ -2922,7 +2989,7 @@
     /**
      * 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 */) {
@@ -2937,7 +3004,7 @@
     /**
      * 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) {
@@ -2954,7 +3021,7 @@
     /**
      * 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) {
@@ -2969,7 +3036,7 @@
     /**
      * 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) {
@@ -2984,7 +3051,7 @@
     /**
      * 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) {
@@ -2999,7 +3066,7 @@
     /**
      * 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) {
@@ -3011,123 +3078,62 @@
                 ${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.spaceTrim((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.spaceTrim((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.spaceTrim((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