@solidxai/core 0.1.13-beta.12 → 0.1.13-beta.13

package/docs/workflow/kestra-concepts-plugins-blueprints.md

@@ -1,315 +0,0 @@
-# Kestra Concepts, Plugins, and Blueprints
-
-This note summarizes the Kestra Academy pages from the `Concepts` section plus the `Plugins` and `Blueprints` lessons. The goal is to translate Kestra's mental model into design inputs for a reusable SolidX workflow engine and builder module.
-
-## Flows
-
-A flow is the top-level workflow container. It defines:
-
-- a unique `id`
-- a `namespace`
-- the `tasks` that perform the work
-
-Kestra treats the flow as the unit of orchestration. The flow holds both the tasks and the orchestration logic that determines how those tasks relate. Flows can be authored in YAML, through a no-code editor, or with AI assistance.
-
-Important behavior:
-
-- Every flow belongs to a namespace
-- Namespaces act like hierarchical folders
-- Flow `id` and `namespace` become permanent after save
-
-### Design implication for us
-
-We will need a first-class workflow definition aggregate with stable identity, logical grouping, versioning, and a representation that can support both code-based and visual editing.
-
-## Tasks
-
-Tasks are the individual executable steps in a flow. They perform discrete actions such as:
-
-- calling an API
-- running code
-- querying a database
-- sending a notification
-
-Kestra highlights two broad task categories:
-
-- Runnable tasks: do actual work
-- Flowable tasks: control orchestration behavior
-
-Every task has at least:
-
-- `id`
-- `type`
-
-Task-specific properties then vary by plugin/task type.
-
-### Design implication for us
-
-Our model should distinguish between:
-
-- step identity
-- step type
-- step configuration
-- executable work steps versus control-flow steps
-
-This is likely the start of a polymorphic node model in our domain.
-
-## Inputs
-
-Inputs parameterize a flow so it can be executed with different values without changing the definition. Kestra inputs have:
-
-- `id`
-- `type`
-
-Common optional properties include:
-
-- `defaults`
-- `displayName`
-- `required`
-- `description`
-
-Kestra supports multiple input types such as string, integer, select, JSON, file, and URI. Inputs are referenced via expressions like `{{ inputs.name }}`.
-
-### Design implication for us
-
-We need a typed workflow input model with validation, defaults, UI metadata, and runtime binding support. Inputs should be usable both at manual execution time and by automated triggers.
-
-## Outputs
-
-Outputs are runtime results produced by tasks. They are stored in the execution context and made available to downstream tasks. Outputs can be:
-
-- simple values
-- structured data
-- files
-
-They are referenced using expressions like `{{ outputs.task_id.output_value }}`.
-
-Kestra also introduces the idea that an entire flow can expose outputs, not just tasks.
-
-### Design implication for us
-
-We need an execution context model that can store and resolve:
-
-- per-step outputs
-- flow-level outputs
-- file or artifact references
-
-This becomes a core part of runtime execution and expression resolution.
-
-## Triggers
-
-Triggers automate flow execution. Kestra describes them as the "when" of a workflow. Examples include:
-
-- schedules
-- polling
-- realtime events
-- webhooks
-- flow completion triggers
-
-Triggers have their own `id`, `type`, and type-specific configuration. They can also pass input values into a flow when they fire. A single flow can have multiple triggers.
-
-### Design implication for us
-
-We need a first-class trigger model that supports:
-
-- multiple trigger instances per workflow
-- trigger-specific configuration
-- input injection
-- manual and automated execution paths
-
-This likely means triggers should be separate domain entities attached to a workflow definition rather than being embedded as anonymous config blobs only.
-
-## Expressions
-
-Expressions are the dynamic binding and transformation layer. Kestra uses `{{ }}` syntax and allows access to runtime context such as:
-
-- `inputs`
-- `outputs`
-- `flow`
-- `execution`
-- `trigger`
-
-Expressions can do more than variable lookup. They can:
-
-- transform values
-- parse JSON
-- format dates
-- perform calculations
-
-### Design implication for us
-
-We need to make an early architectural decision about the expression system:
-
-- whether to design our own expression format
-- whether to embed an existing engine
-- what execution context objects are exposed
-- how expressions are validated at design time versus resolved at runtime
-
-This is a foundational concern because it affects inputs, outputs, conditions, triggers, and task configuration.
-
-## Flowable Tasks
-
-Flowable tasks control orchestration instead of doing business work directly. Kestra highlights patterns such as:
-
-- conditional branching with `If` and `Switch`
-- iteration with `ForEach`, `ForEachItem`, and `LoopUntil`
-- parallel execution
-- subflows for reuse
-
-These tasks combine orchestration rules with expressions.
-
-### Design implication for us
-
-Our workflow graph cannot be modeled as only a flat list of steps. We will need support for:
-
-- branching
-- nesting
-- loops
-- fan-out / parallelism
-- reusable subflow invocation
-
-This pushes us toward a graph or tree-plus-edges model rather than a simple sequential pipeline model.
-
-## Execution
-
-An execution is a single run of a flow. Each execution contains task runs, and each task run has its own runtime behavior, outputs, logs, and status.
-
-Kestra emphasizes:
-
-- execution states such as created, running, success, failed
-- observability through logs, metrics, outputs, topology, and timing views
-- replaying failed task runs or entire executions
-- revisions of flow definitions
-
-### Design implication for us
-
-We should model workflow definition and workflow execution separately. At minimum, our domain will likely need:
-
-- workflow definitions
-- workflow revisions
-- workflow executions
-- step executions
-- execution state transitions
-- logs / metrics / artifacts
-- replay or rerun semantics
-
-## Secrets
-
-Secrets are sensitive values stored outside workflow definitions and referenced at runtime. Kestra exposes them through expressions via a `secret()` function and avoids leaking them into code, logs, and outputs.
-
-### Design implication for us
-
-We need a secret reference strategy, not just plain text fields. The module should support:
-
-- secure secret references in workflow definitions
-- runtime secret resolution
-- masking in logs and UI
-- separation between design-time config and sensitive runtime values
-
-## Plugins
-
-Plugins are the extension mechanism that powers tasks and triggers. In Kestra's framing, plugins are the integration and capability layer that connects workflows to:
-
-- programming runtimes
-- databases
-- APIs
-- cloud systems
-- notification channels
-
-Even "core" capabilities are still exposed as plugin-backed task or trigger types.
-
-### Design implication for us
-
-This is especially important for our module. We should not hard-code every possible step type into the core engine. We likely need:
-
-- a reusable action/task type registry
-- typed configuration schemas per task type
-- trigger type registry
-- optional packaging/distribution story for reusable step providers
-
-In SolidX terms, this may become one of the primary extensibility points of the module.
-
-## Blueprints
-
-Blueprints are curated, ready-to-use example workflows. Kestra presents them as:
-
-- working code
-- documentation
-- tags for discovery
-
-They are meant to accelerate adoption by giving users validated examples that can be copied and adapted.
-
-### Design implication for us
-
-A reusable workflow builder module will benefit from a blueprint/template system from the start or at least early in the roadmap. Blueprints can help with:
-
-- onboarding
-- discoverability
-- best-practice reuse
-- sample implementations of step types and orchestration patterns
-
-## Cross-Cutting Observations
-
-Kestra's model repeatedly separates concerns in a very clean way:
-
-- Definition versus execution
-- Work steps versus control-flow steps
-- Static configuration versus runtime context
-- Secure references versus plain values
-- Core engine versus plugin-provided capabilities
-
-That separation is probably the biggest lesson for our design.
-
-## Likely Domain Areas For Our SolidX Module
-
-Based on these lessons, our reusable module will probably need domain models for at least:
-
-- Workflow definition
-- Workflow revision
-- Workflow namespace or foldering concept
-- Workflow input
-- Workflow output
-- Trigger
-- Step / task
-- Step type registry
-- Step execution
-- Workflow execution
-- Execution logs and artifacts
-- Secret reference
-- Blueprint / template
-
-## Metadata / DSL Implication
-
-Kestra uses YAML as a human-readable workflow definition format. For our SolidX module, we should expect to define an equivalent metadata representation for workflows that can support:
-
-- stable workflow identity
-- typed nodes
-- nested control-flow structures
-- trigger definitions
-- expressions
-- reusable references
-- versioning
-
-That representation will need to work for both:
-
-- a visual workflow builder
-- a code or JSON/YAML style export/import story
-
-## Sources
-
-- [Flows](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404093-flows)
-- [Tasks](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404094-tasks)
-- [Inputs](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404096-inputs)
-- [Outputs](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404097-outputs)
-- [Triggers](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404103-triggers)
-- [Expressions](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404099-expressions)
-- [Flowable Tasks](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404106-flowable-tasks)
-- [Execution](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404107-execution)
-- [Secrets](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404115-secrets)
-- [Plugins](https://academy.kestra.io/p/courses/kestra-fundamentals/3492618-plugins-blueprints/11437898-plugins)
-- [Blueprints](https://academy.kestra.io/p/courses/kestra-fundamentals/3492618-plugins-blueprints/11437900-blueprints)
-
-## Notes
-
-- The extracted lesson text was pulled from the Academy pages directly.
-- Some lessons included image-heavy examples, so the summary focuses on the textual teaching content plus explicit design implications for our module.

package/docs/workflow/loop-until-example-notes.md

@@ -1,198 +0,0 @@
-# LoopUntil Example Notes
-
-## Purpose
-
-This document captures a reference workflow for `LoopUntil`. It complements the `ForEach` example by showing a different kind of loop: repeat-until-success rather than iterate-over-values.
-
----
-
-## Example Workflow YAML
-
-```yaml
-id: loop_until_health_check
-namespace: company.team
-
-tasks:
-  - id: loop
-    type: io.kestra.plugin.core.flow.LoopUntil
-    condition: "{{ outputs.healthCheck.code == 200 }}"
-    checkFrequency:
-      interval: PT30S
-      maxIterations: 50
-    tasks:
-      - id: healthCheck
-        type: io.kestra.plugin.core.http.Request
-        method: GET
-        uri: https://kestra.io/
-```
-
----
-
-## What This Example Adds
-
-This example is useful because it shows:
-
-- condition-based looping
-- repeated polling / health-check behavior
-- loop frequency metadata
-- max-iteration safeguards
-- a loop container with a small loop body
-
-It is the clearest reference for workflows that keep trying until a condition becomes true.
-
----
-
-## High-Level Structure
-
-```text
-Start
-  |
-  v
-loop
-  |
-  v
-healthCheck
-  |
-  v
-repeat until outputs.healthCheck.code == 200
-  |
-  v
-End
-```
-
-Conceptually:
-
-```text
-Workflow
-└── loop
-    └── healthCheck
-```
-
-Runtime interpretation:
-
-```text
-Repeat:
-  run healthCheck
-Until:
-  outputs.healthCheck.code == 200
-
-With:
-  interval = PT30S
-  maxIterations = 50
-```
-
----
-
-## Main Note
-
-### Example With `LoopUntil`
-
-This is the key purpose of the example.
-
-It shows that not all loops are collection-based like `ForEach`.
-
-`LoopUntil` is driven by:
-
-- a stop condition
-- a repeated body
-- retry/check timing configuration
-- a max-iteration limit
-
-So the UI must distinguish between:
-
-- looping over values
-- looping until a condition is met
-
----
-
-## Topology Notes
-
-The screenshot suggests:
-
-- `LoopUntil` is rendered as a grouped/container region
-- the loop node appears at the top of that region
-- the loop body task appears within the same grouped area
-- the visual sequence remains vertical and directional
-
-This is similar to `ForEach` structurally, but the semantics are different enough that the node metadata and docs must explain the difference clearly.
-
----
-
-## Loop Semantics Notes
-
-This example introduces loop control metadata that is especially important for docs and forms:
-
-- `condition`
-- `checkFrequency.interval`
-- `checkFrequency.maxIterations`
-
-That means the schema-driven editor should eventually support:
-
-- expression-aware editing for the stop condition
-- structured editing for timing/frequency settings
-- clear validation for required loop settings
-
----
-
-## Implications For SolidX Flow Modeling
-
-This example implies the loop category should likely have meaningful subtypes:
-
-- `ForEach`
-- `LoopUntil`
-
-Both may be rendered as loop containers, but their configuration UX differs:
-
-- `ForEach` needs collection/value configuration
-- `LoopUntil` needs condition and frequency configuration
-
-So the generic metadata contract should preserve enough node-specific structure to power a richer modal form.
-
----
-
-## Editor Notes
-
-This example fits the current editor direction well:
-
-- code remains the source of truth
-- flow visualizes the loop container and body
-- node editing should be modal and schema-driven
-- docs should explain loop semantics and available configuration
-
-This is also a good candidate for future validation because it contains:
-
-- expressions
-- loop structure
-- nested tasks
-- timing configuration
-
----
-
-## Future UX Notes
-
-This example points to a few future needs:
-
-- loop-type specific modal forms
-- duration / interval input UX
-- expression assistance for loop conditions
-- better visualization of “repeat until” semantics in the docs panel
-
----
-
-## Screenshot References
-
-This screenshot informed the notes above:
-
-- `/var/folders/z_/h0rqj1693gs4cxm3k_vks86c0000gn/T/TemporaryItems/NSIRD_screencaptureui_hm7Us9/Screenshot 2026-07-10 at 17.18.11.png`
-
----
-
-## Recommended Follow-On Use
-
-This example should be used as a reference for:
-
-1. `LoopUntil` node rendering
-2. condition-based loop semantics
-3. interval / max-iteration configuration UX
-4. differentiating loop subtypes in docs and forms
-5. future expression-aware validation for looping constructs