@decaf-ts/ui-decorators 0.20.4 → 0.20.6

package/lib/esm/graph/nodes/utility/return.js

@@ -0,0 +1,52 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/**
+ * @module ui-decorators/graph/nodes/utility/return
+ * @summary Return utility node declaration (DECAF-32 §22.2.2).
+ * @description Return — defines and normalises the final workflow output.
+ */
+import { Model, model, required } from "@decaf-ts/decorator-validation";
+import { uielement } from "./../../../ui/decorators.js";
+import { input, node, output } from "./../../decorators.js";
+// Ensure category styles are registered (idempotent).
+import "./../category-styles.js";
+let ReturnFlowNode = class ReturnFlowNode extends Model {
+};
+__decorate([
+    required(),
+    uielement("textarea", { label: "Input value", placeholder: "Value to normalise" }),
+    input({ handle: "value" }),
+    __metadata("design:type", Object)
+], ReturnFlowNode.prototype, "value", void 0);
+__decorate([
+    required(),
+    uielement("input", { label: "Returned output", placeholder: "Normalised output" }),
+    output({ handle: "result" }),
+    __metadata("design:type", Object)
+], ReturnFlowNode.prototype, "result", void 0);
+ReturnFlowNode = __decorate([
+    node("core.flow.return", {
+        kind: "core.flow.return",
+        category: "Utility",
+        color: "#22c55e",
+        icon: "ti-arrow-back-up",
+        width: 96,
+        height: 96,
+        labels: ["flow", "return", "output"],
+        metadata: {
+            title: "Return",
+            description: "Normalises the input into the final workflow output object.",
+            outputSchema: {},
+        },
+    }),
+    model()
+], ReturnFlowNode);
+export { ReturnFlowNode };
+//# sourceMappingURL=return.js.map

package/lib/esm/graph/nodes/utility/return.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"return.js","sourceRoot":"","sources":["../../../../../src/graph/nodes/utility/return.ts"],"names":[],"mappings":";;;;;;;;;AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,oCAA+B;AACnD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,8BAAyB;AAEvD,sDAAsD;AACtD,iCAA4B;AAiBrB,IAAM,cAAc,GAApB,MAAM,cAAe,SAAQ,KAAK;CAUxC,CAAA;AANC;IAHC,QAAQ,EAAE;IACV,SAAS,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAC;IAClF,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;;6CACX;AAKhB;IAHC,QAAQ,EAAE;IACV,SAAS,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,mBAAmB,EAAE,CAAC;IAClF,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;;8CACZ;AATN,cAAc;IAf1B,IAAI,CAAC,kBAAkB,EAAE;QACxB,IAAI,EAAE,kBAAkB;QACxB,QAAQ,EAAE,SAAS;QACnB,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC;QACpC,QAAQ,EAAE;YACR,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,6DAA6D;YAC1E,YAAY,EAAE,EAAE;SACjB;KACF,CAAC;IACD,KAAK,EAAE;GACK,cAAc,CAU1B"}

package/lib/esm/graph/nodes/utility/utility-log.js

@@ -0,0 +1,57 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/**
+ * @module ui-decorators/graph/nodes/utility/utility-log
+ * @summary Utility Log node declaration (DECAF-48 §4.3).
+ * @description Utility Log — logs the input value through the run's
+ * `ctx.logger` at a configurable level and forwards it unchanged on the
+ * `logged` output port.
+ */
+import { Model, model, required } from "@decaf-ts/decorator-validation";
+import { uielement } from "./../../../ui/decorators.js";
+import { input, node, output } from "./../../decorators.js";
+// Ensure category styles are registered (idempotent).
+import "./../category-styles.js";
+let UtilityLogNode = class UtilityLogNode extends Model {
+};
+__decorate([
+    required(),
+    uielement("textarea", { label: "Input value", placeholder: "Value to log" }),
+    input({ handle: "value" }),
+    __metadata("design:type", Object)
+], UtilityLogNode.prototype, "value", void 0);
+__decorate([
+    uielement("input", { label: "Log level", placeholder: "info, warn, error, ..." }),
+    __metadata("design:type", String)
+], UtilityLogNode.prototype, "level", void 0);
+__decorate([
+    required(),
+    uielement("input", { label: "Logged value", placeholder: "Forwarded value" }),
+    output({ handle: "logged" }),
+    __metadata("design:type", Object)
+], UtilityLogNode.prototype, "logged", void 0);
+UtilityLogNode = __decorate([
+    node("core.utility.log", {
+        kind: "core.utility.log",
+        category: "Utility",
+        color: "#6366f1",
+        icon: "ti-terminal",
+        width: 96,
+        height: 96,
+        labels: ["utility", "log", "debug", "observability"],
+        metadata: {
+            title: "Utility Log",
+            description: "Logs the input value to the run's ctx.logger at a configurable level and forwards it unchanged.",
+        },
+    }),
+    model()
+], UtilityLogNode);
+export { UtilityLogNode };
+//# sourceMappingURL=utility-log.js.map

package/lib/esm/graph/nodes/utility/utility-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utility-log.js","sourceRoot":"","sources":["../../../../../src/graph/nodes/utility/utility-log.ts"],"names":[],"mappings":";;;;;;;;;AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,oCAA+B;AACnD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,8BAAyB;AAGvD,sDAAsD;AACtD,iCAA4B;AAgBrB,IAAM,cAAc,GAApB,MAAM,cAAe,SAAQ,KAAK;CAaxC,CAAA;AATC;IAHC,QAAQ,EAAE;IACV,SAAS,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC;IAC5E,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;;6CACX;AAGhB;IADC,SAAS,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,wBAAwB,EAAE,CAAC;;6CAC7D;AAKrB;IAHC,QAAQ,EAAE;IACV,SAAS,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,CAAC;IAC7E,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;;8CACZ;AAZN,cAAc;IAd1B,IAAI,CAAC,kBAAkB,EAAE;QACxB,IAAI,EAAE,kBAAkB;QACxB,QAAQ,EAAE,SAAS;QACnB,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC;QACpD,QAAQ,EAAE;YACR,KAAK,EAAE,aAAa;YACpB,WAAW,EAAE,iGAAiG;SAC/G;KACF,CAAC;IACD,KAAK,EAAE;GACK,cAAc,CAa1B"}

package/lib/esm/index.js

@@ -16,21 +16,21 @@ export * from "./ui/index.js";
  * @const VERSION
  * @memberOf module:ui-decorators
  */
-export const VERSION = "0.20.4";
+export const VERSION = "0.20.5";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export const COMMIT = "b1ab2bc";
+export const COMMIT = "4e03aa0";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export const FULL_VERSION = "0.20.4-b1ab2bc";
+export const FULL_VERSION = "0.20.5-4e03aa0";
 export const PACKAGE_NAME = "@decaf-ts/ui-decorators";
 Metadata.registerLibrary(PACKAGE_NAME, VERSION);
 //# sourceMappingURL=index.js.map

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;