@decaf-ts/integrations 0.7.0 → 0.9.0

package/lib/types/blob/s3/S3BlobStoreService.d.mts

@@ -1,25 +1,5 @@
-/**
- * @module integrations/blob/s3/service
- * @summary S3-compatible blob store service.
- * @description Blob store backed by AWS S3, MinIO, and Cloudflare R2 via the AWS SDK v3 S3Client.
- */
-import { S3Client } from "@aws-sdk/client-s3";
-import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
-import { BlobStoreService } from "../core/BlobStoreService.d.mts";
-import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, S3BlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
-export declare class S3BlobStoreService extends BlobStoreService<S3Client, S3BlobStoreServiceConfig> {
-    initialize(...args: ContextualArgs<any>): Promise<{
-        config: S3BlobStoreServiceConfig;
-        client: S3Client;
-    }>;
-    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
-    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
-    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
-    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
-    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
-    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
-    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
-    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
-    protected parseError(error: unknown): Error;
-    private ensureBucket;
+import { S3CompatibleBlobStoreService } from "./S3CompatibleBlobStoreService.d.mts";
+import type { S3BlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
+export declare class S3BlobStoreService extends S3CompatibleBlobStoreService {
+    protected configFromEnvironment(): S3BlobStoreServiceConfig | undefined;
 }

package/lib/types/blob/s3/S3CompatibleBlobStoreService.d.cts

@@ -0,0 +1,30 @@
+/**
+ * @module integrations/blob/s3/base-service
+ * @summary S3-compatible blob store base implementation.
+ * @description Shared CRUD implementation backed by the AWS SDK v3 S3Client, used by
+ * the S3, MinIO, and Cloudflare R2 provider services. Deliberately left undecorated:
+ * `@service(...)` on a class whose parent is itself `@service(...)`-decorated breaks
+ * that subclass's inherited field initializers (e.g. `Context` ends up `undefined`).
+ * Each concrete provider below extends this class directly and carries its own
+ * `@service("blob-<provider>")` decorator instead of stacking on top of one another.
+ */
+import { S3Client } from "@aws-sdk/client-s3";
+import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
+import { BlobStoreService } from "../core/BlobStoreService.d.cts";
+import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, S3BlobStoreServiceConfig } from "../core/BlobTypes.d.cts";
+export declare abstract class S3CompatibleBlobStoreService extends BlobStoreService<S3Client, S3BlobStoreServiceConfig> {
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: S3BlobStoreServiceConfig;
+        client: S3Client;
+    }>;
+    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
+    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
+    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
+    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
+    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
+    protected parseError(error: unknown): Error;
+    private ensureBucket;
+}

package/lib/types/blob/s3/S3CompatibleBlobStoreService.d.mts

@@ -0,0 +1,30 @@
+/**
+ * @module integrations/blob/s3/base-service
+ * @summary S3-compatible blob store base implementation.
+ * @description Shared CRUD implementation backed by the AWS SDK v3 S3Client, used by
+ * the S3, MinIO, and Cloudflare R2 provider services. Deliberately left undecorated:
+ * `@service(...)` on a class whose parent is itself `@service(...)`-decorated breaks
+ * that subclass's inherited field initializers (e.g. `Context` ends up `undefined`).
+ * Each concrete provider below extends this class directly and carries its own
+ * `@service("blob-<provider>")` decorator instead of stacking on top of one another.
+ */
+import { S3Client } from "@aws-sdk/client-s3";
+import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
+import { BlobStoreService } from "../core/BlobStoreService.d.mts";
+import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, S3BlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
+export declare abstract class S3CompatibleBlobStoreService extends BlobStoreService<S3Client, S3BlobStoreServiceConfig> {
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: S3BlobStoreServiceConfig;
+        client: S3Client;
+    }>;
+    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
+    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
+    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
+    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
+    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
+    protected parseError(error: unknown): Error;
+    private ensureBucket;
+}

package/lib/types/blob/s3/index.d.cts

@@ -3,6 +3,10 @@
  * @summary S3-compatible blob store exports.
  * @description Re-exports the S3, MinIO, and R2 blob store services.
  */
+export * from "./S3CompatibleBlobStoreService.d.cts";
 export * from "./S3BlobStoreService.d.cts";
+export * from "./S3BlobEnvironment.d.cts";
 export * from "./MinioBlobStoreService.d.cts";
+export * from "./MinioBlobEnvironment.d.cts";
 export * from "./R2BlobStoreService.d.cts";
+export * from "./R2BlobEnvironment.d.cts";

package/lib/types/blob/s3/index.d.mts

@@ -3,6 +3,10 @@
  * @summary S3-compatible blob store exports.
  * @description Re-exports the S3, MinIO, and R2 blob store services.
  */
+export * from "./S3CompatibleBlobStoreService.d.mts";
 export * from "./S3BlobStoreService.d.mts";
+export * from "./S3BlobEnvironment.d.mts";
 export * from "./MinioBlobStoreService.d.mts";
+export * from "./MinioBlobEnvironment.d.mts";
 export * from "./R2BlobStoreService.d.mts";
+export * from "./R2BlobEnvironment.d.mts";

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.