@decaf-ts/ui-decorators 0.20.4 → 0.20.7

package/lib/types/dashboard/types.d.mts

@@ -0,0 +1,67 @@
+/**
+ * @module ui-decorators/dashboard/types
+ * @summary Type definitions for dashboard-selectable components.
+ * @description Flavor-neutral types describing the palette metadata attached
+ * by `@dashcomponent()` and the resolved definition consumed by a palette
+ * service. No Angular or framework imports.
+ */
+import type { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Grid footprint of a dashboard component.
+ * @summary A component's default footprint on the dashboard grid, expressed
+ * in grid units (columns and rows).
+ * @typedef DashComponentSize
+ * @memberOf module:ui-decorators/dashboard/types
+ * @property {number} cols - Number of grid columns occupied.
+ * @property {number} rows - Number of grid rows occupied.
+ */
+export type DashComponentSize = {
+    cols: number;
+    rows: number;
+};
+/**
+ * @description Palette metadata attached to a dashboard-selectable component.
+ * @summary The metadata object stored on a `@dashcomponent`-decorated class.
+ * Carries the translation label key, the default grid size, and an optional
+ * reference to the configuration model used by the component's own CRUD flow.
+ * @typedef DashComponentMetadata
+ * @memberOf module:ui-decorators/dashboard/types
+ * @property {string} [tag] - Component tag resolved for rendering.
+ * @property {string} [label] - Translation label key for the palette.
+ * @property {DashComponentSize} [defaultSize] - Default grid footprint.
+ * @property {Constructor} [model] - Configuration model constructor reference.
+ * @property {Record<string, any>} [props] - Ad-hoc props for the component.
+ * @property {Record<string, unknown>} [metadata] - Free-form extension points.
+ */
+export type DashComponentMetadata = {
+    tag?: string;
+    label?: string;
+    defaultSize?: DashComponentSize;
+    model?: Constructor;
+    props?: Record<string, any>;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * @description Resolved definition of a dashboard-selectable component.
+ * @summary The normalized shape a palette or rendering service consumes from
+ * the registry. Defaults are applied so consumers never resolve undefined
+ * footprint values.
+ * @typedef DashComponentDefinition
+ * @memberOf module:ui-decorators/dashboard/types
+ * @property {string} name - Class name of the decorated component.
+ * @property {string} tag - Component tag resolved for rendering.
+ * @property {string} [label] - Translation label key for the palette.
+ * @property {DashComponentSize} defaultSize - Default grid footprint.
+ * @property {Constructor} [model] - Configuration model constructor reference.
+ * @property {Record<string, any>} [props] - Ad-hoc props for the component.
+ * @property {Record<string, unknown>} [metadata] - Free-form extension points.
+ */
+export type DashComponentDefinition = {
+    name: string;
+    tag: string;
+    label?: string;
+    defaultSize: DashComponentSize;
+    model?: Constructor;
+    props?: Record<string, any>;
+    metadata?: Record<string, unknown>;
+};

package/lib/types/graph/GraphExecutionStateMapper.d.cts

@@ -0,0 +1,66 @@
+/**
+ * @module ui-decorators/graph/GraphExecutionStateMapper
+ * @summary Maps engine state to the frontend-safe visual-state contract.
+ * @description Pure, engine-agnostic helpers that derive
+ * `GraphVisualState` values from engine execution signals. Frontend
+ * bundles may import this from `@decaf-ts/ui-decorators/graph` (no
+ * engine runtime dependency); a future Mastra/NestJS driver maps its own
+ * runtime states onto `GraphVisualState` with the same rules.
+ */
+import type { GraphExecutionEvent } from "./types.d.cts";
+import { GraphExecutionStatus, GraphVisualState } from "./constants.d.cts";
+/**
+ * Maps an engine execution `GraphExecutionStatus` to the shared visual
+ * state. `CACHED` collapses onto `GraphVisualState.SUCCEEDED` for
+ * rendering; `CANCELLED`/`PENDING`/`PLANNING` yield `IDLE`.
+ *
+ * @param status - The engine execution status, if any.
+ * @returns The visual state for the node/edge.
+ */
+export declare function mapExecutionStatus(status?: GraphExecutionStatus): GraphVisualState;
+/**
+ * Options describing a single node's position within a run (DECAF-48 §4.4).
+ */
+export interface GraphVisualStateDerivation {
+    /** Whether the node has already executed (any terminal engine status). */
+    executed: boolean;
+    /** Whether the node is currently running. */
+    running: boolean;
+    /** Whether the node completed successfully (or from cache). */
+    succeeded?: boolean;
+    /** Whether the node failed. */
+    failed?: boolean;
+    /** Number of incoming edges that have completed value routing. */
+    completedUpstreams?: number;
+    /** Total number of incoming edges for the node. */
+    upstreamCount?: number;
+    /** Whether the node is reachable from the workflow inputs in the plan. */
+    reachable?: boolean;
+    /** Whether the whole run has failed (unexecuted nodes then fade/disable). */
+    runFailed?: boolean;
+}
+/**
+ * Derives the visual state for one node from its execution signals.
+ *
+ * Rules (DECAF-48 §4.4 / Req-5/Req-6):
+ * - currently running → `GraphVisualState.RUNNING`
+ * - failed → `GraphVisualState.FAILED`
+ * - executed and succeeded (or from cache) → `GraphVisualState.SUCCEEDED`
+ * - unexecuted and reachable with incomplete upstream deps → `GraphVisualState.BLOCKED`
+ * - unexecuted with `runFailed` → `GraphVisualState.SKIPPED` (faded/disabled)
+ * - otherwise → `GraphVisualState.IDLE`
+ *
+ * @param options - The node execution signals.
+ * @returns The derived visual state.
+ */
+export declare function deriveNodeVisualState(options: GraphVisualStateDerivation): GraphVisualState;
+/**
+ * Translates a `GraphExecutionEvent` into a node visual state when the
+ * event carries enough information. Used by contract conformance checks and
+ * engine-agnostic consumers that derive state from the shared event stream.
+ *
+ * @param event - The graph execution event.
+ * @returns The corresponding `GraphVisualState`, or `IDLE` when the
+ * event does not indicate a specific visual transition.
+ */
+export declare function visualStateOfEvent(event: GraphExecutionEvent): GraphVisualState;

package/lib/types/graph/GraphExecutionStateMapper.d.mts

@@ -0,0 +1,66 @@
+/**
+ * @module ui-decorators/graph/GraphExecutionStateMapper
+ * @summary Maps engine state to the frontend-safe visual-state contract.
+ * @description Pure, engine-agnostic helpers that derive
+ * `GraphVisualState` values from engine execution signals. Frontend
+ * bundles may import this from `@decaf-ts/ui-decorators/graph` (no
+ * engine runtime dependency); a future Mastra/NestJS driver maps its own
+ * runtime states onto `GraphVisualState` with the same rules.
+ */
+import type { GraphExecutionEvent } from "./types.d.mts";
+import { GraphExecutionStatus, GraphVisualState } from "./constants.d.mts";
+/**
+ * Maps an engine execution `GraphExecutionStatus` to the shared visual
+ * state. `CACHED` collapses onto `GraphVisualState.SUCCEEDED` for
+ * rendering; `CANCELLED`/`PENDING`/`PLANNING` yield `IDLE`.
+ *
+ * @param status - The engine execution status, if any.
+ * @returns The visual state for the node/edge.
+ */
+export declare function mapExecutionStatus(status?: GraphExecutionStatus): GraphVisualState;
+/**
+ * Options describing a single node's position within a run (DECAF-48 §4.4).
+ */
+export interface GraphVisualStateDerivation {
+    /** Whether the node has already executed (any terminal engine status). */
+    executed: boolean;
+    /** Whether the node is currently running. */
+    running: boolean;
+    /** Whether the node completed successfully (or from cache). */
+    succeeded?: boolean;
+    /** Whether the node failed. */
+    failed?: boolean;
+    /** Number of incoming edges that have completed value routing. */
+    completedUpstreams?: number;
+    /** Total number of incoming edges for the node. */
+    upstreamCount?: number;
+    /** Whether the node is reachable from the workflow inputs in the plan. */
+    reachable?: boolean;
+    /** Whether the whole run has failed (unexecuted nodes then fade/disable). */
+    runFailed?: boolean;
+}
+/**
+ * Derives the visual state for one node from its execution signals.
+ *
+ * Rules (DECAF-48 §4.4 / Req-5/Req-6):
+ * - currently running → `GraphVisualState.RUNNING`
+ * - failed → `GraphVisualState.FAILED`
+ * - executed and succeeded (or from cache) → `GraphVisualState.SUCCEEDED`
+ * - unexecuted and reachable with incomplete upstream deps → `GraphVisualState.BLOCKED`
+ * - unexecuted with `runFailed` → `GraphVisualState.SKIPPED` (faded/disabled)
+ * - otherwise → `GraphVisualState.IDLE`
+ *
+ * @param options - The node execution signals.
+ * @returns The derived visual state.
+ */
+export declare function deriveNodeVisualState(options: GraphVisualStateDerivation): GraphVisualState;
+/**
+ * Translates a `GraphExecutionEvent` into a node visual state when the
+ * event carries enough information. Used by contract conformance checks and
+ * engine-agnostic consumers that derive state from the shared event stream.
+ *
+ * @param event - The graph execution event.
+ * @returns The corresponding `GraphVisualState`, or `IDLE` when the
+ * event does not indicate a specific visual transition.
+ */
+export declare function visualStateOfEvent(event: GraphExecutionEvent): GraphVisualState;

package/lib/types/graph/GraphResolution.d.cts

@@ -0,0 +1,53 @@
+/**
+ * @module ui-decorators/graph/GraphResolution
+ * @summary Shared graph manifest-resolution contracts.
+ * @description Frontend/backend-shared manifest-resolution types (DECAF-50
+ * §4.11): the effective per-node manifest shape consumed by the planner,
+ * executor, and the frontend catalogue, plus its structural type guard and
+ * the resolution/query contexts. Node/browser compatible — no engine
+ * runtime dependency.
+ */
+import type { GraphCredentialReference, GraphCredentialRequirement, GraphDynamicPortRule, GraphJsonValue, GraphNodeCapability, GraphNodeDisplayManifest, GraphNodePolicyManifest, GraphParameterDefinition, GraphPortManifest } from "./catalog/index.d.cts";
+/**
+ * The effective manifest for one node instance (DECAF-50 §4.11): the
+ * published manifest with dynamic ports expanded against the instance's
+ * parameters. This is the shape the planner and executor consume — the only
+ * input the nine-stage validator's resolved workflow carries per node.
+ */
+export interface GraphResolvedNodeManifest {
+    /** Node kind. */
+    kind: string;
+    /** Display metadata (name, category, icon). */
+    display: GraphNodeDisplayManifest;
+    /** Effective input ports (static plus expanded dynamic). */
+    inputs: GraphPortManifest[];
+    /** Effective output ports (static plus expanded dynamic). */
+    outputs: GraphPortManifest[];
+    /** Effective connection ports, when any. */
+    connections?: GraphPortManifest[];
+    /** Declared parameters. */
+    parameters: GraphParameterDefinition[];
+    /** Dynamic-port rules the manifest declares, when any. */
+    dynamicPorts?: GraphDynamicPortRule[];
+    /** Credential requirements, when any. */
+    credentials?: GraphCredentialRequirement[];
+    /** Capabilities, when any. */
+    capabilities?: GraphNodeCapability[];
+    /** Execution policies, when declared. */
+    policies?: GraphNodePolicyManifest;
+    /** Free-form metadata. */
+    metadata?: Record<string, GraphJsonValue>;
+}
+/** Structural type guard for `GraphResolvedNodeManifest`. */
+export declare function isGraphResolvedNodeManifest(value: unknown): value is GraphResolvedNodeManifest;
+/** Context handed to manifest resolution for a node instance: authorized credentials plus caller metadata. */
+export interface GraphNodeResolutionContext {
+    credentials?: GraphCredentialReference[];
+    requestContext?: unknown;
+    metadata?: Record<string, GraphJsonValue>;
+}
+/** Filters for catalogue manifest listing: restrict results to the given display categories and/or kinds. */
+export interface GraphCatalogueQueryContext {
+    categories?: string[];
+    kinds?: string[];
+}

package/lib/types/graph/GraphResolution.d.mts

@@ -0,0 +1,53 @@
+/**
+ * @module ui-decorators/graph/GraphResolution
+ * @summary Shared graph manifest-resolution contracts.
+ * @description Frontend/backend-shared manifest-resolution types (DECAF-50
+ * §4.11): the effective per-node manifest shape consumed by the planner,
+ * executor, and the frontend catalogue, plus its structural type guard and
+ * the resolution/query contexts. Node/browser compatible — no engine
+ * runtime dependency.
+ */
+import type { GraphCredentialReference, GraphCredentialRequirement, GraphDynamicPortRule, GraphJsonValue, GraphNodeCapability, GraphNodeDisplayManifest, GraphNodePolicyManifest, GraphParameterDefinition, GraphPortManifest } from "./catalog/index.d.mts";
+/**
+ * The effective manifest for one node instance (DECAF-50 §4.11): the
+ * published manifest with dynamic ports expanded against the instance's
+ * parameters. This is the shape the planner and executor consume — the only
+ * input the nine-stage validator's resolved workflow carries per node.
+ */
+export interface GraphResolvedNodeManifest {
+    /** Node kind. */
+    kind: string;
+    /** Display metadata (name, category, icon). */
+    display: GraphNodeDisplayManifest;
+    /** Effective input ports (static plus expanded dynamic). */
+    inputs: GraphPortManifest[];
+    /** Effective output ports (static plus expanded dynamic). */
+    outputs: GraphPortManifest[];
+    /** Effective connection ports, when any. */
+    connections?: GraphPortManifest[];
+    /** Declared parameters. */
+    parameters: GraphParameterDefinition[];
+    /** Dynamic-port rules the manifest declares, when any. */
+    dynamicPorts?: GraphDynamicPortRule[];
+    /** Credential requirements, when any. */
+    credentials?: GraphCredentialRequirement[];
+    /** Capabilities, when any. */
+    capabilities?: GraphNodeCapability[];
+    /** Execution policies, when declared. */
+    policies?: GraphNodePolicyManifest;
+    /** Free-form metadata. */
+    metadata?: Record<string, GraphJsonValue>;
+}
+/** Structural type guard for `GraphResolvedNodeManifest`. */
+export declare function isGraphResolvedNodeManifest(value: unknown): value is GraphResolvedNodeManifest;
+/** Context handed to manifest resolution for a node instance: authorized credentials plus caller metadata. */
+export interface GraphNodeResolutionContext {
+    credentials?: GraphCredentialReference[];
+    requestContext?: unknown;
+    metadata?: Record<string, GraphJsonValue>;
+}
+/** Filters for catalogue manifest listing: restrict results to the given display categories and/or kinds. */
+export interface GraphCatalogueQueryContext {
+    categories?: string[];
+    kinds?: string[];
+}

package/lib/types/graph/constants.d.cts

@@ -282,3 +282,168 @@ export declare function resolveEffectiveColor(explicitColor?: string, category?:
  * category icon, which overrides the default.
  */
 export declare function resolveEffectiveIcon(explicitIcon?: string, category?: string): string;
+import type { GraphRunStatus } from "./types.d.cts";
+/**
+ * Disabled-node execution semantics (DECAF-50 §4.9).
+ *
+ * - `skip` — the node does not execute and produces no outputs.
+ * - `passThroughFirstInput` — the first incoming edge value is forwarded on
+ *   the node's first declared output port.
+ * - `emitDefaults` — every declared output port is emitted with its default
+ *   (absent a declared default, `undefined`).
+ */
+export declare const GRAPH_DISABLED_NODE_BEHAVIORS: readonly ["skip", "passThroughFirstInput", "emitDefaults"];
+/** How a disabled node behaves during execution (DECAF-50 §4.8): skip it, pass through its first input, or emit default outputs. */
+export type GraphDisabledNodeBehavior = (typeof GRAPH_DISABLED_NODE_BEHAVIORS)[number];
+/** The disabled-node behavior applied when a node declares none. */
+export declare const GRAPH_DEFAULT_DISABLED_NODE_BEHAVIOR: GraphDisabledNodeBehavior;
+/** Type guard for {@link GraphDisabledNodeBehavior}. */
+export declare function isGraphDisabledNodeBehavior(value: unknown): value is GraphDisabledNodeBehavior;
+/**
+ * Execution status for a workflow or individual node.
+ */
+export declare enum GraphExecutionStatus {
+    PENDING = "pending",
+    PLANNING = "planning",
+    RUNNING = "running",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed",
+    SKIPPED = "skipped",
+    CANCELLED = "cancelled",
+    CACHED = "cached"
+}
+/**
+ * Visual execution state for a node or edge on the workflow canvas.
+ *
+ * Frontend-safe (DECAF-48 §4.4): a superset of {@link GraphExecutionStatus}
+ * normalised for rendering. `BLOCKED` is derived from the plan and execution
+ * events (waiting on upstream dependencies), not emitted as an engine status.
+ * `SKIPPED` is the post-failure "unexecuted/disabled" visual state.
+ */
+export declare enum GraphVisualState {
+    IDLE = "idle",
+    RUNNING = "running",
+    BLOCKED = "blocked",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed",
+    SKIPPED = "skipped"
+}
+/**
+ * Namespace root for graph run SSE topics (DECAF-48 §4.2). A subscription
+ * filters on these granular topics before `observer.next(...)`.
+ */
+export declare const GRAPH_RUN_TOPIC = "graph.run";
+/**
+ * SSE sub-topic streaming per-node log lines during a run.
+ */
+export declare const GRAPH_RUN_LOG_TOPIC = "graph.run.log";
+/**
+ * SSE sub-topic streaming node/edge execution-state updates during a run.
+ */
+export declare const GRAPH_RUN_STATE_TOPIC = "graph.run.state";
+/**
+ * Logger custom-attribute keys attached to every run log line via
+ * DECAF-9 `logger.for({...})` (DECAF-48 §4.3). Rendered as discrete columns
+ * (not buried in the message string).
+ */
+export declare enum GraphLogAttribute {
+    NODE_ID = "nodeId",
+    WORKFLOW_ID = "workflowId",
+    RUN_ID = "runId",
+    USER = "user"
+}
+/**
+ * Namespace topic helper for a graph execution event.
+ *
+ * Log-carrier events resolve to `graph.run.log`; node/edge execution-state
+ * events resolve to `graph.run.state`; everything else stays under the shared
+ * `graph.run` topic and is only delivered to subscribers that match it.
+ *
+ * @param eventType - The graph execution event type to scope to a topic.
+ * @returns The SSE topic constant for the given event type.
+ */
+export declare function graphRunTopicOf(eventType: GraphExecutionEventType): string;
+/**
+ * Event types emitted through the graph execution observer pipeline.
+ *
+ * DECAF-48 extends this set with the visual-state and run-log event types the
+ * engine emits on the existing Observable: {@link GraphExecutionEventType.NODE_STATE_CHANGED},
+ * {@link GraphExecutionEventType.EDGE_STATE_CHANGED} and
+ * {@link GraphExecutionEventType.GRAPH_RUN_LOG}.
+ */
+export declare enum GraphExecutionEventType {
+    WORKFLOW_STARTED = "workflow.started",
+    WORKFLOW_PLANNED = "workflow.planned",
+    WORKFLOW_COMPLETED = "workflow.completed",
+    WORKFLOW_FAILED = "workflow.failed",
+    WORKFLOW_CANCELLED = "workflow.cancelled",
+    NODE_QUEUED = "node.queued",
+    NODE_STARTED = "node.started",
+    NODE_OUTPUT = "node.output",
+    NODE_COMPLETED = "node.completed",
+    NODE_FAILED = "node.failed",
+    NODE_SKIPPED = "node.skipped",
+    NODE_CACHE_HIT = "node.cacheHit",
+    NODE_PINNED = "node.pinned",
+    NODE_UNPINNED = "node.unpinned",
+    /** Node execution-state transition carrying a `GraphNodeStateChangedPayload` (DECAF-48 §4.4). */
+    NODE_STATE_CHANGED = "node.stateChanged",
+    EDGE_VALUE_ROUTED = "edge.valueRouted",
+    /** Edge execution-state transition carrying a `GraphEdgeStateChangedPayload` (DECAF-48 §4.4). */
+    EDGE_STATE_CHANGED = "edge.stateChanged",
+    /** Structured run log line carrying a `GraphRunLogEntry` (DECAF-48 §4.3). */
+    GRAPH_RUN_LOG = "graph.run.log",
+    LOOP_STARTED = "loop.started",
+    LOOP_ITERATION_STARTED = "loop.iteration.started",
+    LOOP_ITERATION_COMPLETED = "loop.iteration.completed",
+    LOOP_CONDITION_EVALUATED = "loop.condition.evaluated",
+    LOOP_COMPLETED = "loop.completed",
+    LOOP_LIMIT_REACHED = "loop.limitReached",
+    VALIDATION_STARTED = "validation.started",
+    VALIDATION_FAILED = "validation.failed",
+    VALIDATION_COMPLETED = "validation.completed",
+    STORE_READ = "store.read",
+    STORE_WRITE = "store.write",
+    STORE_DELETE = "store.delete"
+}
+/**
+ * Hard limits for the graph run subsystem (DECAF-50 §4.14/§4.16).
+ *
+ * Enforced by the run executor and the HTTP run controller; every omitted
+ * field falls back to {@link DEFAULT_GRAPH_RUN_LIMITS}.
+ */
+export interface GraphRunLimits {
+    /** Maximum serialised JSON size accepted for a run create request. */
+    maxRequestBytes?: number;
+    /**
+     * Maximum number of runs in flight per caller: the run's owner user, or
+     * the caller-key bucket supplied by the HTTP layer for anonymous callers
+     * (per-IP where the host exposes it, a shared `"anonymous"` bucket
+     * otherwise).
+     */
+    maxConcurrentRuns?: number;
+    /** Maximum events retained per run by the in-memory event store. */
+    maxEventsPerRun?: number;
+    /** Maximum serialised size of a single event envelope `payload`. */
+    maxEventPayloadBytes?: number;
+    /** Hard wall-clock budget for a run's engine execution. */
+    executionTimeoutMs?: number;
+    /**
+     * How long a terminal run's replayable event state is kept after the run
+     * finishes before being released (SAA-595 resource governance).
+     */
+    eventReplayWindowMs?: number;
+}
+/** Default run limits: request size, per-caller concurrency, event retention/payload size, execution timeout, and post-terminal event replay window. */
+export declare const DEFAULT_GRAPH_RUN_LIMITS: Required<GraphRunLimits>;
+/**
+ * Terminal graph event types closing a run's SSE stream
+ * (DECAF-50 §4.15). The run SSE endpoint never emits anything after these.
+ */
+export declare const GRAPH_RUN_TERMINAL_EVENT_TYPES: readonly GraphExecutionEventType[];
+/** Whether the event type is a run-stream terminal type (see {@link GRAPH_RUN_TERMINAL_EVENT_TYPES}). */
+export declare function isGraphRunTerminalEventType(type: GraphExecutionEventType): boolean;
+/** Whether the run status is terminal (`succeeded`, `failed`, or `cancelled`). */
+export declare function isGraphRunTerminalStatus(status: GraphRunStatus): boolean;
+/** Type guard for {@link GraphRunStatus}. */
+export declare function isGraphRunStatus(value: unknown): value is GraphRunStatus;

package/lib/types/graph/constants.d.mts

@@ -282,3 +282,168 @@ export declare function resolveEffectiveColor(explicitColor?: string, category?:
  * category icon, which overrides the default.
  */
 export declare function resolveEffectiveIcon(explicitIcon?: string, category?: string): string;
+import type { GraphRunStatus } from "./types.d.mts";
+/**
+ * Disabled-node execution semantics (DECAF-50 §4.9).
+ *
+ * - `skip` — the node does not execute and produces no outputs.
+ * - `passThroughFirstInput` — the first incoming edge value is forwarded on
+ *   the node's first declared output port.
+ * - `emitDefaults` — every declared output port is emitted with its default
+ *   (absent a declared default, `undefined`).
+ */
+export declare const GRAPH_DISABLED_NODE_BEHAVIORS: readonly ["skip", "passThroughFirstInput", "emitDefaults"];
+/** How a disabled node behaves during execution (DECAF-50 §4.8): skip it, pass through its first input, or emit default outputs. */
+export type GraphDisabledNodeBehavior = (typeof GRAPH_DISABLED_NODE_BEHAVIORS)[number];
+/** The disabled-node behavior applied when a node declares none. */
+export declare const GRAPH_DEFAULT_DISABLED_NODE_BEHAVIOR: GraphDisabledNodeBehavior;
+/** Type guard for {@link GraphDisabledNodeBehavior}. */
+export declare function isGraphDisabledNodeBehavior(value: unknown): value is GraphDisabledNodeBehavior;
+/**
+ * Execution status for a workflow or individual node.
+ */
+export declare enum GraphExecutionStatus {
+    PENDING = "pending",
+    PLANNING = "planning",
+    RUNNING = "running",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed",
+    SKIPPED = "skipped",
+    CANCELLED = "cancelled",
+    CACHED = "cached"
+}
+/**
+ * Visual execution state for a node or edge on the workflow canvas.
+ *
+ * Frontend-safe (DECAF-48 §4.4): a superset of {@link GraphExecutionStatus}
+ * normalised for rendering. `BLOCKED` is derived from the plan and execution
+ * events (waiting on upstream dependencies), not emitted as an engine status.
+ * `SKIPPED` is the post-failure "unexecuted/disabled" visual state.
+ */
+export declare enum GraphVisualState {
+    IDLE = "idle",
+    RUNNING = "running",
+    BLOCKED = "blocked",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed",
+    SKIPPED = "skipped"
+}
+/**
+ * Namespace root for graph run SSE topics (DECAF-48 §4.2). A subscription
+ * filters on these granular topics before `observer.next(...)`.
+ */
+export declare const GRAPH_RUN_TOPIC = "graph.run";
+/**
+ * SSE sub-topic streaming per-node log lines during a run.
+ */
+export declare const GRAPH_RUN_LOG_TOPIC = "graph.run.log";
+/**
+ * SSE sub-topic streaming node/edge execution-state updates during a run.
+ */
+export declare const GRAPH_RUN_STATE_TOPIC = "graph.run.state";
+/**
+ * Logger custom-attribute keys attached to every run log line via
+ * DECAF-9 `logger.for({...})` (DECAF-48 §4.3). Rendered as discrete columns
+ * (not buried in the message string).
+ */
+export declare enum GraphLogAttribute {
+    NODE_ID = "nodeId",
+    WORKFLOW_ID = "workflowId",
+    RUN_ID = "runId",
+    USER = "user"
+}
+/**
+ * Namespace topic helper for a graph execution event.
+ *
+ * Log-carrier events resolve to `graph.run.log`; node/edge execution-state
+ * events resolve to `graph.run.state`; everything else stays under the shared
+ * `graph.run` topic and is only delivered to subscribers that match it.
+ *
+ * @param eventType - The graph execution event type to scope to a topic.
+ * @returns The SSE topic constant for the given event type.
+ */
+export declare function graphRunTopicOf(eventType: GraphExecutionEventType): string;
+/**
+ * Event types emitted through the graph execution observer pipeline.
+ *
+ * DECAF-48 extends this set with the visual-state and run-log event types the
+ * engine emits on the existing Observable: {@link GraphExecutionEventType.NODE_STATE_CHANGED},
+ * {@link GraphExecutionEventType.EDGE_STATE_CHANGED} and
+ * {@link GraphExecutionEventType.GRAPH_RUN_LOG}.
+ */
+export declare enum GraphExecutionEventType {
+    WORKFLOW_STARTED = "workflow.started",
+    WORKFLOW_PLANNED = "workflow.planned",
+    WORKFLOW_COMPLETED = "workflow.completed",
+    WORKFLOW_FAILED = "workflow.failed",
+    WORKFLOW_CANCELLED = "workflow.cancelled",
+    NODE_QUEUED = "node.queued",
+    NODE_STARTED = "node.started",
+    NODE_OUTPUT = "node.output",
+    NODE_COMPLETED = "node.completed",
+    NODE_FAILED = "node.failed",
+    NODE_SKIPPED = "node.skipped",
+    NODE_CACHE_HIT = "node.cacheHit",
+    NODE_PINNED = "node.pinned",
+    NODE_UNPINNED = "node.unpinned",
+    /** Node execution-state transition carrying a `GraphNodeStateChangedPayload` (DECAF-48 §4.4). */
+    NODE_STATE_CHANGED = "node.stateChanged",
+    EDGE_VALUE_ROUTED = "edge.valueRouted",
+    /** Edge execution-state transition carrying a `GraphEdgeStateChangedPayload` (DECAF-48 §4.4). */
+    EDGE_STATE_CHANGED = "edge.stateChanged",
+    /** Structured run log line carrying a `GraphRunLogEntry` (DECAF-48 §4.3). */
+    GRAPH_RUN_LOG = "graph.run.log",
+    LOOP_STARTED = "loop.started",
+    LOOP_ITERATION_STARTED = "loop.iteration.started",
+    LOOP_ITERATION_COMPLETED = "loop.iteration.completed",
+    LOOP_CONDITION_EVALUATED = "loop.condition.evaluated",
+    LOOP_COMPLETED = "loop.completed",
+    LOOP_LIMIT_REACHED = "loop.limitReached",
+    VALIDATION_STARTED = "validation.started",
+    VALIDATION_FAILED = "validation.failed",
+    VALIDATION_COMPLETED = "validation.completed",
+    STORE_READ = "store.read",
+    STORE_WRITE = "store.write",
+    STORE_DELETE = "store.delete"
+}
+/**
+ * Hard limits for the graph run subsystem (DECAF-50 §4.14/§4.16).
+ *
+ * Enforced by the run executor and the HTTP run controller; every omitted
+ * field falls back to {@link DEFAULT_GRAPH_RUN_LIMITS}.
+ */
+export interface GraphRunLimits {
+    /** Maximum serialised JSON size accepted for a run create request. */
+    maxRequestBytes?: number;
+    /**
+     * Maximum number of runs in flight per caller: the run's owner user, or
+     * the caller-key bucket supplied by the HTTP layer for anonymous callers
+     * (per-IP where the host exposes it, a shared `"anonymous"` bucket
+     * otherwise).
+     */
+    maxConcurrentRuns?: number;
+    /** Maximum events retained per run by the in-memory event store. */
+    maxEventsPerRun?: number;
+    /** Maximum serialised size of a single event envelope `payload`. */
+    maxEventPayloadBytes?: number;
+    /** Hard wall-clock budget for a run's engine execution. */
+    executionTimeoutMs?: number;
+    /**
+     * How long a terminal run's replayable event state is kept after the run
+     * finishes before being released (SAA-595 resource governance).
+     */
+    eventReplayWindowMs?: number;
+}
+/** Default run limits: request size, per-caller concurrency, event retention/payload size, execution timeout, and post-terminal event replay window. */
+export declare const DEFAULT_GRAPH_RUN_LIMITS: Required<GraphRunLimits>;
+/**
+ * Terminal graph event types closing a run's SSE stream
+ * (DECAF-50 §4.15). The run SSE endpoint never emits anything after these.
+ */
+export declare const GRAPH_RUN_TERMINAL_EVENT_TYPES: readonly GraphExecutionEventType[];
+/** Whether the event type is a run-stream terminal type (see {@link GRAPH_RUN_TERMINAL_EVENT_TYPES}). */
+export declare function isGraphRunTerminalEventType(type: GraphExecutionEventType): boolean;
+/** Whether the run status is terminal (`succeeded`, `failed`, or `cancelled`). */
+export declare function isGraphRunTerminalStatus(status: GraphRunStatus): boolean;
+/** Type guard for {@link GraphRunStatus}. */
+export declare function isGraphRunStatus(value: unknown): value is GraphRunStatus;

package/lib/types/graph/index.d.cts

@@ -9,4 +9,7 @@ export * from "./reader.d.cts";
 export * from "./document/index.d.cts";
 export * from "./catalog/index.d.cts";
 export * from "./types.d.cts";
+export * from "./GraphExecutionStateMapper.d.cts";
+export * from "./GraphResolution.d.cts";
+export * from "./nodes/index.d.cts";
 export * from "./overrides/index.d.cts";

package/lib/types/graph/index.d.mts

@@ -9,4 +9,7 @@ export * from "./reader.d.mts";
 export * from "./document/index.d.mts";
 export * from "./catalog/index.d.mts";
 export * from "./types.d.mts";
+export * from "./GraphExecutionStateMapper.d.mts";
+export * from "./GraphResolution.d.mts";
+export * from "./nodes/index.d.mts";
 export * from "./overrides/index.d.mts";