@decaf-ts/integrations 0.10.8 → 0.12.0

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

@@ -1,75 +0,0 @@
-/**
- * @module integrations/graph/engine/runs/GraphRunExecutor
- * @summary Asynchronous graph run execution (DECAF-50 §4.16).
- * @description Schedules runs against the {@link GraphExecutionEngine},
- * mirrors engine events into the run's sequenced SSE stream, enforces run
- * timeouts via per-run `AbortController`s, and finalizes the run's terminal
- * state in the run store. Exactly one execution per `runId` — repeated
- * schedules await the same completion promise.
- */
-import type { Context, MaybeContextualArg } from "@decaf-ts/core";
-import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
-import { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
-import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.mts";
-import { GraphRunEventPublisher } from "./GraphRunEventPublisher.d.mts";
-import { type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
-import { type GraphRun, type GraphRunStore } from "./types.d.mts";
-/** Why a run was aborted: explicit user cancellation or run timeout. */
-export type GraphRunAbortReason = "user" | "timeout";
-/** Lifecycle hooks observed by {@link GraphRunExecutor} when a run completes. */
-export interface GraphRunExecutionHooks {
-    /** Called once a run reaches a terminal state, with its result when successful. */
-    onRunCompleted?: (run: GraphRun, result?: GraphExecutionResult) => Promise<void>;
-}
-/**
- * Resolves the canonical document (and its fingerprint) a run executes,
- * accepting an optional Decaf {@link Context} as leading argument.
- */
-export type GraphRunDocumentProvider = (...args: MaybeContextualArg<Context>) => Promise<{
-    document: GraphWorkflowDocument;
-    fingerprint: string;
-}>;
-/**
- * Executes graph runs asynchronously (DECAF-50 §4.16): schedules a run
- * against the {@link GraphExecutionEngine}, mirrors engine events into the
- * run's sequenced SSE stream, enforces run timeouts via per-run
- * `AbortController`s, and finalizes the run's terminal state in the run
- * store. Exactly one execution per `runId` — repeated schedules await the
- * same completion promise.
- */
-export declare class GraphRunExecutor {
-    private readonly engine;
-    private readonly runStore;
-    private readonly publisher;
-    private readonly limits;
-    private readonly hooks;
-    private readonly controllers;
-    private readonly completions;
-    private readonly timeouts;
-    constructor(engine: GraphExecutionEngine, runStore: GraphRunStore, publisher: GraphRunEventPublisher, hooks?: GraphRunExecutionHooks, limits?: GraphRunLimits);
-    /** Returns (creating if needed) the run's `AbortController`. */
-    begin(runId: string): AbortController;
-    /** Aborts the run, if it is still in flight. Returns whether an abort was issued. */
-    abort(runId: string, reason: GraphRunAbortReason): boolean;
-    /** Whether the run's abort signal has fired. */
-    isAborted(runId: string): boolean;
-    /** The run's abort reason, when aborted. */
-    abortReason(runId: string): GraphRunAbortReason | undefined;
-    /** The run's in-flight completion promise, when one is scheduled. */
-    waitFor(runId: string): Promise<GraphRun> | undefined;
-    /**
-     * Schedules the run for execution and returns its completion promise
-     * (deduplicated per `runId`). Engine events are mirrored to the run's SSE
-     * stream; failures still emit a terminal event and finalize the run as
-     * `failed`.
-     */
-    schedule(run: GraphRun, documentProvider: GraphRunDocumentProvider, inputs: GraphExecutionValues, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
-    /** Releases all per-run state (controller, completion, timeout, publisher sequencing). */
-    release(runId: string): void;
-    private armTimeout;
-    private runExecution;
-    private emitTerminal;
-    private finalize;
-    private persist;
-    private envelopeOf;
-}

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

@@ -1,8 +0,0 @@
-import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
-/**
- * Computes a stable SHA-256 fingerprint of a canonical
- * {@link GraphWorkflowDocument}: object keys are sorted and `undefined`
- * values skipped, so documents that serialize identically always produce the
- * same fingerprint regardless of key insertion order.
- */
-export declare function graphRunDocumentFingerprint(document: GraphWorkflowDocument): string;

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

@@ -1,8 +0,0 @@
-import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
-/**
- * Computes a stable SHA-256 fingerprint of a canonical
- * {@link GraphWorkflowDocument}: object keys are sorted and `undefined`
- * values skipped, so documents that serialize identically always produce the
- * same fingerprint regardless of key insertion order.
- */
-export declare function graphRunDocumentFingerprint(document: GraphWorkflowDocument): string;

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

@@ -1,93 +0,0 @@
-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

@@ -1,93 +0,0 @@
-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

@@ -1,28 +0,0 @@
-/**
- * @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

@@ -1,28 +0,0 @@
-/**
- * @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

@@ -1,12 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,25 +0,0 @@
-/**
- * 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

@@ -1,25 +0,0 @@
-/**
- * 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

@@ -1,83 +0,0 @@
-/**
- * @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

@@ -1,83 +0,0 @@
-/**
- * @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/snapshots/GraphExecutionSnapshotMapper.d.cts

@@ -1,10 +0,0 @@
-import type { GraphExecutionResult, GraphExecutionSnapshotPatch } from "../types.d.cts";
-/**
- * Maps a {@link GraphExecutionResult} to a {@link GraphExecutionSnapshotPatch}.
- */
-export declare class GraphExecutionSnapshotMapper {
-    /**
-     * Creates a snapshot patch from an execution result.
-     */
-    map(result: GraphExecutionResult): GraphExecutionSnapshotPatch;
-}

package/lib/types/graph/engine/snapshots/GraphExecutionSnapshotMapper.d.mts

@@ -1,10 +0,0 @@
-import type { GraphExecutionResult, GraphExecutionSnapshotPatch } from "../types.d.mts";
-/**
- * Maps a {@link GraphExecutionResult} to a {@link GraphExecutionSnapshotPatch}.
- */
-export declare class GraphExecutionSnapshotMapper {
-    /**
-     * Creates a snapshot patch from an execution result.
-     */
-    map(result: GraphExecutionResult): GraphExecutionSnapshotPatch;
-}

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

@@ -1,6 +0,0 @@
-/**
- * @module integrations/graph/snapshots
- * @summary Graph execution snapshot mapping.
- * @description Re-exports the snapshot patch mapper.
- */
-export * from "./GraphExecutionSnapshotMapper.d.cts";

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

@@ -1,6 +0,0 @@
-/**
- * @module integrations/graph/snapshots
- * @summary Graph execution snapshot mapping.
- * @description Re-exports the snapshot patch mapper.
- */
-export * from "./GraphExecutionSnapshotMapper.d.mts";