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

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

@@ -0,0 +1,1262 @@
+# 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.