@decaf-ts/integrations 0.8.0 → 0.9.0

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

@@ -0,0 +1,17 @@
+import { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import { GraphNodeCatalogue } from "./GraphNodeCatalogue.d.cts";
+import { type GraphNodeRegistration } from "./GraphNodeRegistration.d.cts";
+/**
+ * Builds the built-in node registrations (DECAF-50 §4.12): every built-in
+ * manifest from {@link GRAPH_BUILT_IN_NODE_MANIFESTS_BY_KIND} that has a
+ * default executor, paired with that executor as a
+ * {@link GraphNodeRegistration}. Engine-bound executors (loops, switch) are
+ * only included when an `engine` is provided.
+ */
+export declare function builtInGraphNodeRegistrations(engine?: GraphExecutionEngine): GraphNodeRegistration[];
+/**
+ * Registers all built-in graph nodes (see
+ * {@link builtInGraphNodeRegistrations}) into the given
+ * {@link GraphNodeCatalogue} and returns it for chaining.
+ */
+export declare function registerBuiltInGraphNodes(catalogue: GraphNodeCatalogue, engine?: GraphExecutionEngine): GraphNodeCatalogue;

package/lib/types/graph/engine/catalog/GraphBuiltInRegistrations.d.mts

@@ -0,0 +1,17 @@
+import { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import { GraphNodeCatalogue } from "./GraphNodeCatalogue.d.mts";
+import { type GraphNodeRegistration } from "./GraphNodeRegistration.d.mts";
+/**
+ * Builds the built-in node registrations (DECAF-50 §4.12): every built-in
+ * manifest from {@link GRAPH_BUILT_IN_NODE_MANIFESTS_BY_KIND} that has a
+ * default executor, paired with that executor as a
+ * {@link GraphNodeRegistration}. Engine-bound executors (loops, switch) are
+ * only included when an `engine` is provided.
+ */
+export declare function builtInGraphNodeRegistrations(engine?: GraphExecutionEngine): GraphNodeRegistration[];
+/**
+ * Registers all built-in graph nodes (see
+ * {@link builtInGraphNodeRegistrations}) into the given
+ * {@link GraphNodeCatalogue} and returns it for chaining.
+ */
+export declare function registerBuiltInGraphNodes(catalogue: GraphNodeCatalogue, engine?: GraphExecutionEngine): GraphNodeCatalogue;

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

@@ -0,0 +1,13 @@
+import { InternalError, NotFoundError } from "@decaf-ts/db-decorators";
+/** Thrown when a node registration or its manifest fails catalogue validation (e.g. invalid ports, unsafe ids, duplicate kinds). */
+export declare class GraphNodeRegistrationError extends InternalError {
+    constructor(msg: string | Error | unknown);
+}
+/** Thrown when a node kind is not registered in the backend catalogue. */
+export declare class GraphNodeNotFoundError extends NotFoundError {
+    constructor(msg: string | Error | unknown);
+}
+/** Thrown when a declared node method is not registered for a node kind. */
+export declare class GraphNodeMethodNotFoundError extends NotFoundError {
+    constructor(msg: string | Error | unknown);
+}

package/lib/types/graph/engine/catalog/GraphCatalogueErrors.d.mts

@@ -0,0 +1,13 @@
+import { InternalError, NotFoundError } from "@decaf-ts/db-decorators";
+/** Thrown when a node registration or its manifest fails catalogue validation (e.g. invalid ports, unsafe ids, duplicate kinds). */
+export declare class GraphNodeRegistrationError extends InternalError {
+    constructor(msg: string | Error | unknown);
+}
+/** Thrown when a node kind is not registered in the backend catalogue. */
+export declare class GraphNodeNotFoundError extends NotFoundError {
+    constructor(msg: string | Error | unknown);
+}
+/** Thrown when a declared node method is not registered for a node kind. */
+export declare class GraphNodeMethodNotFoundError extends NotFoundError {
+    constructor(msg: string | Error | unknown);
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @module integrations/graph/engine/catalog/GraphNodeCatalogue
+ * @summary Trusted backend node catalogue (DECAF-50 §4.10–§4.12).
+ * @description The single registry of node kinds the nine-stage validator
+ * resolves against and the execution engine pulls executors from.
+ * Registrations are validated fail-fast on
+ * {@link GraphNodeCatalogue.register} (manifest serializability, static
+ * ports, parameters, dynamic-port rules, credentials, method declarations)
+ * and manifests are served as JSON-safe clones — never class instances.
+ */
+import type { GraphNodeManifest, GraphNodeMethodManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphCatalogueQueryContext, GraphNodeResolutionContext, GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeMethod, GraphNodeRegistration, GraphNodeRegistrationOptions } from "./GraphNodeRegistration.d.cts";
+/**
+ * Backend-side trusted node catalogue (DECAF-50 §4.10–§4.12): the single
+ * registry of node kinds the nine-stage validator resolves against and the
+ * execution engine pulls executors from. Registrations are validated on
+ * {@link GraphNodeCatalogue.register} (manifest serializability, static
+ * ports, parameters, dynamic-port rules, credentials, method declarations)
+ * and manifests are served as JSON-safe clones — never class instances.
+ * Supports the transition path via
+ * {@link GraphNodeCatalogue.registerExecutor}, which creates placeholder
+ * manifests with lenient policies for legacy executor-only registrations
+ * (removed at cutover, P7).
+ */
+export declare class GraphNodeCatalogue {
+    private readonly entries;
+    private readonly resolver;
+    /**
+     * Validates and registers a node kind. Throws
+     * {@link GraphNodeRegistrationError} on invalid manifests, and on duplicate
+     * kinds unless `options.replace` is set.
+     */
+    register(registration: GraphNodeRegistration, options?: GraphNodeRegistrationOptions): this;
+    /**
+     * Registers an executor for a kind. When the kind has no manifest yet, a
+     * placeholder manifest is created with transition-leniency policies
+     * (`allowUndeclaredParameters`/`allowUnknownOutputs`, DECAF-50 §4.18) that
+     * are removed at cutover (P7).
+     */
+    registerExecutor(kind: string, executor: GraphNodeExecutor): this;
+    /** Removes a kind registration. */
+    unregister(kind: string): this;
+    /** Whether a kind is registered. */
+    has(kind: string): boolean;
+    private entry;
+    /** Returns a JSON-safe clone of the kind's registered manifest. */
+    getManifest(kind: string): GraphNodeManifest;
+    /** Returns the kind's registered executor. */
+    getExecutor(kind: string): GraphNodeExecutor;
+    /** Returns the declared method manifest for a kind, if declared. */
+    getMethodDeclaration(kind: string, method: string): GraphNodeMethodManifest;
+    /** Returns the registered method implementation for a kind. */
+    getMethod(kind: string, method: string): GraphNodeMethod;
+    /** Lists all method declarations registered for a kind. */
+    listMethodDeclarations(kind: string): GraphNodeMethodManifest[];
+    /** Lists registered manifests, optionally filtered by kind and display category. */
+    listManifests(context?: GraphCatalogueQueryContext): GraphNodeManifest[];
+    /** Lists all registered kinds, sorted. */
+    listKinds(): string[];
+    /** Number of registered kinds. */
+    get size(): number;
+    /**
+     * Resolves the effective manifest for a node instance (dynamic ports
+     * expanded, instance context applied) as a
+     * {@link GraphResolvedNodeManifest}.
+     */
+    resolveManifest(kind: string, instance: GraphNodeInstance, context?: GraphNodeResolutionContext): Promise<GraphResolvedNodeManifest>;
+}

package/lib/types/graph/engine/catalog/GraphNodeCatalogue.d.mts

@@ -0,0 +1,71 @@
+/**
+ * @module integrations/graph/engine/catalog/GraphNodeCatalogue
+ * @summary Trusted backend node catalogue (DECAF-50 §4.10–§4.12).
+ * @description The single registry of node kinds the nine-stage validator
+ * resolves against and the execution engine pulls executors from.
+ * Registrations are validated fail-fast on
+ * {@link GraphNodeCatalogue.register} (manifest serializability, static
+ * ports, parameters, dynamic-port rules, credentials, method declarations)
+ * and manifests are served as JSON-safe clones — never class instances.
+ */
+import type { GraphNodeManifest, GraphNodeMethodManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphCatalogueQueryContext, GraphNodeResolutionContext, GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeMethod, GraphNodeRegistration, GraphNodeRegistrationOptions } from "./GraphNodeRegistration.d.mts";
+/**
+ * Backend-side trusted node catalogue (DECAF-50 §4.10–§4.12): the single
+ * registry of node kinds the nine-stage validator resolves against and the
+ * execution engine pulls executors from. Registrations are validated on
+ * {@link GraphNodeCatalogue.register} (manifest serializability, static
+ * ports, parameters, dynamic-port rules, credentials, method declarations)
+ * and manifests are served as JSON-safe clones — never class instances.
+ * Supports the transition path via
+ * {@link GraphNodeCatalogue.registerExecutor}, which creates placeholder
+ * manifests with lenient policies for legacy executor-only registrations
+ * (removed at cutover, P7).
+ */
+export declare class GraphNodeCatalogue {
+    private readonly entries;
+    private readonly resolver;
+    /**
+     * Validates and registers a node kind. Throws
+     * {@link GraphNodeRegistrationError} on invalid manifests, and on duplicate
+     * kinds unless `options.replace` is set.
+     */
+    register(registration: GraphNodeRegistration, options?: GraphNodeRegistrationOptions): this;
+    /**
+     * Registers an executor for a kind. When the kind has no manifest yet, a
+     * placeholder manifest is created with transition-leniency policies
+     * (`allowUndeclaredParameters`/`allowUnknownOutputs`, DECAF-50 §4.18) that
+     * are removed at cutover (P7).
+     */
+    registerExecutor(kind: string, executor: GraphNodeExecutor): this;
+    /** Removes a kind registration. */
+    unregister(kind: string): this;
+    /** Whether a kind is registered. */
+    has(kind: string): boolean;
+    private entry;
+    /** Returns a JSON-safe clone of the kind's registered manifest. */
+    getManifest(kind: string): GraphNodeManifest;
+    /** Returns the kind's registered executor. */
+    getExecutor(kind: string): GraphNodeExecutor;
+    /** Returns the declared method manifest for a kind, if declared. */
+    getMethodDeclaration(kind: string, method: string): GraphNodeMethodManifest;
+    /** Returns the registered method implementation for a kind. */
+    getMethod(kind: string, method: string): GraphNodeMethod;
+    /** Lists all method declarations registered for a kind. */
+    listMethodDeclarations(kind: string): GraphNodeMethodManifest[];
+    /** Lists registered manifests, optionally filtered by kind and display category. */
+    listManifests(context?: GraphCatalogueQueryContext): GraphNodeManifest[];
+    /** Lists all registered kinds, sorted. */
+    listKinds(): string[];
+    /** Number of registered kinds. */
+    get size(): number;
+    /**
+     * Resolves the effective manifest for a node instance (dynamic ports
+     * expanded, instance context applied) as a
+     * {@link GraphResolvedNodeManifest}.
+     */
+    resolveManifest(kind: string, instance: GraphNodeInstance, context?: GraphNodeResolutionContext): Promise<GraphResolvedNodeManifest>;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * @module integrations/graph/engine/catalog/GraphNodeManifestResolver
+ * @summary Manifest resolution against node instances (DECAF-50 §4.11).
+ * @description Expands a manifest's `dynamicPorts` rules against the
+ * instance's parameter values and resolves the effective
+ * {@link GraphResolvedNodeManifest} — static plus expanded dynamic ports,
+ * JSON-safe cloned, with credentials/capabilities/policies/metadata carried
+ * over.
+ */
+import type { GraphJsonValue, GraphNodeManifest, GraphPortManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeResolutionContext, GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedManifestProvider } from "./GraphNodeRegistration.d.cts";
+/** Result of expanding a manifest's dynamic-port rules: concrete input/output/connection ports. */
+export interface GraphDynamicPortResolution {
+    inputs: GraphPortManifest[];
+    outputs: GraphPortManifest[];
+    connections: GraphPortManifest[];
+}
+/**
+ * Expands a manifest's `dynamicPorts` rules (DECAF-50 §4.11) against the
+ * given parameter values — e.g. `repeatFromParameter` turns each array item
+ * into a concrete port with a templated id/label. Static ports are never
+ * duplicated; expanded ports are appended per direction.
+ */
+export declare function resolveGraphDynamicPorts(manifest: Pick<GraphNodeManifest, "dynamicPorts" | "inputs" | "outputs" | "connections">, parameters: Record<string, GraphJsonValue>): GraphDynamicPortResolution;
+/**
+ * Resolves a manifest against parameter values into a
+ * {@link GraphResolvedNodeManifest}: static ports plus expanded dynamic
+ * ports, with credentials/capabilities/policies/metadata carried over. The
+ * result is a JSON-safe clone.
+ */
+export declare function resolveGraphNodeManifest(manifest: GraphNodeManifest, parameters: Record<string, GraphJsonValue>): GraphResolvedNodeManifest;
+/**
+ * Resolves the effective manifest for a node instance. Prefers the
+ * registration's `resolveManifest` provider (validated for shape and JSON
+ * safety) and falls back to static-plus-dynamic resolution via
+ * {@link resolveGraphNodeManifest}.
+ */
+export declare class GraphNodeManifestResolver {
+    resolve(kind: string, manifest: GraphNodeManifest, provider: GraphResolvedManifestProvider | undefined, instance: GraphNodeInstance, context?: GraphNodeResolutionContext): Promise<GraphResolvedNodeManifest>;
+}

package/lib/types/graph/engine/catalog/GraphNodeManifestResolver.d.mts

@@ -0,0 +1,42 @@
+/**
+ * @module integrations/graph/engine/catalog/GraphNodeManifestResolver
+ * @summary Manifest resolution against node instances (DECAF-50 §4.11).
+ * @description Expands a manifest's `dynamicPorts` rules against the
+ * instance's parameter values and resolves the effective
+ * {@link GraphResolvedNodeManifest} — static plus expanded dynamic ports,
+ * JSON-safe cloned, with credentials/capabilities/policies/metadata carried
+ * over.
+ */
+import type { GraphJsonValue, GraphNodeManifest, GraphPortManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeResolutionContext, GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedManifestProvider } from "./GraphNodeRegistration.d.mts";
+/** Result of expanding a manifest's dynamic-port rules: concrete input/output/connection ports. */
+export interface GraphDynamicPortResolution {
+    inputs: GraphPortManifest[];
+    outputs: GraphPortManifest[];
+    connections: GraphPortManifest[];
+}
+/**
+ * Expands a manifest's `dynamicPorts` rules (DECAF-50 §4.11) against the
+ * given parameter values — e.g. `repeatFromParameter` turns each array item
+ * into a concrete port with a templated id/label. Static ports are never
+ * duplicated; expanded ports are appended per direction.
+ */
+export declare function resolveGraphDynamicPorts(manifest: Pick<GraphNodeManifest, "dynamicPorts" | "inputs" | "outputs" | "connections">, parameters: Record<string, GraphJsonValue>): GraphDynamicPortResolution;
+/**
+ * Resolves a manifest against parameter values into a
+ * {@link GraphResolvedNodeManifest}: static ports plus expanded dynamic
+ * ports, with credentials/capabilities/policies/metadata carried over. The
+ * result is a JSON-safe clone.
+ */
+export declare function resolveGraphNodeManifest(manifest: GraphNodeManifest, parameters: Record<string, GraphJsonValue>): GraphResolvedNodeManifest;
+/**
+ * Resolves the effective manifest for a node instance. Prefers the
+ * registration's `resolveManifest` provider (validated for shape and JSON
+ * safety) and falls back to static-plus-dynamic resolution via
+ * {@link resolveGraphNodeManifest}.
+ */
+export declare class GraphNodeManifestResolver {
+    resolve(kind: string, manifest: GraphNodeManifest, provider: GraphResolvedManifestProvider | undefined, instance: GraphNodeInstance, context?: GraphNodeResolutionContext): Promise<GraphResolvedNodeManifest>;
+}

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

@@ -0,0 +1,22 @@
+import type { GraphNodeMethodManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeMethod } from "./GraphNodeRegistration.d.cts";
+/**
+ * Per-kind registry of declared node methods (DECAF-50 §4.12): validates at
+ * construction that every declared method has an implementation and no
+ * implementation exists without a declaration, then serves declarations and
+ * implementations by name.
+ */
+export declare class GraphNodeMethodRegistry {
+    private readonly kind;
+    private readonly declarations;
+    private readonly implementations;
+    constructor(kind: string, declared: GraphNodeMethodManifest[], provided?: Record<string, GraphNodeMethod>);
+    /** Whether a method with the given name is declared. */
+    has(name: string): boolean;
+    /** Returns the method's declaration; throws {@link GraphNodeMethodNotFoundError} when undeclared. */
+    getDeclaration(name: string): GraphNodeMethodManifest;
+    /** Returns the method's implementation (asserting it is declared first). */
+    get(name: string): GraphNodeMethod;
+    /** Lists all declarations, sorted by method name. */
+    list(): GraphNodeMethodManifest[];
+}

package/lib/types/graph/engine/catalog/GraphNodeMethodRegistry.d.mts

@@ -0,0 +1,22 @@
+import type { GraphNodeMethodManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeMethod } from "./GraphNodeRegistration.d.mts";
+/**
+ * Per-kind registry of declared node methods (DECAF-50 §4.12): validates at
+ * construction that every declared method has an implementation and no
+ * implementation exists without a declaration, then serves declarations and
+ * implementations by name.
+ */
+export declare class GraphNodeMethodRegistry {
+    private readonly kind;
+    private readonly declarations;
+    private readonly implementations;
+    constructor(kind: string, declared: GraphNodeMethodManifest[], provided?: Record<string, GraphNodeMethod>);
+    /** Whether a method with the given name is declared. */
+    has(name: string): boolean;
+    /** Returns the method's declaration; throws {@link GraphNodeMethodNotFoundError} when undeclared. */
+    getDeclaration(name: string): GraphNodeMethodManifest;
+    /** Returns the method's implementation (asserting it is declared first). */
+    get(name: string): GraphNodeMethod;
+    /** Lists all declarations, sorted by method name. */
+    list(): GraphNodeMethodManifest[];
+}

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

@@ -0,0 +1,68 @@
+/**
+ * @module integrations/graph/engine/catalog/GraphNodeRegistration
+ * @summary Catalogue registration contracts (DECAF-50 §4.12).
+ * @description The manifest+executor {@link GraphNodeRegistration} pairing
+ * the catalogue registers, the node-method invocation contracts
+ * (`GraphNodeMethodRequest`/`GraphNodeMethodContext`), the
+ * resolved-manifest provider hook, and the `defineGraphNode` /
+ * `declaredGraphNodeMethods` helpers.
+ */
+import type { GraphCredentialReference, GraphJsonValue, GraphNodeManifest, GraphNodeMethodManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphNodeResolutionContext, GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+/** Invocation payload for a catalogue-exposed node method (DECAF-50 §4.12). */
+export interface GraphNodeMethodRequest {
+    /** Node kind owning the method. */
+    kind: string;
+    /** Declared method name. */
+    method: string;
+    /** Node parameter values to invoke with. */
+    parameters: Record<string, GraphJsonValue>;
+    /** Optional method payload. */
+    payload?: GraphJsonValue;
+}
+/** Runtime context handed to a node method implementation. */
+export interface GraphNodeMethodContext {
+    /** Opaque caller request context. */
+    requestContext?: unknown;
+    /** Credential references authorized for the invocation. */
+    credentials?: GraphCredentialReference[];
+    /** Additional metadata. */
+    metadata?: Record<string, GraphJsonValue>;
+}
+/** A catalogue-exposed node method implementation. */
+export type GraphNodeMethod = (request: GraphNodeMethodRequest, context: GraphNodeMethodContext) => Promise<GraphJsonValue>;
+/**
+ * Registration hook that resolves the effective
+ * {@link GraphResolvedNodeManifest} for a node instance (dynamic ports
+ * expanded), overriding the static manifest resolution.
+ */
+export type GraphResolvedManifestProvider = (instance: GraphNodeInstance, context?: GraphNodeResolutionContext) => Promise<GraphResolvedNodeManifest> | GraphResolvedNodeManifest;
+/**
+ * A catalogue registration (DECAF-50 §4.12): the published manifest plus the
+ * executor that runs the node, and optionally declared-method implementations
+ * and a resolved-manifest provider.
+ */
+export interface GraphNodeRegistration {
+    /** Published node manifest. */
+    manifest: GraphNodeManifest;
+    /** Executor that performs the node's work. */
+    executor: GraphNodeExecutor;
+    /** Implementations for the manifest's declared methods. */
+    methods?: Record<string, GraphNodeMethod>;
+    /** Optional dynamic-manifest resolution provider. */
+    resolveManifest?: GraphResolvedManifestProvider;
+}
+/** Options for {@link GraphNodeCatalogue.register}. */
+export interface GraphNodeRegistrationOptions {
+    /** Replace an existing registration for the same kind. */
+    replace?: boolean;
+}
+/**
+ * Identity helper that types a registration payload as a
+ * {@link GraphNodeRegistration} for catalogue registration.
+ */
+export declare function defineGraphNode(registration: GraphNodeRegistration): GraphNodeRegistration;
+/** Returns the method manifests declared by a node manifest. */
+export declare function declaredGraphNodeMethods(manifest: GraphNodeManifest): GraphNodeMethodManifest[];

package/lib/types/graph/engine/catalog/GraphNodeRegistration.d.mts

@@ -0,0 +1,68 @@
+/**
+ * @module integrations/graph/engine/catalog/GraphNodeRegistration
+ * @summary Catalogue registration contracts (DECAF-50 §4.12).
+ * @description The manifest+executor {@link GraphNodeRegistration} pairing
+ * the catalogue registers, the node-method invocation contracts
+ * (`GraphNodeMethodRequest`/`GraphNodeMethodContext`), the
+ * resolved-manifest provider hook, and the `defineGraphNode` /
+ * `declaredGraphNodeMethods` helpers.
+ */
+import type { GraphCredentialReference, GraphJsonValue, GraphNodeManifest, GraphNodeMethodManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphNodeResolutionContext, GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+/** Invocation payload for a catalogue-exposed node method (DECAF-50 §4.12). */
+export interface GraphNodeMethodRequest {
+    /** Node kind owning the method. */
+    kind: string;
+    /** Declared method name. */
+    method: string;
+    /** Node parameter values to invoke with. */
+    parameters: Record<string, GraphJsonValue>;
+    /** Optional method payload. */
+    payload?: GraphJsonValue;
+}
+/** Runtime context handed to a node method implementation. */
+export interface GraphNodeMethodContext {
+    /** Opaque caller request context. */
+    requestContext?: unknown;
+    /** Credential references authorized for the invocation. */
+    credentials?: GraphCredentialReference[];
+    /** Additional metadata. */
+    metadata?: Record<string, GraphJsonValue>;
+}
+/** A catalogue-exposed node method implementation. */
+export type GraphNodeMethod = (request: GraphNodeMethodRequest, context: GraphNodeMethodContext) => Promise<GraphJsonValue>;
+/**
+ * Registration hook that resolves the effective
+ * {@link GraphResolvedNodeManifest} for a node instance (dynamic ports
+ * expanded), overriding the static manifest resolution.
+ */
+export type GraphResolvedManifestProvider = (instance: GraphNodeInstance, context?: GraphNodeResolutionContext) => Promise<GraphResolvedNodeManifest> | GraphResolvedNodeManifest;
+/**
+ * A catalogue registration (DECAF-50 §4.12): the published manifest plus the
+ * executor that runs the node, and optionally declared-method implementations
+ * and a resolved-manifest provider.
+ */
+export interface GraphNodeRegistration {
+    /** Published node manifest. */
+    manifest: GraphNodeManifest;
+    /** Executor that performs the node's work. */
+    executor: GraphNodeExecutor;
+    /** Implementations for the manifest's declared methods. */
+    methods?: Record<string, GraphNodeMethod>;
+    /** Optional dynamic-manifest resolution provider. */
+    resolveManifest?: GraphResolvedManifestProvider;
+}
+/** Options for {@link GraphNodeCatalogue.register}. */
+export interface GraphNodeRegistrationOptions {
+    /** Replace an existing registration for the same kind. */
+    replace?: boolean;
+}
+/**
+ * Identity helper that types a registration payload as a
+ * {@link GraphNodeRegistration} for catalogue registration.
+ */
+export declare function defineGraphNode(registration: GraphNodeRegistration): GraphNodeRegistration;
+/** Returns the method manifests declared by a node manifest. */
+export declare function declaredGraphNodeMethods(manifest: GraphNodeManifest): GraphNodeMethodManifest[];

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

@@ -0,0 +1,6 @@
+export * from "./GraphCatalogueErrors.d.cts";
+export * from "./GraphNodeRegistration.d.cts";
+export * from "./GraphNodeMethodRegistry.d.cts";
+export * from "./GraphNodeManifestResolver.d.cts";
+export * from "./GraphNodeCatalogue.d.cts";
+export * from "./GraphBuiltInRegistrations.d.cts";

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

@@ -0,0 +1,6 @@
+export * from "./GraphCatalogueErrors.d.mts";
+export * from "./GraphNodeRegistration.d.mts";
+export * from "./GraphNodeMethodRegistry.d.mts";
+export * from "./GraphNodeManifestResolver.d.mts";
+export * from "./GraphNodeCatalogue.d.mts";
+export * from "./GraphBuiltInRegistrations.d.mts";

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

@@ -3,8 +3,8 @@
  * @summary Graph execution engine-private constants and enums.
  * @description Engine-only constants, default limits, and enumerations.
  * Frontend-safe enums (`GraphExecutionStatus`, `GraphExecutionEventType`)
- * live in `../shared/constants`; 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.
  */
 /**
  * Boundary identifier used as the node id for workflow-level input/output ports.

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

@@ -3,8 +3,8 @@
  * @summary Graph execution engine-private constants and enums.
  * @description Engine-only constants, default limits, and enumerations.
  * Frontend-safe enums (`GraphExecutionStatus`, `GraphExecutionEventType`)
- * live in `../shared/constants`; 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.
  */
 /**
  * Boundary identifier used as the node id for workflow-level input/output ports.

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

@@ -0,0 +1,9 @@
+import { GraphExecutionError } from "./GraphExecutionError.d.cts";
+/**
+ * Thrown when a graph run is cancelled before completion: carries the run id
+ * under the `GRAPH_RUN_CANCELLED` code so run lifecycle bookkeeping can
+ * distinguish cancellation from failure.
+ */
+export declare class GraphRunCancelledError extends GraphExecutionError {
+    constructor(runId: string);
+}

package/lib/types/graph/engine/errors/GraphRunCancelledError.d.mts

@@ -0,0 +1,9 @@
+import { GraphExecutionError } from "./GraphExecutionError.d.mts";
+/**
+ * Thrown when a graph run is cancelled before completion: carries the run id
+ * under the `GRAPH_RUN_CANCELLED` code so run lifecycle bookkeeping can
+ * distinguish cancellation from failure.
+ */
+export declare class GraphRunCancelledError extends GraphExecutionError {
+    constructor(runId: string);
+}

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

@@ -12,3 +12,4 @@ export * from "./GraphPortError.d.cts";
 export * from "./GraphStoreError.d.cts";
 export * from "./GraphTopologyError.d.cts";
 export * from "./GraphBreakSignal.d.cts";
+export * from "./GraphRunCancelledError.d.cts";

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

@@ -12,3 +12,4 @@ export * from "./GraphPortError.d.mts";
 export * from "./GraphStoreError.d.mts";
 export * from "./GraphTopologyError.d.mts";
 export * from "./GraphBreakSignal.d.mts";
+export * from "./GraphRunCancelledError.d.mts";

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

@@ -5,7 +5,7 @@
  */
 import type { Observable } from "@decaf-ts/core";
 import type { GraphExecutionObserver } from "./GraphExecutionObserver.d.cts";
-import type { GraphExecutionEvent } from "../types.d.cts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Manages observer registration and event dispatch for the graph execution
  * engine.

package/lib/types/graph/engine/events/GraphExecutionEventEmitter.d.mts

@@ -5,7 +5,7 @@
  */
 import type { Observable } from "@decaf-ts/core";
 import type { GraphExecutionObserver } from "./GraphExecutionObserver.d.mts";
-import type { GraphExecutionEvent } from "../types.d.mts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Manages observer registration and event dispatch for the graph execution
  * engine.

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

@@ -3,7 +3,7 @@
  * @summary Factory for creating graph execution events with unique ids, sequence numbers, and timestamps.
  * @description Provides a stateful factory that produces monotonically-sequenced events for a single execution run.
  */
-import type { GraphExecutionEvent } from "../types.d.cts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Factory that enriches partial events with a unique id, an incrementing
  * sequence number, and a timestamp.

package/lib/types/graph/engine/events/GraphExecutionEventFactory.d.mts

@@ -3,7 +3,7 @@
  * @summary Factory for creating graph execution events with unique ids, sequence numbers, and timestamps.
  * @description Provides a stateful factory that produces monotonically-sequenced events for a single execution run.
  */
-import type { GraphExecutionEvent } from "../types.d.mts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Factory that enriches partial events with a unique id, an incrementing
  * sequence number, and a timestamp.

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

@@ -4,7 +4,7 @@
  * @description Extends Decaf's {@link Observer} so graph events flow through the standard Observable/Observer pipeline.
  */
 import type { Observer } from "@decaf-ts/core";
-import type { GraphExecutionEvent } from "../types.d.cts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Observer that receives {@link GraphExecutionEvent} instances from the
  * graph execution engine.

package/lib/types/graph/engine/events/GraphExecutionObserver.d.mts

@@ -4,7 +4,7 @@
  * @description Extends Decaf's {@link Observer} so graph events flow through the standard Observable/Observer pipeline.
  */
 import type { Observer } from "@decaf-ts/core";
-import type { GraphExecutionEvent } from "../types.d.mts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Observer that receives {@link GraphExecutionEvent} instances from the
  * graph execution engine.

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

@@ -3,7 +3,6 @@
  * @summary Graph execution event pipeline.
  * @description Re-exports the observer interface, event emitter, and event factory.
  */
-export * from "./GraphExecutionEvent.d.cts";
 export * from "./GraphExecutionObserver.d.cts";
 export * from "./GraphExecutionEventEmitter.d.cts";
 export * from "./GraphExecutionEventFactory.d.cts";

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

@@ -3,7 +3,6 @@
  * @summary Graph execution event pipeline.
  * @description Re-exports the observer interface, event emitter, and event factory.
  */
-export * from "./GraphExecutionEvent.d.mts";
 export * from "./GraphExecutionObserver.d.mts";
 export * from "./GraphExecutionEventEmitter.d.mts";
 export * from "./GraphExecutionEventFactory.d.mts";