@solidxai/core 0.1.12-beta.2 → 0.1.12-beta.4

package/docs/workflow/workflow-node-ui-metadata-contract.md

@@ -1,1262 +0,0 @@
-# Workflow Node UI Metadata Contract
-
-## Purpose
-
-This document explains the newly added workflow node metadata interfaces in:
-
-- `solid-core-module/src/types/workflow-dsl.types.ts`
-- `solid-core-ui/src/types/extension-registry.ts`
-
-The goal is to support a workflow editor that is:
-
-- schema-driven by default
-- dynamically documented
-- extensible through optional UI overrides
-- safe for both `solid-core-ui` and consuming `solid-ui` projects
-
-The core principle remains:
-
-- backend metadata is the source of truth
-- custom React components are optional escape hatches
-- UI modules resolve component keys, the backend does not import React directly
-
----
-
-## Design Summary
-
-The new contract separates concerns into four layers:
-
-1. `runtime`
-   What the node does when executed.
-2. `authoring`
-   How the node is configured in schema-driven forms.
-3. `documentation`
-   What the Docs panel can render.
-4. `ui`
-   Optional extension keys for richer editors and docs renderers.
-
----
-
-## Object Graph
-
-The following diagram shows how the newly added types relate to each other.
-
-```mermaid
-graph TD
-  A["WorkflowNodeProviderMetadata"] --> B["authoring: WorkflowNodeAuthoringMetadata"]
-  A --> C["runtime: WorkflowNodeRuntimeMetadata"]
-  A --> D["documentation: WorkflowNodeDocumentationMetadata"]
-  A --> E["ui: WorkflowNodeUiMetadata"]
-  A --> F["examples: WorkflowNodeExampleDefinition[]"]
-  A --> G["metrics: WorkflowNodeMetricDefinition[]"]
-  A --> H["definitions: WorkflowNodeReferenceDefinition[]"]
-  A --> I["configSchema / uiSchema / outputSchema"]
-
-  B --> B1["defaultConfiguration"]
-  B --> B2["configurationFields: WorkflowNodeConfigurationFieldDefinition[]"]
-  B --> B3["childSlots: WorkflowNodeChildSlotDefinition[]"]
-  B --> B4["outputs: WorkflowNodeOutputDefinition[]"]
-  B --> B5["supportsExpressions / retry / timeout / onError / etc."]
-
-  B2 --> B2a["valueType: WorkflowNodeConfigurationValueType"]
-  B2 --> B2b["extensionComponentKey?"]
-  B2 --> B2c["schema / uiSchema"]
-
-  B3 --> B3a["sequence"]
-  B3 --> B3b["branch-collection"]
-
-  D --> D1["summary"]
-  D --> D2["sections: WorkflowNodeDocumentationSection[]"]
-  D --> D3["examples: WorkflowNodeExampleDefinition[]"]
-  D --> D4["outputs: WorkflowNodeOutputDefinition[]"]
-  D --> D5["metrics: WorkflowNodeMetricDefinition[]"]
-  D --> D6["definitions: WorkflowNodeReferenceDefinition[]"]
-
-  E --> E1["editorComponentKey"]
-  E --> E2["docsComponentKey"]
-  E --> E3["paletteComponentKey"]
-  E --> E4["fieldComponentKeys"]
-  E --> E5["layoutHints"]
-
-  J["WorkflowNodeMetadataResponse"] --> A
-
-  K["solid-core-ui ExtensionComponentTypes"] --> K1["workflowNodeEditor"]
-  K --> K2["workflowNodeDocs"]
-  K --> K3["workflowNodeFieldEditor"]
-  K --> K4["workflowNodePaletteCard"]
-
-  E1 -.resolved by.-> K1
-  E2 -.resolved by.-> K2
-  B2b -.resolved by.-> K3
-  E3 -.resolved by.-> K4
-```
-
-### Hierarchy in words
-
-At the top level:
-
-- `WorkflowNodeProviderMetadata` is the main backend contract for one node type
-- `WorkflowNodeMetadataResponse` is the client-facing shape that can expose that metadata to the UI
-
-Inside node metadata:
-
-- `authoring` drives schema-based form editing
-- `runtime` describes execution behavior hints
-- `documentation` drives the Docs panel
-- `ui` provides optional extension keys and layout hints
-
-Inside authoring:
-
-- `configurationFields` define editable properties
-- each property can use `WorkflowNodeConfigurationValueType`
-- each property can optionally point to a field-level extension component
-- `childSlots` define control-node nesting structure
-- `outputs` define what downstream nodes can reference
-
-Inside documentation:
-
-- sections, examples, outputs, metrics, and definitions can all be rendered dynamically
-
-On the frontend:
-
-- `workflowNodeEditor` is the full-node editor escape hatch
-- `workflowNodeDocs` is the custom docs renderer escape hatch
-- `workflowNodeFieldEditor` is the preferred field-level override
-- `workflowNodePaletteCard` customizes node selection/palette cards
-
-### Runtime execution graph
-
-The following smaller diagram shows how the runtime-side workflow types fit together during actual execution.
-
-```mermaid
-graph TD
-  A["WorkflowDefinitionDsl"] --> B["WorkflowNodeDefinition[]"]
-  B --> C["WorkflowRuntimeContext"]
-  C --> D["WorkflowNodeExecutionContext"]
-
-  D --> E["WorkflowNodeHandler.execute(...)"]
-  E --> F["WorkflowNodeHandlerResult"]
-
-  C --> G["input"]
-  C --> H["variables"]
-  C --> I["outputs"]
-  C --> J["execution: WorkflowExecution"]
-  C --> K["stepExecution: WorkflowStepExecution?"]
-  C --> L["item / index / parentNodeId"]
-
-  D --> M["expression resolver"]
-  D --> N["runNodes(...)"]
-  D --> O["emitLog(...)"]
-  D --> P["emitArtifact(...)"]
-
-  F --> Q["output"]
-  F --> R["artifacts"]
-  F --> S["status"]
-
-  O --> T["WorkflowExecutionLog"]
-  P --> U["WorkflowExecutionArtifact"]
-  Q --> I
-  S --> K
-
-  V["Future: WorkflowExecutionMetric"] -.pending.-> W["metric persistence / telemetry"]
-  E -.may emit.-> V
-```
-
-### Runtime hierarchy in words
-
-At execution time:
-
-- `WorkflowDefinitionDsl` is parsed from `definitionYaml` and contains the ordered `WorkflowNodeDefinition[]`
-- the runtime builds a `WorkflowRuntimeContext`
-- when a node is about to run, that becomes a `WorkflowNodeExecutionContext`
-- the node handler executes against that context
-- the result can update:
-  - `outputs`
-  - `WorkflowStepExecution` status
-  - `WorkflowExecutionLog`
-  - `WorkflowExecutionArtifact`
-
-Important separation:
-
-- `WorkflowNodeDefinition` is design-time configuration
-- `WorkflowRuntimeContext` is in-memory execution state
-- `WorkflowExecution`, `WorkflowStepExecution`, logs, and artifacts are persisted runtime records
-- `metrics` are still pending a persistence or telemetry strategy
-
----
-
-## New Backend Types
-
-### `WorkflowNodeConfigurationValueType`
-
-This is the common vocabulary for describing field value shapes across authoring, outputs, and docs.
-
-```ts
-type WorkflowNodeConfigurationValueType =
-  | "string"
-  | "number"
-  | "integer"
-  | "boolean"
-  | "object"
-  | "array"
-  | "json"
-  | "secret"
-  | "expression"
-  | "relation"
-  | "uri"
-  | "any";
-```
-
-Example:
-
-```ts
-const queryFieldType: WorkflowNodeConfigurationValueType = "string";
-const providerFieldType: WorkflowNodeConfigurationValueType = "object";
-const secretFieldType: WorkflowNodeConfigurationValueType = "secret";
-```
-
-Why it matters:
-
-- keeps backend and frontend aligned on data type meaning
-- supports form generation
-- supports docs badges such as `String`, `Object`, `URI`, `Secret`
-
----
-
-### `WorkflowNodeProviderMetadata`
-
-This is now the canonical metadata contract for one node type.
-
-Example:
-
-```ts
-const httpRequestNodeMetadata: WorkflowNodeProviderMetadata = {
-  type: "http.request",
-  kind: "task",
-  version: "1.0.0",
-  category: "integration",
-  subcategory: "http",
-  label: "HTTP Request",
-  description: "Execute an outbound HTTP request and expose the response.",
-  icon: "globe",
-  tags: ["http", "api", "integration"],
-  aliases: ["http.fetch"],
-  configSchema: {
-    type: "object",
-    required: ["uri"],
-    properties: {
-      method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"] },
-      uri: { type: "string" },
-      headers: { type: "object" },
-      body: {},
-      timeoutMs: { type: "number" }
-    }
-  },
-  uiSchema: {
-    "ui:order": ["method", "uri", "headers", "body", "timeoutMs"]
-  },
-  outputSchema: {
-    type: "object",
-    properties: {
-      ok: { type: "boolean" },
-      status: { type: "number" },
-      headers: { type: "object" },
-      body: {}
-    }
-  },
-  examples: [
-    {
-      key: "simple-get",
-      label: "Simple GET request",
-      language: "json",
-      snippet: "{\"method\":\"GET\",\"uri\":\"{{ inputs.endpoint }}\"}",
-      configurationOnly: true
-    }
-  ],
-  metrics: [
-    {
-      key: "http.request.duration",
-      label: "Request duration",
-      type: "timer",
-      unit: "ms"
-    }
-  ],
-  definitions: [
-    {
-      key: "success-status-behavior",
-      label: "Success status behavior",
-      content: "When configured, the node treats only the given status codes as successful."
-    }
-  ],
-  authoring: {
-    supportsExpressions: true,
-    supportsRetryPolicy: true,
-    supportsTimeoutMs: true,
-    supportsOnError: true,
-    supportsDisableToggle: true,
-    supportsName: true,
-    supportsDescription: true
-  },
-  runtime: {
-    emitsLogs: true,
-    emitsArtifacts: false,
-    deterministicOutputs: false,
-    executionMode: "task",
-    successStatuses: ["success"]
-  },
-  documentation: {
-    summary: "Call an API, capture the response, and expose it to downstream nodes."
-  },
-  ui: {
-    defaultEditorMode: "schema",
-    editorComponentKey: "workflow.node.httpRequest.editor",
-    docsComponentKey: "workflow.node.httpRequest.docs",
-    paletteComponentKey: "workflow.node.httpRequest.palette",
-    modalSize: "xl"
-  }
-};
-```
-
-Why it matters:
-
-- one object can power Code, Flow, and Docs
-- allows core tasks and consuming-project tasks to look uniform
-- enables future API endpoints such as `GET /workflow-node-types`
-
----
-
-### `WorkflowNodeChildSlotDefinition`
-
-Describes how a control node owns nested node collections.
-
-Example for an `if` node:
-
-```ts
-const ifChildSlots: WorkflowNodeChildSlotDefinition[] = [
-  {
-    key: "then",
-    label: "Then branch",
-    description: "Runs when the condition evaluates to true.",
-    kind: "sequence",
-    required: true,
-    minItems: 1
-  },
-  {
-    key: "else",
-    label: "Else branch",
-    description: "Runs when the condition evaluates to false.",
-    kind: "sequence",
-    required: false
-  }
-];
-```
-
-Example for a `parallel` node:
-
-```ts
-const parallelChildSlots: WorkflowNodeChildSlotDefinition[] = [
-  {
-    key: "branches",
-    label: "Parallel branches",
-    description: "Each branch runs concurrently and contains its own ordered node list.",
-    kind: "branch-collection",
-    required: true,
-    minItems: 1
-  }
-];
-```
-
-Why it matters:
-
-- tells the Flow editor which nested containers to render
-- keeps control-node authoring declarative
-- avoids hardcoding `then`, `else`, `children`, `branches` everywhere
-
----
-
-### `WorkflowNodeConfigurationFieldDefinition`
-
-Describes one configurable field for schema-driven authoring.
-
-Example:
-
-```ts
-const uriField: WorkflowNodeConfigurationFieldDefinition = {
-  key: "uri",
-  label: "Request URI",
-  description: "The target endpoint for the request.",
-  valueType: "uri",
-  required: true,
-  path: "uri",
-  expressionAllowed: true,
-  secretAllowed: false,
-  examples: ["https://example.com", "{{ inputs.endpoint }}"],
-  group: "Request",
-  widgetHint: "text",
-  schema: {
-    type: "string"
-  },
-  uiSchema: {
-    "ui:placeholder": "https://api.example.com/orders"
-  }
-};
-```
-
-Example with an escape-hatch field renderer:
-
-```ts
-const headersField: WorkflowNodeConfigurationFieldDefinition = {
-  key: "headers",
-  label: "Headers",
-  description: "Optional request headers.",
-  valueType: "object",
-  path: "headers",
-  expressionAllowed: true,
-  group: "Request",
-  widgetHint: "key-value-editor",
-  extensionComponentKey: "workflow.node.field.headersEditor"
-};
-```
-
-Why it matters:
-
-- default form generation happens from these definitions
-- special UX can still be plugged in at the field level
-- supports property tables in the Docs panel
-
----
-
-### `WorkflowNodeOutputDefinition`
-
-Describes one named output exposed by a node.
-
-Example:
-
-```ts
-const httpOutputs: WorkflowNodeOutputDefinition[] = [
-  {
-    key: "status",
-    label: "HTTP status",
-    description: "Status code returned by the remote server.",
-    valueType: "integer",
-    path: "status",
-    required: true
-  },
-  {
-    key: "body",
-    label: "Response body",
-    description: "Parsed response body.",
-    valueType: "any",
-    path: "body"
-  }
-];
-```
-
-Why it matters:
-
-- powers downstream autocomplete such as `{{ outputs.makeRequest.status }}`
-- powers output docs
-- keeps output semantics explicit instead of implied only by runtime code
-
----
-
-### `WorkflowNodeMetricDefinition`
-
-Describes metrics that a node may emit or contribute to.
-
-Example:
-
-```ts
-const httpMetrics: WorkflowNodeMetricDefinition[] = [
-  {
-    key: "http.request.duration",
-    label: "Request duration",
-    description: "Measures the end-to-end request duration.",
-    type: "timer",
-    unit: "ms",
-    tags: ["http", "latency"]
-  },
-  {
-    key: "http.request.error.count",
-    label: "Request errors",
-    description: "Counts request failures.",
-    type: "counter",
-    tags: ["http", "errors"]
-  }
-];
-```
-
-Why it matters:
-
-- lets the Docs panel show observability affordances
-- helps future execution dashboards stay aligned with task metadata
-
----
-
-### `WorkflowNodeExampleDefinition`
-
-Represents a runnable or illustrative example.
-
-Example:
-
-```ts
-const simpleExample: WorkflowNodeExampleDefinition = {
-  key: "simple-log",
-  label: "Simple log statement",
-  description: "Minimal log task example.",
-  language: "json",
-  snippet: "{\"message\":\"Hello {{ inputs.name }}\"}",
-  configurationOnly: true
-};
-```
-
-Flow-level example:
-
-```ts
-const fullFlowExample: WorkflowNodeExampleDefinition = {
-  key: "health-check-flow",
-  label: "Health check flow",
-  description: "Make a request and log the status code.",
-  language: "json",
-  snippet: "{\n  \"nodes\": [\n    {\n      \"id\": \"makeRequest\",\n      \"kind\": \"task\",\n      \"type\": \"http.request\",\n      \"configuration\": {\n        \"uri\": \"{{ inputs.uri }}\"\n      }\n    }\n  ]\n}"
-};
-```
-
-Why it matters:
-
-- docs become immediately practical
-- examples can later power “insert sample configuration” actions
-
----
-
-### `WorkflowNodeReferenceDefinition`
-
-Represents richer supporting definitions, reference cards, or embedded sub-docs.
-
-Example:
-
-```ts
-const pgVectorDefinition: WorkflowNodeReferenceDefinition = {
-  key: "pgvector-connection",
-  label: "PGVector connection definition",
-  description: "Fields required when using the PGVector embedding store.",
-  content: "The PGVector provider needs host, port, user, password, database, and table.",
-  schema: {
-    type: "object",
-    required: ["host", "port", "database", "table"]
-  },
-  examples: [
-    {
-      key: "pgvector-sample",
-      label: "PGVector sample",
-      language: "json",
-      snippet: "{\"host\":\"localhost\",\"port\":5432,\"database\":\"postgres\",\"table\":\"embeddings\"}",
-      configurationOnly: true
-    }
-  ]
-};
-```
-
-Why it matters:
-
-- supports the richer Kestra-style docs experience
-- lets one task document nested definition families cleanly
-
----
-
-### `WorkflowNodeDocumentationSection`
-
-Represents one named section in the Docs panel.
-
-Example:
-
-```ts
-const docsSections: WorkflowNodeDocumentationSection[] = [
-  {
-    key: "summary",
-    label: "Summary",
-    markdown: "Calls an HTTP endpoint and exposes the response to downstream nodes.",
-    initiallyExpanded: true
-  },
-  {
-    key: "error-behavior",
-    label: "Error behavior",
-    markdown: "Network failures and timeout failures cause the node to fail."
-  }
-];
-```
-
-Why it matters:
-
-- keeps docs structured instead of one long markdown blob
-- supports stable tabs, accordions, and search anchors later
-
----
-
-### `WorkflowNodeAuthoringMetadata`
-
-Defines the schema-driven authoring experience.
-
-Example:
-
-```ts
-const httpAuthoring: WorkflowNodeAuthoringMetadata = {
-  defaultConfiguration: {
-    method: "GET",
-    headers: {},
-    timeoutMs: 30000
-  },
-  configurationFields: [
-    {
-      key: "method",
-      label: "Method",
-      valueType: "string",
-      required: false,
-      enumValues: ["GET", "POST", "PUT", "PATCH", "DELETE"],
-      defaultValue: "GET",
-      group: "Request"
-    },
-    {
-      key: "uri",
-      label: "URI",
-      valueType: "uri",
-      required: true,
-      expressionAllowed: true,
-      group: "Request"
-    }
-  ],
-  outputs: [
-    {
-      key: "status",
-      label: "Status",
-      valueType: "integer",
-      required: true
-    }
-  ],
-  supportsExpressions: true,
-  supportsRetryPolicy: true,
-  supportsTimeoutMs: true,
-  supportsOnError: true,
-  supportsDisableToggle: true,
-  supportsName: true,
-  supportsDescription: true,
-  searchableText: ["http", "api", "request", "rest"]
-};
-```
-
-Why it matters:
-
-- this is the default engine for modal-form node editing
-- lets the editor stay metadata-driven for most nodes
-
----
-
-### `WorkflowNodeRuntimeMetadata`
-
-Describes runtime behavior hints.
-
-Example:
-
-```ts
-const forEachRuntime: WorkflowNodeRuntimeMetadata = {
-  emitsLogs: false,
-  emitsArtifacts: false,
-  deterministicOutputs: false,
-  executionMode: "engine-controlled",
-  successStatuses: ["success", "skipped"]
-};
-```
-
-Why it matters:
-
-- separates runtime semantics from docs and authoring concerns
-- especially useful for control nodes where the engine owns traversal
-
----
-
-### `WorkflowNodeDocumentationMetadata`
-
-Bundles the content needed for the Docs panel.
-
-Example:
-
-```ts
-const searchNodeDocs: WorkflowNodeDocumentationMetadata = {
-  summary: "Search an embedding store and return ranked matches.",
-  sections: [
-    {
-      key: "behavior",
-      label: "Behavior",
-      markdown: "The node computes embeddings using the configured provider and queries the selected store."
-    }
-  ],
-  examples: [
-    {
-      key: "search-example",
-      label: "Search embeddings",
-      language: "json",
-      snippet: "{\"query\":\"workflow builder\",\"maxResults\":5}",
-      configurationOnly: true
-    }
-  ],
-  outputs: [
-    {
-      key: "results",
-      label: "Results",
-      valueType: "array"
-    }
-  ],
-  metrics: [
-    {
-      key: "ai.provider.calls",
-      label: "Provider calls",
-      type: "counter"
-    }
-  ],
-  definitions: [
-    {
-      key: "embedding-store-definitions",
-      label: "Embedding store definitions",
-      content: "Available stores may define different required connection properties."
-    }
-  ]
-};
-```
-
-Why it matters:
-
-- gives the Docs panel a stable API
-- aligns closely with the examples shown in the Kestra screenshots
-
----
-
-### `WorkflowNodeUiMetadata`
-
-Defines optional UI extension keys and layout hints.
-
-Example:
-
-```ts
-const httpUi: WorkflowNodeUiMetadata = {
-  editorComponentKey: "workflow.node.httpRequest.editor",
-  docsComponentKey: "workflow.node.httpRequest.docs",
-  paletteComponentKey: "workflow.node.httpRequest.palette",
-  defaultEditorMode: "schema",
-  fieldComponentKeys: {
-    headers: "workflow.node.field.headersEditor",
-    body: "workflow.node.field.bodyEditor"
-  },
-  modalSize: "xl",
-  layoutHints: {
-    preferredPanel: "flow",
-    groupOrder: ["Request", "Authentication", "Advanced"],
-    stickySummary: true
-  }
-};
-```
-
-Meaning of the fields:
-
-- `editorComponentKey`
-  Optional full-node editor override.
-- `docsComponentKey`
-  Optional docs renderer override.
-- `paletteComponentKey`
-  Optional custom card for the node picker/palette.
-- `defaultEditorMode`
-  Tells the UI whether the preferred experience is still schema-first or custom-first.
-- `fieldComponentKeys`
-  Field-specific escape hatches without replacing the entire node editor.
-- `modalSize`
-  Good for large configuration surfaces.
-- `layoutHints`
-  Helps the UI arrange content without hardcoding per-node behavior.
-
-Why it matters:
-
-- keeps the backend decoupled from React
-- gives the UI enough information to resolve optional enhancements
-
----
-
-### `WorkflowNodeMetadataResponse`
-
-Represents the shape the backend can safely expose to clients.
-
-Example:
-
-```ts
-const metadataResponse: WorkflowNodeMetadataResponse = {
-  type: "http.request",
-  kind: "task",
-  version: "1.0.0",
-  category: "integration",
-  subcategory: "http",
-  label: "HTTP Request",
-  description: "Execute an outbound HTTP request.",
-  icon: "globe",
-  tags: ["http", "api"],
-  configSchema: {
-    type: "object",
-    required: ["uri"]
-  },
-  uiSchema: {
-    "ui:order": ["method", "uri", "headers", "body"]
-  },
-  outputSchema: {
-    type: "object",
-    properties: {
-      status: { type: "number" }
-    }
-  },
-  examples: [
-    {
-      key: "basic",
-      label: "Basic request",
-      language: "json",
-      snippet: "{\"uri\":\"{{ inputs.url }}\"}",
-      configurationOnly: true
-    }
-  ],
-  metrics: [
-    {
-      key: "http.request.duration",
-      label: "Request duration",
-      type: "timer"
-    }
-  ],
-  definitions: [
-    {
-      key: "status-definition",
-      label: "Status definition",
-      content: "HTTP status code returned by the response."
-    }
-  ],
-  authoring: httpAuthoring,
-  runtime: {
-    emitsLogs: true,
-    executionMode: "task"
-  },
-  documentation: searchNodeDocs,
-  ui: httpUi
-};
-```
-
-Why it matters:
-
-- good DTO/API shape for the future editor
-- allows UI clients to stay ignorant of server implementation details
-
----
-
-## Example: Full Core Node Metadata
-
-Below is a compact end-to-end example for a core `log.write` node:
-
-```ts
-const logWriteNode: WorkflowNodeProviderMetadata = {
-  type: "log.write",
-  kind: "task",
-  version: "1.0.0",
-  category: "core",
-  label: "Write Log",
-  description: "Write a log line into the workflow execution log.",
-  icon: "file-text",
-  tags: ["log", "observability"],
-  configSchema: {
-    type: "object",
-    required: ["message"],
-    properties: {
-      level: { type: "string", enum: ["debug", "info", "warn", "error"] },
-      message: { type: "string" },
-      metadata: { type: "object" }
-    }
-  },
-  authoring: {
-    defaultConfiguration: {
-      level: "info"
-    },
-    configurationFields: [
-      {
-        key: "level",
-        label: "Level",
-        valueType: "string",
-        enumValues: ["debug", "info", "warn", "error"],
-        defaultValue: "info",
-        group: "Message"
-      },
-      {
-        key: "message",
-        label: "Message",
-        valueType: "string",
-        required: true,
-        expressionAllowed: true,
-        group: "Message"
-      },
-      {
-        key: "metadata",
-        label: "Metadata",
-        valueType: "object",
-        expressionAllowed: true,
-        group: "Advanced"
-      }
-    ],
-    outputs: [
-      {
-        key: "message",
-        label: "Rendered message",
-        valueType: "string"
-      },
-      {
-        key: "level",
-        label: "Rendered level",
-        valueType: "string"
-      }
-    ],
-    supportsExpressions: true,
-    supportsDisableToggle: true,
-    supportsName: true,
-    supportsDescription: true
-  },
-  runtime: {
-    emitsLogs: true,
-    emitsArtifacts: false,
-    deterministicOutputs: true,
-    executionMode: "task",
-    successStatuses: ["success"]
-  },
-  documentation: {
-    summary: "A lightweight task for debug messages, audit breadcrumbs, and quick verification.",
-    sections: [
-      {
-        key: "usage",
-        label: "Usage",
-        markdown: "Use this task to inspect expressions and execution values during development."
-      }
-    ],
-    examples: [
-      {
-        key: "simple-message",
-        label: "Simple message",
-        language: "json",
-        snippet: "{\"message\":\"Hello {{ inputs.name }}\"}",
-        configurationOnly: true
-      }
-    ],
-    outputs: [
-      {
-        key: "message",
-        label: "Message",
-        valueType: "string"
-      }
-    ]
-  },
-  ui: {
-    defaultEditorMode: "schema",
-    modalSize: "lg",
-    layoutHints: {
-      preferredPanel: "flow",
-      groupOrder: ["Message", "Advanced"]
-    }
-  }
-};
-```
-
----
-
-## New Frontend Extension Component Types
-
-The following lines were added to:
-
-- `solid-core-ui/src/types/extension-registry.ts`
-
-```ts
-workflowNodeEditor: "workflowNodeEditor",
-workflowNodeDocs: "workflowNodeDocs",
-workflowNodeFieldEditor: "workflowNodeFieldEditor",
-workflowNodePaletteCard: "workflowNodePaletteCard",
-```
-
-Each one is documented below.
-
----
-
-### `workflowNodeEditor`
-
-Line:
-
-```ts
-workflowNodeEditor: "workflowNodeEditor"
-```
-
-Meaning:
-
-- registers a full custom node editor experience
-- used only when schema-driven editing is insufficient
-- should be rare
-
-When to use:
-
-- deeply nested configurations
-- highly visual domain-specific editors
-- tasks that need a specialized multi-step setup flow
-
-Example registration:
-
-```ts
-{
-  name: "workflow.node.httpRequest.editor",
-  type: ExtensionComponentTypes.workflowNodeEditor,
-  component: HttpRequestNodeEditor
-}
-```
-
-Expected usage:
-
-- backend metadata sets `ui.editorComponentKey = "workflow.node.httpRequest.editor"`
-- the workflow editor resolves that key through the extension registry
-
----
-
-### `workflowNodeDocs`
-
-Line:
-
-```ts
-workflowNodeDocs: "workflowNodeDocs"
-```
-
-Meaning:
-
-- registers a custom docs renderer for one node type
-- default docs should still come from metadata
-
-When to use:
-
-- interactive docs
-- searchable nested definitions
-- complex examples needing special rendering
-
-Example registration:
-
-```ts
-{
-  name: "workflow.node.search.docs",
-  type: ExtensionComponentTypes.workflowNodeDocs,
-  component: SearchNodeDocsPanel
-}
-```
-
-Expected usage:
-
-- backend metadata sets `ui.docsComponentKey = "workflow.node.search.docs"`
-- otherwise the generic Docs renderer uses `documentation`, `examples`, `outputs`, `metrics`, and `definitions`
-
----
-
-### `workflowNodeFieldEditor`
-
-Line:
-
-```ts
-workflowNodeFieldEditor: "workflowNodeFieldEditor"
-```
-
-Meaning:
-
-- registers a field-level override for one configuration field
-- this is the preferred escape hatch before replacing the whole node editor
-
-When to use:
-
-- key/value header editors
-- auth setup widgets
-- provider pickers
-- nested object builders
-
-Example registration:
-
-```ts
-{
-  name: "workflow.node.field.headersEditor",
-  type: ExtensionComponentTypes.workflowNodeFieldEditor,
-  component: HeadersKeyValueEditor
-}
-```
-
-Expected usage:
-
-- backend metadata sets either:
-  - `WorkflowNodeConfigurationFieldDefinition.extensionComponentKey`
-  - or `WorkflowNodeUiMetadata.fieldComponentKeys["headers"]`
-
-This is the main UI override pattern we want to encourage.
-
----
-
-### `workflowNodePaletteCard`
-
-Line:
-
-```ts
-workflowNodePaletteCard: "workflowNodePaletteCard"
-```
-
-Meaning:
-
-- registers a custom visual representation for the node picker / palette / insert dialog
-
-When to use:
-
-- rich node cards with icons, tags, quick examples, or usage hints
-- domain-specific palettes where discoverability matters
-
-Example registration:
-
-```ts
-{
-  name: "workflow.node.httpRequest.palette",
-  type: ExtensionComponentTypes.workflowNodePaletteCard,
-  component: HttpRequestPaletteCard
-}
-```
-
-Expected usage:
-
-- backend metadata sets `ui.paletteComponentKey = "workflow.node.httpRequest.palette"`
-- otherwise the default palette card can be rendered from `label`, `description`, `category`, `icon`, and `tags`
-
----
-
-## Recommended Precedence Rules
-
-To keep behavior predictable, the workflow UI should use this order:
-
-1. render from backend metadata only
-2. if a field-level override exists, use `workflowNodeFieldEditor`
-3. if a full-node editor override exists, use `workflowNodeEditor`
-4. if a docs override exists, use `workflowNodeDocs`
-5. if a palette override exists, use `workflowNodePaletteCard`
-
-This preserves the intended design:
-
-- schema-driven first
-- extension-driven only when needed
-
----
-
-## Recommended First Implementations
-
-The first core nodes to enrich with this metadata should likely be:
-
-1. `log.write`
-2. `http.request`
-3. `if`
-4. `forEach`
-5. `parallel`
-
-Suggested rollout:
-
-1. enrich backend metadata for `log.write`
-2. build a generic schema-driven modal editor
-3. build a generic docs panel
-4. add one field-level override example
-5. only after that introduce full custom node editors if still necessary
-
----
-
-## Pending Features And Open Decisions
-
-These items are intentionally not fully implemented yet and should be treated as pending design or delivery work.
-
-### Metrics persistence and observability
-
-The current `metrics` metadata is useful as a node capability declaration, but it does not become operationally valuable until we choose how metrics are emitted and stored.
-
-Current status:
-
-- `WorkflowNodeMetricDefinition` documents what a node may measure
-- the runtime does not yet persist metrics into a dedicated table
-- the runtime does not yet publish metrics to a monitoring backend
-- the execution UI does not yet visualize metrics
-
-Practical implication:
-
-- today, `metrics` is mainly design metadata for docs and future observability
-- for production value, we need one or both of the following:
-  - persist metrics in a workflow runtime table for querying and dashboards
-  - emit metrics to an external observability system
-
-Suggested next-step options:
-
-1. Add a dedicated workflow execution metric table, for example `workflowExecutionMetric`
-2. Extend execution logs with metric-shaped entries as a simpler interim step
-3. Emit metrics to an external telemetry backend while keeping only summaries in SolidX
-
-Recommended direction:
-
-- keep `metrics` in the node contract now
-- treat runtime metric storage as a separate pending feature
-- avoid overbuilding the metrics UI before persistence/emission strategy is agreed
-
-### Node metadata API
-
-Pending:
-
-- dedicated API endpoint for listing workflow node metadata for the editor
-- stable DTO mapping from provider metadata to client-safe response payloads
-
-### Expression-aware autocomplete
-
-Pending:
-
-- Monaco autocomplete based on workflow DSL plus node metadata
-- expression suggestions for `inputs`, `outputs`, `execution`, `trigger`, and loop context
-
-### Generic workflow docs renderer
-
-Pending:
-
-- reusable renderer for `summary`, `sections`, `examples`, `outputs`, `metrics`, and `definitions`
-- search/filter experience inside the Docs panel
-
-### Flow editor integration
-
-Pending:
-
-- mapping `childSlots` metadata into React Flow containers and insertion affordances
-- node modal editor using schema-driven forms by default
-
-### Blueprints
-
-Pending:
-
-- reintroduce `WorkflowBlueprint` as a first-class concept after the core definition/execution editor is stable
-- define blueprint metadata shape for starter workflows, tags, categories, and descriptions
-- decide whether blueprints live as:
-  - dedicated persisted records
-  - metadata-backed JSON assets only
-  - or both
-- support blueprint browsing in the workflow editor
-- support “create from blueprint” flows
-- support core-provided and consuming-project-provided blueprint packs
-
-Recommended direction:
-
-- treat blueprints as curated starter workflows, not a separate execution concept
-- keep them aligned with the same workflow DSL as normal definitions
-- design the Blueprints panel after the node metadata API and generic docs renderer are in place
-- defer full blueprint management UX until the definition editor foundation is stable
-
----
-
-## Final Guidance
-
-This contract is intentionally designed so that:
-
-- the backend describes node behavior and metadata
-- the frontend can render most nodes dynamically
-- `solid-core-ui` can ship polished defaults
-- consuming `solid-ui` projects can override only the pieces they need
-
-That keeps the workflow system extensible without making every task implementation expensive.