@decaf-ts/integrations 0.7.0 → 0.9.0

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

@@ -0,0 +1,26 @@
+import { type GraphRunEventEnvelope, type GraphRunEventEnvelopeInput, type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import { type GraphRunEventStore } from "./types.d.mts";
+/**
+ * Sequences and persists run events for the SSE run stream (DECAF-50 §4.16):
+ * assigns a monotonically increasing `sequence` per run, stamps ISO
+ * timestamps, truncates oversized/non-serializable payloads to the
+ * configured limits, and chains appends per run so store writes preserve
+ * publish order.
+ */
+export declare class GraphRunEventPublisher {
+    private readonly store;
+    private readonly limits;
+    private readonly sequences;
+    private readonly chains;
+    constructor(store: GraphRunEventStore, limits?: GraphRunLimits);
+    /**
+     * Assigns the next sequence number for the run, stamps and limits the
+     * payload, and appends the envelope to the store in publish order.
+     */
+    publish(event: GraphRunEventEnvelopeInput): Promise<GraphRunEventEnvelope>;
+    /** Highest sequence number issued for the run (0 when none). */
+    lastSequence(runId: string): number;
+    /** Drops sequencing state for a finished run. */
+    release(runId: string): void;
+    private limitPayload;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * @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.cts";
+import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.cts";
+import { GraphRunEventPublisher } from "./GraphRunEventPublisher.d.cts";
+import { type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import { type GraphRun, type GraphRunStore } from "./types.d.cts";
+/** 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/GraphRunExecutor.d.mts

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

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

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

@@ -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>;
+}