@decaf-ts/ui-decorators 0.20.4 → 0.20.6

package/lib/cjs/graph/nodes/utility/utility-log.cjs

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UtilityLogNode = void 0;
+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.
+ */
+const decorator_validation_1 = require("@decaf-ts/decorator-validation");
+const decorators_js_1 = require("./../../../ui/decorators.cjs");
+const decorators_js_2 = require("./../../decorators.cjs");
+// Ensure category styles are registered (idempotent).
+require("./../category-styles.cjs");
+let UtilityLogNode = class UtilityLogNode extends decorator_validation_1.Model {
+};
+exports.UtilityLogNode = UtilityLogNode;
+__decorate([
+    (0, decorator_validation_1.required)(),
+    (0, decorators_js_1.uielement)("textarea", { label: "Input value", placeholder: "Value to log" }),
+    (0, decorators_js_2.input)({ handle: "value" }),
+    __metadata("design:type", Object)
+], UtilityLogNode.prototype, "value", void 0);
+__decorate([
+    (0, decorators_js_1.uielement)("input", { label: "Log level", placeholder: "info, warn, error, ..." }),
+    __metadata("design:type", String)
+], UtilityLogNode.prototype, "level", void 0);
+__decorate([
+    (0, decorator_validation_1.required)(),
+    (0, decorators_js_1.uielement)("input", { label: "Logged value", placeholder: "Forwarded value" }),
+    (0, decorators_js_2.output)({ handle: "logged" }),
+    __metadata("design:type", Object)
+], UtilityLogNode.prototype, "logged", void 0);
+exports.UtilityLogNode = UtilityLogNode = __decorate([
+    (0, decorators_js_2.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.",
+        },
+    }),
+    (0, decorator_validation_1.model)()
+], UtilityLogNode);
+//# sourceMappingURL=utility-log.js.map
+//# sourceMappingURL=utility-log.cjs.map

package/lib/cjs/graph/nodes/utility/utility-log.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph/nodes/utility/utility-log.cjs","sourceRoot":"","sources":["graph/nodes/utility/utility-log.js"],"names":[],"mappings":"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"}

package/lib/cjs/index.cjs

@@ -33,21 +33,21 @@ __exportStar(require("./ui/index.cjs"), exports);
  * @const VERSION
  * @memberOf module:ui-decorators
  */
-exports.VERSION = "0.20.4";
+exports.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
  */
-exports.COMMIT = "b1ab2bc";
+exports.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
  */
-exports.FULL_VERSION = "0.20.4-b1ab2bc";
+exports.FULL_VERSION = "0.20.5-4e03aa0";
 exports.PACKAGE_NAME = "@decaf-ts/ui-decorators";
 decoration_1.Metadata.registerLibrary(exports.PACKAGE_NAME, exports.VERSION);
 //# sourceMappingURL=index.js.map

package/lib/esm/graph/GraphExecutionStateMapper.js

@@ -0,0 +1,91 @@
+import { GraphExecutionEventType, GraphExecutionStatus, GraphVisualState, } from "./constants.js";
+/**
+ * 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 function mapExecutionStatus(status) {
+    switch (status) {
+        case GraphExecutionStatus.RUNNING:
+            return GraphVisualState.RUNNING;
+        case GraphExecutionStatus.SUCCEEDED:
+        case GraphExecutionStatus.CACHED:
+            return GraphVisualState.SUCCEEDED;
+        case GraphExecutionStatus.FAILED:
+            return GraphVisualState.FAILED;
+        case GraphExecutionStatus.SKIPPED:
+            return GraphVisualState.SKIPPED;
+        case GraphExecutionStatus.PENDING:
+        case GraphExecutionStatus.PLANNING:
+        case GraphExecutionStatus.CANCELLED:
+        default:
+            return GraphVisualState.IDLE;
+    }
+}
+/**
+ * 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 function deriveNodeVisualState(options) {
+    if (options.running)
+        return GraphVisualState.RUNNING;
+    if (options.failed)
+        return GraphVisualState.FAILED;
+    if (options.executed && options.succeeded !== false) {
+        return options.succeeded
+            ? GraphVisualState.SUCCEEDED
+            : GraphVisualState.FAILED;
+    }
+    const upstream = options.upstreamCount ?? 0;
+    const completed = options.completedUpstreams ?? 0;
+    if (upstream > 0 && completed < upstream)
+        return GraphVisualState.BLOCKED;
+    if (options.runFailed)
+        return GraphVisualState.SKIPPED;
+    return GraphVisualState.IDLE;
+}
+/**
+ * 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 function visualStateOfEvent(event) {
+    if (event.status)
+        return mapExecutionStatus(event.status);
+    const payloadState = event.payload
+        ?.state;
+    if (payloadState)
+        return payloadState;
+    switch (event.type) {
+        case GraphExecutionEventType.NODE_STARTED:
+        case GraphExecutionEventType.EDGE_STATE_CHANGED:
+        case GraphExecutionEventType.NODE_STATE_CHANGED:
+            return GraphVisualState.RUNNING;
+        case GraphExecutionEventType.NODE_COMPLETED:
+            return GraphVisualState.SUCCEEDED;
+        case GraphExecutionEventType.NODE_FAILED:
+            return GraphVisualState.FAILED;
+        case GraphExecutionEventType.NODE_SKIPPED:
+            return GraphVisualState.SKIPPED;
+        default:
+            return GraphVisualState.IDLE;
+    }
+}
+//# sourceMappingURL=GraphExecutionStateMapper.js.map

package/lib/esm/graph/GraphExecutionStateMapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphExecutionStateMapper.js","sourceRoot":"","sources":["../../../src/graph/GraphExecutionStateMapper.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,GACjB,uBAAoB;AAErB;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA6B;IAE7B,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,oBAAoB,CAAC,OAAO;YAC/B,OAAO,gBAAgB,CAAC,OAAO,CAAC;QAClC,KAAK,oBAAoB,CAAC,SAAS,CAAC;QACpC,KAAK,oBAAoB,CAAC,MAAM;YAC9B,OAAO,gBAAgB,CAAC,SAAS,CAAC;QACpC,KAAK,oBAAoB,CAAC,MAAM;YAC9B,OAAO,gBAAgB,CAAC,MAAM,CAAC;QACjC,KAAK,oBAAoB,CAAC,OAAO;YAC/B,OAAO,gBAAgB,CAAC,OAAO,CAAC;QAClC,KAAK,oBAAoB,CAAC,OAAO,CAAC;QAClC,KAAK,oBAAoB,CAAC,QAAQ,CAAC;QACnC,KAAK,oBAAoB,CAAC,SAAS,CAAC;QACpC;YACE,OAAO,gBAAgB,CAAC,IAAI,CAAC;IACjC,CAAC;AACH,CAAC;AAwBD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAmC;IAEnC,IAAI,OAAO,CAAC,OAAO;QAAE,OAAO,gBAAgB,CAAC,OAAO,CAAC;IACrD,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,gBAAgB,CAAC,MAAM,CAAC;IACnD,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;QACpD,OAAO,OAAO,CAAC,SAAS;YACtB,CAAC,CAAC,gBAAgB,CAAC,SAAS;YAC5B,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,OAAO,CAAC,kBAAkB,IAAI,CAAC,CAAC;IAClD,IAAI,QAAQ,GAAG,CAAC,IAAI,SAAS,GAAG,QAAQ;QAAE,OAAO,gBAAgB,CAAC,OAAO,CAAC;IAC1E,IAAI,OAAO,CAAC,SAAS;QAAE,OAAO,gBAAgB,CAAC,OAAO,CAAC;IACvD,OAAO,gBAAgB,CAAC,IAAI,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA0B;IAC3D,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAI,KAAK,CAAC,OAAoD;QAC9E,EAAE,KAAK,CAAC;IACV,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,uBAAuB,CAAC,YAAY,CAAC;QAC1C,KAAK,uBAAuB,CAAC,kBAAkB,CAAC;QAChD,KAAK,uBAAuB,CAAC,kBAAkB;YAC7C,OAAO,gBAAgB,CAAC,OAAO,CAAC;QAClC,KAAK,uBAAuB,CAAC,cAAc;YACzC,OAAO,gBAAgB,CAAC,SAAS,CAAC;QACpC,KAAK,uBAAuB,CAAC,WAAW;YACtC,OAAO,gBAAgB,CAAC,MAAM,CAAC;QACjC,KAAK,uBAAuB,CAAC,YAAY;YACvC,OAAO,gBAAgB,CAAC,OAAO,CAAC;QAClC;YACE,OAAO,gBAAgB,CAAC,IAAI,CAAC;IACjC,CAAC;AACH,CAAC"}

package/lib/esm/graph/GraphResolution.js

@@ -0,0 +1,13 @@
+/** Structural type guard for `GraphResolvedNodeManifest`. */
+export function isGraphResolvedNodeManifest(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (typeof record["kind"] === "string" &&
+        typeof record["display"] === "object" &&
+        record["display"] !== null &&
+        Array.isArray(record["inputs"]) &&
+        Array.isArray(record["outputs"]) &&
+        Array.isArray(record["parameters"]));
+}
+//# sourceMappingURL=GraphResolution.js.map

package/lib/esm/graph/GraphResolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphResolution.js","sourceRoot":"","sources":["../../../src/graph/GraphResolution.ts"],"names":[],"mappings":"AAoDA,6DAA6D;AAC7D,MAAM,UAAU,2BAA2B,CACzC,KAAc;IAEd,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9E,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,CACL,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,QAAQ;QAClC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,QAAQ;QACrC,MAAM,CAAC,SAAS,CAAC,KAAK,IAAI;QAC1B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAChC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CACpC,CAAC;AACJ,CAAC"}

package/lib/esm/graph/constants.js

@@ -89,4 +89,183 @@ export function resolveEffectiveIcon(explicitIcon, category) {
         return explicitIcon;
     return graphCategoryStyleOf(category).icon ?? GRAPH_DEFAULT_CATEGORY_STYLE.icon;
 }
+/**
+ * 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 const GRAPH_DISABLED_NODE_BEHAVIORS = [
+    "skip",
+    "passThroughFirstInput",
+    "emitDefaults",
+];
+/** The disabled-node behavior applied when a node declares none. */
+export const GRAPH_DEFAULT_DISABLED_NODE_BEHAVIOR = "skip";
+/** Type guard for {@link GraphDisabledNodeBehavior}. */
+export function isGraphDisabledNodeBehavior(value) {
+    return GRAPH_DISABLED_NODE_BEHAVIORS.includes(value);
+}
+/**
+ * Execution status for a workflow or individual node.
+ */
+export var GraphExecutionStatus;
+(function (GraphExecutionStatus) {
+    GraphExecutionStatus["PENDING"] = "pending";
+    GraphExecutionStatus["PLANNING"] = "planning";
+    GraphExecutionStatus["RUNNING"] = "running";
+    GraphExecutionStatus["SUCCEEDED"] = "succeeded";
+    GraphExecutionStatus["FAILED"] = "failed";
+    GraphExecutionStatus["SKIPPED"] = "skipped";
+    GraphExecutionStatus["CANCELLED"] = "cancelled";
+    GraphExecutionStatus["CACHED"] = "cached";
+})(GraphExecutionStatus || (GraphExecutionStatus = {}));
+/**
+ * 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 var GraphVisualState;
+(function (GraphVisualState) {
+    GraphVisualState["IDLE"] = "idle";
+    GraphVisualState["RUNNING"] = "running";
+    GraphVisualState["BLOCKED"] = "blocked";
+    GraphVisualState["SUCCEEDED"] = "succeeded";
+    GraphVisualState["FAILED"] = "failed";
+    GraphVisualState["SKIPPED"] = "skipped";
+})(GraphVisualState || (GraphVisualState = {}));
+/**
+ * Namespace root for graph run SSE topics (DECAF-48 §4.2). A subscription
+ * filters on these granular topics before `observer.next(...)`.
+ */
+export const GRAPH_RUN_TOPIC = "graph.run";
+/**
+ * SSE sub-topic streaming per-node log lines during a run.
+ */
+export const GRAPH_RUN_LOG_TOPIC = `${GRAPH_RUN_TOPIC}.log`;
+/**
+ * SSE sub-topic streaming node/edge execution-state updates during a run.
+ */
+export const GRAPH_RUN_STATE_TOPIC = `${GRAPH_RUN_TOPIC}.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 var GraphLogAttribute;
+(function (GraphLogAttribute) {
+    GraphLogAttribute["NODE_ID"] = "nodeId";
+    GraphLogAttribute["WORKFLOW_ID"] = "workflowId";
+    GraphLogAttribute["RUN_ID"] = "runId";
+    GraphLogAttribute["USER"] = "user";
+})(GraphLogAttribute || (GraphLogAttribute = {}));
+/**
+ * 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 function graphRunTopicOf(eventType) {
+    switch (eventType) {
+        case GraphExecutionEventType.GRAPH_RUN_LOG:
+            return GRAPH_RUN_LOG_TOPIC;
+        case GraphExecutionEventType.NODE_STATE_CHANGED:
+        case GraphExecutionEventType.EDGE_STATE_CHANGED:
+            return GRAPH_RUN_STATE_TOPIC;
+        default:
+            return GRAPH_RUN_TOPIC;
+    }
+}
+/**
+ * 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 var GraphExecutionEventType;
+(function (GraphExecutionEventType) {
+    GraphExecutionEventType["WORKFLOW_STARTED"] = "workflow.started";
+    GraphExecutionEventType["WORKFLOW_PLANNED"] = "workflow.planned";
+    GraphExecutionEventType["WORKFLOW_COMPLETED"] = "workflow.completed";
+    GraphExecutionEventType["WORKFLOW_FAILED"] = "workflow.failed";
+    GraphExecutionEventType["WORKFLOW_CANCELLED"] = "workflow.cancelled";
+    GraphExecutionEventType["NODE_QUEUED"] = "node.queued";
+    GraphExecutionEventType["NODE_STARTED"] = "node.started";
+    GraphExecutionEventType["NODE_OUTPUT"] = "node.output";
+    GraphExecutionEventType["NODE_COMPLETED"] = "node.completed";
+    GraphExecutionEventType["NODE_FAILED"] = "node.failed";
+    GraphExecutionEventType["NODE_SKIPPED"] = "node.skipped";
+    GraphExecutionEventType["NODE_CACHE_HIT"] = "node.cacheHit";
+    GraphExecutionEventType["NODE_PINNED"] = "node.pinned";
+    GraphExecutionEventType["NODE_UNPINNED"] = "node.unpinned";
+    /** Node execution-state transition carrying a `GraphNodeStateChangedPayload` (DECAF-48 §4.4). */
+    GraphExecutionEventType["NODE_STATE_CHANGED"] = "node.stateChanged";
+    GraphExecutionEventType["EDGE_VALUE_ROUTED"] = "edge.valueRouted";
+    /** Edge execution-state transition carrying a `GraphEdgeStateChangedPayload` (DECAF-48 §4.4). */
+    GraphExecutionEventType["EDGE_STATE_CHANGED"] = "edge.stateChanged";
+    /** Structured run log line carrying a `GraphRunLogEntry` (DECAF-48 §4.3). */
+    GraphExecutionEventType["GRAPH_RUN_LOG"] = "graph.run.log";
+    GraphExecutionEventType["LOOP_STARTED"] = "loop.started";
+    GraphExecutionEventType["LOOP_ITERATION_STARTED"] = "loop.iteration.started";
+    GraphExecutionEventType["LOOP_ITERATION_COMPLETED"] = "loop.iteration.completed";
+    GraphExecutionEventType["LOOP_CONDITION_EVALUATED"] = "loop.condition.evaluated";
+    GraphExecutionEventType["LOOP_COMPLETED"] = "loop.completed";
+    GraphExecutionEventType["LOOP_LIMIT_REACHED"] = "loop.limitReached";
+    GraphExecutionEventType["VALIDATION_STARTED"] = "validation.started";
+    GraphExecutionEventType["VALIDATION_FAILED"] = "validation.failed";
+    GraphExecutionEventType["VALIDATION_COMPLETED"] = "validation.completed";
+    GraphExecutionEventType["STORE_READ"] = "store.read";
+    GraphExecutionEventType["STORE_WRITE"] = "store.write";
+    GraphExecutionEventType["STORE_DELETE"] = "store.delete";
+})(GraphExecutionEventType || (GraphExecutionEventType = {}));
+/** Default run limits: request size, per-caller concurrency, event retention/payload size, execution timeout, and post-terminal event replay window. */
+export const DEFAULT_GRAPH_RUN_LIMITS = {
+    maxRequestBytes: 4_000_000,
+    maxConcurrentRuns: 32,
+    maxEventsPerRun: 10_000,
+    maxEventPayloadBytes: 256_000,
+    executionTimeoutMs: 600_000,
+    eventReplayWindowMs: 300_000,
+};
+/**
+ * Terminal graph event types closing a run's SSE stream
+ * (DECAF-50 §4.15). The run SSE endpoint never emits anything after these.
+ */
+export const GRAPH_RUN_TERMINAL_EVENT_TYPES = [
+    GraphExecutionEventType.WORKFLOW_COMPLETED,
+    GraphExecutionEventType.WORKFLOW_FAILED,
+    GraphExecutionEventType.WORKFLOW_CANCELLED,
+];
+/** Whether the event type is a run-stream terminal type (see {@link GRAPH_RUN_TERMINAL_EVENT_TYPES}). */
+export function isGraphRunTerminalEventType(type) {
+    return GRAPH_RUN_TERMINAL_EVENT_TYPES.includes(type);
+}
+/** Whether the run status is terminal (`succeeded`, `failed`, or `cancelled`). */
+export function isGraphRunTerminalStatus(status) {
+    return status === "succeeded" || status === "failed" || status === "cancelled";
+}
+/** Type guard for {@link GraphRunStatus}. */
+export function isGraphRunStatus(value) {
+    return (typeof value === "string" &&
+        [
+            "queued",
+            "validating",
+            "running",
+            "succeeded",
+            "failed",
+            "cancelled",
+        ].includes(value));
+}
 //# sourceMappingURL=constants.js.map

package/lib/esm/graph/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/graph/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,SAKX;AALD,WAAY,SAAS;IACnB,4BAAe,CAAA;IACf,gCAAgC,CAAA;IAChC,gCAAgC,CAAA;IAChC,gCAAgC,CAAA;AAClC,CAAC,EALW,SAAS,KAAT,SAAS,QAKpB;AAED,MAAM,CAAN,IAAY,aAIX;AAJD,WAAY,aAAa;IACvB,gCAAe,CAAA;IACf,kCAAiB,CAAA;IACjB,0CAAyB,CAAA;AAC3B,CAAC,EAJW,aAAa,KAAb,aAAa,QAIxB;AA6FD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAElC;IACF,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE;IACpB,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;IAC3C,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;IAC3C,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE;IACzB,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE;IACvC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;CAC3B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAa;IAEb,OAAO,yBAAyB,CAAC,KAAK,CAAC,IAAI,yBAAyB,CAAC,IAAI,CAAC;AAC5E,CAAC;AA2JD;;;;;;;GAOG;AACH,MAAM,6BAA6B,GAAuC,EAAE,CAAC;AAE7E;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAuB;IAC9D,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,YAAY;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAgB,EAChB,KAAyB;IAEzB,6BAA6B,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAiB;IACpD,IAAI,QAAQ,IAAI,6BAA6B,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxD,OAAO,6BAA6B,CAAC,QAAQ,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,4BAA4B,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,aAAsB,EACtB,QAAiB;IAEjB,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,YAAqB,EACrB,QAAiB;IAEjB,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAC,IAAI,IAAI,4BAA4B,CAAC,IAAK,CAAC;AACnF,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/graph/constants.ts"],"names":[],"mappings":"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"}

package/lib/esm/graph/index.js

@@ -9,5 +9,8 @@ export * from "./reader.js";
 export * from "./document/index.js";
 export * from "./catalog/index.js";
 export * from "./types.js";
+export * from "./GraphExecutionStateMapper.js";
+export * from "./GraphResolution.js";
+export * from "./nodes/index.js";
 export * from "./overrides/index.js";
 //# sourceMappingURL=index.js.map

package/lib/esm/graph/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/graph/index.ts"],"names":[],"mappings":"AAAA,iCAAsB;AACtB,8BAAqB;AAErB,+BAA4B;AAC5B,gCAA6B;AAC7B,8BAA2B;AAC3B,qCAA4B;AAC5B,8BAA2B;AAC3B,4BAAyB;AACzB,oCAA2B;AAC3B,mCAA0B;AAC1B,2BAAwB;AACxB,qCAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/graph/index.ts"],"names":[],"mappings":"AAAA,iCAAsB;AACtB,8BAAqB;AAErB,+BAA4B;AAC5B,gCAA6B;AAC7B,8BAA2B;AAC3B,qCAA4B;AAC5B,8BAA2B;AAC3B,4BAAyB;AACzB,oCAA2B;AAC3B,mCAA0B;AAC1B,2BAAwB;AACxB,+CAA4C;AAC5C,qCAAkC;AAClC,iCAAwB;AACxB,qCAA4B"}

package/lib/esm/graph/nodes/agents/agent.js

@@ -0,0 +1,101 @@
+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/agents/agent
+ * @summary Production Agent node declaration.
+ * @description The Agent node is the primary AI agent entrypoint. It is a
+ * rectangular node with `@connection()` ports for its structural
+ * dependencies: `model` (the LLM), `memory` (the memory store), and
+ * `workspace` (the workspace/context). Connections are rendered on the
+ * bottom side of the node (DECAF-32 §21.3). Each connection category has a
+ * distinct color defined in the category style registry.
+ *
+ * The single `prompt` input accepts placeholder expressions (§22.4) such as
+ * `{{ $input.brief }}` or `{{ $node["Research"].output.summary }}` that are
+ * resolved at execution time by the placeholder compiler.
+ */
+import { Model, model, required } from "@decaf-ts/decorator-validation";
+import { uielement } from "./../../../ui/decorators.js";
+import { connection, input, node, output } from "./../../decorators.js";
+// Ensure category styles are registered (idempotent).
+import "./../category-styles.js";
+/**
+ * Agent node — an AI agent that orchestrates a model, memory, and workspace.
+ *
+ * The agent has:
+ * - `@input` port on the **left**: `prompt` (the task prompt; supports
+ *   placeholder expressions like `{{ $input.something }}` per §22.4).
+ * - `@output` ports on the **right**: `response` (the agent's output), `actions`
+ *   (any actions the agent decided to take).
+ * - `@connection` ports on the **bottom**: `model` (LLM), `memory` (memory
+ *   store), `workspace` (workspace/context). Each connection has a distinct
+ *   category color.
+ *
+ * The node is rectangular (not rounded) to visually distinguish it from
+ * regular processing nodes. The `color` and `icon` are omitted from `@node()`
+ * so they are resolved from the `"Agent"` category style.
+ */
+let AgentNode = class AgentNode extends Model {
+};
+__decorate([
+    required(),
+    uielement("textarea", {
+        label: "Prompt",
+        placeholder: "Enter task prompt. Supports placeholders like {{ $input.brief }} or {{ $node[\"Research\"].output.summary }}",
+    }),
+    input({ handle: "prompt" }),
+    __metadata("design:type", String)
+], AgentNode.prototype, "prompt", void 0);
+__decorate([
+    required(),
+    uielement("textarea", { label: "Response", placeholder: "Agent response" }),
+    output({ handle: "response" }),
+    __metadata("design:type", String)
+], AgentNode.prototype, "response", void 0);
+__decorate([
+    required(),
+    uielement("textarea", { label: "Actions", placeholder: "Actions taken by the agent" }),
+    output({ handle: "actions" }),
+    __metadata("design:type", Array)
+], AgentNode.prototype, "actions", void 0);
+__decorate([
+    connection({ category: "model", handle: "model" }),
+    __metadata("design:type", Object)
+], AgentNode.prototype, "model", void 0);
+__decorate([
+    connection({ category: "memory", handle: "memory" }),
+    __metadata("design:type", Object)
+], AgentNode.prototype, "memory", void 0);
+__decorate([
+    connection({ category: "workspace", handle: "workspace" }),
+    __metadata("design:type", Object)
+], AgentNode.prototype, "workspace", void 0);
+AgentNode = __decorate([
+    node("core.agent", {
+        kind: "core.agent",
+        category: "Agent",
+        // color and icon omitted — resolved from the "Agent" category style
+        width: 120,
+        height: 140,
+        labels: ["agent", "ai", "orchestrator"],
+        metadata: {
+            title: "Agent",
+            description: "AI agent that orchestrates a model, memory, and workspace to complete a task.",
+            shape: "rectangle",
+        },
+    }),
+    model()
+], AgentNode);
+export { AgentNode };
+/**
+ * All built-in agent node constructors.
+ */
+export const GRAPH_AGENT_NODES = [AgentNode];
+//# sourceMappingURL=agent.js.map

package/lib/esm/graph/nodes/agents/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../src/graph/nodes/agents/agent.ts"],"names":[],"mappings":";;;;;;;;;AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,oCAA+B;AACnD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,8BAAyB;AAEnE,sDAAsD;AACtD,iCAA4B;AAE5B;;;;;;;;;;;;;;;GAeG;AAgBI,IAAM,SAAS,GAAf,MAAM,SAAU,SAAQ,KAAK;CAiCnC,CAAA;AAxBC;IANC,QAAQ,EAAE;IACV,SAAS,CAAC,UAAU,EAAE;QACrB,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,8GAA8G;KAC5H,CAAC;IACD,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;;yCACZ;AAOhB;IAHC,QAAQ,EAAE;IACV,SAAS,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAC3E,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;;2CACb;AAKlB;IAHC,QAAQ,EAAE;IACV,SAAS,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,4BAA4B,EAAE,CAAC;IACtF,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;;0CACV;AAKpB;IADC,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;;wCACnC;AAGhB;IADC,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;;yCACpC;AAGjB;IADC,UAAU,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;;4CACvC;AAhCT,SAAS;IAfrB,IAAI,CAAC,YAAY,EAAE;QAClB,IAAI,EAAE,YAAY;QAClB,QAAQ,EAAE,OAAO;QACjB,oEAAoE;QACpE,KAAK,EAAE,GAAG;QACV,MAAM,EAAE,GAAG;QACX,MAAM,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,cAAc,CAAC;QACvC,QAAQ,EAAE;YACR,KAAK,EAAE,OAAO;YACd,WAAW,EACT,+EAA+E;YACjF,KAAK,EAAE,WAAW;SACnB;KACF,CAAC;IACD,KAAK,EAAE;GACK,SAAS,CAiCrB;;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,SAAS,CAAU,CAAC"}

package/lib/esm/graph/nodes/base.js

@@ -0,0 +1,31 @@
+/**
+ * @module ui-decorators/graph/nodes/base
+ * @summary Base class for shared graph node declarations.
+ * @description `GraphNode` extends `Model` with an overridable
+ * `applyMetadata` static method. Concrete node kinds that support dynamic
+ * metadata changes (e.g. `SwitchFlowNode` adding case output ports) override
+ * this method to compute their own ports, size, and data patches — the node
+ * is exclusively responsible for itself in every way.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+export class GraphNode extends Model {
+    /**
+     * Applies a metadata patch to this node class, returning the resulting
+     * ports, size, and data patches.
+     *
+     * The default implementation returns `null` (no changes). Concrete node
+     * kinds that support dynamic metadata override this to compute their own
+     * ports and size from the metadata — the caller (renderer) simply relays
+     * the result to the diagram model.
+     *
+     * @param _meta - The metadata patch (node-kind-specific, e.g.
+     *   `SwitchNodeMetadata`).
+     * @returns The computed change, or `null` when the node kind does not
+     *   support dynamic metadata.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    static applyMetadata(_meta) {
+        return null;
+    }
+}
+//# sourceMappingURL=base.js.map

package/lib/esm/graph/nodes/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../src/graph/nodes/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAGvD,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC;;;;;;;;;;;;;OAaG;IACH,6DAA6D;IAC7D,MAAM,CAAC,aAAa,CAAC,KAAc;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/lib/esm/graph/nodes/boundary/input-value.js

@@ -0,0 +1,48 @@
+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/boundary/input-value
+ * @summary Workflow input value boundary node declaration.
+ * @description Shared canvas node representing a workflow input value
+ * (decorator id `graph-input-value-node`), moved from the for-angular
+ * boundary nodes so both sides share the declaration. Reusable value node
+ * whose single `value` output may feed multiple targets.
+ */
+import { Model, model } from "@decaf-ts/decorator-validation";
+import { output, node } from "./../../decorators.js";
+// Ensure category styles are registered (idempotent).
+import "./../category-styles.js";
+let GraphInputValueNode = class GraphInputValueNode extends Model {
+};
+__decorate([
+    output({
+        handle: 'value',
+        connectionRules: {
+            allowMultiple: true,
+        },
+    }),
+    __metadata("design:type", Object)
+], GraphInputValueNode.prototype, "value", void 0);
+GraphInputValueNode = __decorate([
+    node('graph-input-value-node', {
+        kind: 'value',
+        category: 'Boundary',
+        color: '#0f766e',
+        icon: 'ti-circle-plus',
+        labels: ['workflow', 'input', 'value'],
+        metadata: {
+            title: 'Workflow input value',
+            description: 'Reusable canvas value node representing a workflow input.',
+        },
+    }),
+    model()
+], GraphInputValueNode);
+export { GraphInputValueNode };
+//# sourceMappingURL=input-value.js.map

package/lib/esm/graph/nodes/boundary/input-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-value.js","sourceRoot":"","sources":["../../../../../src/graph/nodes/boundary/input-value.ts"],"names":[],"mappings":";;;;;;;;;AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,8BAAyB;AAEhD,sDAAsD;AACtD,iCAA4B;AAcrB,IAAM,mBAAmB,GAAzB,MAAM,mBAAoB,SAAQ,KAAK;CAQ7C,CAAA;AADC;IANC,MAAM,CAAC;QACN,MAAM,EAAE,OAAO;QACf,eAAe,EAAE;YACf,aAAa,EAAE,IAAI;SACpB;KACF,CAAC;;kDACc;AAPL,mBAAmB;IAZ/B,IAAI,CAAC,wBAAwB,EAAE;QAC9B,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,UAAU;QACpB,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC;QACtC,QAAQ,EAAE;YACR,KAAK,EAAE,sBAAsB;YAC7B,WAAW,EAAE,2DAA2D;SACzE;KACF,CAAC;IACD,KAAK,EAAE;GACK,mBAAmB,CAQ/B"}