@decaf-ts/integrations 0.8.0 → 0.9.0

package/lib/types/graph/engine/runs/GraphRunService.d.cts

@@ -0,0 +1,93 @@
+import type { Context, MaybeContextualArg } from "@decaf-ts/core";
+import { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import { type GraphRunEventEnvelope, type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import { type GraphRun, type GraphRunCreateRequest, type GraphRunDocumentResolver, type GraphRunEventStore, type GraphRunStore } from "./types.d.cts";
+/** Construction options for {@link GraphRunService}. */
+export interface GraphRunServiceOptions {
+    /** Run limits (timeouts, event payload caps, concurrency); defaults from {@link DEFAULT_GRAPH_RUN_LIMITS}. */
+    limits?: GraphRunLimits;
+    /** Resolves saved workflow documents for by-`workflowId` run requests. */
+    documentResolver?: GraphRunDocumentResolver;
+    /** Called once per run when it reaches a terminal state. */
+    onRunCompleted?: (run: GraphRun, result?: GraphRun["result"]) => Promise<void>;
+    /**
+     * Explicit DECAF-48 §4.15 standalone tolerance: when `true`, anonymous
+     * callers (no resolved identity) are tolerated on owned runs. Defaults to
+     * `false` — ownership checks fail closed for absent identities (SAA-595).
+     */
+    allowAnonymousAccess?: boolean;
+}
+/**
+ * Run lifecycle service (DECAF-50 §4.16): creates, tracks, cancels, and
+ * observes graph runs on top of a {@link GraphRunStore} and
+ * {@link GraphRunEventStore}. Enforces per-caller run limits (concurrency
+ * buckets keyed by owner or caller key, timeout, event payload size), scopes
+ * every read/cancel to the owning user, auto-releases retained event state
+ * after the configured replay window (SAA-595), and exposes the sequenced
+ * event stream the SSE controller replays.
+ */
+export declare class GraphRunService {
+    private readonly engine;
+    private readonly runStore;
+    private readonly eventStore;
+    private readonly publisher;
+    private readonly executor;
+    private readonly options;
+    private readonly activeByCaller;
+    private readonly callerKeysByRun;
+    private readonly releaseTimers;
+    constructor(engine: GraphExecutionEngine, runStore: GraphRunStore, eventStore: GraphRunEventStore, options?: GraphRunServiceOptions);
+    /** Effective run limits, with defaults applied. */
+    get limits(): Required<GraphRunLimits>;
+    /**
+     * Creates and schedules a run for a saved `workflowId` or an inline
+     * workflow document, enforcing the per-caller concurrency limit and
+     * ownership bookkeeping. Returns the queued run immediately; execution
+     * continues in the background.
+     *
+     * `concurrencyKey` buckets anonymous callers for the per-caller
+     * concurrency cap (e.g. a per-IP key from the HTTP layer); it defaults to
+     * the owner user, or `"anonymous"` when both are absent.
+     *
+     * @throws ValidationError when the request carries no workflow identity, a
+     * `workflowId` without a configured resolver, or the per-caller concurrency
+     * limit is exhausted.
+     */
+    createRun(request: GraphRunCreateRequest, ownerUser: string | null, concurrencyKey?: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /** Reads a run, asserting it belongs to `ownerUser`. */
+    getRun(runId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /**
+     * Cancels a non-terminal run: aborts in-flight execution and persists the
+     * `cancelled` status. Terminal runs are returned unchanged.
+     */
+    cancelRun(runId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /** Lists a run's event envelopes after the given sequence (ownership-checked). */
+    listEvents(runId: string, afterSequence: number, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphRunEventEnvelope[]>;
+    /** Subscribes a live listener to a run's event stream (ownership-checked); returns an unsubscribe function. */
+    subscribeEvents(runId: string, ownerUser: string | null, listener: (event: GraphRunEventEnvelope) => void, ...args: MaybeContextualArg<Context>): Promise<() => void>;
+    /** Subscribes a listener to a run's event stream without re-reading the run. */
+    subscribeRunEvents(run: GraphRun, listener: (event: GraphRunEventEnvelope) => void): () => void;
+    /** Waits for a scheduled run to finish, then returns its final state. */
+    waitForRun(runId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /**
+     * Convenience helper: creates a run and waits for its completion. The
+     * optional `concurrencyKey` is forwarded to {@link createRun} to bucket
+     * anonymous callers for the per-caller concurrency cap.
+     */
+    executeAndWait(request: GraphRunCreateRequest, ownerUser: string | null, concurrencyKey?: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /**
+     * Releases all per-run bookkeeping for a finished run: caller-bucket
+     * membership, executor state, publisher sequencing, retained event state,
+     * and any pending auto-release timer.
+     */
+    release(runId: string): void;
+    /**
+     * Removes a run from its caller's concurrency bucket and schedules event
+     * state release after the configured replay window.
+     */
+    private finishActiveRun;
+    private validateCreateRequest;
+    private documentProviderFor;
+    private assertOwnership;
+    private generateRunId;
+}

package/lib/types/graph/engine/runs/GraphRunService.d.mts

@@ -0,0 +1,93 @@
+import type { Context, MaybeContextualArg } from "@decaf-ts/core";
+import { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import { type GraphRunEventEnvelope, type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import { type GraphRun, type GraphRunCreateRequest, type GraphRunDocumentResolver, type GraphRunEventStore, type GraphRunStore } from "./types.d.mts";
+/** Construction options for {@link GraphRunService}. */
+export interface GraphRunServiceOptions {
+    /** Run limits (timeouts, event payload caps, concurrency); defaults from {@link DEFAULT_GRAPH_RUN_LIMITS}. */
+    limits?: GraphRunLimits;
+    /** Resolves saved workflow documents for by-`workflowId` run requests. */
+    documentResolver?: GraphRunDocumentResolver;
+    /** Called once per run when it reaches a terminal state. */
+    onRunCompleted?: (run: GraphRun, result?: GraphRun["result"]) => Promise<void>;
+    /**
+     * Explicit DECAF-48 §4.15 standalone tolerance: when `true`, anonymous
+     * callers (no resolved identity) are tolerated on owned runs. Defaults to
+     * `false` — ownership checks fail closed for absent identities (SAA-595).
+     */
+    allowAnonymousAccess?: boolean;
+}
+/**
+ * Run lifecycle service (DECAF-50 §4.16): creates, tracks, cancels, and
+ * observes graph runs on top of a {@link GraphRunStore} and
+ * {@link GraphRunEventStore}. Enforces per-caller run limits (concurrency
+ * buckets keyed by owner or caller key, timeout, event payload size), scopes
+ * every read/cancel to the owning user, auto-releases retained event state
+ * after the configured replay window (SAA-595), and exposes the sequenced
+ * event stream the SSE controller replays.
+ */
+export declare class GraphRunService {
+    private readonly engine;
+    private readonly runStore;
+    private readonly eventStore;
+    private readonly publisher;
+    private readonly executor;
+    private readonly options;
+    private readonly activeByCaller;
+    private readonly callerKeysByRun;
+    private readonly releaseTimers;
+    constructor(engine: GraphExecutionEngine, runStore: GraphRunStore, eventStore: GraphRunEventStore, options?: GraphRunServiceOptions);
+    /** Effective run limits, with defaults applied. */
+    get limits(): Required<GraphRunLimits>;
+    /**
+     * Creates and schedules a run for a saved `workflowId` or an inline
+     * workflow document, enforcing the per-caller concurrency limit and
+     * ownership bookkeeping. Returns the queued run immediately; execution
+     * continues in the background.
+     *
+     * `concurrencyKey` buckets anonymous callers for the per-caller
+     * concurrency cap (e.g. a per-IP key from the HTTP layer); it defaults to
+     * the owner user, or `"anonymous"` when both are absent.
+     *
+     * @throws ValidationError when the request carries no workflow identity, a
+     * `workflowId` without a configured resolver, or the per-caller concurrency
+     * limit is exhausted.
+     */
+    createRun(request: GraphRunCreateRequest, ownerUser: string | null, concurrencyKey?: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /** Reads a run, asserting it belongs to `ownerUser`. */
+    getRun(runId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /**
+     * Cancels a non-terminal run: aborts in-flight execution and persists the
+     * `cancelled` status. Terminal runs are returned unchanged.
+     */
+    cancelRun(runId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /** Lists a run's event envelopes after the given sequence (ownership-checked). */
+    listEvents(runId: string, afterSequence: number, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphRunEventEnvelope[]>;
+    /** Subscribes a live listener to a run's event stream (ownership-checked); returns an unsubscribe function. */
+    subscribeEvents(runId: string, ownerUser: string | null, listener: (event: GraphRunEventEnvelope) => void, ...args: MaybeContextualArg<Context>): Promise<() => void>;
+    /** Subscribes a listener to a run's event stream without re-reading the run. */
+    subscribeRunEvents(run: GraphRun, listener: (event: GraphRunEventEnvelope) => void): () => void;
+    /** Waits for a scheduled run to finish, then returns its final state. */
+    waitForRun(runId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /**
+     * Convenience helper: creates a run and waits for its completion. The
+     * optional `concurrencyKey` is forwarded to {@link createRun} to bucket
+     * anonymous callers for the per-caller concurrency cap.
+     */
+    executeAndWait(request: GraphRunCreateRequest, ownerUser: string | null, concurrencyKey?: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /**
+     * Releases all per-run bookkeeping for a finished run: caller-bucket
+     * membership, executor state, publisher sequencing, retained event state,
+     * and any pending auto-release timer.
+     */
+    release(runId: string): void;
+    /**
+     * Removes a run from its caller's concurrency bucket and schedules event
+     * state release after the configured replay window.
+     */
+    private finishActiveRun;
+    private validateCreateRequest;
+    private documentProviderFor;
+    private assertOwnership;
+    private generateRunId;
+}

package/lib/types/graph/engine/runs/InMemoryGraphRunEventStore.d.cts

@@ -0,0 +1,28 @@
+/**
+ * @module integrations/graph/engine/runs/InMemoryGraphRunEventStore
+ * @summary In-memory reference run event store.
+ * @description Non-persistent {@link GraphRunEventStore} backed by per-run
+ * arrays: appends notify live subscribers, `listAfter` serves SSE replays,
+ * and retention keeps at most `maxEventsPerRun` envelopes per run — evicting
+ * non-terminal events first so terminal outcomes are never dropped.
+ */
+import type { GraphRunEventEnvelope } from "@decaf-ts/ui-decorators/graph";
+import type { GraphRunEventStore } from "./types.d.cts";
+import { type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Non-persistent {@link GraphRunEventStore} backed by per-run arrays:
+ * appends notify live subscribers, `listAfter` serves SSE replays, and
+ * retention keeps at most `maxEventsPerRun` envelopes per run — evicting
+ * non-terminal events first so terminal outcomes are never dropped.
+ */
+export declare class InMemoryGraphRunEventStore implements GraphRunEventStore {
+    private readonly events;
+    private readonly listeners;
+    private readonly limits;
+    constructor(limits?: GraphRunLimits);
+    append(event: GraphRunEventEnvelope): Promise<void>;
+    listAfter(runId: string, sequence: number): Promise<GraphRunEventEnvelope[]>;
+    subscribe(runId: string, listener: (event: GraphRunEventEnvelope) => void): () => void;
+    release(runId: string): void;
+    private enforceRetention;
+}

package/lib/types/graph/engine/runs/InMemoryGraphRunEventStore.d.mts

@@ -0,0 +1,28 @@
+/**
+ * @module integrations/graph/engine/runs/InMemoryGraphRunEventStore
+ * @summary In-memory reference run event store.
+ * @description Non-persistent {@link GraphRunEventStore} backed by per-run
+ * arrays: appends notify live subscribers, `listAfter` serves SSE replays,
+ * and retention keeps at most `maxEventsPerRun` envelopes per run — evicting
+ * non-terminal events first so terminal outcomes are never dropped.
+ */
+import type { GraphRunEventEnvelope } from "@decaf-ts/ui-decorators/graph";
+import type { GraphRunEventStore } from "./types.d.mts";
+import { type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Non-persistent {@link GraphRunEventStore} backed by per-run arrays:
+ * appends notify live subscribers, `listAfter` serves SSE replays, and
+ * retention keeps at most `maxEventsPerRun` envelopes per run — evicting
+ * non-terminal events first so terminal outcomes are never dropped.
+ */
+export declare class InMemoryGraphRunEventStore implements GraphRunEventStore {
+    private readonly events;
+    private readonly listeners;
+    private readonly limits;
+    constructor(limits?: GraphRunLimits);
+    append(event: GraphRunEventEnvelope): Promise<void>;
+    listAfter(runId: string, sequence: number): Promise<GraphRunEventEnvelope[]>;
+    subscribe(runId: string, listener: (event: GraphRunEventEnvelope) => void): () => void;
+    release(runId: string): void;
+    private enforceRetention;
+}

package/lib/types/graph/engine/runs/InMemoryGraphRunStore.d.cts

@@ -0,0 +1,12 @@
+import type { GraphRun, GraphRunStore } from "./types.d.cts";
+/**
+ * Non-persistent {@link GraphRunStore} backed by a `Map`: serves tests and
+ * in-process deployments. Runs are cloned on save/read so callers never
+ * share mutable references with the store.
+ */
+export declare class InMemoryGraphRunStore implements GraphRunStore {
+    private readonly runs;
+    saveRun(run: GraphRun): Promise<void>;
+    readRun(runId: string): Promise<GraphRun | null>;
+    release(runId: string): void;
+}

package/lib/types/graph/engine/runs/InMemoryGraphRunStore.d.mts

@@ -0,0 +1,12 @@
+import type { GraphRun, GraphRunStore } from "./types.d.mts";
+/**
+ * Non-persistent {@link GraphRunStore} backed by a `Map`: serves tests and
+ * in-process deployments. Runs are cloned on save/read so callers never
+ * share mutable references with the store.
+ */
+export declare class InMemoryGraphRunStore implements GraphRunStore {
+    private readonly runs;
+    saveRun(run: GraphRun): Promise<void>;
+    readRun(runId: string): Promise<GraphRun | null>;
+    release(runId: string): void;
+}

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

@@ -0,0 +1,8 @@
+export * from "./types.d.cts";
+export * from "./ownership.d.cts";
+export * from "./GraphRunFingerprint.d.cts";
+export * from "./InMemoryGraphRunEventStore.d.cts";
+export * from "./InMemoryGraphRunStore.d.cts";
+export * from "./GraphRunEventPublisher.d.cts";
+export * from "./GraphRunExecutor.d.cts";
+export * from "./GraphRunService.d.cts";

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

@@ -0,0 +1,8 @@
+export * from "./types.d.mts";
+export * from "./ownership.d.mts";
+export * from "./GraphRunFingerprint.d.mts";
+export * from "./InMemoryGraphRunEventStore.d.mts";
+export * from "./InMemoryGraphRunStore.d.mts";
+export * from "./GraphRunEventPublisher.d.mts";
+export * from "./GraphRunExecutor.d.mts";
+export * from "./GraphRunService.d.mts";

package/lib/types/graph/engine/runs/ownership.d.cts

@@ -0,0 +1,25 @@
+/**
+ * Centralized graph resource ownership check (SAA-595 security hardening).
+ *
+ * Fail-closed by default: a resource that carries an owner is only accessible
+ * to that owner; an absent caller identity is denied unless the explicit
+ * `allowAnonymousAccess` tolerance (DECAF-48 §4.15 standalone runs) is set.
+ * Owner-less resources remain accessible to everyone.
+ *
+ * @param resource - The guarded resource (or its persisted record); only its
+ *   `owner` member is read. `null`/`undefined` counts as owner-less.
+ * @param callerOwner - Identity of the caller resolved from the request
+ *   context; `null`/`undefined`/`""` represent anonymous callers.
+ * @param options - `resourceKind`/`resourceId` name the resource in the
+ *   denial message; `allowAnonymousAccess` opts in to the DECAF-48 §4.15
+ *   standalone tolerance (default `false`).
+ * @throws ForbiddenError when the resource is owned and the caller is a
+ *   different user, or an anonymous caller without the explicit tolerance.
+ */
+export declare function assertGraphResourceOwnership(resource: {
+    owner?: string | null;
+} | null | undefined, callerOwner: string | null | undefined, options: {
+    allowAnonymousAccess?: boolean;
+    resourceKind: string;
+    resourceId: string;
+}): void;

package/lib/types/graph/engine/runs/ownership.d.mts

@@ -0,0 +1,25 @@
+/**
+ * Centralized graph resource ownership check (SAA-595 security hardening).
+ *
+ * Fail-closed by default: a resource that carries an owner is only accessible
+ * to that owner; an absent caller identity is denied unless the explicit
+ * `allowAnonymousAccess` tolerance (DECAF-48 §4.15 standalone runs) is set.
+ * Owner-less resources remain accessible to everyone.
+ *
+ * @param resource - The guarded resource (or its persisted record); only its
+ *   `owner` member is read. `null`/`undefined` counts as owner-less.
+ * @param callerOwner - Identity of the caller resolved from the request
+ *   context; `null`/`undefined`/`""` represent anonymous callers.
+ * @param options - `resourceKind`/`resourceId` name the resource in the
+ *   denial message; `allowAnonymousAccess` opts in to the DECAF-48 §4.15
+ *   standalone tolerance (default `false`).
+ * @throws ForbiddenError when the resource is owned and the caller is a
+ *   different user, or an anonymous caller without the explicit tolerance.
+ */
+export declare function assertGraphResourceOwnership(resource: {
+    owner?: string | null;
+} | null | undefined, callerOwner: string | null | undefined, options: {
+    allowAnonymousAccess?: boolean;
+    resourceKind: string;
+    resourceId: string;
+}): void;

package/lib/types/graph/engine/runs/types.d.cts

@@ -0,0 +1,83 @@
+/**
+ * @module integrations/graph/engine/runs/types
+ * @summary Graph run lifecycle contracts (engine side).
+ * @description Engine-scoped run contracts for the lifecycle subsystem
+ * (DECAF-50 §4.14–§4.16). The frontend-safe run wire contract —
+ * `GraphRunStatus`, `GraphRunEventEnvelope`, `GraphRunEventEnvelopeInput`
+ * and the run limits/terminal predicates — lives in
+ * `@decaf-ts/ui-decorators/graph` (imported from there).
+ *
+ * Engine-only contracts: the full {@link GraphRun} shape (whose `result?`
+ * carries engine dates) and the run store/event-store/create-request/
+ * document-resolver ports.
+ */
+import type { Context, MaybeContextualArg } from "@decaf-ts/core";
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.cts";
+import type { GraphExecutionErrorPayload } from "@decaf-ts/ui-decorators/graph";
+import type { GraphRunEventEnvelope, GraphRunStatus } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Engine-side run record (DECAF-50 §4.14): lifecycle status, timestamps, and
+ * — once terminal — the execution result, error payload, and the fingerprint
+ * of the document the run executed.
+ */
+export interface GraphRun {
+    /** Unique run id. */
+    runId: string;
+    /** Workflow (document) id the run executes. */
+    workflowId: string;
+    /** Owning user; `null` for anonymous callers. */
+    ownerUser: string | null;
+    /** Current lifecycle status. */
+    status: GraphRunStatus;
+    /** ISO timestamp when the run was created. */
+    createdAt: string;
+    /** ISO timestamp when execution started, once it has. */
+    startedAt?: string;
+    /** ISO timestamp when the run reached a terminal state. */
+    finishedAt?: string;
+    /** Execution result, present on successful completion. */
+    result?: GraphExecutionResult;
+    /** Structured error payload, present on failure. */
+    error?: GraphExecutionErrorPayload;
+    /** Fingerprint of the executed document (stable SHA-256). */
+    documentFingerprint?: string;
+}
+/**
+ * Persistence port for run records: durable implementations save/read runs
+ * with an optional leading Decaf {@link Context}.
+ */
+export interface GraphRunEventStore {
+    /** Appends a sequenced event envelope and notifies live subscribers. */
+    append(event: GraphRunEventEnvelope): Promise<void>;
+    /** Returns the run's envelopes with `sequence` greater than the given one (SSE replay). */
+    listAfter(runId: string, sequence: number): Promise<GraphRunEventEnvelope[]>;
+    /**
+     * Subscribes a live listener to the run's stream; returns an unsubscribe function.
+     */
+    subscribe(runId: string, listener: (event: GraphRunEventEnvelope) => void): () => void;
+    /**
+     * Releases all retained event state for a finished run (after the replay
+     * window). Optional: in-memory stores implement it; durable stores may
+     * no-op or keep events for audit.
+     */
+    release?(runId: string): void;
+}
+/** Persistence port for run records: save and read {@link GraphRun}s by id, with optional leading {@link Context}. */
+export interface GraphRunStore {
+    saveRun(run: GraphRun, ...args: MaybeContextualArg<Context>): Promise<void>;
+    readRun(runId: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun | null>;
+}
+/** A run-creation request: an inline workflow document, or a saved `workflowId` plus optional input values. */
+export interface GraphRunCreateRequest {
+    /** Inline workflow document to execute. */
+    workflow?: GraphWorkflowDocument;
+    /** Saved workflow id to execute (requires a document resolver). */
+    workflowId?: string;
+    /** Input values bound to the workflow's input ports. */
+    inputs?: GraphExecutionValues;
+}
+/** Resolves a saved workflow document by id for by-`workflowId` run requests. */
+export interface GraphRunDocumentResolver {
+    resolve(workflowId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
+}

package/lib/types/graph/engine/runs/types.d.mts

@@ -0,0 +1,83 @@
+/**
+ * @module integrations/graph/engine/runs/types
+ * @summary Graph run lifecycle contracts (engine side).
+ * @description Engine-scoped run contracts for the lifecycle subsystem
+ * (DECAF-50 §4.14–§4.16). The frontend-safe run wire contract —
+ * `GraphRunStatus`, `GraphRunEventEnvelope`, `GraphRunEventEnvelopeInput`
+ * and the run limits/terminal predicates — lives in
+ * `@decaf-ts/ui-decorators/graph` (imported from there).
+ *
+ * Engine-only contracts: the full {@link GraphRun} shape (whose `result?`
+ * carries engine dates) and the run store/event-store/create-request/
+ * document-resolver ports.
+ */
+import type { Context, MaybeContextualArg } from "@decaf-ts/core";
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.mts";
+import type { GraphExecutionErrorPayload } from "@decaf-ts/ui-decorators/graph";
+import type { GraphRunEventEnvelope, GraphRunStatus } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Engine-side run record (DECAF-50 §4.14): lifecycle status, timestamps, and
+ * — once terminal — the execution result, error payload, and the fingerprint
+ * of the document the run executed.
+ */
+export interface GraphRun {
+    /** Unique run id. */
+    runId: string;
+    /** Workflow (document) id the run executes. */
+    workflowId: string;
+    /** Owning user; `null` for anonymous callers. */
+    ownerUser: string | null;
+    /** Current lifecycle status. */
+    status: GraphRunStatus;
+    /** ISO timestamp when the run was created. */
+    createdAt: string;
+    /** ISO timestamp when execution started, once it has. */
+    startedAt?: string;
+    /** ISO timestamp when the run reached a terminal state. */
+    finishedAt?: string;
+    /** Execution result, present on successful completion. */
+    result?: GraphExecutionResult;
+    /** Structured error payload, present on failure. */
+    error?: GraphExecutionErrorPayload;
+    /** Fingerprint of the executed document (stable SHA-256). */
+    documentFingerprint?: string;
+}
+/**
+ * Persistence port for run records: durable implementations save/read runs
+ * with an optional leading Decaf {@link Context}.
+ */
+export interface GraphRunEventStore {
+    /** Appends a sequenced event envelope and notifies live subscribers. */
+    append(event: GraphRunEventEnvelope): Promise<void>;
+    /** Returns the run's envelopes with `sequence` greater than the given one (SSE replay). */
+    listAfter(runId: string, sequence: number): Promise<GraphRunEventEnvelope[]>;
+    /**
+     * Subscribes a live listener to the run's stream; returns an unsubscribe function.
+     */
+    subscribe(runId: string, listener: (event: GraphRunEventEnvelope) => void): () => void;
+    /**
+     * Releases all retained event state for a finished run (after the replay
+     * window). Optional: in-memory stores implement it; durable stores may
+     * no-op or keep events for audit.
+     */
+    release?(runId: string): void;
+}
+/** Persistence port for run records: save and read {@link GraphRun}s by id, with optional leading {@link Context}. */
+export interface GraphRunStore {
+    saveRun(run: GraphRun, ...args: MaybeContextualArg<Context>): Promise<void>;
+    readRun(runId: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun | null>;
+}
+/** A run-creation request: an inline workflow document, or a saved `workflowId` plus optional input values. */
+export interface GraphRunCreateRequest {
+    /** Inline workflow document to execute. */
+    workflow?: GraphWorkflowDocument;
+    /** Saved workflow id to execute (requires a document resolver). */
+    workflowId?: string;
+    /** Input values bound to the workflow's input ports. */
+    inputs?: GraphExecutionValues;
+}
+/** Resolves a saved workflow document by id for by-`workflowId` run requests. */
+export interface GraphRunDocumentResolver {
+    resolve(workflowId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
+}

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

@@ -5,13 +5,13 @@
  * types (`ExprValue`, `ConditionExpression`, `CodeCondition`,
  * `SwitchCaseCondition`, `SwitchCase`, `SwitchNodeMetadata`,
  * `NodeMetadataChange`, `GraphExecutionEvent`, `GraphExecutionErrorPayload`)
- * live in `../shared/types`; engine modules import shared symbols from there
- * and engine-private symbols from here.
+ * live in `@decaf-ts/ui-decorators/graph`; engine modules import shared
+ * symbols from there and engine-private symbols from here.
  */
-import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionStatus } from "../shared/constants.d.cts";
-import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "../shared/types.d.cts";
-export type { GraphExecutionErrorPayload, GraphExecutionEvent, } from "../shared/types.d.cts";
+import type { GraphCredentialReference, GraphJsonValue, GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionStatus } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Unique identifier for a single graph execution run.
  */
@@ -49,6 +49,7 @@ export interface GraphExecutionOptions {
     usePinnedValues?: boolean;
     writeThroughCache?: boolean;
     metadata?: Record<string, unknown>;
+    abortSignal?: AbortSignal;
 }
 /**
  * Result of executing a single node.
@@ -67,13 +68,16 @@ export interface GraphNodeExecutionResult {
 }
 /**
  * Result of executing an entire workflow.
+ *
+ * The executed source of truth is the canonical {@link GraphWorkflowDocument}
+ * (never a decorated workflow definition).
  */
 export interface GraphExecutionResult {
     runId: GraphRunId;
     parentRunId?: GraphRunId;
     workflowId: GraphWorkflowId;
     status: GraphExecutionStatus;
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     inputs: GraphExecutionValues;
     outputs: GraphExecutionValues;
     nodeResults: Record<GraphNodeId, GraphNodeExecutionResult>;
@@ -82,14 +86,34 @@ export interface GraphExecutionResult {
     finishedAt?: Date;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Credential references resolved for a node execution (DECAF-50 §4.9/§4.16).
+ * Documents carry references only; secret material never enters the request.
+ */
+export type GraphResolvedCredentials = Record<string, GraphCredentialReference>;
+/**
+ * Request passed to request-based node executors (DECAF-50 §4.9).
+ * Configuration (`parameters`, `credentials`, `metadata`) and input data
+ * (`inputs`) are separated.
+ */
+export interface GraphNodeExecutionRequest {
+    nodeId: string;
+    kind: string;
+    inputs: GraphExecutionValues;
+    parameters: Record<string, GraphJsonValue>;
+    credentials: GraphResolvedCredentials;
+    metadata?: Record<string, GraphJsonValue>;
+}
 /**
  * Options used to construct a {@link GraphExecutionContext}.
  */
 export interface GraphExecutionContextOptions {
     runId: GraphRunId;
     parentRunId?: GraphRunId;
-    workflow: GraphWorkflowDefinition;
-    node: GraphNodeDefinition;
+    workflowId: GraphWorkflowId;
+    document: GraphWorkflowDocument;
+    node: GraphNodeInstance;
+    manifest: GraphResolvedNodeManifest;
     path: string[];
     metadata?: Record<string, unknown>;
 }
@@ -97,7 +121,8 @@ export interface GraphExecutionContextOptions {
  * Metadata describing a loop node's behaviour.
  */
 export interface GraphLoopMetadata {
-    body: GraphWorkflowDefinition | unknown;
+    /** The nested loop-body workflow document (DECAF-50 §4.9). */
+    body: GraphWorkflowDocument;
     maxIterations?: number;
     timeoutMs?: number;
     condition?: GraphConditionDefinition;
@@ -142,7 +167,7 @@ export interface GraphPinningMetadata {
  * Options for pinning a node after a completed run.
  */
 export interface GraphPinNodeOptions {
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     plan: unknown;
     result: GraphExecutionResult;
     nodeId: string;
@@ -153,7 +178,7 @@ export interface GraphPinNodeOptions {
  * Options for unpinning a node.
  */
 export interface GraphUnpinNodeOptions {
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     nodeId: string;
     fingerprint: string;
     namespace?: string;