@solidxai/core 0.1.13-beta.2 → 0.1.13-beta.21

package/dist/types/workflow-dsl.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-dsl.types.js","sourceRoot":"","sources":["../../src/types/workflow-dsl.types.ts"],"names":[],"mappings":"","sourcesContent":["import { WorkflowExecution } from '../entities/workflow-execution.entity';\nimport { WorkflowStepExecution } from '../entities/workflow-step-execution.entity';\n\n/**\n * Declares the execution role of a node in the workflow graph.\n *\n * - `task`: performs one unit of work, for example `log.write` or `http.request`.\n * - `control`: owns child-node execution semantics, for example `if`, `parallel`, `sequential`, or `switch`.\n * - `subflow`: reserved for invoking another workflow as a node.\n *\n * Example:\n * ```yaml\n * kind: control\n * type: if\n * ```\n */\nexport type WorkflowNodeKind = 'task' | 'control' | 'subflow';\n\n/**\n * Describes the logical value type of a configurable node field.\n *\n * This powers schema-driven authoring UI, validation messaging, docs badges, and future field-editor selection.\n *\n * Example:\n * ```yaml\n * configuration:\n *   uri: \"{{ variables.defaultUrl }}\" # valueType: uri, expressionAllowed: true\n * ```\n */\nexport type WorkflowNodeConfigurationValueType =\n  | 'string'\n  | 'number'\n  | 'integer'\n  | 'boolean'\n  | 'object'\n  | 'array'\n  | 'json'\n  | 'secret'\n  | 'expression'\n  | 'relation'\n  | 'uri'\n  | 'any';\n\n/** Lifecycle status for an entire workflow execution. */\nexport type WorkflowExecutionStatus =\n  | 'enqueued'\n  | 'created'\n  | 'running'\n  | 'success'\n  | 'failed'\n  | 'cancelled';\n\n/** Lifecycle status for one node execution inside a workflow execution. */\nexport type WorkflowStepExecutionStatus =\n  | 'created'\n  | 'running'\n  | 'success'\n  | 'failed'\n  | 'skipped';\n\n/**\n * Retry behavior attached to a node instance in the workflow YAML.\n *\n * This belongs to the editable runtime surface when a node provider sets\n * `authoring.supportsRetryPolicy`.\n *\n * Example:\n * ```yaml\n * retryPolicy:\n *   maxRetries: 3\n *   delayMs: 1000\n * ```\n */\nexport interface WorkflowRetryPolicy {\n  /** Maximum number of retry attempts after the initial failure. */\n  maxRetries?: number;\n\n  /** Delay between retry attempts in milliseconds. */\n  delayMs?: number;\n}\n\n/**\n * A concrete node instance inside `WorkflowDefinitionDsl.nodes` or inside a\n * control node child slot.\n *\n * This is the author-facing DSL shape saved in `definitionYaml`. The topology\n * renderer interprets `kind`, `type`, and child-slot keys (`tasks`, `then`,\n * `else`, `cases`, `defaults`) to draw the graph dynamically. The edit modal\n * exposes common fields plus `configuration` fields declared by the matching\n * `WorkflowNodeProviderMetadata.authoring` metadata.\n *\n * Example:\n * ```yaml\n * - id: check_status\n *   name: Check status\n *   kind: control\n *   type: if\n *   configuration:\n *     condition: \"{{ outputs.http_request.code != 200 }}\"\n *   then:\n *     - id: alert\n *       kind: task\n *       type: log.write\n *       configuration:\n *         message: Server is down\n * ```\n */\nexport interface WorkflowNodeDefinition {\n  /** Stable unique identifier for output lookup, execution tracking, and UI mutations. */\n  id: string;\n\n  /** Optional display label for the node card; UI can fall back to `id`. */\n  name?: string;\n\n  /** Optional human-readable note explaining what this node does. */\n  description?: string;\n\n  /** Declares whether this is a work node, control-flow node, or subflow node. */\n  kind: WorkflowNodeKind;\n\n  /**\n   * Provider type key used to resolve execution handler, schema, docs, icon, and\n   * authoring metadata. Examples: `log.write`, `http.request`, `if`, `switch`.\n   */\n  type: string;\n\n  /** When true, the engine skips this node at runtime. */\n  disabled?: boolean;\n\n  /** Optional node execution timeout in milliseconds. */\n  timeoutMs?: number;\n\n  /** Optional retry policy for failed task execution. */\n  retryPolicy?: WorkflowRetryPolicy;\n\n  /** Error behavior: `fail` stops the workflow; `continue` moves to the next node. */\n  onError?: 'fail' | 'continue';\n\n  /**\n   * Provider-specific input properties for this node.\n   *\n   * Think of this as the node's input payload: each provider declares which\n   * properties it accepts, and the schema-driven form writes those properties\n   * into this object using `WorkflowNodeConfigurationFieldDefinition.path` or\n   * `.key`.\n   *\n   * Values may be literals or expression strings. When expressions are allowed\n   * for a field, the runtime evaluates them against workflow context before the\n   * node handler receives the effective input value.\n   *\n   * Example for `type: http.request`:\n   * ```yaml\n   * configuration:\n   *   method: GET\n   *   uri: \"{{ variables.defaultUrl }}\"\n   * ```\n   */\n  configuration?: Record<string, any>;\n\n  /** Non-runtime custom annotations for tooling and future extensions. */\n  metadata?: Record<string, any>;\n\n  /**\n   * Ordered child nodes for control nodes that own a generic task collection.\n   *\n   * Used by grouping controls such as `sequential` and `parallel`, and also by\n   * loop-style controls where the same child task collection is executed for\n   * each item or iteration. The control node defines the execution semantics;\n   * this property defines the child nodes that participate.\n   *\n   * Example for `type: sequential`:\n   * ```yaml\n   * tasks:\n   *   - id: first\n   *     kind: task\n   *     type: log.write\n   *   - id: second\n   *     kind: task\n   *     type: log.write\n   * ```\n   */\n  tasks?: WorkflowNodeDefinition[];\n\n  /**\n   * Child nodes executed when an `if` control node condition resolves truthy.\n   *\n   * Example:\n   * ```yaml\n   * then:\n   *   - id: server_unreachable_alert\n   *     kind: task\n   *     type: log.write\n   * ```\n   */\n  then?: WorkflowNodeDefinition[];\n\n  /** Child nodes executed when an `if` control node condition resolves falsey. */\n  else?: WorkflowNodeDefinition[];\n\n  /** Child nodes executed when no `switch.cases` entry matches the switch value. */\n  defaults?: WorkflowNodeDefinition[];\n\n  /**\n   * Named child-node collections for `switch`.\n   *\n   * Keys are case values. Values are the nodes that run when the evaluated switch\n   * value matches that key.\n   *\n   * Example:\n   * ```yaml\n   * cases:\n   *   true:\n   *     - id: is_true\n   *       kind: task\n   *       type: log.write\n   *   false:\n   *     - id: is_false\n   *       kind: task\n   *       type: log.write\n   * ```\n   */\n  cases?: Record<string, WorkflowNodeDefinition[]>;\n}\n\n/**\n * A workflow trigger definition.\n *\n * Triggers start workflow executions, but they are not part of the main node\n * sequence rendered in topology.\n */\nexport interface WorkflowTriggerDefinition {\n  /** Stable trigger id within the workflow. */\n  id: string;\n\n  /** Optional display label for UI surfaces. */\n  name?: string;\n\n  /** Trigger provider key, for example a schedule trigger type. */\n  type: string;\n\n  /** Provider-specific trigger settings. */\n  configuration?: Record<string, any>;\n\n  /** When true, the trigger is defined but inactive. */\n  disabled?: boolean;\n\n  /** Custom annotations for trigger tooling. */\n  metadata?: Record<string, any>;\n}\n\n/**\n * Root workflow DSL document saved as YAML.\n *\n * Rendering phases are:\n * 1. fetch `definitionYaml`;\n * 2. parse YAML into this shape;\n * 3. validate this shape and all nested nodes;\n * 4. render topology using node provider metadata and child-slot rules.\n *\n * Example:\n * ```yaml\n * version: 1.0.0\n * variables:\n *   defaultUrl: https://example.com\n * nodes:\n *   - id: start\n *     kind: task\n *     type: log.write\n * ```\n */\nexport interface WorkflowDefinitionDsl {\n  /** DSL version of this workflow definition. */\n  version?: string;\n\n  /** Workflow-level markdown/plaintext description for humans. */\n  description?: string;\n\n  /** Workflow input declarations or defaults. */\n  inputs?: Record<string, any>;\n\n  /** Workflow-scoped reusable values available to expressions. */\n  variables?: Record<string, any>;\n\n  /** Top-level executable node sequence. */\n  nodes: WorkflowNodeDefinition[];\n\n  /** Optional workflow triggers that can create executions. */\n  triggers?: WorkflowTriggerDefinition[];\n\n  /** Workflow-level custom annotations for tooling. */\n  metadata?: Record<string, any>;\n}\n\n/**\n * Provider metadata declared by `@WorkflowNodeProvider(...)`.\n *\n * This is not saved inside workflow YAML. It describes how a `type` behaves,\n * how it is edited, what docs are shown, and what runtime features are enabled.\n *\n * Example provider fragment:\n * ```ts\n * @WorkflowNodeProvider({\n *   type: 'http.request',\n *   kind: 'task',\n *   authoring: {\n *     configurationFields: [{ key: 'uri', required: true, valueType: 'uri' }]\n *   }\n * })\n * ```\n */\nexport interface WorkflowNodeProviderMetadata {\n  /** Provider type key matched by `WorkflowNodeDefinition.type`. */\n  type: string;\n\n  /** Node kind supported by this provider. */\n  kind: WorkflowNodeKind;\n\n  /** Provider metadata version, independent from workflow DSL version. */\n  version?: string;\n\n  /** Top-level palette/docs grouping. */\n  category?: string;\n\n  /** Secondary palette/docs grouping. */\n  subcategory?: string;\n\n  /** Human label shown in node cards, palettes, dialogs, and docs. */\n  label?: string;\n\n  /** Human description shown in docs and selection surfaces. */\n  description?: string;\n\n  /** Icon key consumed by the UI icon resolver. */\n  icon?: string;\n\n  /** Search/filter tags for palette and docs surfaces. */\n  tags?: string[];\n\n  /** Alternate type/search labels accepted for discovery. */\n  aliases?: string[];\n\n  /** Machine schema for node configuration validation. */\n  configSchema?: Record<string, any>;\n\n  /** Optional schema hints for configuration UI. */\n  uiSchema?: Record<string, any>;\n\n  /** Machine schema describing the node output payload. */\n  outputSchema?: Record<string, any>;\n\n  /** Documentation examples shown in node docs. */\n  examples?: WorkflowNodeExampleDefinition[];\n\n  /** Runtime metrics emitted or documented by the node. */\n  metrics?: WorkflowNodeMetricDefinition[];\n\n  /** Reference material for docs, such as expression variables or output fields. */\n  definitions?: WorkflowNodeReferenceDefinition[];\n\n  /** Authoring metadata that defines the editable surface for this node type. */\n  authoring?: WorkflowNodeAuthoringMetadata;\n\n  /** Runtime capability metadata used by execution tooling and docs. */\n  runtime?: WorkflowNodeRuntimeMetadata;\n\n  /** Human documentation metadata. */\n  documentation?: WorkflowNodeDocumentationMetadata;\n\n  /** UI integration metadata for custom editors, docs, palette, and layout hints. */\n  ui?: WorkflowNodeUiMetadata;\n}\n\n/**\n * Declares which parts of a node are editable in generic authoring UI.\n *\n * This metadata is what the topology edit/add modal reads to decide which common\n * fields, configuration fields, and child-slot affordances to expose.\n */\nexport interface WorkflowNodeAuthoringMetadata {\n  /** Initial `configuration` object for a newly added node. */\n  defaultConfiguration?: Record<string, any>;\n\n  /** Schema-driven editable fields that write to `node.configuration`. */\n  configurationFields?: WorkflowNodeConfigurationFieldDefinition[];\n\n  /** Optional higher-level layout for configuration fields. */\n  configurationLayout?: WorkflowNodeConfigurationLayoutDefinition;\n\n  /** Child collections owned by this node when `kind: control`. */\n  childSlots?: WorkflowNodeChildSlotDefinition[];\n\n  /** Documented or typed outputs produced by this node. */\n  outputs?: WorkflowNodeOutputDefinition[];\n\n  /** Whether this node generally supports expression values. */\n  supportsExpressions?: boolean;\n\n  /** Expose `retryPolicy` in the edit modal. */\n  supportsRetryPolicy?: boolean;\n\n  /** Expose `timeoutMs` in the edit modal. */\n  supportsTimeoutMs?: boolean;\n\n  /** Expose `onError` in the edit modal. */\n  supportsOnError?: boolean;\n\n  /** Expose `disabled` in the edit modal. */\n  supportsDisableToggle?: boolean;\n\n  /** Expose the common `name` field in the edit modal. */\n  supportsName?: boolean;\n\n  /** Expose the common `description` field in the edit modal. */\n  supportsDescription?: boolean;\n\n  /** Extra searchable text for palette and docs discovery. */\n  searchableText?: string[];\n}\n\n/** Declarative layout for schema-driven node configuration fields. */\nexport interface WorkflowNodeConfigurationLayoutDefinition {\n  /** Layout strategy. Only `tabs` is currently implemented by the generic UI. */\n  type: 'tabs';\n\n  /** Tab definitions. Fields not assigned to a tab should fall back to `Other`. */\n  tabs: WorkflowNodeConfigurationLayoutTabDefinition[];\n}\n\n/** One configuration tab. Tabs may include explicit fields and/or whole groups. */\nexport interface WorkflowNodeConfigurationLayoutTabDefinition {\n  /** Stable tab key. */\n  key: string;\n\n  /** Human label shown in the editor. */\n  label: string;\n\n  /** Field keys or field paths to include in this tab. */\n  fields?: string[];\n\n  /** Group labels to include in this tab. */\n  groups?: string[];\n}\n\n/**\n * Describes a control node child collection that can be edited from topology.\n *\n * Child slots tell the renderer and mutation layer which node property contains\n * child nodes and how those children should be arranged.\n *\n * Example for `if`:\n * ```ts\n * { key: 'then', label: 'Then', kind: 'sequence', layout: 'sequential' }\n * ```\n *\n * Example for `switch`:\n * ```ts\n * { key: 'cases', label: 'Cases', kind: 'case-collection', layout: 'parallel' }\n * ```\n */\nexport interface WorkflowNodeChildSlotDefinition {\n  /** Property key on `WorkflowNodeDefinition`, for example `tasks`, `then`, `else`, `cases`. */\n  key: string;\n\n  /** Human label shown in topology or editor summaries. */\n  label?: string;\n\n  /** Human explanation of what this child slot means. */\n  description?: string;\n\n  /**\n   * Shape of child data.\n   *\n   * `sequence` means the property is `WorkflowNodeDefinition[]`.\n   * `case-collection` means the property is `Record<string, WorkflowNodeDefinition[]>`.\n   */\n  kind: 'sequence' | 'case-collection';\n\n  /**\n   * Preferred visual arrangement for children in this slot.\n   *\n   * `sequential` renders top-to-bottom. `parallel` renders peer lines side-by-side.\n   */\n  layout?: 'sequential' | 'parallel';\n\n  /** Whether a valid node instance should contain this child slot. */\n  required?: boolean;\n\n  /** Minimum allowed children or cases. */\n  minItems?: number;\n\n  /** Maximum allowed children or cases. */\n  maxItems?: number;\n}\n\n/**\n * Describes one editable field in `WorkflowNodeDefinition.configuration`.\n *\n * These definitions drive the generic schema-based add/edit modal. They are the\n * bridge between provider metadata and the user-editable YAML.\n *\n * Example:\n * ```ts\n * { key: 'uri', label: 'URI', valueType: 'uri', required: true }\n * ```\n * writes:\n * ```yaml\n * configuration:\n *   uri: https://example.com\n * ```\n */\nexport interface WorkflowNodeConfigurationFieldDefinition {\n  /** Stable field key and default path within `configuration`. */\n  key: string;\n\n  /** Human label shown above the form field. */\n  label?: string;\n\n  /** Help text shown below or near the field. */\n  description?: string;\n\n  /** Logical type used for validation, docs badges, and default editor selection. */\n  valueType?: WorkflowNodeConfigurationValueType;\n\n  /** Whether this field must be present for a valid node configuration. */\n  required?: boolean;\n\n  /** Dot-path override inside `configuration`; defaults to `key`. */\n  path?: string;\n\n  /** Whether the field supports expression strings like `{{ inputs.value }}`. */\n  expressionAllowed?: boolean;\n\n  /** Whether the field supports secret references or secret handling. */\n  secretAllowed?: boolean;\n\n  /** Initial value used when creating a new node of this type. */\n  defaultValue?: any;\n\n  /** Fixed option list rendered as a select-like control. */\n  enumValues?: Array<string | number | boolean>;\n\n  /** Example values for docs and future inline help. */\n  examples?: any[];\n\n  /** Form grouping label used to visually cluster related fields. */\n  group?: string;\n\n  /** Preferred generic widget, for example `textarea`, `yaml-editor`, or `json-editor`. */\n  widgetHint?: string;\n\n  /** Custom field editor component registry key. */\n  extensionComponentKey?: string;\n\n  /** Optional machine schema for this specific field. */\n  schema?: Record<string, any>;\n\n  /** Optional UI schema for this specific field. */\n  uiSchema?: Record<string, any>;\n}\n\n/** Describes one output value produced by a node provider. */\nexport interface WorkflowNodeOutputDefinition {\n  /** Stable output key. */\n  key: string;\n\n  /** Human label for docs. */\n  label?: string;\n\n  /** Human explanation of the output. */\n  description?: string;\n\n  /** Logical value type of the output. */\n  valueType?: WorkflowNodeConfigurationValueType;\n\n  /** Dot path inside the runtime output object. */\n  path?: string;\n\n  /** Whether the output is expected on successful execution. */\n  required?: boolean;\n\n  /** Optional machine schema for this output value. */\n  schema?: Record<string, any>;\n}\n\n/** Documents a runtime metric associated with a node provider. */\nexport interface WorkflowNodeMetricDefinition {\n  /** Stable metric key. */\n  key: string;\n\n  /** Human label for docs. */\n  label?: string;\n\n  /** Human explanation of the metric. */\n  description?: string;\n\n  /** Metric shape. */\n  type?: 'counter' | 'gauge' | 'histogram' | 'timer' | 'summary';\n\n  /** Unit label, for example `ms`, `bytes`, or `count`. */\n  unit?: string;\n\n  /** Dot path if derived from output or execution context. */\n  path?: string;\n\n  /** Metric tags emitted with the value. */\n  tags?: string[];\n}\n\n/** Example snippet shown in node documentation. */\nexport interface WorkflowNodeExampleDefinition {\n  /** Stable example key. */\n  key: string;\n\n  /** Human example title. */\n  label?: string;\n\n  /** Short explanation of what the example demonstrates. */\n  description?: string;\n\n  /** Snippet language for syntax highlighting. */\n  language?: 'json' | 'yaml' | 'javascript' | 'typescript' | 'text';\n\n  /** The example source text. */\n  snippet: string;\n\n  /** True when the snippet only represents `configuration`, not a full node. */\n  configurationOnly?: boolean;\n\n  /** Custom annotations for docs tooling. */\n  metadata?: Record<string, any>;\n}\n\n/** Additional reference block shown in node documentation. */\nexport interface WorkflowNodeReferenceDefinition {\n  /** Stable reference key. */\n  key: string;\n\n  /** Human reference title. */\n  label?: string;\n\n  /** Short explanation of the reference. */\n  description?: string;\n\n  /** Main reference content. */\n  content?: string;\n\n  /** Examples attached to this reference block. */\n  examples?: WorkflowNodeExampleDefinition[];\n\n  /** Optional machine schema for referenced data. */\n  schema?: Record<string, any>;\n\n  /** Custom annotations for docs tooling. */\n  metadata?: Record<string, any>;\n}\n\n/** Runtime capability metadata for a node provider. */\nexport interface WorkflowNodeRuntimeMetadata {\n  /** Whether the node commonly emits log entries. */\n  emitsLogs?: boolean;\n\n  /** Whether the node may emit artifacts. */\n  emitsArtifacts?: boolean;\n\n  /** Whether the same input should produce stable output. */\n  deterministicOutputs?: boolean;\n\n  /** Whether execution is a normal task handler or engine-orchestrated control flow. */\n  executionMode?: 'task' | 'engine-controlled';\n\n  /** Statuses considered successful for this node type. */\n  successStatuses?: WorkflowStepExecutionStatus[];\n}\n\n/** Human-facing documentation metadata for a node provider. */\nexport interface WorkflowNodeDocumentationMetadata {\n  /** Short docs summary shown in node documentation surfaces. */\n  summary?: string;\n}\n\n/** UI integration metadata for node authoring and documentation. */\nexport interface WorkflowNodeUiMetadata {\n  /** Icon key used by topology cards, palette items, and docs. */\n  icon?: string;\n\n  /** Icon foreground color used by palette/dialog/topology surfaces. */\n  iconColor?: string;\n\n  /** Icon tile background color used by palette/dialog/topology surfaces. */\n  iconBackgroundColor?: string;\n\n  /** Optional icon tile border color for richer palette treatments. */\n  iconBorderColor?: string;\n\n  /** Custom full-node editor component registry key. */\n  editorComponentKey?: string;\n\n  /** Custom documentation component registry key. */\n  docsComponentKey?: string;\n\n  /** Custom palette item component registry key. */\n  paletteComponentKey?: string;\n\n  /** Default edit mode: generic schema form or custom editor. */\n  defaultEditorMode?: 'schema' | 'custom';\n\n  /** Per-field custom editor component registry keys keyed by configuration field key. */\n  fieldComponentKeys?: Record<string, string>;\n\n  /** Preferred modal size for add/edit UI. */\n  modalSize?: 'sm' | 'md' | 'lg' | 'xl' | 'full';\n\n  /** Optional visual hints for docs/editor/topology layout. */\n  layoutHints?: {\n    /** Preferred workflow page panel when this node is focused. */\n    preferredPanel?: 'code' | 'flow' | 'docs';\n\n    /** Preferred order for configuration field groups. */\n    groupOrder?: string[];\n\n    /** Whether a summary should remain visible while editing long forms. */\n    stickySummary?: boolean;\n  };\n}\n\n/**\n * Serialized provider metadata returned to the frontend.\n *\n * This intentionally mirrors `WorkflowNodeProviderMetadata` so the UI can render\n * the palette, docs modal, topology cards, and add/edit dialog without importing\n * backend provider classes.\n */\nexport interface WorkflowNodeMetadataResponse {\n  /** Provider type key matched by `WorkflowNodeDefinition.type`. */\n  type: string;\n\n  /** Node kind supported by this provider. */\n  kind: WorkflowNodeKind;\n\n  /** Provider metadata version. */\n  version?: string;\n\n  /** Top-level palette/docs grouping. */\n  category?: string;\n\n  /** Secondary palette/docs grouping. */\n  subcategory?: string;\n\n  /** Human label shown in UI. */\n  label?: string;\n\n  /** Human description shown in UI. */\n  description?: string;\n\n  /** Icon key consumed by the UI icon resolver. */\n  icon?: string;\n\n  /** Search/filter tags. */\n  tags?: string[];\n\n  /** Machine schema for node configuration validation. */\n  configSchema?: Record<string, any>;\n\n  /** Optional schema hints for configuration UI. */\n  uiSchema?: Record<string, any>;\n\n  /** Machine schema describing node output payload. */\n  outputSchema?: Record<string, any>;\n\n  /** Documentation examples. */\n  examples?: WorkflowNodeExampleDefinition[];\n\n  /** Runtime metrics. */\n  metrics?: WorkflowNodeMetricDefinition[];\n\n  /** Reference docs blocks. */\n  definitions?: WorkflowNodeReferenceDefinition[];\n\n  /** Authoring metadata consumed by generic UI. */\n  authoring?: WorkflowNodeAuthoringMetadata;\n\n  /** Runtime capability metadata. */\n  runtime?: WorkflowNodeRuntimeMetadata;\n\n  /** Human documentation metadata. */\n  documentation?: WorkflowNodeDocumentationMetadata;\n\n  /** UI integration metadata. */\n  ui?: WorkflowNodeUiMetadata;\n}\n\n/** Return value from a node execution handler. */\nexport interface WorkflowNodeHandlerResult {\n  /** Final step status; defaults are inferred when omitted. */\n  status?: WorkflowStepExecutionStatus;\n\n  /** Output payload stored under this node id for downstream expressions. */\n  output?: any;\n\n  /** Artifacts emitted by this node execution. */\n  artifacts?: WorkflowArtifactEmitRequest[];\n}\n\n/** Log entry emitted by node handlers during workflow execution. */\nexport interface WorkflowLogEmitRequest {\n  /** Log level. */\n  level?: 'debug' | 'info' | 'warn' | 'error';\n\n  /** Human log message. */\n  message: string;\n\n  /** Optional structured event type. */\n  eventType?: string;\n\n  /** Optional source label, usually node/provider related. */\n  source?: string;\n\n  /** Structured context values for querying/debugging. */\n  context?: Record<string, any>;\n\n  /** Custom annotations for log consumers. */\n  metadata?: Record<string, any>;\n}\n\n/** Artifact emitted by a node execution. */\nexport interface WorkflowArtifactEmitRequest {\n  /** Human or stable artifact name. */\n  name: string;\n\n  /** Human explanation of the artifact. */\n  description?: string;\n\n  /** Logical artifact kind, for example `file`, `json`, or `report`. */\n  artifactType?: string;\n\n  /** URI where the artifact can be fetched. */\n  uri?: string;\n\n  /** File name when the artifact maps to a file. */\n  fileName?: string;\n\n  /** MIME type when known. */\n  mimeType?: string;\n\n  /** Artifact size in bytes when known. */\n  sizeBytes?: number;\n\n  /** Optional checksum for integrity checks. */\n  checksum?: string;\n\n  /** Inline payload for small artifacts. */\n  payload?: any;\n\n  /** Custom annotations for artifact consumers. */\n  metadata?: Record<string, any>;\n}\n\n/** Expression service available to node handlers. */\nexport interface WorkflowExpressionResolver {\n  /** Recursively interpolates expression strings inside a value. */\n  interpolate<T = any>(value: T, context: WorkflowRuntimeContext): T;\n\n  /** Evaluates a condition-like expression to a boolean. */\n  evaluateCondition(expression: any, context: WorkflowRuntimeContext): boolean;\n\n  /** Resolves one expression string against runtime context. */\n  resolveExpression(expression: string, context: WorkflowRuntimeContext): any;\n}\n\n/** Runtime context shared by workflow execution and node execution. */\nexport interface WorkflowRuntimeContext {\n  /** Parent workflow execution entity. */\n  execution: WorkflowExecution;\n\n  /** Current step execution, when inside a node handler. */\n  stepExecution?: WorkflowStepExecution;\n\n  /** Current node definition, when inside a node handler. */\n  node?: WorkflowNodeDefinition;\n\n  /** Input values supplied when execution was requested. */\n  input: Record<string, any>;\n\n  /** Workflow variables from DSL plus request-time overrides. */\n  variables: Record<string, any>;\n\n  /** Decrypted global secrets available to workflow expressions. */\n  secrets?: Record<string, any>;\n\n  /** Outputs keyed by node id. */\n  outputs: Record<string, any>;\n\n  /** Internal counters used to generate stable execution/log ordering. */\n  counters?: {\n    /** Step counter. */\n    step: number;\n\n    /** Log counter. */\n    log: number;\n  };\n\n  /** Current item for itemized/iterative control nodes. */\n  item?: any;\n\n  /** Current item index for itemized/iterative control nodes. */\n  index?: number;\n\n  /** Parent control node id when executing nested child nodes. */\n  parentNodeId?: string;\n\n  /** Parent step execution key when executing nested child nodes. */\n  parentStepExecutionKey?: string;\n}\n\n/**\n * Node-handler execution context.\n *\n * This extends runtime context with guaranteed current-node values, expression\n * helpers, nested execution helpers, and emitters.\n */\nexport interface WorkflowNodeExecutionContext extends WorkflowRuntimeContext {\n  /** Current node definition being executed. */\n  node: WorkflowNodeDefinition;\n\n  /** Current step execution entity. */\n  stepExecution: WorkflowStepExecution;\n\n  /** Expression helper bound to the current runtime context. */\n  expression: WorkflowExpressionResolver;\n\n  /** Execute child nodes with optional context overrides. Used by control nodes. */\n  runNodes(\n    nodes: WorkflowNodeDefinition[],\n    options?: Partial<WorkflowRuntimeContext>,\n  ): Promise<Record<string, any>>;\n\n  /** Emit a structured log entry for this node execution. */\n  emitLog(entry: WorkflowLogEmitRequest): Promise<void>;\n\n  /** Emit an artifact for this node execution. */\n  emitArtifact(entry: WorkflowArtifactEmitRequest): Promise<void>;\n}\n\n/** Request payload for starting a workflow execution. */\nexport interface WorkflowExecutionRequest {\n  /** Input values supplied by caller. */\n  input?: Record<string, any>;\n\n  /** Variable overrides supplied by caller. */\n  variables?: Record<string, any>;\n\n  /** Trigger source/type if execution was trigger-created. */\n  triggerType?: string;\n\n  /** User id responsible for the request, when available. */\n  requestedByUserId?: number;\n}\n\n/** API response describing a workflow execution. */\nexport interface WorkflowExecutionResponse {\n  /** Database id. */\n  id: number;\n\n  /** Public/stable execution identifier. */\n  executionIdentifier: string;\n\n  /** Workflow key that was executed. */\n  workflowKey: string;\n\n  /** Current or final execution status. */\n  status: WorkflowExecutionStatus;\n\n  /** Execution start timestamp. */\n  startedAt: Date;\n\n  /** Execution finish timestamp, if completed. */\n  finishedAt?: Date;\n\n  /** Execution duration in milliseconds, if completed. */\n  durationMs?: number;\n\n  /** Final workflow output payload. */\n  outputPayload?: any;\n\n  /** Human-readable failure summary, when failed. */\n  errorSummary?: string;\n}\n"]}
+{"version":3,"file":"workflow-dsl.types.js","sourceRoot":"","sources":["../../src/types/workflow-dsl.types.ts"],"names":[],"mappings":"","sourcesContent":["import { WorkflowExecution } from '../entities/workflow-execution.entity';\nimport { WorkflowStepExecution } from '../entities/workflow-step-execution.entity';\n\n/**\n * Declares the execution role of a node in the workflow graph.\n *\n * - `task`: performs one unit of work, for example `log.write` or `http.request`.\n * - `control`: owns child-node execution semantics, for example `if`, `parallel`, `sequential`, or `switch`.\n * - `subflow`: reserved for invoking another workflow as a node.\n *\n * Example:\n * ```yaml\n * kind: control\n * type: if\n * ```\n */\nexport type WorkflowNodeKind = 'task' | 'control' | 'subflow';\n\n/**\n * Describes the logical value type of a configurable node field.\n *\n * This powers schema-driven authoring UI, validation messaging, docs badges, and future field-editor selection.\n *\n * Example:\n * ```yaml\n * configuration:\n *   uri: \"{{ variables.defaultUrl }}\" # valueType: uri, expressionAllowed: true\n * ```\n */\nexport type WorkflowNodeConfigurationValueType =\n  | 'string'\n  | 'number'\n  | 'integer'\n  | 'boolean'\n  | 'object'\n  | 'array'\n  | 'json'\n  | 'secret'\n  | 'expression'\n  | 'relation'\n  | 'uri'\n  | 'any';\n\n/** Lifecycle status for an entire workflow execution. */\nexport type WorkflowExecutionStatus =\n  | 'enqueued'\n  | 'created'\n  | 'running'\n  | 'success'\n  | 'failed'\n  | 'cancelled';\n\n/** Lifecycle status for one node execution inside a workflow execution. */\nexport type WorkflowStepExecutionStatus =\n  | 'created'\n  | 'running'\n  | 'success'\n  | 'failed'\n  | 'skipped';\n\n/**\n * Retry behavior attached to a node instance in the workflow YAML.\n *\n * This belongs to the editable runtime surface when a node provider sets\n * `authoring.supportsRetryPolicy`.\n *\n * Example:\n * ```yaml\n * retryPolicy:\n *   maxRetries: 3\n *   delayMs: 1000\n * ```\n */\nexport interface WorkflowRetryPolicy {\n  /** Maximum number of retry attempts after the initial failure. */\n  maxRetries?: number;\n\n  /** Delay between retry attempts in milliseconds. */\n  delayMs?: number;\n}\n\n/**\n * A concrete node instance inside `WorkflowDefinitionDsl.nodes` or inside a\n * control node child slot.\n *\n * This is the author-facing DSL shape saved in `definitionYaml`. The topology\n * renderer interprets `kind`, `type`, and child-slot keys (`tasks`, `then`,\n * `else`, `cases`, `defaults`) to draw the graph dynamically. The edit modal\n * exposes common fields plus `configuration` fields declared by the matching\n * `WorkflowNodeProviderMetadata.authoring` metadata.\n *\n * Example:\n * ```yaml\n * - id: check_status\n *   name: Check status\n *   kind: control\n *   type: if\n *   configuration:\n *     condition: \"{{ outputs.http_request.code != 200 }}\"\n *   then:\n *     - id: alert\n *       kind: task\n *       type: log.write\n *       configuration:\n *         message: Server is down\n * ```\n */\nexport interface WorkflowNodeDefinition {\n  /** Stable unique identifier for output lookup, execution tracking, and UI mutations. */\n  id: string;\n\n  /** Optional display label for the node card; UI can fall back to `id`. */\n  name?: string;\n\n  /** Optional human-readable note explaining what this node does. */\n  description?: string;\n\n  /** Declares whether this is a work node, control-flow node, or subflow node. */\n  kind: WorkflowNodeKind;\n\n  /**\n   * Provider type key used to resolve execution handler, schema, docs, icon, and\n   * authoring metadata. Examples: `log.write`, `http.request`, `if`, `switch`.\n   */\n  type: string;\n\n  /** When true, the engine skips this node at runtime. */\n  disabled?: boolean;\n\n  /** Optional node execution timeout in milliseconds. */\n  timeoutMs?: number;\n\n  /** Optional retry policy for failed task execution. */\n  retryPolicy?: WorkflowRetryPolicy;\n\n  /** Error behavior: `fail` stops the workflow; `continue` moves to the next node. */\n  onError?: 'fail' | 'continue';\n\n  /**\n   * Provider-specific input properties for this node.\n   *\n   * Think of this as the node's input payload: each provider declares which\n   * properties it accepts, and the schema-driven form writes those properties\n   * into this object using `WorkflowNodeConfigurationFieldDefinition.path` or\n   * `.key`.\n   *\n   * Values may be literals or expression strings. When expressions are allowed\n   * for a field, the runtime evaluates them against workflow context before the\n   * node handler receives the effective input value.\n   *\n   * Example for `type: http.request`:\n   * ```yaml\n   * configuration:\n   *   method: GET\n   *   uri: \"{{ variables.defaultUrl }}\"\n   * ```\n   */\n  configuration?: Record<string, any>;\n\n  /** Non-runtime custom annotations for tooling and future extensions. */\n  metadata?: Record<string, any>;\n\n  /**\n   * Ordered child nodes for control nodes that own a generic task collection.\n   *\n   * Used by grouping controls such as `sequential` and `parallel`, and also by\n   * loop-style controls where the same child task collection is executed for\n   * each item or iteration. The control node defines the execution semantics;\n   * this property defines the child nodes that participate.\n   *\n   * Example for `type: sequential`:\n   * ```yaml\n   * tasks:\n   *   - id: first\n   *     kind: task\n   *     type: log.write\n   *   - id: second\n   *     kind: task\n   *     type: log.write\n   * ```\n   */\n  tasks?: WorkflowNodeDefinition[];\n\n  /**\n   * Child nodes executed when an `if` control node condition resolves truthy.\n   *\n   * Example:\n   * ```yaml\n   * then:\n   *   - id: server_unreachable_alert\n   *     kind: task\n   *     type: log.write\n   * ```\n   */\n  then?: WorkflowNodeDefinition[];\n\n  /** Child nodes executed when an `if` control node condition resolves falsey. */\n  else?: WorkflowNodeDefinition[];\n\n  /** Child nodes executed when no `switch.cases` entry matches the switch value. */\n  defaults?: WorkflowNodeDefinition[];\n\n  /** Child nodes executed when this node or its child subtree fails. */\n  errors?: WorkflowNodeDefinition[];\n\n  /**\n   * Named child-node collections for `switch`.\n   *\n   * Keys are case values. Values are the nodes that run when the evaluated switch\n   * value matches that key.\n   *\n   * Example:\n   * ```yaml\n   * cases:\n   *   true:\n   *     - id: is_true\n   *       kind: task\n   *       type: log.write\n   *   false:\n   *     - id: is_false\n   *       kind: task\n   *       type: log.write\n   * ```\n   */\n  cases?: Record<string, WorkflowNodeDefinition[]>;\n}\n\n/**\n * A workflow trigger definition.\n *\n * Triggers start workflow executions, but they are not part of the main node\n * sequence rendered in topology.\n */\nexport interface WorkflowTriggerDefinition {\n  /** Stable trigger id within the workflow. */\n  id: string;\n\n  /** Optional display label for UI surfaces. */\n  name?: string;\n\n  /** Trigger provider key, for example a schedule trigger type. */\n  type: string;\n\n  /** Provider-specific trigger settings. */\n  configuration?: Record<string, any>;\n\n  /** When true, the trigger is defined but inactive. */\n  disabled?: boolean;\n\n  /** Custom annotations for trigger tooling. */\n  metadata?: Record<string, any>;\n}\n\n/**\n * Root workflow DSL document saved as YAML.\n *\n * Rendering phases are:\n * 1. fetch `definitionYaml`;\n * 2. parse YAML into this shape;\n * 3. validate this shape and all nested nodes;\n * 4. render topology using node provider metadata and child-slot rules.\n *\n * Example:\n * ```yaml\n * version: 1.0.0\n * variables:\n *   defaultUrl: https://example.com\n * nodes:\n *   - id: start\n *     kind: task\n *     type: log.write\n * ```\n */\nexport interface WorkflowDefinitionDsl {\n  /** DSL version of this workflow definition. */\n  version?: string;\n\n  /** Workflow-level markdown/plaintext description for humans. */\n  description?: string;\n\n  /** Workflow input declarations or defaults. */\n  inputs?: Record<string, any>;\n\n  /** Workflow-scoped reusable values available to expressions. */\n  variables?: Record<string, any>;\n\n  /** Top-level executable node sequence. */\n  nodes: WorkflowNodeDefinition[];\n\n  /** Optional workflow triggers that can create executions. */\n  triggers?: WorkflowTriggerDefinition[];\n\n  /** Workflow-level error handler nodes executed sequentially when execution fails. */\n  errors?: WorkflowNodeDefinition[];\n\n  /** Workflow-level cleanup nodes executed sequentially after success or failure. */\n  finally?: WorkflowNodeDefinition[];\n\n  /** Workflow-level custom annotations for tooling. */\n  metadata?: Record<string, any>;\n}\n\n/**\n * Provider metadata declared by `@WorkflowNodeProvider(...)`.\n *\n * This is not saved inside workflow YAML. It describes how a `type` behaves,\n * how it is edited, what docs are shown, and what runtime features are enabled.\n *\n * Example provider fragment:\n * ```ts\n * @WorkflowNodeProvider({\n *   type: 'http.request',\n *   kind: 'task',\n *   authoring: {\n *     configurationFields: [{ key: 'uri', required: true, valueType: 'uri' }]\n *   }\n * })\n * ```\n */\nexport interface WorkflowNodeProviderMetadata {\n  /** Provider type key matched by `WorkflowNodeDefinition.type`. */\n  type: string;\n\n  /** Node kind supported by this provider. */\n  kind: WorkflowNodeKind;\n\n  /** Provider metadata version, independent from workflow DSL version. */\n  version?: string;\n\n  /** Top-level palette/docs grouping. */\n  category?: string;\n\n  /** Secondary palette/docs grouping. */\n  subcategory?: string;\n\n  /** Human label shown in node cards, palettes, dialogs, and docs. */\n  label?: string;\n\n  /** Human description shown in docs and selection surfaces. */\n  description?: string;\n\n  /** Icon key consumed by the UI icon resolver. */\n  icon?: string;\n\n  /** Search/filter tags for palette and docs surfaces. */\n  tags?: string[];\n\n  /** Alternate type/search labels accepted for discovery. */\n  aliases?: string[];\n\n  /** Machine schema for node configuration validation. */\n  configSchema?: Record<string, any>;\n\n  /** Optional schema hints for configuration UI. */\n  uiSchema?: Record<string, any>;\n\n  /** Machine schema describing the node output payload. */\n  outputSchema?: Record<string, any>;\n\n  /** Documentation examples shown in node docs. */\n  examples?: WorkflowNodeExampleDefinition[];\n\n  /** Runtime metrics emitted or documented by the node. */\n  metrics?: WorkflowNodeMetricDefinition[];\n\n  /** Reference material for docs, such as expression variables or output fields. */\n  definitions?: WorkflowNodeReferenceDefinition[];\n\n  /** Authoring metadata that defines the editable surface for this node type. */\n  authoring?: WorkflowNodeAuthoringMetadata;\n\n  /** Runtime capability metadata used by execution tooling and docs. */\n  runtime?: WorkflowNodeRuntimeMetadata;\n\n  /** Human documentation metadata. */\n  documentation?: WorkflowNodeDocumentationMetadata;\n\n  /** UI integration metadata for custom editors, docs, palette, and layout hints. */\n  ui?: WorkflowNodeUiMetadata;\n}\n\n/**\n * Declares which parts of a node are editable in generic authoring UI.\n *\n * This metadata is what the topology edit/add modal reads to decide which common\n * fields, configuration fields, and child-slot affordances to expose.\n */\nexport interface WorkflowNodeAuthoringMetadata {\n  /** Initial `configuration` object for a newly added node. */\n  defaultConfiguration?: Record<string, any>;\n\n  /** Schema-driven editable fields that write to `node.configuration`. */\n  configurationFields?: WorkflowNodeConfigurationFieldDefinition[];\n\n  /** Optional higher-level layout for configuration fields. */\n  configurationLayout?: WorkflowNodeConfigurationLayoutDefinition;\n\n  /** Child collections owned by this node when `kind: control`. */\n  childSlots?: WorkflowNodeChildSlotDefinition[];\n\n  /** Documented or typed outputs produced by this node. */\n  outputs?: WorkflowNodeOutputDefinition[];\n\n  /** Whether this node generally supports expression values. */\n  supportsExpressions?: boolean;\n\n  /** Expose `retryPolicy` in the edit modal. */\n  supportsRetryPolicy?: boolean;\n\n  /** Expose `timeoutMs` in the edit modal. */\n  supportsTimeoutMs?: boolean;\n\n  /** Expose `onError` in the edit modal. */\n  supportsOnError?: boolean;\n\n  /** Expose `disabled` in the edit modal. */\n  supportsDisableToggle?: boolean;\n\n  /** Expose the common `name` field in the edit modal. */\n  supportsName?: boolean;\n\n  /** Expose the common `description` field in the edit modal. */\n  supportsDescription?: boolean;\n\n  /** Extra searchable text for palette and docs discovery. */\n  searchableText?: string[];\n}\n\n/** Declarative layout for schema-driven node configuration fields. */\nexport interface WorkflowNodeConfigurationLayoutDefinition {\n  /** Layout strategy. Only `tabs` is currently implemented by the generic UI. */\n  type: 'tabs';\n\n  /** Tab definitions. Fields not assigned to a tab should fall back to `Other`. */\n  tabs: WorkflowNodeConfigurationLayoutTabDefinition[];\n}\n\n/** One configuration tab. Tabs may include explicit fields and/or whole groups. */\nexport interface WorkflowNodeConfigurationLayoutTabDefinition {\n  /** Stable tab key. */\n  key: string;\n\n  /** Human label shown in the editor. */\n  label: string;\n\n  /** Field keys or field paths to include in this tab. */\n  fields?: string[];\n\n  /** Group labels to include in this tab. */\n  groups?: string[];\n}\n\n/**\n * Describes a control node child collection that can be edited from topology.\n *\n * Child slots tell the renderer and mutation layer which node property contains\n * child nodes and how those children should be arranged.\n *\n * Example for `if`:\n * ```ts\n * { key: 'then', label: 'Then', kind: 'sequence', layout: 'sequential' }\n * ```\n *\n * Example for `switch`:\n * ```ts\n * { key: 'cases', label: 'Cases', kind: 'case-collection', layout: 'parallel' }\n * ```\n */\nexport interface WorkflowNodeChildSlotDefinition {\n  /** Property key on `WorkflowNodeDefinition`, for example `tasks`, `then`, `else`, `cases`. */\n  key: string;\n\n  /** Human label shown in topology or editor summaries. */\n  label?: string;\n\n  /** Human explanation of what this child slot means. */\n  description?: string;\n\n  /**\n   * Shape of child data.\n   *\n   * `sequence` means the property is `WorkflowNodeDefinition[]`.\n   * `case-collection` means the property is `Record<string, WorkflowNodeDefinition[]>`.\n   */\n  kind: 'sequence' | 'case-collection';\n\n  /**\n   * Preferred visual arrangement for children in this slot.\n   *\n   * `sequential` renders top-to-bottom. `parallel` renders peer lines side-by-side.\n   */\n  layout?: 'sequential' | 'parallel';\n\n  /** Whether a valid node instance should contain this child slot. */\n  required?: boolean;\n\n  /** Minimum allowed children or cases. */\n  minItems?: number;\n\n  /** Maximum allowed children or cases. */\n  maxItems?: number;\n}\n\n/**\n * Describes one editable field in `WorkflowNodeDefinition.configuration`.\n *\n * These definitions drive the generic schema-based add/edit modal. They are the\n * bridge between provider metadata and the user-editable YAML.\n *\n * Example:\n * ```ts\n * { key: 'uri', label: 'URI', valueType: 'uri', required: true }\n * ```\n * writes:\n * ```yaml\n * configuration:\n *   uri: https://example.com\n * ```\n */\nexport interface WorkflowNodeConfigurationFieldDefinition {\n  /** Stable field key and default path within `configuration`. */\n  key: string;\n\n  /** Human label shown above the form field. */\n  label?: string;\n\n  /** Help text shown below or near the field. */\n  description?: string;\n\n  /** Logical type used for validation, docs badges, and default editor selection. */\n  valueType?: WorkflowNodeConfigurationValueType;\n\n  /** Whether this field must be present for a valid node configuration. */\n  required?: boolean;\n\n  /** Dot-path override inside `configuration`; defaults to `key`. */\n  path?: string;\n\n  /** Whether the field supports expression strings like `{{ inputs.value }}`. */\n  expressionAllowed?: boolean;\n\n  /** Whether the field supports secret references or secret handling. */\n  secretAllowed?: boolean;\n\n  /** Initial value used when creating a new node of this type. */\n  defaultValue?: any;\n\n  /** Fixed option list rendered as a select-like control. */\n  enumValues?: Array<string | number | boolean>;\n\n  /** Example values for docs and future inline help. */\n  examples?: any[];\n\n  /** Form grouping label used to visually cluster related fields. */\n  group?: string;\n\n  /** Preferred generic widget, for example `textarea`, `yaml-editor`, or `json-editor`. */\n  widgetHint?: string;\n\n  /** Custom field editor component registry key. */\n  extensionComponentKey?: string;\n\n  /** Optional machine schema for this specific field. */\n  schema?: Record<string, any>;\n\n  /** Optional UI schema for this specific field. */\n  uiSchema?: Record<string, any>;\n}\n\n/** Describes one output value produced by a node provider. */\nexport interface WorkflowNodeOutputDefinition {\n  /** Stable output key. */\n  key: string;\n\n  /** Human label for docs. */\n  label?: string;\n\n  /** Human explanation of the output. */\n  description?: string;\n\n  /** Logical value type of the output. */\n  valueType?: WorkflowNodeConfigurationValueType;\n\n  /** Dot path inside the runtime output object. */\n  path?: string;\n\n  /** Whether the output is expected on successful execution. */\n  required?: boolean;\n\n  /**\n   * Whether this output is added to `outputs.<nodeId>` for downstream expressions.\n   * Defaults to true. Set false for observability-only outputs that should be\n   * stored on the step execution but not suggested or exposed to later nodes.\n   */\n  includeInRuntimeContext?: boolean;\n\n  /** Optional machine schema for this output value. */\n  schema?: Record<string, any>;\n}\n\n/** Documents a runtime metric associated with a node provider. */\nexport interface WorkflowNodeMetricDefinition {\n  /** Stable metric key. */\n  key: string;\n\n  /** Human label for docs. */\n  label?: string;\n\n  /** Human explanation of the metric. */\n  description?: string;\n\n  /** Metric shape. */\n  type?: 'counter' | 'gauge' | 'histogram' | 'timer' | 'summary';\n\n  /** Unit label, for example `ms`, `bytes`, or `count`. */\n  unit?: string;\n\n  /** Dot path if derived from output or execution context. */\n  path?: string;\n\n  /** Metric tags emitted with the value. */\n  tags?: string[];\n}\n\n/** Example snippet shown in node documentation. */\nexport interface WorkflowNodeExampleDefinition {\n  /** Stable example key. */\n  key: string;\n\n  /** Human example title. */\n  label?: string;\n\n  /** Short explanation of what the example demonstrates. */\n  description?: string;\n\n  /** Snippet language for syntax highlighting. */\n  language?: 'json' | 'yaml' | 'javascript' | 'typescript' | 'text';\n\n  /** The example source text. */\n  snippet: string;\n\n  /** True when the snippet only represents `configuration`, not a full node. */\n  configurationOnly?: boolean;\n\n  /** Custom annotations for docs tooling. */\n  metadata?: Record<string, any>;\n}\n\n/** Additional reference block shown in node documentation. */\nexport interface WorkflowNodeReferenceDefinition {\n  /** Stable reference key. */\n  key: string;\n\n  /** Human reference title. */\n  label?: string;\n\n  /** Short explanation of the reference. */\n  description?: string;\n\n  /** Main reference content. */\n  content?: string;\n\n  /** Examples attached to this reference block. */\n  examples?: WorkflowNodeExampleDefinition[];\n\n  /** Optional machine schema for referenced data. */\n  schema?: Record<string, any>;\n\n  /** Custom annotations for docs tooling. */\n  metadata?: Record<string, any>;\n}\n\n/** Runtime capability metadata for a node provider. */\nexport interface WorkflowNodeRuntimeMetadata {\n  /** Whether the node commonly emits log entries. */\n  emitsLogs?: boolean;\n\n  /** Whether the node may emit artifacts. */\n  emitsArtifacts?: boolean;\n\n  /** Whether the same input should produce stable output. */\n  deterministicOutputs?: boolean;\n\n  /** Whether execution is a normal task handler or engine-orchestrated control flow. */\n  executionMode?: 'task' | 'engine-controlled';\n\n  /** Statuses considered successful for this node type. */\n  successStatuses?: WorkflowStepExecutionStatus[];\n}\n\n/** Human-facing documentation metadata for a node provider. */\nexport interface WorkflowNodeDocumentationMetadata {\n  /** Short docs summary shown in node documentation surfaces. */\n  summary?: string;\n}\n\n/** UI integration metadata for node authoring and documentation. */\nexport interface WorkflowNodeUiMetadata {\n  /** Icon key used by topology cards, palette items, and docs. */\n  icon?: string;\n\n  /** Icon foreground color used by palette/dialog/topology surfaces. */\n  iconColor?: string;\n\n  /** Icon tile background color used by palette/dialog/topology surfaces. */\n  iconBackgroundColor?: string;\n\n  /** Optional icon tile border color for richer palette treatments. */\n  iconBorderColor?: string;\n\n  /** Custom full-node editor component registry key. */\n  editorComponentKey?: string;\n\n  /** Custom documentation component registry key. */\n  docsComponentKey?: string;\n\n  /** Custom palette item component registry key. */\n  paletteComponentKey?: string;\n\n  /** Default edit mode: generic schema form or custom editor. */\n  defaultEditorMode?: 'schema' | 'custom';\n\n  /** Per-field custom editor component registry keys keyed by configuration field key. */\n  fieldComponentKeys?: Record<string, string>;\n\n  /** Preferred modal size for add/edit UI. */\n  modalSize?: 'sm' | 'md' | 'lg' | 'xl' | 'full';\n\n  /** Optional visual hints for docs/editor/topology layout. */\n  layoutHints?: {\n    /** Preferred workflow page panel when this node is focused. */\n    preferredPanel?: 'code' | 'flow' | 'docs';\n\n    /** Preferred order for configuration field groups. */\n    groupOrder?: string[];\n\n    /** Whether a summary should remain visible while editing long forms. */\n    stickySummary?: boolean;\n  };\n}\n\n/**\n * Serialized provider metadata returned to the frontend.\n *\n * This intentionally mirrors `WorkflowNodeProviderMetadata` so the UI can render\n * the palette, docs modal, topology cards, and add/edit dialog without importing\n * backend provider classes.\n */\nexport interface WorkflowNodeMetadataResponse {\n  /** Provider type key matched by `WorkflowNodeDefinition.type`. */\n  type: string;\n\n  /** Node kind supported by this provider. */\n  kind: WorkflowNodeKind;\n\n  /** Provider metadata version. */\n  version?: string;\n\n  /** Top-level palette/docs grouping. */\n  category?: string;\n\n  /** Secondary palette/docs grouping. */\n  subcategory?: string;\n\n  /** Human label shown in UI. */\n  label?: string;\n\n  /** Human description shown in UI. */\n  description?: string;\n\n  /** Icon key consumed by the UI icon resolver. */\n  icon?: string;\n\n  /** Search/filter tags. */\n  tags?: string[];\n\n  /** Machine schema for node configuration validation. */\n  configSchema?: Record<string, any>;\n\n  /** Optional schema hints for configuration UI. */\n  uiSchema?: Record<string, any>;\n\n  /** Machine schema describing node output payload. */\n  outputSchema?: Record<string, any>;\n\n  /** Documentation examples. */\n  examples?: WorkflowNodeExampleDefinition[];\n\n  /** Runtime metrics. */\n  metrics?: WorkflowNodeMetricDefinition[];\n\n  /** Reference docs blocks. */\n  definitions?: WorkflowNodeReferenceDefinition[];\n\n  /** Authoring metadata consumed by generic UI. */\n  authoring?: WorkflowNodeAuthoringMetadata;\n\n  /** Runtime capability metadata. */\n  runtime?: WorkflowNodeRuntimeMetadata;\n\n  /** Human documentation metadata. */\n  documentation?: WorkflowNodeDocumentationMetadata;\n\n  /** UI integration metadata. */\n  ui?: WorkflowNodeUiMetadata;\n}\n\n/** Return value from a node execution handler. */\nexport interface WorkflowNodeHandlerResult {\n  /** Final step status; defaults are inferred when omitted. */\n  status?: WorkflowStepExecutionStatus;\n\n  /** Output payload stored under this node id for downstream expressions. */\n  output?: any;\n\n  /** Artifacts emitted by this node execution. */\n  artifacts?: WorkflowArtifactEmitRequest[];\n}\n\n/** Log entry emitted by node handlers during workflow execution. */\nexport interface WorkflowLogEmitRequest {\n  /** Log level. */\n  level?: 'debug' | 'info' | 'warn' | 'error';\n\n  /** Human log message. */\n  message: string;\n\n  /** Optional structured event type. */\n  eventType?: string;\n\n  /** Optional source label, usually node/provider related. */\n  source?: string;\n\n  /** Structured context values for querying/debugging. */\n  context?: Record<string, any>;\n\n  /** Custom annotations for log consumers. */\n  metadata?: Record<string, any>;\n}\n\n/** Artifact emitted by a node execution. */\nexport interface WorkflowArtifactEmitRequest {\n  /** Human or stable artifact name. */\n  name: string;\n\n  /** Human explanation of the artifact. */\n  description?: string;\n\n  /** Logical artifact kind, for example `file`, `json`, or `report`. */\n  artifactType?: string;\n\n  /** URI where the artifact can be fetched. */\n  uri?: string;\n\n  /** File name when the artifact maps to a file. */\n  fileName?: string;\n\n  /** MIME type when known. */\n  mimeType?: string;\n\n  /** Artifact size in bytes when known. */\n  sizeBytes?: number;\n\n  /** Optional checksum for integrity checks. */\n  checksum?: string;\n\n  /** Inline payload for small artifacts. */\n  payload?: any;\n\n  /** Custom annotations for artifact consumers. */\n  metadata?: Record<string, any>;\n}\n\n/** Expression service available to node handlers. */\nexport interface WorkflowExpressionResolver {\n  /** Recursively interpolates expression strings inside a value. */\n  interpolate<T = any>(value: T, context: WorkflowRuntimeContext): T;\n\n  /** Evaluates a condition-like expression to a boolean. */\n  evaluateCondition(expression: any, context: WorkflowRuntimeContext): boolean;\n\n  /** Resolves one expression string against runtime context. */\n  resolveExpression(expression: string, context: WorkflowRuntimeContext): any;\n}\n\n/** Loop context exposed to expressions for nested itemized controls. */\nexport interface WorkflowLoopContext {\n  /** Current item for this loop frame. */\n  item: any;\n\n  /** Zero-based iteration index for this loop frame. */\n  index: number;\n\n  /** Loop control node id. */\n  nodeId?: string;\n\n  /** Loop control step execution key. */\n  stepExecutionKey?: string;\n}\n\n/** Runtime context shared by workflow execution and node execution. */\nexport interface WorkflowRuntimeContext {\n  /** Parent workflow execution entity. */\n  execution: WorkflowExecution;\n\n  /** Current step execution, when inside a node handler. */\n  stepExecution?: WorkflowStepExecution;\n\n  /** Current node definition, when inside a node handler. */\n  node?: WorkflowNodeDefinition;\n\n  /** Input values supplied when execution was requested. */\n  input: Record<string, any>;\n\n  /** Workflow variables from DSL plus request-time overrides. */\n  variables: Record<string, any>;\n\n  /** Decrypted global secrets available to workflow expressions. */\n  secrets?: Record<string, any>;\n\n  /** Outputs keyed by node id. */\n  outputs: Record<string, any>;\n\n  /** Internal counters used to generate stable execution/log ordering. */\n  counters?: {\n    /** Step counter. */\n    step: number;\n\n    /** Log counter. */\n    log: number;\n  };\n\n  /** Current item for itemized/iterative control nodes. */\n  item?: any;\n\n  /** Current item index for itemized/iterative control nodes. */\n  index?: number;\n\n  /** Nearest parent loop frame, when inside nested loop children. */\n  parent?: WorkflowLoopContext;\n\n  /** Parent loop frames, nearest first. */\n  parents?: WorkflowLoopContext[];\n\n  /** Loop frames from outermost to innermost, including the current loop. */\n  loops?: WorkflowLoopContext[];\n\n  /** Current error context when executing an error handler. */\n  error?: any;\n\n  /** Parent control node id when executing nested child nodes. */\n  parentNodeId?: string;\n\n  /** Parent step execution key when executing nested child nodes. */\n  parentStepExecutionKey?: string;\n}\n\n/**\n * Node-handler execution context.\n *\n * This extends runtime context with guaranteed current-node values, expression\n * helpers, nested execution helpers, and emitters.\n */\nexport interface WorkflowNodeExecutionContext extends WorkflowRuntimeContext {\n  /** Current node definition being executed. */\n  node: WorkflowNodeDefinition;\n\n  /** Current step execution entity. */\n  stepExecution: WorkflowStepExecution;\n\n  /** Expression helper bound to the current runtime context. */\n  expression: WorkflowExpressionResolver;\n\n  /** Execute child nodes with optional context overrides. Used by control nodes. */\n  runNodes(\n    nodes: WorkflowNodeDefinition[],\n    options?: Partial<WorkflowRuntimeContext>,\n  ): Promise<Record<string, any>>;\n\n  /** Emit a structured log entry for this node execution. */\n  emitLog(entry: WorkflowLogEmitRequest): Promise<void>;\n\n  /** Emit an artifact for this node execution. */\n  emitArtifact(entry: WorkflowArtifactEmitRequest): Promise<void>;\n}\n\n/** Request payload for starting a workflow execution. */\nexport interface WorkflowExecutionRequest {\n  /** Input values supplied by caller. */\n  input?: Record<string, any>;\n\n  /** Variable overrides supplied by caller. */\n  variables?: Record<string, any>;\n\n  /** Trigger source/type if execution was trigger-created. */\n  triggerType?: string;\n\n  /** User id responsible for the request, when available. */\n  requestedByUserId?: number;\n}\n\n/** API response describing a workflow execution. */\nexport interface WorkflowExecutionResponse {\n  /** Database id. */\n  id: number;\n\n  /** Public/stable execution identifier. */\n  executionIdentifier: string;\n\n  /** Workflow key that was executed. */\n  workflowKey: string;\n\n  /** Current or final execution status. */\n  status: WorkflowExecutionStatus;\n\n  /** Execution start timestamp. */\n  startedAt: Date;\n\n  /** Execution finish timestamp, if completed. */\n  finishedAt?: Date;\n\n  /** Execution duration in milliseconds, if completed. */\n  durationMs?: number;\n\n  /** Final workflow output payload. */\n  outputPayload?: any;\n\n  /** Human-readable failure summary, when failed. */\n  errorSummary?: string;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidxai/core",
-  "version": "0.1.13-beta.2",
+  "version": "0.1.13-beta.21",
   "description": "This module is a NestJS module containing all the required core providers required by a Solid application",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,7 +45,7 @@
     "bcrypt": "^5.1.1",
     "bson": "^6.10.1",
     "cache-manager": "^5.5.2",
-    "cache-manager-redis-store": "^3.0.1",
+    "cache-manager-redis-yet": "^5.1.5",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",
     "cron-parser": "^5.5.0",

package/src/commands/run-tests.command.ts

@@ -3,10 +3,13 @@ import { SubCommand, CommandRunner, Option } from 'nest-commander';
 import * as path from 'path';
 import { ModuleMetadataHelperService } from 'src/helpers/module-metadata-helper.service';
 import { ConsoleReporter } from 'src/testing/reporter/console-reporter';
+import { ProgressReporter } from 'src/testing/reporter/progress-reporter';
 import { WebhookReporter } from 'src/testing/reporter/webhook-reporter';
 import { runFromMetadata } from 'src/testing/runner/run-from-metadata';
 import type { TestingMetadata } from 'src/testing/contracts/testing-metadata.types';
 import { SpecRegistry } from 'src/testing/core/spec-registry';
+import { SettingService } from 'src/services/setting.service';
+import type { SolidCoreSetting } from 'src/services/settings/default-settings-provider.service';
 
 interface TestRunCommandOptions {
   module?: string;
@@ -18,11 +21,14 @@ interface TestRunCommandOptions {
   apiBaseUrl?: string;
   uiBaseUrl?: string;
   headless?: boolean;
+  uiTimeoutMs?: number;
+  uiNavigationTimeoutMs?: number;
   timeoutMs?: number;
   retries?: number;
   listSpecs?: boolean;
   printApiLogs?: boolean;
   runName?: string;
+  progress?: boolean;
 }
 
 @SubCommand({
@@ -34,6 +40,7 @@ export class TestRunCommand extends CommandRunner {
 
   constructor(
     private readonly moduleMetadataHelperService: ModuleMetadataHelperService,
+    private readonly settingService: SettingService,
   ) {
     super();
   }
@@ -89,13 +96,24 @@ export class TestRunCommand extends CommandRunner {
       const apiBaseUrl = options?.apiBaseUrl ?? process.env.BASE_URL;
       const uiBaseUrl = options?.uiBaseUrl ?? process.env.FRONTEND_BASE_URL;
       const headless = options?.headless ?? true;
+      const uiTimeoutMs =
+        options?.uiTimeoutMs
+        ?? toPositiveNumber(process.env.UI_TIMEOUT_MS)
+        ?? toPositiveNumber(this.settingService.getConfigValue<SolidCoreSetting>('uiTestDefaultTimeoutMs'));
+      const uiNavigationTimeoutMs =
+        options?.uiNavigationTimeoutMs
+        ?? toPositiveNumber(process.env.UI_NAVIGATION_TIMEOUT_MS)
+        ?? toPositiveNumber(this.settingService.getConfigValue<SolidCoreSetting>('uiTestNavigationTimeoutMs'));
       const printApiLogs = options?.printApiLogs ?? false;
 
       const webhookUrl = process.env.SOLIDCTL_WEBHOOK_URL;
       const runName = options?.runName ?? `run-${Date.now()}`;
-      const reporter = webhookUrl
+      const baseReporter = webhookUrl
         ? new WebhookReporter(webhookUrl, runName)
         : new ConsoleReporter();
+      const reporter = options?.progress === false
+        ? baseReporter
+        : new ProgressReporter(baseReporter);
 
       try {
         await runFromMetadata({
@@ -105,7 +123,12 @@ export class TestRunCommand extends CommandRunner {
           skipScenarioIds,
           reporter,
           api: apiBaseUrl ? { baseUrl: apiBaseUrl } : undefined,
-          ui: { baseUrl: uiBaseUrl, headless },
+          ui: {
+            baseUrl: uiBaseUrl,
+            headless,
+            defaultTimeoutMs: uiTimeoutMs,
+            navigationTimeoutMs: uiNavigationTimeoutMs,
+          },
           defaults: {
             timeoutMs: options?.timeoutMs,
             retries: options?.retries,
@@ -120,8 +143,8 @@ export class TestRunCommand extends CommandRunner {
         console.error('Run tests command failed');
         process.exitCode = 1;
       } finally {
-        if (reporter instanceof WebhookReporter) {
-          await reporter.flush(Number(process.exitCode ?? 0));
+        if (baseReporter instanceof WebhookReporter) {
+          await baseReporter.flush(Number(process.exitCode ?? 0));
         }
       }
       return;
@@ -225,6 +248,26 @@ export class TestRunCommand extends CommandRunner {
     return val === 'false' ? false : true;
   }
 
+  @Option({
+    flags: '--ui-timeout-ms [number]',
+    description:
+      'Default timeout in ms for UI steps (waits, clicks, fills). Defaults to process.env.UI_TIMEOUT_MS, then the uiTestDefaultTimeoutMs setting, then 30000.',
+    required: false,
+  })
+  parseUiTimeoutMs(val: string): number {
+    return Number(val);
+  }
+
+  @Option({
+    flags: '--ui-navigation-timeout-ms [number]',
+    description:
+      'Default timeout in ms for ui.goto navigation. Defaults to process.env.UI_NAVIGATION_TIMEOUT_MS, then the uiTestNavigationTimeoutMs setting, then --ui-timeout-ms.',
+    required: false,
+  })
+  parseUiNavigationTimeoutMs(val: string): number {
+    return Number(val);
+  }
+
   @Option({
     flags: '--timeout-ms [number]',
     description: 'Default scenario timeout in milliseconds.',
@@ -251,6 +294,15 @@ export class TestRunCommand extends CommandRunner {
   parseRunName(val: string): string {
     return val;
   }
+
+  @Option({
+    flags: '--no-progress',
+    description: 'Disable the interactive test progress footer.',
+    required: false,
+  })
+  parseNoProgress(): boolean {
+    return false;
+  }
 }
 
 function splitCsv(value?: string): string[] | undefined {
@@ -262,6 +314,14 @@ function splitCsv(value?: string): string[] | undefined {
   return items.length ? items : undefined;
 }
 
+// Accepts unknown because settings come back already parsed as numbers, while env
+// vars arrive as strings.
+function toPositiveNumber(value?: unknown): number | undefined {
+  if (value === null || value === undefined || value === '') return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 function resolveSpecPath(entry: string, metadataPath: string): string {
   if (path.isAbsolute(entry)) {
     return entry;

package/src/commands/seed.command.ts

@@ -7,6 +7,7 @@ interface SeedCommandOptions {
   seeder?: string;
   modulesToSeed?: string;
   prune?: boolean;
+  skipHooks?: boolean;
 }
 
 @Command({ name: 'seed', description: 'Install seed data for a given module' })
@@ -28,6 +29,7 @@ export class SeedCommand extends CommandRunner {
         modulesToSeed,
         pruneMetadata: false,
         seedGlobalMetadata: true,
+        skipHooks: false,
       };
       this.logger.log(`Modules to seed: ${modulesToSeed.join(', ')}`);
     } else {
@@ -39,10 +41,22 @@ export class SeedCommand extends CommandRunner {
         modulesToSeed: null,
         pruneMetadata: false,
         seedGlobalMetadata: true,
+        skipHooks: false,
       };
       parsedConf.pruneMetadata = true;
     }
 
+    if (options?.skipHooks) {
+      parsedConf = parsedConf ?? {
+        modulesToSeed: null,
+        pruneMetadata: false,
+        seedGlobalMetadata: true,
+        skipHooks: false,
+      };
+      parsedConf.skipHooks = true;
+      this.logger.log('Skipping pre-seed and post-seed hooks.');
+    }
+
     const seeder = this.solidRegistry
       .getSeeders()
       .filter((seeder) => seeder.name === options.seeder)
@@ -74,4 +88,9 @@ export class SeedCommand extends CommandRunner {
   parsePrune(): boolean {
     return true;
   }
+
+  @Option({ flags: '--skip-hooks', description: 'Skip emitting pre-seed and post-seed lifecycle hooks/events.' })
+  parseSkipHooks(): boolean {
+    return true;
+  }
 }

package/src/config/cache.options.ts

@@ -1,6 +1,14 @@
 import { CacheModuleAsyncOptions } from '@nestjs/cache-manager';
 import { ConfigModule, ConfigService } from '@nestjs/config';
-import { redisStore } from 'cache-manager-redis-store';
+// cache-manager-redis-yet, not cache-manager-redis-store. The latter stops at
+// 3.0.1 and implements the cache-manager v4 store contract: it expects an
+// options object and reads `options.ttl` in seconds. cache-manager v5 calls
+// `store.set(key, value, ttl)` with a bare number of milliseconds, so that
+// store found no `.ttl`, fell back to an unset default, and issued a plain
+// `SET` - silently discarding every TTL passed anywhere in the app and leaving
+// Redis keys that never expire. redis-yet implements the v5 contract and
+// writes with `PX`, so millisecond TTLs land correctly.
+import { redisStore } from 'cache-manager-redis-yet';
 import { isRedisConfigured } from 'src/helpers/environment.helper';
 
 export const CacheManagerOptions: CacheModuleAsyncOptions = {

package/src/constants/chatter-message.constants.ts

@@ -1,3 +1,5 @@
+import { USER_SUMMARY_FIELDS } from 'src/constants/user.constants';
+
 export const CHATTER_MESSAGE_TYPE = {
     AUDIT: 'audit',
     CUSTOM: 'custom',
@@ -16,3 +18,13 @@ export const CHATTER_MESSAGE_STATUS = {
     PENDING: 'pending',
     COMPLETED: 'completed',
 } as const;
+
+/**
+ * Columns of the message author exposed by the chatter APIs.
+ *
+ * The chatter panel renders `fullName` (name label + initials avatar) and uses `id`
+ * for the own-note edit check; the admin list/form/tree views display `fullName` via
+ * each view's `coModelFieldToDisplay`. That is exactly the platform-wide summary
+ * shape, so this is an alias rather than a second list to keep in step.
+ */
+export const CHATTER_MESSAGE_USER_FIELDS = USER_SUMMARY_FIELDS;

package/src/constants/draft-publish-fields.ts

@@ -0,0 +1,5 @@
+// The versioning columns CommonEntity adds for draft/publish support. These don't exist on
+// legacy tables (see LegacyCommonEntityWithExistingId) and don't carry over when a new draft
+// version is copied from its source entity, so both of those call sites share this list rather
+// than each hand-enumerating the same four names.
+export const DRAFT_PUBLISH_VERSIONING_FIELD_NAMES = ['isPublished', 'isLatest', 'initialEntityVersionId', 'publishedTracker'] as const;

package/src/constants/error-messages.ts

@@ -127,6 +127,20 @@ export const ERROR_MESSAGES = {
 
     DEFAULT_REGEX_PATTERN_NOT_MATCHING_ERROR_MSG: 'Invalid regex pattern.',
 
+    // MPIN errors.
+    // MPIN_INVALID is deliberately shared by "wrong MPIN" and "unknown handle",
+    // so a failed sign-in never reveals whether the credential handle was real.
+    // MPIN_REVOKED is separate and is returned for any attempt against a
+    // deactivated credential - it discloses nothing useful, since a dead
+    // credential grants no capability, and it lets the client stop retrying.
+    MPIN_INVALID: 'Invalid MPIN.',
+    MPIN_LOCKED: 'MPIN sign-in is temporarily locked due to repeated failed attempts.',
+    MPIN_REVOKED: 'MPIN sign-in has been disabled for this device. Please sign in normally.',
+    MPIN_NOT_ENABLED: 'MPIN sign-in is not enabled.',
+    MPIN_FORMAT_INVALID: 'MPIN does not meet the required format.',
+    MPIN_TOO_PREDICTABLE: 'MPIN is too easy to guess. Avoid repeated or sequential digits.',
+    MPIN_CREDENTIAL_NOT_FOUND: 'MPIN device credential not found.',
+
     PERMISSION_MESSAGES: {
     insertMany: (model?: string) =>
       `You do not have permission to import ${model ?? 'these'} records.`,

package/src/constants/media-file-types.ts

@@ -1,5 +1,7 @@
 export type MediaCategory = 'image' | 'audio' | 'video' | 'file' | 'pdf';
 
+export const MEDIA_CATEGORIES = ['image', 'audio', 'video', 'file', 'pdf'] as const;
+
 const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'webp', 'gif', 'bmp', 'tiff', 'heic', 'heif'];
 const AUDIO_EXTENSIONS = ['mp3', 'wav', 'ogg', 'aac', 'm4a', 'flac', 'webm'];
 const VIDEO_EXTENSIONS = ['mp4', 'mov', 'avi', 'mkv', 'mpeg', 'mpg', '3gp', '3g2', 'webm', 'ogg'];
@@ -15,8 +17,134 @@ export const DANGEROUS_EXTENSIONS = new Set([
     'html', 'htm', 'xhtml', 'svg', 'xml',
     'js', 'mjs', 'php', 'phtml', 'jsp', 'asp', 'aspx',
     'exe', 'sh', 'bat', 'cmd', 'ps1', 'jar', 'dll',
+    'msi', 'msix', 'msp', 'com', 'scr', 'vbs', 'vbe', 'wsf', 'wsh', 'hta', 'cpl', 'pif', 'reg',
+]);
+
+
+/**
+ * Mimetypes that are never safe to accept, regardless of extension. These render as active
+ * content in a browser (svg can carry <script>), so they are rejected even when the filename
+ * looks harmless. Kept alongside DANGEROUS_EXTENSIONS so upload paths check both.
+ */
+export const DANGEROUS_MIME_TYPES = new Set([
+    'image/svg+xml', 'text/html', 'application/xhtml+xml',
 ]);
 
+/**
+ * Percent-decodes a filename, repeating a bounded number of times so a double-encoded payload
+ * (`%252e` -> `%2e` -> `.`) survives a single pass through a proxy/framework that already
+ * decoded once. Malformed escape sequences are left as-is rather than thrown, since this runs
+ * on attacker-controlled input and a literal `%` in a filename (`100%done.pdf`) is legal.
+ */
+function decodePercentEncodingSafely(name: string): string {
+    let decoded = name;
+    for (let i = 0; i < 3; i++) {
+        let next: string;
+        try {
+            next = decodeURIComponent(decoded);
+        } catch {
+            return decoded;
+        }
+        if (next === decoded) {
+            return decoded;
+        }
+        decoded = next;
+    }
+    return decoded;
+}
+
+/**
+ * Reduces a client-supplied name to the name that will actually be resolved on disk, so
+ * extension checks can't be dodged by decorating it. Each step defends a known bypass:
+ *
+ *  - `evil.exe%2e`         -> percent-encoding a trailing dot (or anything else) hides the real
+ *                             extension from naive string matching; decode before inspecting it.
+ *  - `../../evil.exe`      -> only the final path segment is the file name.
+ *  - `evil.exe\0.png`      -> a NUL truncates the name at the syscall/filesystem layer, so
+ *                             anything after it is invisible to the OS but visible to naive
+ *                             validation.
+ *  - `evil.exe::$DATA`     -> NTFS alternate data stream suffix; the file on disk is evil.exe.
+ *  - `evil.exe.` / `.exe ` -> Windows silently strips trailing dots and spaces when resolving
+ *                             a path, so these land on disk as evil.exe.
+ */
+export function normalizeUploadedFileName(fileName?: string | null): string {
+    if (!fileName) {
+        return '';
+    }
+
+    let name = decodePercentEncodingSafely(String(fileName));
+    name = name.split(/[/\\]/).pop() ?? '';
+
+    const nulIndex = name.indexOf('\0');
+    if (nulIndex >= 0) {
+        name = name.slice(0, nulIndex);
+    }
+
+    const streamIndex = name.indexOf(':');
+    if (streamIndex >= 0) {
+        name = name.slice(0, streamIndex);
+    }
+
+    return name.replace(/[\s.]+$/, '');
+}
+
+/**
+ * The effective extension - what the OS/browser will treat the file as. Used for media
+ * category resolution and inline-safety decisions. Always normalizes first, so
+ * `evil.exe.` resolves to `exe` rather than to nothing.
+ */
+export function getLowercaseFileExtension(fileName?: string | null): string | undefined {
+    const name = normalizeUploadedFileName(fileName);
+
+    const lastDotIndex = name.lastIndexOf('.');
+    if (lastDotIndex < 0 || lastDotIndex === name.length - 1) {
+        return undefined;
+    }
+
+    return name.slice(lastDotIndex + 1).toLowerCase();
+}
+
+/**
+ * Every dot-delimited segment after the stem, lowercased. The danger check uses this rather
+ * than only the effective extension so a dangerous type buried in a double extension
+ * (`evil.exe.png`, `shell.php.jpg`) is still caught - several servers and browsers resolve
+ * such names by an earlier segment than the last one.
+ *
+ * The stem is skipped so an innocuous file that merely starts with a keyword (`exe.png`)
+ * isn't rejected.
+ */
+export function getLowercaseFileExtensionSegments(fileName?: string | null): string[] {
+    const segments = normalizeUploadedFileName(fileName).toLowerCase().split('.');
+    return segments.slice(1).filter(segment => segment.length > 0);
+}
+
+/** Minimal shape of an uploaded file, so this module stays free of framework imports. */
+export interface UploadedFileLike {
+    mimetype?: string;
+    originalname?: string;
+    filename?: string;
+}
+
+/** originalname is the client-supplied name; filename is multer's on-disk name. */
+export function getUploadedFileName(file?: UploadedFileLike | null): string {
+    return file?.originalname ?? file?.filename ?? '';
+}
+
+/**
+ * Single predicate for "must never be stored". Shared by every upload entry point
+ * (MediaFieldCrudManager, chatter attachments) so the rules can't drift between them.
+ * Extensions are checked before mimetype so a spoofed Content-Type (e.g.
+ * application/octet-stream, or image/png, on an .html file) can't bypass it.
+ */
+export function isDangerousMediaFile(file?: UploadedFileLike | null): boolean {
+    const segments = getLowercaseFileExtensionSegments(getUploadedFileName(file));
+    if (segments.some(segment => DANGEROUS_EXTENSIONS.has(segment))) {
+        return true;
+    }
+
+    return DANGEROUS_MIME_TYPES.has((file?.mimetype || '').toLowerCase().trim());
+}
+
 /**
  * Single source of truth for extension -> coarse media category. Shared by upload-time
  * validation (MediaFieldCrudManager) and serve-time header hardening (ServeStaticModule), so

package/src/constants/success-messages.ts

@@ -6,6 +6,11 @@ export const SUCCESS_MESSAGES = {
     LOGOUT_SUCCESS: 'Logged out successfully',
     USER_REGISTERED: 'User registered successfully.',
 
+    // MPIN messages
+    MPIN_SETUP_SUCCESS: 'MPIN set up successfully.',
+    MPIN_CHANGED_SUCCESS: 'MPIN changed successfully.',
+    MPIN_DEVICE_REVOKED: 'MPIN sign-in removed for this device.',
+
     // CRUD service messages
     RECORD_RECOVERED: 'Record successfully recovered',
     SELECTED_RECORDS_RECOVERED: 'Selected records successfully recovered',

package/src/constants/user.constants.ts

@@ -0,0 +1,13 @@
+/**
+ * The columns of a `User` that are safe to embed in another entity's API response.
+ *
+ * Whenever a user is attached to a record the caller asked for - a `createdBy` /
+ * `updatedBy` populate, a chatter message author - the caller wants to display who it
+ * was, not to read their profile. Everything else on `User` is PII (email, mobile),
+ * authz metadata (roles, apiKeys) or secret, and the embedded user is frequently
+ * someone the viewer has no other visibility of.
+ *
+ * `fullName` is nullable; consumers that need a fallback should use the record's own
+ * context rather than widening this list.
+ */
+export const USER_SUMMARY_FIELDS = ['id', 'fullName'] as const;

package/src/controllers/authentication.controller.ts

@@ -107,8 +107,11 @@ export class AuthenticationController {
     @Post('logout')
     @Public()
     @HttpCode(HttpStatus.OK)
-    async logout(@Body('refreshToken') refreshToken: string) {
-        return this.authService.logout(refreshToken);
+    async logout(
+        @Body('refreshToken') refreshToken: string,
+        @Body('allDevices') allDevices?: boolean,
+    ) {
+        return this.authService.logout(refreshToken, allDevices === true);
     }
 
     @ApiBearerAuth("jwt")

package/src/controllers/chatter-message.controller.ts

@@ -95,6 +95,14 @@ export class ChatterMessageController {
     return this.service.find(query);  
   }
 
+  @ApiBearerAuth("jwt")
+  @ApiQuery({ name: 'search', required: false, type: String })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  @Get('mentionable-users')
+  async getMentionableUsers(@Query() query: any) {
+    return this.service.getMentionableUsers(query?.search, query?.limit ? +query.limit : undefined);
+  }
+
   @ApiBearerAuth("jwt")
   @Get(':id')
   async findOne(@Param('id') id: string, @Query() query: any) {