@adriane-ai/graph-sdk 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,2684 @@
+type MessageId = Brand<string, "MessageId">;
+type ToolCall = {
+    id: string;
+    name: string;
+    input: unknown;
+};
+type BaseMessage = {
+    id: MessageId;
+    createdAt: Date;
+    metadata?: Record<string, unknown>;
+};
+type HumanMessage = BaseMessage & {
+    role: "human";
+    content: string;
+};
+type AIMessage = BaseMessage & {
+    role: "ai";
+    content: string;
+    toolCalls?: ToolCall[];
+};
+type ToolMessage = BaseMessage & {
+    role: "tool";
+    toolCallId: string;
+    content: string;
+};
+type SystemMessage = BaseMessage & {
+    role: "system";
+    content: string;
+};
+type Message = HumanMessage | AIMessage | ToolMessage | SystemMessage;
+
+type Brand<T, TBrand extends string> = T & {
+    readonly __brand: TBrand;
+};
+type NodeId = Brand<string, "NodeId">;
+type EdgeId = Brand<string, "EdgeId">;
+type GraphId = Brand<string, "GraphId">;
+type RunId = Brand<string, "RunId">;
+type ChannelReducer = "replace" | "append" | "merge";
+type ChannelDefinition<T> = {
+    type: string;
+    reducer: ChannelReducer;
+    default?: T;
+};
+type ChannelsSchema = Record<string, ChannelDefinition<unknown>>;
+type ResolvedChannels<TChannels extends ChannelsSchema> = {
+    [K in keyof TChannels]: TChannels[K] extends ChannelDefinition<infer TValue> ? TValue : never;
+};
+declare const NODE_TYPES: readonly ["action", "agent", "tool", "human-gate", "subgraph"];
+type NodeType = (typeof NODE_TYPES)[number];
+declare const EDGE_TYPES: readonly ["default", "conditional"];
+type EdgeType = (typeof EDGE_TYPES)[number];
+declare const GRAPH_STATUSES: readonly ["idle", "running", "suspended", "completed", "failed"];
+type GraphStatus = (typeof GRAPH_STATUSES)[number];
+type RetryPolicy = {
+    maxAttempts: number;
+    backoffMs: number;
+};
+type Command<TChannels extends ChannelsSchema = ChannelsSchema> = {
+    goto: NodeId | NodeId[];
+    update?: Partial<ResolvedChannels<TChannels>>;
+};
+type NodeDefinition = {
+    id: NodeId;
+    type: NodeType;
+    label: string;
+    subgraphId?: GraphId;
+    inputMapping?: Record<string, string>;
+    outputMapping?: Record<string, string>;
+    fanOut?: {
+        parallelTo: NodeId[];
+        joinAt: NodeId;
+    };
+    retryPolicy?: RetryPolicy;
+    metadata?: Record<string, unknown>;
+};
+type EdgeDefinition = {
+    id: EdgeId;
+    from: NodeId;
+    to: NodeId;
+    type: EdgeType;
+    condition?: string;
+};
+type GraphState<TChannels extends ChannelsSchema = ChannelsSchema> = {
+    runId: RunId;
+    graphId: GraphId;
+    currentNodeId: NodeId;
+    status: GraphStatus;
+    channels: ResolvedChannels<TChannels>;
+    version: number;
+    checkpointId?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+type GraphDefinition<TChannels extends ChannelsSchema = ChannelsSchema> = {
+    id: GraphId;
+    version: string;
+    name: string;
+    recursionLimit?: number;
+    channels: TChannels;
+    nodes: NodeDefinition[];
+    edges: EdgeDefinition[];
+    entryNodeId: NodeId;
+    metadata?: Record<string, unknown>;
+};
+
+declare const GRAPH_VALIDATION_ERROR_CODES: {
+    readonly DUPLICATE_NODE_ID: "DUPLICATE_NODE_ID";
+    readonly DUPLICATE_EDGE_ID: "DUPLICATE_EDGE_ID";
+    readonly MISSING_ENTRY_NODE: "MISSING_ENTRY_NODE";
+    readonly INVALID_EDGE_REFERENCE: "INVALID_EDGE_REFERENCE";
+    readonly CYCLE_DETECTED: "CYCLE_DETECTED";
+    readonly INVALID_CONDITION_FORMAT: "INVALID_CONDITION_FORMAT";
+};
+type GraphValidationErrorCode = (typeof GRAPH_VALIDATION_ERROR_CODES)[keyof typeof GRAPH_VALIDATION_ERROR_CODES];
+type GraphValidationPath = (string | number)[];
+declare class GraphValidationError extends Error {
+    readonly code: GraphValidationErrorCode;
+    readonly path: GraphValidationPath;
+    constructor(code: GraphValidationErrorCode, message: string, path?: GraphValidationPath);
+}
+
+type ArtifactId = string & {
+    readonly __brand: "ArtifactId";
+};
+type ArtifactVersion = number;
+type ArtifactRef = {
+    id: ArtifactId;
+    version: ArtifactVersion;
+};
+
+type MemoryNamespace = string[];
+type MemoryKey = string;
+type MemoryItem = {
+    namespace: MemoryNamespace;
+    key: MemoryKey;
+    value: unknown;
+    createdAt: string;
+    updatedAt: string;
+    embedding?: number[];
+};
+
+interface BaseStore {
+    get(namespace: MemoryNamespace, key: MemoryKey): Promise<MemoryItem | undefined>;
+    put(namespace: MemoryNamespace, key: MemoryKey, value: unknown): Promise<MemoryItem>;
+    delete(namespace: MemoryNamespace, key: MemoryKey): Promise<void>;
+    search(namespace: MemoryNamespace, query: string, topK: number): Promise<MemoryItem[]>;
+    list(namespace: MemoryNamespace, prefix?: string): Promise<MemoryItem[]>;
+}
+
+type BaseCallbackEvent = {
+    runId: string;
+    nodeId?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+};
+type CallbackEvent = (BaseCallbackEvent & {
+    type: "onLLMStart";
+    input: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onLLMToken";
+    token: string;
+}) | (BaseCallbackEvent & {
+    type: "onLLMEnd";
+    output: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onLLMError";
+    error: string;
+}) | (BaseCallbackEvent & {
+    type: "onToolStart";
+    tool: string;
+    input: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onToolEnd";
+    tool: string;
+    output: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onToolError";
+    tool: string;
+    error: string;
+}) | (BaseCallbackEvent & {
+    type: "onNodeStart";
+    input: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onNodeEnd";
+    output: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onNodeError";
+    error: string;
+}) | (BaseCallbackEvent & {
+    type: "onChainStart";
+    input: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onChainEnd";
+    output: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onChainError";
+    error: string;
+}) | (BaseCallbackEvent & {
+    type: "onAgentAction";
+    action: string;
+    payload?: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onAgentFinish";
+    result: unknown;
+});
+
+interface CallbackHandler {
+    onLLMStart?(event: Extract<CallbackEvent, {
+        type: "onLLMStart";
+    }>): void | Promise<void>;
+    onLLMToken?(event: Extract<CallbackEvent, {
+        type: "onLLMToken";
+    }>): void | Promise<void>;
+    onLLMEnd?(event: Extract<CallbackEvent, {
+        type: "onLLMEnd";
+    }>): void | Promise<void>;
+    onLLMError?(event: Extract<CallbackEvent, {
+        type: "onLLMError";
+    }>): void | Promise<void>;
+    onToolStart?(event: Extract<CallbackEvent, {
+        type: "onToolStart";
+    }>): void | Promise<void>;
+    onToolEnd?(event: Extract<CallbackEvent, {
+        type: "onToolEnd";
+    }>): void | Promise<void>;
+    onToolError?(event: Extract<CallbackEvent, {
+        type: "onToolError";
+    }>): void | Promise<void>;
+    onNodeStart?(event: Extract<CallbackEvent, {
+        type: "onNodeStart";
+    }>): void | Promise<void>;
+    onNodeEnd?(event: Extract<CallbackEvent, {
+        type: "onNodeEnd";
+    }>): void | Promise<void>;
+    onNodeError?(event: Extract<CallbackEvent, {
+        type: "onNodeError";
+    }>): void | Promise<void>;
+    onChainStart?(event: Extract<CallbackEvent, {
+        type: "onChainStart";
+    }>): void | Promise<void>;
+    onChainEnd?(event: Extract<CallbackEvent, {
+        type: "onChainEnd";
+    }>): void | Promise<void>;
+    onChainError?(event: Extract<CallbackEvent, {
+        type: "onChainError";
+    }>): void | Promise<void>;
+    onAgentAction?(event: Extract<CallbackEvent, {
+        type: "onAgentAction";
+    }>): void | Promise<void>;
+    onAgentFinish?(event: Extract<CallbackEvent, {
+        type: "onAgentFinish";
+    }>): void | Promise<void>;
+}
+interface CallbackManager {
+    addHandler(handler: CallbackHandler): void;
+    removeHandler(handler: CallbackHandler): void;
+    emit(event: CallbackEvent): Promise<void>;
+    createChild(tags?: string[], metadata?: Record<string, unknown>): CallbackManager;
+}
+
+declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "mistral", "ollama", "mock"];
+type LLMProvider = (typeof LLM_PROVIDERS)[number];
+type LLMModel = string;
+/** A text span in a structured message. */
+type LLMTextBlock = {
+    type: "text";
+    text: string;
+};
+/** An assistant turn requesting a tool call. */
+type LLMToolUseBlock = {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+};
+/** A user turn returning a tool's result, paired to a prior `tool_use` by id. */
+type LLMToolResultBlock = {
+    type: "tool_result";
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+};
+type LLMContentBlock = LLMTextBlock | LLMToolUseBlock | LLMToolResultBlock;
+type LLMMessage = {
+    role: "system" | "user" | "assistant";
+    /**
+     * Either plain text or a list of content blocks. Blocks carry `tool_use` /
+     * `tool_result` turns so a tool-calling agent can hold a real multi-turn
+     * conversation with the provider instead of stuffing observations into text.
+     */
+    content: string | LLMContentBlock[];
+};
+/**
+ * Tool definition exposed to the provider. Part of the cacheable prefix: the tool
+ * list must be deterministic (stable order, stable schema) or it busts the cache.
+ */
+type LLMToolDef = {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+};
+type LLMRequest = {
+    provider: LLMProvider;
+    model: LLMModel;
+    messages: LLMMessage[];
+    /**
+     * Immutable system prompt. Forms the cacheable prefix together with `tools`.
+     * Keep volatile content (dates, timestamps, session ids) OUT of here.
+     */
+    system?: string;
+    tools?: LLMToolDef[];
+    maxTokens?: number;
+    temperature?: number;
+    stream?: boolean;
+};
+/** A structured tool call surfaced by the provider (e.g. an Anthropic `tool_use` block). */
+type LLMToolCall = {
+    id: string;
+    name: string;
+    input: unknown;
+};
+type LLMResponse = {
+    content: string;
+    /**
+     * Structured tool calls the model wants executed. Present when the provider
+     * stops on a tool-use turn; consumers should run these instead of parsing the
+     * text content for a tool protocol.
+     */
+    toolCalls?: LLMToolCall[];
+    /** Why the model stopped — `"tool_use"` signals it is waiting on tool results. */
+    stopReason?: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        /** Tokens served from the prompt cache (~0.1x cost). */
+        cacheReadTokens?: number;
+        /** Tokens written to the prompt cache this call (~1.25x cost). */
+        cacheWriteTokens?: number;
+    };
+    model: string;
+    provider: LLMProvider;
+};
+type LLMStreamChunk = {
+    delta: string;
+    done: boolean;
+};
+
+interface LLMProviderAdapter {
+    provider: LLMProvider;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+}
+interface LLMGateway {
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+    registerAdapter(adapter: LLMProviderAdapter): void;
+}
+
+type Blocker = {
+    code: string;
+    message: string;
+    nodeId?: NodeId;
+};
+type AgentResult = {
+    artifacts: ArtifactRef[];
+    blockers: Blocker[];
+    approvalRequests: Array<{
+        subject: ArtifactRef | {
+            description: string;
+        };
+        reason: string;
+    }>;
+    confidence: number;
+    reasoning: string;
+    requiresHumanReview: boolean;
+};
+
+type ZodSchema<T> = {
+    parse(input: unknown): T;
+};
+type ToolId = string & {
+    readonly __brand: "ToolId";
+};
+type ToolDefinition<TInput, TOutput> = {
+    id: ToolId;
+    name: string;
+    description: string;
+    inputSchema: ZodSchema<TInput>;
+    outputSchema: ZodSchema<TOutput>;
+    permissions: string[];
+    requiresApproval?: boolean;
+    /**
+     * JSON Schema for the tool's input, advertised to the LLM. `inputSchema` only
+     * validates (`.parse`); this is what the provider needs to emit tool calls.
+     */
+    jsonSchema?: Record<string, unknown>;
+};
+type ToolHandler<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
+interface ToolRegistry {
+    register<TInput, TOutput>(definition: ToolDefinition<TInput, TOutput>, handler: ToolHandler<TInput, TOutput>): void;
+    resolve(id: ToolId): {
+        definition: ToolDefinition<unknown, unknown>;
+        handler: ToolHandler<unknown, unknown>;
+    } | undefined;
+    list(): ToolDefinition<unknown, unknown>[];
+}
+declare class InMemoryToolRegistry implements ToolRegistry {
+    private readonly entries;
+    register<TInput, TOutput>(definition: ToolDefinition<TInput, TOutput>, handler: ToolHandler<TInput, TOutput>): void;
+    resolve(id: ToolId): {
+        definition: ToolDefinition<unknown, unknown>;
+        handler: ToolHandler<unknown, unknown>;
+    } | undefined;
+    list(): ToolDefinition<unknown, unknown>[];
+}
+
+/**
+ * Versioned prompt registry. Agents reference prompts by id (+ optional version)
+ * instead of hardcoding them inline (rule 090). The `system` text is the immutable,
+ * cacheable prefix — keep volatile/dynamic values out of it and pass those in the
+ * per-call user message instead.
+ */
+type PromptTemplate = {
+    id: string;
+    version: string;
+    system: string;
+    description?: string;
+};
+interface PromptRegistry {
+    register(template: PromptTemplate): void;
+    get(id: string, version?: string): PromptTemplate;
+    list(): PromptTemplate[];
+}
+declare class InMemoryPromptRegistry implements PromptRegistry {
+    private readonly byId;
+    private readonly latest;
+    register(template: PromptTemplate): void;
+    get(id: string, version?: string): PromptTemplate;
+    list(): PromptTemplate[];
+}
+
+type CheckpointId = string & {
+    readonly __brand: "CheckpointId";
+};
+type Checkpoint<TChannels extends ChannelsSchema = ChannelsSchema> = {
+    id: CheckpointId;
+    runId: RunId;
+    graphState: GraphState<TChannels>;
+    createdAt: string;
+};
+type RunEvent = {
+    type: "node_started";
+    runId: RunId;
+    nodeId: NodeId;
+    timestamp: string;
+} | {
+    type: "node_completed";
+    runId: RunId;
+    nodeId: NodeId;
+    output: unknown;
+    timestamp: string;
+} | {
+    type: "node_failed";
+    runId: RunId;
+    nodeId: NodeId;
+    error: string;
+    attempt: number;
+    timestamp: string;
+} | {
+    type: "run_suspended";
+    runId: RunId;
+    nodeId: NodeId;
+    reason: string;
+    timestamp: string;
+} | {
+    type: "run_resumed";
+    runId: RunId;
+    nodeId: NodeId;
+    timestamp: string;
+} | {
+    type: "run_completed";
+    runId: RunId;
+    finalState: GraphState<ChannelsSchema>;
+    timestamp: string;
+} | {
+    type: "run_failed";
+    runId: RunId;
+    error: string;
+    timestamp: string;
+};
+
+type NodeExecutionContext = {
+    memory: BaseStore;
+};
+type NodeHandler<TChannels extends ChannelsSchema = ChannelsSchema, TInput = unknown, TOutput extends Partial<ResolvedChannels<TChannels>> | Command<TChannels> = Partial<ResolvedChannels<TChannels>> | Command<TChannels>> = (input: TInput, state: GraphState<TChannels>, context: NodeExecutionContext) => Promise<TOutput>;
+interface NodeRegistry {
+    register(nodeId: NodeId, handler: NodeHandler): void;
+    resolve(nodeId: NodeId): NodeHandler | undefined;
+}
+type ConditionFn = (state: GraphState) => boolean;
+interface ConditionRegistry {
+    register(name: string, fn: ConditionFn): void;
+    resolve(name: string): ConditionFn | undefined;
+}
+interface Checkpointer {
+    save(checkpoint: Checkpoint): Promise<void>;
+    load(runId: RunId): Promise<Checkpoint | undefined>;
+    loadById(id: CheckpointId): Promise<Checkpoint | undefined>;
+    list(runId: RunId): Promise<Checkpoint[]>;
+}
+interface EventBus {
+    emit(event: RunEvent): void;
+    subscribe(handler: (event: RunEvent) => void): () => void;
+}
+
+type StepBudget = {
+    maxSteps: number;
+    currentSteps: number;
+};
+
+declare class InMemoryCheckpointer implements Checkpointer {
+    private readonly checkpointsById;
+    private readonly latestCheckpointByRunId;
+    private readonly checkpointIdsByRunId;
+    save(checkpoint: Checkpoint): Promise<void>;
+    load(runId: RunId): Promise<Checkpoint | undefined>;
+    loadById(id: CheckpointId): Promise<Checkpoint | undefined>;
+    list(runId: RunId): Promise<Checkpoint[]>;
+}
+
+declare const STREAM_MODES: readonly ["values", "updates", "debug", "messages"];
+type StreamMode = (typeof STREAM_MODES)[number];
+type StreamEvent = {
+    type: "state_value";
+    state: GraphState;
+} | {
+    type: "state_update";
+    delta: Record<string, unknown>;
+    nodeId: NodeId;
+} | {
+    type: "message_delta";
+    delta: string;
+    nodeId: NodeId;
+    messageId: string;
+} | {
+    type: "tool_call";
+    toolId: string;
+    input: unknown;
+    nodeId: NodeId;
+} | {
+    type: "debug";
+    payload: unknown;
+    nodeId: NodeId;
+};
+
+type InterruptConfig = {
+    before?: NodeId[];
+    after?: NodeId[];
+};
+declare class DynamicInterrupt extends Error {
+    readonly reason: string;
+    readonly patch?: Record<string, unknown>;
+    constructor(reason: string, patch?: Record<string, unknown>);
+}
+
+type GraphRuntimeDeps = {
+    graph: GraphDefinition<ChannelsSchema>;
+    nodeRegistry: NodeRegistry;
+    conditionRegistry: ConditionRegistry;
+    checkpointer: Checkpointer;
+    eventBus: EventBus;
+    callbackManager?: CallbackManager;
+    memory?: BaseStore;
+    stepBudget?: StepBudget;
+    subgraphResolver?: (graphId: GraphId) => GraphDefinition | undefined;
+    interruptConfig?: InterruptConfig;
+};
+declare class GraphRuntime {
+    private readonly graph;
+    private readonly nodeRegistry;
+    private readonly conditionRegistry;
+    private readonly checkpointer;
+    private readonly eventBus;
+    private readonly callbackManager;
+    readonly memory: BaseStore;
+    readonly stepBudget: StepBudget;
+    private readonly nodeById;
+    private readonly subgraphResolver?;
+    private readonly interruptConfig?;
+    private readonly stateHistoryByRunId;
+    private readonly stepsByRunId;
+    private readonly inboxByRunId;
+    constructor(deps: GraphRuntimeDeps);
+    start(runId: RunId, initialData: Record<string, unknown>): Promise<GraphState>;
+    stream(runId: RunId, initialData: Record<string, unknown>, mode: StreamMode): AsyncIterable<StreamEvent>;
+    resume(runId: RunId): Promise<GraphState>;
+    executeNode(nodeId: NodeId, state: GraphState): Promise<GraphState>;
+    nextNode(currentNodeId: NodeId, state: GraphState): NodeId | null;
+    send(runId: RunId, nodeId: NodeId, input: unknown): Promise<void>;
+    private selectNextEdge;
+    private runLoop;
+    private persistCheckpoint;
+    getHistory(runId: RunId): GraphState<ChannelsSchema>[];
+    updateState(runId: RunId, patch: Partial<Record<string, unknown>>, resumeFrom?: NodeId): Promise<GraphState>;
+    getCheckpoints(runId: RunId): Promise<Checkpoint[]>;
+    replayFrom(runId: RunId, checkpointId: CheckpointId): Promise<GraphState>;
+    applyUpdate(channels: Record<string, unknown>, partialUpdate: Partial<Record<string, unknown>>): Record<string, unknown>;
+    private buildInitialChannels;
+    private applyInputMapping;
+    private applyOutputMapping;
+    private setSubgraphRunId;
+    private getOrCreateSubgraphRunId;
+    private readInterruptMeta;
+    private clearInterruptMeta;
+    private suspendRun;
+    private computeDelta;
+    private areEqual;
+    private assertRecursionLimit;
+    private consumeStepBudget;
+    private consumeInjectedInput;
+    private resolveCommand;
+    private resolveNextNode;
+    private executeFanOut;
+    private extractMessageEvents;
+    private extractToolCallEvents;
+}
+
+declare class DefaultLLMGateway implements LLMGateway {
+    private readonly adapters;
+    registerAdapter(adapter: LLMProviderAdapter): void;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+    private validateRequest;
+}
+
+type MockAdapterOptions = {
+    provider: LLMProvider;
+    response?: LLMResponse;
+    /**
+     * Scripted responses replayed one per `complete()` call (the last repeats once
+     * exhausted). Lets a test drive a multi-turn agent — e.g. a `tool_use` turn
+     * followed by a final-answer turn. Takes precedence over `response`.
+     */
+    responses?: LLMResponse[];
+    chunks?: LLMStreamChunk[];
+};
+declare class MockLLMProviderAdapter implements LLMProviderAdapter {
+    readonly provider: LLMProvider;
+    private readonly responses;
+    private readonly chunks;
+    private index;
+    constructor(options: MockAdapterOptions);
+    complete(): Promise<LLMResponse>;
+    stream(): AsyncIterable<LLMStreamChunk>;
+}
+
+/**
+ * Provider-shaped request the adapter assembles. This is the cache seam: the
+ * `system` and `tools` blocks carry the cache_control breakpoints and must stay
+ * byte-stable across calls. The default port translates this into the SDK request;
+ * tests fake the port and assert on this shape directly.
+ */
+type AnthropicCreateParams = {
+    model: string;
+    maxTokens: number;
+    system?: Array<{
+        type: "text";
+        text: string;
+        cacheable?: boolean;
+    }>;
+    tools?: Array<{
+        name: string;
+        description?: string;
+        inputSchema: Record<string, unknown>;
+        cacheable?: boolean;
+    }>;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: string | LLMContentBlock[];
+    }>;
+};
+/** Structural subset of the SDK `Message` the adapter actually reads. */
+type AnthropicRawResponse = {
+    content: Array<{
+        type: string;
+        text?: string;
+        id?: string;
+        name?: string;
+        input?: unknown;
+    }>;
+    stop_reason?: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens?: number | null;
+        cache_creation_input_tokens?: number | null;
+    };
+};
+/**
+ * The only seam onto the Anthropic SDK. The default implementation wraps a real
+ * client; tests supply a fake so the cache + accounting logic is covered without
+ * a network call or an API key.
+ */
+interface AnthropicClientPort {
+    create(params: AnthropicCreateParams): Promise<AnthropicRawResponse>;
+    stream(params: AnthropicCreateParams): AsyncIterable<LLMStreamChunk>;
+}
+type AnthropicAdapterOptions = {
+    /** Override the model used when the request does not name a Claude model. */
+    defaultModel?: string;
+    /** Inject a client port (tests) or an API key (production). */
+    port?: AnthropicClientPort;
+    apiKey?: string;
+};
+declare class AnthropicProviderAdapter implements LLMProviderAdapter {
+    readonly provider: "anthropic";
+    private readonly port;
+    private readonly defaultModel;
+    constructor(options?: AnthropicAdapterOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+    /**
+     * Assemble the provider request. The cacheable prefix is `tools` then `system`
+     * (Anthropic render order); a breakpoint on the last tool and on the system block
+     * caches that prefix. Sampling params are intentionally dropped — Opus 4.7/4.8
+     * reject `temperature`/`top_p`/`top_k`. No date/timestamp is added here.
+     */
+    private buildParams;
+    private collectSystem;
+    private resolveModel;
+    private toResponse;
+}
+
+/**
+ * The OpenAI `/v1/chat/completions` request body the adapter assembles. This is the
+ * seam tests assert against directly: {@link buildRequestBody} is a pure function, so
+ * the request mapping is covered without a network call or an API key.
+ */
+type OpenAIChatRequestBody = {
+    model: string;
+    messages: OpenAIChatMessage[];
+    tools?: Array<{
+        type: "function";
+        function: {
+            name: string;
+            description?: string;
+            parameters: Record<string, unknown>;
+        };
+    }>;
+    temperature?: number;
+    max_tokens?: number;
+};
+/** A single message in the OpenAI chat shape. */
+type OpenAIChatMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+};
+/** Structural subset of the OpenAI chat completion response the adapter reads. */
+type OpenAIChatResponse = {
+    choices: Array<{
+        message: {
+            content?: string | null;
+            tool_calls?: Array<{
+                id: string;
+                type?: string;
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }> | null;
+        };
+        finish_reason?: string | null;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+    };
+};
+/**
+ * The only seam onto the HTTP transport. The default implementation POSTs the body to
+ * `baseUrl + '/chat/completions'` via global `fetch`; tests supply a fake so the
+ * request/response mapping is covered without a network call.
+ */
+interface OpenAICompatibleTransportPort {
+    send(body: OpenAIChatRequestBody): Promise<OpenAIChatResponse>;
+}
+type OpenAICompatibleAdapterOptions = {
+    /** Provider key this adapter registers under in the gateway map. Default `'mistral'`. */
+    provider?: LLMProvider;
+    /** API base, e.g. `https://api.mistral.ai/v1` or `http://localhost:11434/v1`. */
+    baseUrl: string;
+    /** Model used when the request does not name a model id for this provider. */
+    defaultModel: string;
+    /** Bearer token; omitted for keyless servers such as a local Ollama. */
+    apiKey?: string;
+    /** Inject a transport port (tests) instead of the default `fetch`-backed one. */
+    port?: OpenAICompatibleTransportPort;
+};
+/**
+ * One adapter for any server speaking the OpenAI `/v1/chat/completions` shape. Both
+ * a local **Ollama** server (`http://localhost:11434/v1`, keyless) and **Mistral
+ * cloud** (`https://api.mistral.ai/v1`, bearer key) are driven by this same class;
+ * use {@link OpenAICompatibleProviderAdapter.ollama} / `.mistral` to construct them.
+ */
+declare class OpenAICompatibleProviderAdapter implements LLMProviderAdapter {
+    readonly provider: LLMProvider;
+    private readonly port;
+    private readonly baseUrl;
+    private readonly defaultModel;
+    constructor(options: OpenAICompatibleAdapterOptions);
+    /** Mistral cloud: bearer-keyed, hosted at `https://api.mistral.ai/v1`. */
+    static mistral(apiKey?: string, model?: string): OpenAICompatibleProviderAdapter;
+    /**
+     * A local Ollama server (keyless, `http://localhost:11434/v1`). Registers under the
+     * `'mistral'` provider key so it routes through the same gateway slot as Mistral cloud.
+     */
+    static ollama(model?: string, baseUrl?: string): OpenAICompatibleProviderAdapter;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+    private toResponse;
+}
+
+/**
+ * An abstract capability tier. Wire-compatible (camelCase) with the Rust
+ * `ModelTier` enum in `crates/llm-gateway`.
+ */
+type ModelTier = "frontier" | "balanced" | "fast" | "creative";
+/** All four tiers, in declaration order — handy for seeding tables. */
+declare const MODEL_TIERS: readonly ModelTier[];
+/**
+ * The outcome of {@link ModelPolicy.resolve}: a concrete provider + model, plus
+ * whether the model came from the recommended per-tier defaults (`true`) or from
+ * an explicit override (`false`).
+ */
+type ModelChoice = {
+    provider: LLMProvider;
+    model: string;
+    recommended: boolean;
+};
+/** `tier -> model` for a single provider. */
+type TierModelTable = Record<ModelTier, string>;
+/** Optional override passed to {@link ModelPolicy.resolve}. */
+type ResolveOverride = {
+    provider?: LLMProvider;
+    model?: string;
+};
+/**
+ * The shared capability-tier contract defaults: the recommended model for each
+ * provider at each tier. Mirrors the Rust `ModelPolicy::default` table exactly.
+ */
+declare const DEFAULT_TIER_TABLE: Partial<Record<LLMProvider, TierModelTable>>;
+/** The default cross-provider preference order, highest first. */
+declare const DEFAULT_PREFERENCE: readonly LLMProvider[];
+/**
+ * Capability-tier model policy: map an abstract capability tier
+ * (`frontier` / `balanced` / `fast` / `creative`) onto a concrete
+ * `{ provider, model }` choice, given which providers are actually available.
+ *
+ * Mirrors the Rust `crates/llm-gateway` `ModelPolicy` byte for byte in behaviour
+ * and wire shape. The point: "I only have Mistral" -> every tier resolves to the
+ * mistral column; "only Anthropic" -> `fast` -> haiku, `frontier` -> opus,
+ * `creative` -> fable.
+ */
+declare class ModelPolicy {
+    private readonly table;
+    private readonly preference;
+    /**
+     * Construct a policy. Either argument may be omitted to keep the contract
+     * default for that piece.
+     */
+    constructor(options?: {
+        table?: Partial<Record<LLMProvider, TierModelTable>>;
+        preference?: readonly LLMProvider[];
+    });
+    /**
+     * Which providers are usable given the current process environment:
+     * `anthropic` iff `ANTHROPIC_API_KEY` is set; `mistral` iff `MISTRAL_API_KEY`
+     * is set; `ollama` iff `ADRIANE_USE_OLLAMA=1`. Order follows the policy
+     * preference so callers get a deterministic list.
+     */
+    availableFromEnv(env?: NodeJS.ProcessEnv): LLMProvider[];
+    /**
+     * Resolve a capability tier to a concrete `{ provider, model, recommended }`.
+     *
+     * - An explicit `override.provider` and/or `override.model` wins, with
+     *   `recommended = false`. When only one of the two is given, the other is
+     *   filled from the policy: an override provider maps the tier to that
+     *   provider's recommended model; an override model rides on the first
+     *   available provider (or the override provider if also given).
+     * - Otherwise the highest-preference provider that is both available and
+     *   present in the table supplies its tier model, with `recommended = true`.
+     * - If nothing is available, the mock provider is returned.
+     */
+    resolve(tier: ModelTier, available: readonly LLMProvider[], override?: ResolveOverride): ModelChoice;
+    /** The recommended model for a provider+tier from the table, if present. */
+    private modelFor;
+    /** The first preference-ordered provider that is in `available`. */
+    private firstAvailable;
+}
+
+type ApprovalId = string & {
+    readonly __brand: "ApprovalId";
+};
+declare const APPROVAL_STATUSES: readonly ["pending", "approved", "rejected"];
+type ApprovalStatus = (typeof APPROVAL_STATUSES)[number];
+type ApprovalRequest = {
+    id: ApprovalId;
+    runId: RunId;
+    nodeId: NodeId;
+    requestedBy: string;
+    subject: ArtifactRef | {
+        description: string;
+    };
+    status: ApprovalStatus;
+    resolvedBy?: string;
+    resolvedAt?: Date;
+    rejectionReason?: string;
+    createdAt: Date;
+};
+
+type RequestApprovalParams = {
+    runId: RunId;
+    nodeId: NodeId;
+    requestedBy: string;
+    subject: ArtifactRef | {
+        description: string;
+    };
+};
+interface ApprovalEngine {
+    request(params: RequestApprovalParams): Promise<ApprovalRequest>;
+    approve(id: ApprovalId, resolvedBy: string): Promise<ApprovalRequest>;
+    reject(id: ApprovalId, resolvedBy: string, reason: string): Promise<ApprovalRequest>;
+    getPending(runId?: RunId): Promise<ApprovalRequest[]>;
+    getById(id: ApprovalId): Promise<ApprovalRequest | undefined>;
+}
+
+/** Default channel an agent node writes its {@link import("@adriane-ai/agents-core").AgentResult} into. */
+declare const DEFAULT_AGENT_OUTPUT_CHANNEL = "agentResult";
+/**
+ * Channel holding the names of tools whose human approval has been granted. The
+ * control plane writes it (see `CompiledGraph.approveAndResume`) before resuming a
+ * run that suspended for approval; the agent then executes those tools.
+ */
+declare const APPROVED_TOOLS_CHANNEL = "__approvedTools";
+/** Reason carried by the dynamic interrupt an agent node raises when it needs approval. */
+declare const AGENT_APPROVAL_INTERRUPT = "agent-approval-required";
+/**
+ * Channel holding the ApprovalEngine request ids created when a run suspends for
+ * approval. On resume the node looks each up; the ones the engine reports as
+ * `approved` unlock their tools — the engine is the source of truth, not a flag.
+ */
+declare const APPROVAL_IDS_CHANNEL = "__approvalIds";
+/** Where an agent node gets its system prompt. */
+type AgentPromptSource = {
+    registry: PromptRegistry;
+    id: string;
+    version?: string;
+}
+/** Inline convenience: the SDK registers this string and references it by id. */
+ | {
+    system: string;
+};
+/** Config for {@link GraphBuilder.agentNode}. */
+type AgentNodeConfig = {
+    llm: LLMGateway;
+    prompt: AgentPromptSource;
+    tools?: ToolRegistry;
+    provider?: LLMProvider;
+    model?: string;
+    /**
+     * Abstract capability tier (`"frontier" | "balanced" | "fast" | "creative"`). When
+     * set and no explicit {@link AgentNodeConfig.model} is given, the concrete model is
+     * resolved by the {@link ModelPolicy}: on the Rust path the bridge resolves it from
+     * the process env (so "I only have Mistral" maps every tier to the mistral column);
+     * on the TS fallback path the SDK resolves it here against `availableFromEnv()` so
+     * the agent runs on a consistent concrete provider+model. An explicit `model` (and
+     * an explicit `provider`) always wins over the tier (the override stays `false`-
+     * recommended in policy terms).
+     */
+    tier?: ModelTier;
+    maxIterations?: number;
+    name?: string;
+    description?: string;
+    /** Channel that receives the agent's result. Defaults to {@link DEFAULT_AGENT_OUTPUT_CHANNEL}. */
+    outputChannel?: string;
+    /**
+     * When true, the node suspends the whole run (a dynamic interrupt) the moment the
+     * agent needs approval, instead of just flagging `requiresHumanReview`. Resume with
+     * `CompiledGraph.approveAndResume(runId, { approvedTools })` to continue. Default false.
+     */
+    suspendForApproval?: boolean;
+    /**
+     * Route approvals through an {@link ApprovalEngine}: on suspend the node files a
+     * request per gated tool; on resume it executes the tools the engine reports as
+     * approved. The engine becomes the source of truth (a human resolves it out of
+     * band) instead of the `__approvedTools` channel.
+     */
+    approvalEngine?: ApprovalEngine;
+    label?: string;
+};
+/** Config for {@link GraphBuilder.toolNode}. */
+type ToolNodeConfig = {
+    tools: ToolRegistry;
+    /** Execute all tool calls concurrently instead of sequentially. */
+    parallel?: boolean;
+    label?: string;
+};
+/**
+ * A tool's name plus its TS `execute` fn — the data the Rust bridge needs to back a
+ * `jsToolName` with a JS callback. The Rust engine never imports the tool registry;
+ * it calls this `execute` over the napi seam (`on_node` with `kind:"tool"`).
+ */
+type RustToolBinding = {
+    name: string;
+    execute: (input: unknown) => Promise<unknown>;
+};
+/**
+ * The serializable shape of an agent node, plus its JS-backed tool executes, that
+ * the Rust engine bridge consumes (see `EngineSpec.agents` / `jsToolNames`). It is a
+ * pure projection of {@link AgentNodeConfig} — the system prompt is the *resolved*
+ * string (never a registry reference), since the bridge has no prompt registry.
+ *
+ * The LLM gateway itself is **not** carried: the Rust agent path builds its own
+ * gateway (env adapters or a deterministic mock). A graph whose agents rely on a
+ * specific TS `AgentNodeConfig.llm` therefore keeps its semantics only on the TS
+ * engine; the Rust path is opt-in for agents (see `CompiledGraph`).
+ */
+type RustAgentConfig = {
+    provider: string;
+    model?: string;
+    /**
+     * Abstract capability tier carried to the Rust `AgentSpec.tier`. When set with no
+     * explicit `model`, the Rust bridge resolves the concrete model via `ModelPolicy`
+     * against the process env. An explicit `model` always wins.
+     */
+    tier?: ModelTier;
+    /** Resolved system prompt string. */
+    system?: string;
+    toolNames: string[];
+    maxIterations?: number;
+    suspendForApproval: boolean;
+    /** Tools (by name) requiring approval — those marked `requiresApproval`. */
+    approvalToolNames: string[];
+    outputChannel: string;
+    /** JS-backed tool executes, one per tool in the registry. */
+    toolBindings: RustToolBinding[];
+    /**
+     * SDK-only (never serialized to the wire): whether this agent node was configured
+     * with a TS {@link ApprovalEngine}. The engine-backed approval flow — filing a
+     * request per gated tool and reading the engine's decision on resume — lives in the
+     * TS `createAgentNodeHandler`; the Rust agent path does not invoke it. So a graph
+     * with an `approvalEngine` keeps its agent nodes on the TS engine under `auto`.
+     */
+    usesApprovalEngine: boolean;
+};
+/**
+ * The governance binding an agent node contributes to {@link CompiledGraph}: the
+ * (optional) {@link ApprovalEngine} a human resolves requests through, the principal
+ * that *requests* approvals on this node's behalf (`config.name ?? nodeId`, the same
+ * `requestedBy` the node files requests under), and the names of its approval-gated
+ * tools. {@link CompiledGraph.approveAndResume} uses it to (a) approve the matching
+ * pending engine requests before resuming on the TS path, and (b) stamp each granted
+ * tool's `requestedBy` for the Rust engine's no-self-approval guard-rail.
+ */
+type AgentApprovalBinding = {
+    approvalEngine?: ApprovalEngine;
+    requestedBy: string;
+    approvalToolNames: string[];
+};
+/** Project an {@link AgentNodeConfig} into its {@link AgentApprovalBinding}. */
+declare const toAgentApprovalBinding: (nodeId: string, config: AgentNodeConfig) => AgentApprovalBinding;
+/**
+ * Project an {@link AgentNodeConfig} into the {@link RustAgentConfig} the Rust engine
+ * bridge consumes. Resolves the system prompt to a concrete string and pulls the tool
+ * names / approval flags / executes out of the registry. Pure — no LLM call.
+ */
+declare const toRustAgentConfig: (nodeId: string, config: AgentNodeConfig) => RustAgentConfig;
+/** Config for {@link streamAgentTokens}. */
+type StreamAgentConfig = {
+    llm: LLMGateway;
+    prompt: AgentPromptSource;
+    provider?: LLMProvider;
+    model?: string;
+};
+/**
+ * Stream an agent's reply token by token through the gateway's `stream()`. This is
+ * the single-turn (no-tools) path — ideal for a chat UI that wants live output.
+ * Yields text deltas as they arrive and returns when the provider signals done.
+ *
+ * ```ts
+ * for await (const delta of streamAgentTokens({ llm, prompt: { system } }, "Bonjour ?")) {
+ *   process.stdout.write(delta);
+ * }
+ * ```
+ */
+declare function streamAgentTokens(config: StreamAgentConfig, input: unknown): AsyncIterable<string>;
+declare const createAgentNodeHandler: (nodeId: string, config: AgentNodeConfig) => NodeHandler;
+/**
+ * Build the handler for a tool node: executes the tool calls emitted by the last
+ * AI message in the `messages` channel. Tools flagged `requiresApproval` suspend
+ * the run via a dynamic interrupt instead of executing.
+ */
+declare const createToolNodeHandler: (config: ToolNodeConfig) => NodeHandler;
+
+/**
+ * The component library surface: pure (no-LLM) compute building blocks addressable
+ * by a string `kind` plus a `params` object. Mirrors the Rust `adriane_components`
+ * library (`crates/components`) one-for-one in kind, params and behaviour.
+ *
+ * Each factory in {@link components} returns a {@link ComponentDescriptor}: the Phase
+ * C carrier the Rust engine needs (`{ kind, params }`, surfaced as the graph's
+ * `componentNodes` map) **and** a faithful TypeScript `handler` for the fallback path
+ * when the native addon is absent. The components are simple and pure, so the two
+ * implementations agree byte-for-byte on ASCII input.
+ *
+ * Use {@link GraphBuilder.component} to push a node carrying both:
+ *
+ * ```ts
+ * import { createGraph, components } from "@adriane-ai/graph-sdk";
+ *
+ * const app = createGraph({ name: "prompt" })
+ *   .channel("name", { type: "string", default: "" })
+ *   .channel("prompt", { type: "string", default: "" })
+ *   .component("build", components.promptBuilder({ template: "Hi {{name}}", into: "prompt" }))
+ *   .compile();
+ * ```
+ */
+
+/** The component kinds the library knows, matching `ComponentRegistry::kinds()`. */
+type ComponentKind = "promptBuilder" | "jsonValidator" | "outputParser" | "router" | "retriever" | "reranker" | "textCleaner" | "documentSplitter" | "htmlToText" | "csvParser" | "documentJoiner" | "deduplicator" | "truncator" | "regexExtractor" | "answerBuilder" | "fieldMapper" | "fieldExtractor" | "bm25Retriever" | "keywordRetriever" | "sentenceWindowSplitter" | "languageDetector" | "metadataFilter" | "listJoiner" | "mergeRanker" | "evaluator" | "chatMessageBuilder" | "conditionalRouter" | "documentWriter";
+/**
+ * The serializable projection of a component node the Rust engine bridge consumes
+ * (the Phase C `componentNodes` carrier, camelCase): a component `kind` plus its
+ * validated `params` object. Pure data — no closures.
+ */
+type RustComponentConfig = {
+    kind: ComponentKind;
+    params: Record<string, unknown>;
+};
+/**
+ * What a component factory returns: the Phase C carrier (`kind` + `params`) so the
+ * node runs natively on Rust, plus an equivalent TS {@link NodeHandler} for the
+ * fallback path. {@link GraphBuilder.component} pushes a node from this descriptor.
+ */
+type ComponentDescriptor = RustComponentConfig & {
+    /** The faithful TS-equivalent handler used when the native addon is absent. */
+    handler: NodeHandler;
+};
+/**
+ * What an **integration component** factory returns (the vendor-I/O pattern, e.g.
+ * {@link components.httpFetch} / {@link components.webSearch}). Unlike a
+ * {@link ComponentDescriptor}, an integration component is **not** a Rust component:
+ * it has no `kind`/`params` carrier and is **not** registered in `componentNodes`.
+ * It is a plain `NodeHandler` (an injectable closure over an injected I/O impl) added
+ * as a regular JS node via {@link import("./builder.js").GraphBuilder.node}; on the
+ * Rust engine it runs over the async JS seam (`on_node`) like any other JS handler.
+ *
+ * ```ts
+ * createGraph({ name: "fetch" })
+ *   .channel("body", { type: "json", default: null })
+ *   .node("get", components.httpFetch({ url: "https://x", into: "body", fetchImpl: fake }));
+ * ```
+ */
+type IntegrationComponentHandler = NodeHandler;
+/** Params for {@link components.promptBuilder}. */
+type PromptBuilderParams = {
+    /** Template with `{{var}}` placeholders filled from the channels. */
+    template: string;
+    /** Channel the rendered string is written into. */
+    into: string;
+};
+/** Params for {@link components.jsonValidator}. */
+type JsonValidatorParams = {
+    /** Channel whose value is validated. */
+    from: string;
+    /** Required object keys to assert present. */
+    requiredKeys?: string[];
+    /** Expected JSON type (`"object" | "array" | "string" | ...`). */
+    expectType?: "string" | "number" | "boolean" | "object" | "array" | "null";
+    /** Channel receiving the `boolean` validity flag. */
+    okInto: string;
+    /** Channel receiving the `string[]` of validation errors. */
+    errorsInto: string;
+};
+/** Params for {@link components.outputParser}. */
+type OutputParserParams = {
+    /** Text channel to extract the first JSON value from. */
+    from: string;
+    /** Channel receiving the parsed value (or `null` when none is found). */
+    into: string;
+};
+/** One routing rule for {@link components.router}. */
+type RouterRule = {
+    /** Exact match against the textual form of the `from` value. */
+    equals?: string;
+    /** Substring match against the textual form of the `from` value. */
+    contains?: string;
+    /** The route string emitted when this rule matches. */
+    route: string;
+};
+/** Params for {@link components.router}. */
+type RouterParams = {
+    /** Channel whose value is matched against the rules. */
+    from: string;
+    /** Ordered rules; the first match wins. */
+    rules: RouterRule[];
+    /** Route emitted when no rule matches. */
+    defaultRoute: string;
+    /** Channel the chosen route string is written into. */
+    into: string;
+};
+/** A candidate document for {@link components.retriever}. */
+type RetrieverDoc = {
+    id: string;
+    content: string;
+};
+/** Params for {@link components.retriever}. */
+type RetrieverParams = {
+    /** Channel holding the query text (falls back to this literal when the channel is empty). */
+    query: string;
+    /** Channel receiving the top-`k` `{ id, content, score }` array. */
+    into: string;
+    /** Number of results to keep (default 4). */
+    k?: number;
+    /** The corpus to score against. */
+    docs: RetrieverDoc[];
+};
+/** Params for {@link components.reranker}. */
+type RerankerParams = {
+    /** Channel holding the retrieval-result array to reorder. */
+    from: string;
+    /** Channel receiving the reordered array. */
+    into: string;
+    /** Optional channel holding query text for embedding-based re-scoring. */
+    query?: string;
+};
+/** Params for {@link components.textCleaner}. */
+type TextCleanerParams = {
+    /** Channel whose text is normalised. */
+    from: string;
+    /** Channel receiving the cleaned text. */
+    into: string;
+    /** Lowercase the text. Defaults to `false`. */
+    lowercase?: boolean;
+    /** Strip `<…>` HTML tags. Defaults to `false`. */
+    stripHtml?: boolean;
+    /** Collapse runs of whitespace to a single space. Defaults to `false`. */
+    collapseWhitespace?: boolean;
+    /** Trim leading/trailing whitespace. Defaults to `false`. */
+    trim?: boolean;
+};
+/** Params for {@link components.documentSplitter}. */
+type DocumentSplitterParams = {
+    /** Channel holding the text to split. */
+    from: string;
+    /** Channel receiving the `string[]` of chunks. */
+    into: string;
+    /** Split unit: `"chars"` sliding windows or greedy `"sentences"` packing. */
+    by: "chars" | "sentences";
+    /** Window size in characters (`by:"chars"`) or sentences (`by:"sentences"`). Must be > 0. */
+    size: number;
+    /** Overlap repeated at the start of each next chunk. Must be smaller than `size`. Defaults to 0. */
+    overlap?: number;
+};
+/** Params for {@link components.htmlToText}. */
+type HtmlToTextParams = {
+    /** Channel holding the HTML text. */
+    from: string;
+    /** Channel receiving the tag-stripped, entity-decoded text. */
+    into: string;
+};
+/** Params for {@link components.csvParser}. */
+type CsvParserParams = {
+    /** Channel holding the CSV text. */
+    from: string;
+    /** Channel receiving the parsed rows array. */
+    into: string;
+    /** Single-character cell delimiter. Defaults to `","`. */
+    delimiter?: string;
+    /** When `true` (default) the first row supplies object keys; otherwise rows are arrays. */
+    header?: boolean;
+};
+/** Params for {@link components.documentJoiner}. */
+type DocumentJoinerParams = {
+    /** Channels whose array values are concatenated in order. */
+    fromChannels: string[];
+    /** Channel receiving the merged array. */
+    into: string;
+    /** Optional object field to de-duplicate the merged items by. */
+    dedupeBy?: string;
+};
+/** Params for {@link components.deduplicator}. */
+type DeduplicatorParams = {
+    /** Channel holding the array to de-duplicate. */
+    from: string;
+    /** Channel receiving the de-duplicated array. */
+    into: string;
+    /** Optional object field to compare items by (else whole-value compare). */
+    key?: string;
+};
+/** Params for {@link components.truncator}. */
+type TruncatorParams = {
+    /** Channel holding the text to truncate. */
+    from: string;
+    /** Channel receiving the (possibly truncated) text. */
+    into: string;
+    /** Maximum character length (the ellipsis counts against this budget). */
+    maxChars: number;
+    /** Suffix appended when truncated. Defaults to `"…"`. */
+    ellipsis?: string;
+};
+/** Params for {@link components.regexExtractor}. */
+type RegexExtractorParams = {
+    /** Channel holding the text to match against. */
+    from: string;
+    /** Channel receiving the match (or matches when `all`). */
+    into: string;
+    /**
+     * Literal-substring pattern with optional leading `^` (start) and trailing `$`
+     * (end) anchors. No character classes / quantifiers / capture groups.
+     */
+    pattern: string;
+    /** Accepted for forward-compat; only `0` (the whole match) is supported. Defaults to 0. */
+    group?: number;
+    /** When `true`, return every non-overlapping occurrence as an array. Defaults to `false`. */
+    all?: boolean;
+};
+/** Params for {@link components.answerBuilder}. */
+type AnswerBuilderParams = {
+    /** Channel supplying the core answer text. */
+    from: string;
+    /** Channel receiving the assembled answer. */
+    into: string;
+    /** Optional channel holding a retrieval-result array rendered as numbered citations. */
+    contextFrom?: string;
+    /** Optional `{{answer}}`/`{{citations}}` template controlling the layout. */
+    template?: string;
+};
+/** Params for {@link components.fieldMapper}. */
+type FieldMapperParams = {
+    /** Channel holding the source object. */
+    from: string;
+    /** Channel receiving the remapped object. */
+    into: string;
+    /** `{ outKey: inKeyPath }` map; `inKeyPath` is a dotted path into the source. */
+    mapping: Record<string, string>;
+};
+/** Params for {@link components.fieldExtractor}. */
+type FieldExtractorParams = {
+    /** Channel holding the source value. */
+    from: string;
+    /** Channel receiving the extracted scalar. */
+    into: string;
+    /** Optional dotted path descended into the `from` value (else the whole value). */
+    path?: string;
+    /**
+     * When `true`, if the resulting value is a string containing a `"final:"` marker,
+     * return only the text after the **last** `"final:"` (trimmed) — reduces an
+     * agent reasoning trace to its final answer. Non-strings pass through. Defaults to `false`.
+     */
+    finalOnly?: boolean;
+};
+/** A candidate document for the lexical retrievers. */
+type LexicalDoc = {
+    id: string;
+    content: string;
+};
+/** Params for {@link components.bm25Retriever}. */
+type Bm25RetrieverParams = {
+    /** Channel holding the query text (falls back to this literal when empty). */
+    query: string;
+    /** Channel receiving the top-`k` `{ id, content, score }` array. */
+    into: string;
+    /** Number of results to keep (default 4). */
+    k?: number;
+    /** The corpus to rank. */
+    docs: LexicalDoc[];
+    /** BM25 term-frequency saturation. Defaults to 1.2. */
+    k1?: number;
+    /** BM25 length-normalization. Defaults to 0.75. */
+    b?: number;
+};
+/** Params for {@link components.keywordRetriever}. */
+type KeywordRetrieverParams = {
+    /** Channel holding the query text (falls back to this literal when empty). */
+    query: string;
+    /** Channel receiving the top-`k` `{ id, content, score }` array. */
+    into: string;
+    /** Number of results to keep (default 4). */
+    k?: number;
+    /** The corpus to rank. */
+    docs: LexicalDoc[];
+};
+/** Params for {@link components.sentenceWindowSplitter}. */
+type SentenceWindowSplitterParams = {
+    /** Channel holding the text to split. */
+    from: string;
+    /** Channel receiving the `string[]` of overlapping sentence windows. */
+    into: string;
+    /** Sentences per window. Defaults to 3. */
+    windowSize?: number;
+    /** Sentences advanced between windows (`1 <= stride <= windowSize`). Defaults to 1. */
+    stride?: number;
+};
+/** Params for {@link components.languageDetector}. */
+type LanguageDetectorParams = {
+    /** Channel holding the text to classify. */
+    from: string;
+    /** Channel receiving the detected language code (`"en" | "fr" | ... | "und"`). */
+    into: string;
+    /** Optional channel receiving the winning language's share of hits in `[0, 1]`. */
+    confidenceInto?: string;
+};
+/** A predicate operator shared by {@link components.metadataFilter} and {@link components.conditionalRouter}. */
+type PredicateOp = "equals" | "notEquals" | "contains" | "exists" | "absent" | "gt" | "gte" | "lt" | "lte";
+/** Params for {@link components.metadataFilter}. */
+type MetadataFilterParams = {
+    /** Channel holding the array to filter. */
+    from: string;
+    /** Channel receiving the filtered array. */
+    into: string;
+    /** Dotted path into each item compared by the predicate. */
+    field: string;
+    /** The predicate operator. */
+    op: PredicateOp;
+    /** The comparison value (required except for `exists`/`absent`). */
+    value?: unknown;
+};
+/** Params for {@link components.listJoiner}. */
+type ListJoinerParams = {
+    /** Channels whose array values are combined. */
+    fromChannels: string[];
+    /** Channel receiving the combined array. */
+    into: string;
+    /** Combine mode: `"concat"` (default), `"union"` (dedupe), or `"interleave"`. */
+    mode?: "concat" | "union" | "interleave";
+};
+/** Params for {@link components.mergeRanker}. */
+type MergeRankerParams = {
+    /** Channels each holding a retrieval-result array to fuse. */
+    fromChannels: string[];
+    /** Channel receiving the fused `{ id, content, score }` array. */
+    into: string;
+    /** Object field identifying items across lists. Defaults to `"id"`. */
+    idKey?: string;
+    /** Keep only the top-`k` fused results (default: keep all). */
+    k?: number;
+    /** Reciprocal Rank Fusion constant. Defaults to 60. */
+    rrfK?: number;
+};
+/** Params for {@link components.evaluator}. */
+type EvaluatorParams = {
+    /** Channel holding the expected/reference text. */
+    expectedFrom: string;
+    /** Channel holding the actual/candidate text. */
+    actualFrom: string;
+    /** Channel receiving the numeric score in `[0, 1]`. */
+    into: string;
+    /** Scoring metric. Defaults to `"tokenF1"`. */
+    metric?: "tokenF1" | "overlap" | "exact";
+    /** Optional channel receiving a boolean `score >= threshold`. */
+    passInto?: string;
+    /** Pass threshold for `passInto`. Defaults to 0.5. */
+    threshold?: number;
+};
+/** One message spec for {@link components.chatMessageBuilder}. */
+type ChatMessageSpec = {
+    /** The message role. */
+    role: "system" | "user" | "assistant";
+    /** A literal body, rendered through the `{{var}}` template engine. */
+    content?: string;
+    /** A channel name whose value supplies the body verbatim. */
+    contentFrom?: string;
+};
+/** Params for {@link components.chatMessageBuilder}. */
+type ChatMessageBuilderParams = {
+    /** Channel receiving the `[{ role, content }]` array. */
+    into: string;
+    /** The ordered message specs. */
+    messages: ChatMessageSpec[];
+    /** Optional channel prepended as a leading system message when non-empty. */
+    systemFrom?: string;
+};
+/** One branch for {@link components.conditionalRouter}. */
+type ConditionalRouterBranch = {
+    /** The predicate evaluated against the channels (`field` is a dotted path). */
+    when: {
+        field: string;
+        op: PredicateOp;
+        value?: unknown;
+    };
+    /** The route string emitted when `when` holds. */
+    route: string;
+};
+/** Params for {@link components.conditionalRouter}. */
+type ConditionalRouterParams = {
+    /** Channel the chosen route string is written into. */
+    into: string;
+    /** Route emitted when no branch matches. */
+    defaultRoute: string;
+    /** Ordered branches; the first matching branch wins. */
+    branches: ConditionalRouterBranch[];
+};
+/** Params for {@link components.documentWriter}. */
+type DocumentWriterParams = {
+    /** Channel holding the incoming documents array to append. */
+    from: string;
+    /** Channel receiving the accumulated store array. */
+    into: string;
+    /** Channel holding the current store. Defaults to `into`. */
+    store?: string;
+    /** Optional object field to de-duplicate the merged store by. */
+    dedupeBy?: string;
+};
+/**
+ * The result of an HTTP fetch surfaced into the `into` channel.
+ *
+ * The default impl never throws on a non-2xx response or a transport error — a
+ * failure is surfaced as data so a graph degrades gracefully instead of crashing
+ * the run:
+ *  - on a completed response: `{ status, ok, body, json }` (`json` is the parsed
+ *    body when the `content-type` is JSON, else `undefined`; `ok` mirrors
+ *    `Response.ok`, i.e. a 2xx status);
+ *  - on a transport error / timeout: `{ ok: false, error }` (`status`/`body` absent).
+ */
+type HttpFetchResult = {
+    /** The HTTP status code, when a response was received. */
+    status?: number;
+    /** `true` for a 2xx response; `false` on a non-2xx response or a transport error. */
+    ok: boolean;
+    /** The response body as text, when a response was received. */
+    body?: string;
+    /** The parsed JSON body, present only when the response `content-type` was JSON. */
+    json?: unknown;
+    /** The error message, present only on a transport error / timeout. */
+    error?: string;
+};
+/**
+ * The transport an {@link HttpFetchImpl} is invoked with: the resolved URL plus the
+ * request options the default impl assembled from the params (method/headers/body/
+ * the abort `signal` driving the timeout). Mirrors the `(input, init)` shape of the
+ * WHATWG `fetch`, so `globalThis.fetch` is itself a valid impl.
+ */
+type HttpFetchRequestInit = {
+    method: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+};
+/**
+ * An injectable fetch implementation. Receives the resolved URL and the assembled
+ * request init, and must resolve to something `Response`-shaped (`status`, `ok`,
+ * `text()`, `headers.get()`). The real `globalThis.fetch` satisfies this — the
+ * default impl simply calls it — so a test can inject a fake `Response`-like object.
+ */
+type HttpFetchImpl = (url: string, init: HttpFetchRequestInit) => Promise<HttpFetchResponseLike> | HttpFetchResponseLike;
+/** The minimal `Response`-shaped surface the default httpFetch impl consumes. */
+type HttpFetchResponseLike = {
+    status: number;
+    ok: boolean;
+    text(): Promise<string> | string;
+    headers: {
+        get(name: string): string | null;
+    };
+};
+/** Params for {@link components.httpFetch}. */
+type HttpFetchParams = {
+    /** A literal URL to fetch (mutually exclusive with `urlFrom`). */
+    url?: string;
+    /** A channel whose value supplies the URL (takes precedence when its channel is set). */
+    urlFrom?: string;
+    /** Channel receiving the {@link HttpFetchResult}. */
+    into: string;
+    /** HTTP method. Defaults to `"GET"`. */
+    method?: string;
+    /** Request headers sent with the call. */
+    headers?: Record<string, string>;
+    /** Request body (sent verbatim) for non-GET methods. */
+    body?: string;
+    /** Abort the request after this many milliseconds (drives an `AbortController`). */
+    timeoutMs?: number;
+    /**
+     * The transport to call. Defaults to the real `globalThis.fetch`. Inject a fake
+     * (a `Response`-like returning function) to keep a test offline, or to point the
+     * call at a stub transport.
+     */
+    fetchImpl?: HttpFetchImpl;
+};
+/** One web-search result: a title, a url and a snippet. */
+type WebSearchResult = {
+    title: string;
+    url: string;
+    snippet: string;
+};
+/**
+ * What the web-search connector writes into the `into` channel: the normalized
+ * `results` plus an optional `note`. The default connector populates `note` when it
+ * degrades gracefully (e.g. no `TAVILY_API_KEY`), leaving `results` empty so a graph
+ * runs without crashing.
+ */
+type WebSearchOutcome = {
+    results: WebSearchResult[];
+    note?: string;
+};
+/**
+ * An injectable web-search implementation. Receives the query + `k`, returns either a
+ * bare `WebSearchResult[]` (which is wrapped as `{ results }`) or a full
+ * {@link WebSearchOutcome} (so an impl can attach its own `note`).
+ */
+type WebSearchImpl = (query: string, k: number) => Promise<WebSearchResult[] | WebSearchOutcome> | WebSearchResult[] | WebSearchOutcome;
+/**
+ * The minimal transport the default Tavily connector posts through: a function with
+ * the WHATWG `fetch` `(url, init)` shape resolving to a `Response`-like object. The
+ * real `globalThis.fetch` satisfies it; a test injects a fake to stay offline.
+ */
+type WebSearchTransport = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<HttpFetchResponseLike> | HttpFetchResponseLike;
+/** Params for {@link components.webSearch}. */
+type WebSearchParams = {
+    /** A literal query (mutually exclusive with `queryFrom`). */
+    query?: string;
+    /** A channel whose value supplies the query (takes precedence when its channel is set). */
+    queryFrom?: string;
+    /** Channel receiving the {@link WebSearchOutcome}. */
+    into: string;
+    /** Number of results to request. Defaults to 3. */
+    k?: number;
+    /**
+     * The search implementation to call. Defaults to a real Tavily connector behind the
+     * `TAVILY_API_KEY` env var: when the key is set it POSTs to the Tavily API; when it
+     * is absent it degrades gracefully (no network, empty results + a note). Inject a
+     * fake to keep a test offline or to point at another provider.
+     */
+    searchImpl?: WebSearchImpl;
+    /**
+     * The HTTP transport the default Tavily connector posts through. Defaults to the real
+     * `globalThis.fetch`. Inject a fake to exercise the connector offline. Ignored when
+     * `searchImpl` is supplied.
+     */
+    transport?: WebSearchTransport;
+};
+/**
+ * The component factory surface. Each factory validates nothing here (the Rust
+ * `ComponentRegistry::build_handler` validates `params` at graph-build time, and the
+ * TS handlers tolerate the same shapes), returning a {@link ComponentDescriptor}
+ * carrying both the native carrier and a faithful TS handler.
+ */
+declare const components: {
+    /** Render `{{var}}` placeholders from the channels into a target channel. */
+    readonly promptBuilder: (params: PromptBuilderParams) => ComponentDescriptor;
+    /** Validate a channel value's type / required keys, writing an ok flag + errors. */
+    readonly jsonValidator: (params: JsonValidatorParams) => ComponentDescriptor;
+    /** Extract the first JSON object/array from a text channel into a target channel. */
+    readonly outputParser: (params: OutputParserParams) => ComponentDescriptor;
+    /** Pick a route string from a channel value (pairs with a conditional edge). */
+    readonly router: (params: RouterParams) => ComponentDescriptor;
+    /** Score candidate docs against a query and keep the top-`k`. */
+    readonly retriever: (params: RetrieverParams) => ComponentDescriptor;
+    /** Reorder a retrieval-result array, optionally re-scoring against a query. */
+    readonly reranker: (params: RerankerParams) => ComponentDescriptor;
+    /** Normalise a text channel: strip HTML, lowercase, collapse whitespace, trim. */
+    readonly textCleaner: (params: TextCleanerParams) => ComponentDescriptor;
+    /** Split a text channel into an array of chunk strings by chars or sentences. */
+    readonly documentSplitter: (params: DocumentSplitterParams) => ComponentDescriptor;
+    /** Strip HTML tags from a text channel and decode the common named entities. */
+    readonly htmlToText: (params: HtmlToTextParams) => ComponentDescriptor;
+    /** Parse a CSV text channel into an array of row objects (or arrays). */
+    readonly csvParser: (params: CsvParserParams) => ComponentDescriptor;
+    /** Concatenate the array values across several channels into one merged array. */
+    readonly documentJoiner: (params: DocumentJoinerParams) => ComponentDescriptor;
+    /** De-duplicate an array channel, keeping the first occurrence and order. */
+    readonly deduplicator: (params: DeduplicatorParams) => ComponentDescriptor;
+    /** Truncate a text channel to at most `maxChars` characters with an ellipsis. */
+    readonly truncator: (params: TruncatorParams) => ComponentDescriptor;
+    /** Extract literal-pattern matches (with `^`/`$` anchors) from a text channel. */
+    readonly regexExtractor: (params: RegexExtractorParams) => ComponentDescriptor;
+    /** Assemble a final answer string, optionally appending numbered citations. */
+    readonly answerBuilder: (params: AnswerBuilderParams) => ComponentDescriptor;
+    /** Remap an object channel's fields (by dotted path) into a new object. */
+    readonly fieldMapper: (params: FieldMapperParams) => ComponentDescriptor;
+    /** Extract a scalar from a channel (optional dotted path; finalOnly reduces an agent trace to its final answer). */
+    readonly fieldExtractor: (params: FieldExtractorParams) => ComponentDescriptor;
+    /** Lexical BM25 ranking of a corpus against a query; keep the top-`k`. */
+    readonly bm25Retriever: (params: Bm25RetrieverParams) => ComponentDescriptor;
+    /** Keyword-overlap ranking of a corpus against a query; keep the top-`k`. */
+    readonly keywordRetriever: (params: KeywordRetrieverParams) => ComponentDescriptor;
+    /** Split text into overlapping windows of whole sentences. */
+    readonly sentenceWindowSplitter: (params: SentenceWindowSplitterParams) => ComponentDescriptor;
+    /** Heuristic language detection over a small set of common languages. */
+    readonly languageDetector: (params: LanguageDetectorParams) => ComponentDescriptor;
+    /** Filter an array channel by a dotted-path metadata predicate. */
+    readonly metadataFilter: (params: MetadataFilterParams) => ComponentDescriptor;
+    /** Combine several array channels by concat / union / interleave. */
+    readonly listJoiner: (params: ListJoinerParams) => ComponentDescriptor;
+    /** Fuse several retrieval streams into one ranking with Reciprocal Rank Fusion. */
+    readonly mergeRanker: (params: MergeRankerParams) => ComponentDescriptor;
+    /** Score actual vs expected text (token-F1 / overlap / exact), with an optional pass flag. */
+    readonly evaluator: (params: EvaluatorParams) => ComponentDescriptor;
+    /** Assemble a role-tagged chat-message array an LLM generator consumes. */
+    readonly chatMessageBuilder: (params: ChatMessageBuilderParams) => ComponentDescriptor;
+    /** Multi-branch rule routing over the channels (pairs with a conditional edge). */
+    readonly conditionalRouter: (params: ConditionalRouterParams) => ComponentDescriptor;
+    /** Append documents into an in-state document store array (optionally de-duplicating). */
+    readonly documentWriter: (params: DocumentWriterParams) => ComponentDescriptor;
+    /**
+     * **Integration component (vendor I/O).** Perform an HTTP request, writing an
+     * {@link HttpFetchResult} (`{ status, ok, body, json }`) to `into`. This is **not**
+     * a Rust component: it returns a plain {@link NodeHandler} added with
+     * {@link import("./builder.js").GraphBuilder.node} and runs over the JS seam on the
+     * Rust engine. The default transport is the real `globalThis.fetch` (supports
+     * `method`/`headers`/`body`/`timeoutMs` via an `AbortController`); it never throws —
+     * a non-2xx is surfaced via `ok`/`status`, and an error/timeout writes
+     * `{ ok: false, error }`. Inject `fetchImpl` to override the transport (e.g. offline
+     * in tests).
+     */
+    readonly httpFetch: (params: HttpFetchParams) => IntegrationComponentHandler;
+    /**
+     * **Integration component (vendor I/O).** Run a web search, writing a
+     * {@link WebSearchOutcome} (`{ results, note? }`) to `into`. This is **not** a Rust
+     * component: it returns a plain {@link NodeHandler} added with
+     * {@link import("./builder.js").GraphBuilder.node} and runs over the JS seam on the
+     * Rust engine. The default is a real Tavily connector behind `TAVILY_API_KEY`
+     * (POSTs to `https://api.tavily.com/search`, normalizing results to
+     * `[{ title, url, snippet }]`); when the key is absent it degrades gracefully with
+     * **no** network call (empty results + a note). Inject `searchImpl` to override the
+     * provider, or `transport` to keep the Tavily connector offline.
+     */
+    readonly webSearch: (params: WebSearchParams) => IntegrationComponentHandler;
+};
+
+/** A map of channel name → value type. The generic that flows through the builder. */
+type ChannelValues = Record<string, unknown>;
+/** The starting (channel-less) state of a fresh {@link import("./builder.js").GraphBuilder}. */
+type EmptyChannels = Record<never, never>;
+/** {@link GraphState} with strongly-typed channels. */
+type TypedGraphState<TState extends ChannelValues> = Omit<GraphState, "channels"> & {
+    channels: TState;
+};
+/**
+ * What a node handler may return: a partial update to the declared channels
+ * (type-checked) plus any additional keys (the runtime passes unknown keys
+ * through), or a routing {@link Command}.
+ */
+type ChannelUpdate<TState extends ChannelValues> = (Partial<TState> & Record<string, unknown>) | Command;
+/** A node handler with strongly-typed state and return value. */
+type TypedNodeHandler<TState extends ChannelValues> = (input: unknown, state: TypedGraphState<TState>, context: NodeExecutionContext) => Promise<ChannelUpdate<TState>>;
+/** A conditional-edge predicate over strongly-typed state. */
+type TypedCondition<TState extends ChannelValues> = (state: TypedGraphState<TState>) => boolean;
+/** Initial data accepted by a run: declared channels (typed) plus arbitrary extras. */
+type InitialData<TState extends ChannelValues> = Partial<TState> & Record<string, unknown>;
+
+/** Options for {@link CompiledGraph.approveAndResume}. */
+type ApproveAndResumeOptions = {
+    /** Names of approval-gated tools the human has granted. They execute on resume. */
+    approvedTools: string[];
+    /**
+     * The principal granting the approval — a human, NEVER the agent that requested it.
+     * It is recorded as each granted tool's `resolvedBy` and carried to the Rust engine,
+     * which rejects the resume if it is empty or equals the tool's requester (the
+     * no-self-approval guard-rail). On the TS path, when an agent node was configured with
+     * an {@link import("@adriane-ai/approval-engine").ApprovalEngine}, the matching pending
+     * requests are approved through the engine under this principal before resuming — so
+     * the engine's own `ensureCanResolve` enforces the same invariant. Defaults to
+     * `"human"` when omitted.
+     */
+    resolvedBy?: string;
+};
+/** Wiring assembled by {@link GraphBuilder.compile} and handed to a {@link CompiledGraph}. */
+type CompiledGraphParts = {
+    definition: GraphDefinition;
+    handlers: Map<string, NodeHandler>;
+    conditions: Map<string, ConditionFn>;
+    /**
+     * Per agent node, the serializable config + JS tool executes the Rust engine bridge
+     * needs (see {@link RustAgentConfig}). Empty for graphs with no agent nodes.
+     */
+    agentConfigs?: Map<string, RustAgentConfig>;
+    /**
+     * Per agent node, the governance binding (the optional {@link ApprovalEngine} plus
+     * the principal that requests approvals and the node's gated tool names) that
+     * {@link CompiledGraph.approveAndResume} uses to approve pending engine requests on
+     * the TS path and to stamp each granted tool's `requestedBy` for the Rust guard-rail.
+     * Empty for graphs with no agent nodes.
+     */
+    agentApprovals?: Map<string, AgentApprovalBinding>;
+    /**
+     * Per component node, the `{ kind, params }` carrier the Rust engine bridge needs to
+     * run the native component handler (see {@link RustComponentConfig}). Empty for
+     * graphs with no component nodes.
+     */
+    componentConfigs?: Map<string, RustComponentConfig>;
+};
+/** Options accepted by {@link CompiledGraph.run} / {@link CompiledGraph.stream}. */
+type RunOptions = {
+    /** Provide a stable run id (e.g. to correlate with an external system). */
+    runId?: RunId;
+};
+/**
+ * A validated, runnable graph. Holds the engine wiring (registries, checkpointer,
+ * event bus, runtime) so callers don't touch the lower-level `@adriane-ai/graph-runtime`
+ * primitives unless they want to.
+ *
+ * Execution runs on the **Rust engine** via `@adriane-ai/napi` when the native addon is
+ * present and the graph is one Rust can run faithfully; otherwise it falls back to
+ * the in-process TypeScript {@link GraphRuntime}. The public API is identical either
+ * way — `run` / `resume` / `approveAndResume` / `stream` / `onEvent` behave the same.
+ */
+declare class CompiledGraph<TState extends ChannelValues = ChannelValues> {
+    readonly definition: GraphDefinition;
+    private readonly checkpointer;
+    private readonly eventBus;
+    private readonly runtime;
+    /**
+     * The Rust runner, when this graph runs on the Rust engine; else `null` (TS path).
+     * Typed on `ChannelValues` (not `TState`) on purpose: the runner round-trips state as
+     * serialized `GraphState`/JSON, so it never needs the precise channel shape — and
+     * keeping `TState` out of every *field* keeps `CompiledGraph<TState>` variance-friendly
+     * (a `CompiledGraph<Specific>` stays assignable to `CompiledGraph<ChannelValues>`,
+     * e.g. when stored in a heterogeneous registry). The public methods re-narrow to
+     * `TState` at their boundary.
+     */
+    private readonly rustRunner;
+    /** The last suspended state seen per run id, fed back into the Rust resume/approve. */
+    private readonly suspendedStates;
+    /** Per agent node, the governance binding used by {@link approveAndResume}. */
+    private readonly agentApprovals;
+    constructor(parts: CompiledGraphParts);
+    /**
+     * Decide whether this graph runs on the Rust engine and, if so, build the runner.
+     *
+     * Since Phase F the napi seam **awaits** a callback's returned `Promise`, so the
+     * SDK's genuinely-async JS node handlers and tool `execute` fns round-trip through
+     * Rust faithfully — the old "synchronous seam" limitation is gone. Two boundaries
+     * remain, and they shape the `"auto"` policy:
+     *
+     * 1. The Rust agent path builds its **own** LLM gateway from env (Mistral / Anthropic
+     *    / Ollama / a deterministic mock); it does *not* use the TS `AgentNodeConfig.llm`.
+     *    That is the intended "engine on Rust" behavior (the proven live path). The TS
+     *    `llm` is consulted only on the TS fallback path. Observable *structure* (final
+     *    status, suspend-on-approval, approve-and-resume, lifecycle events) is identical
+     *    across engines on the deterministic mock — proven by the fidelity test in
+     *    `rust-engine.test.ts`. Only the `AgentResult.reasoning` *text* differs (the two
+     *    mocks emit different strings), which is not part of the structural contract.
+     * 2. The TS {@link import("@adriane-ai/approval-engine").ApprovalEngine}-backed approval
+     *    flow (file a request per gated tool, read the engine's decision on resume) lives
+     *    in `createAgentNodeHandler`; the Rust agent path does not invoke it. So an agent
+     *    node configured with `approvalEngine` would not file requests on Rust.
+     *
+     * Therefore `"auto"` (the default) routes a graph to Rust when the addon is present
+     * **unless** any agent node uses a TS `approvalEngine` — that one case stays on the
+     * TS engine to preserve the engine-backed approval semantics. Everything else (agent
+     * nodes on the Rust gateway, JS action/custom/tool nodes, human gates, named
+     * conditions, channel-based `approveAndResume`) runs on Rust. When the addon is
+     * absent it falls back to the TS engine. `"rust"` forces Rust regardless (the caller
+     * accepts the Rust-gateway / no-`approvalEngine` contract); `"ts"` forces TypeScript.
+     * The public SDK API is unchanged across engines.
+     *
+     * Two narrower limitations are *not* gated on (they affect both `auto` and `rust`,
+     * but no SDK API surfaces them as a routing choice): a JS handler that returns a
+     * routing {@link import("@adriane-ai/graph-core").Command} (`{ goto }`) has its `goto`
+     * dropped on Rust (the seam applies a channel update + static-edge routing — build a
+     * conditional edge instead); and a {@link GraphBuilder.toolNode} whose tool is
+     * `requiresApproval` *fails* rather than suspends on Rust (its handler throws a
+     * `DynamicInterrupt`, which the seam surfaces as a node failure, not a clean
+     * suspension). Route such graphs with `ADRIANE_SDK_ENGINE=ts` if you need them.
+     */
+    private maybeCreateRustRunner;
+    /**
+     * Adapt the (async) JS node handlers into the async producers the Rust seam needs.
+     * The Rust side awaits the returned promise, so a handler doing real async work
+     * round-trips faithfully. A handler that returns a routing {@link Command} (not a
+     * plain channel update) is coerced to an empty update — the Rust seam applies a
+     * channel-update map only; in-handler routing commands stay a TS-engine feature.
+     */
+    private buildNodeFns;
+    /** Async tool executes for every JS-backed tool across all agent nodes. */
+    private buildToolFns;
+    /** The named condition predicates, retyped for the Rust seam (already synchronous). */
+    private buildConditionFns;
+    /** True when this graph executes on the Rust engine. */
+    get usesRustEngine(): boolean;
+    /** Start a fresh run from the entry node and execute until completion or suspension. */
+    run(initialData?: InitialData<TState>, options?: RunOptions): Promise<TypedGraphState<TState>>;
+    /** Resume a previously suspended run from its latest checkpoint. */
+    resume(runId: RunId): Promise<TypedGraphState<TState>>;
+    /**
+     * Grant approval for the named tools and resume a run that suspended for approval
+     * (an agent node with `suspendForApproval`). On the Rust path the approved tools are
+     * written into `__approvedTools` by the engine before resuming; on the TS path the
+     * channel is updated directly. Either way the agent re-runs and executes the
+     * now-approved tools instead of gating them again. An agent never approves its own
+     * tools; this is the human seam.
+     */
+    approveAndResume(runId: RunId, options: ApproveAndResumeOptions): Promise<TypedGraphState<TState>>;
+    /**
+     * Project granted tool names into the wire shape the Rust engine validates: each
+     * tool carries the principal that requested it (the owning agent node) and the
+     * distinct principal granting it. Names are sorted so the wire payload is
+     * deterministic regardless of the caller's ordering.
+     */
+    private toApprovedToolWire;
+    /** The agent node that declared `toolName` as approval-gated, as the request principal. */
+    private requesterOfTool;
+    /**
+     * For each agent node with an {@link ApprovalEngine}, approve the pending requests
+     * whose gated tool is in `approvedTools`, through the engine, under `resolvedBy`. The
+     * engine rejects a self-approval, so this is the TS-side enforcement point that
+     * mirrors the Rust guard-rail.
+     */
+    private approvePendingThroughEngines;
+    /**
+     * Stream events as the graph executes. See {@link StreamMode} for the available
+     * shapes. The Rust engine has no incremental stream surface yet, so when running on
+     * Rust this drives a full run and yields a single terminal `state_value`. On the TS
+     * engine it streams natively.
+     */
+    stream(initialData: InitialData<TState>, mode: StreamMode, options?: RunOptions): AsyncIterable<StreamEvent>;
+    /** Single-shot stream for the Rust path: run to terminal state, emit it once. */
+    private streamViaRust;
+    /** Subscribe to the run-event lifecycle stream. Returns an unsubscribe function. */
+    onEvent(handler: (event: RunEvent) => void): () => void;
+    /**
+     * Escape hatch for the TS engine: the underlying runtime (time-travel, manual node
+     * execution). On the Rust path the runtime is present but **not** the executor; use
+     * {@link CompiledGraph.usesRustEngine} to branch, and the run-handle methods
+     * (`run` / `resume` / `approveAndResume`) which behave identically across engines.
+     */
+    get engine(): GraphRuntime;
+    /** Record a run's state if it suspended, so resume/approve can feed it back to Rust. */
+    private captureSuspension;
+    private requireSuspendedState;
+}
+
+/**
+ * Discriminated-union result type used across the SDK's "safe" entry points
+ * (e.g. {@link GraphBuilder.safeCompile}). Mirrors Zod's `safeParse` ergonomics.
+ */
+type Result<T, E> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: E;
+};
+/** Base class for every error thrown by `@adriane-ai/graph-sdk`. */
+declare class AdrianeSdkError extends Error {
+    constructor(message: string);
+}
+/** Thrown when `.compile()` is called on a graph that fails validation. */
+declare class GraphCompileError extends AdrianeSdkError {
+    readonly errors: GraphValidationError[];
+    constructor(errors: GraphValidationError[]);
+}
+/** Thrown when two nodes are added under the same id. */
+declare class DuplicateNodeError extends AdrianeSdkError {
+    constructor(nodeId: string);
+}
+/** Thrown when an action node is added without an executable handler. */
+declare class MissingHandlerError extends AdrianeSdkError {
+    constructor(nodeId: string);
+}
+
+/** Options passed to {@link createGraph}. */
+type CreateGraphOptions = {
+    name: string;
+    /** Defaults to a slugified `name`. */
+    id?: string;
+    /** Semver-ish version string. Defaults to `"0.0.0"`. */
+    version?: string;
+    recursionLimit?: number;
+    metadata?: Record<string, unknown>;
+};
+/** Channel shorthand: `reducer` defaults to `"replace"`. The value type is inferred from `default`. */
+type ChannelInput<TValue = unknown> = {
+    type: string;
+    reducer?: ChannelReducer;
+    default?: TValue;
+};
+/** Config form for non-trivial nodes. A bare handler is the common case. */
+type NodeInput<TState extends ChannelValues> = {
+    type?: NodeType;
+    handler?: TypedNodeHandler<TState>;
+    label?: string;
+    retryPolicy?: RetryPolicy;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Fluent builder for an Adriane graph. Add channels, nodes and edges, then
+ * {@link GraphBuilder.compile} into a runnable {@link CompiledGraph}.
+ *
+ * The `TState` type parameter accumulates the declared channels as you call
+ * `.channel(...)`, so handler state and the result of `run`/`resume` are fully
+ * typed without any manual annotation.
+ *
+ * Conditions are always **named predicates** registered here — never `eval`'d
+ * strings — which is what keeps conditional routing safe and inspectable.
+ */
+declare class GraphBuilder<TState extends ChannelValues = EmptyChannels> {
+    private readonly options;
+    private readonly channels;
+    private readonly nodes;
+    private readonly edges;
+    private readonly handlers;
+    private readonly conditions;
+    /** Per agent node, the serializable config the Rust engine bridge needs. */
+    private readonly agentConfigs;
+    /** Per agent node, the governance binding (approval engine + requester) for resume. */
+    private readonly agentApprovals;
+    /** Per component node, the `{ kind, params }` carrier the Rust engine bridge needs. */
+    private readonly componentConfigs;
+    private entryNodeId;
+    constructor(options: CreateGraphOptions);
+    /** Reinterpret `this` under a wider channel type after declaring a new channel. */
+    private widen;
+    /** Declare a state channel. `reducer` defaults to `"replace"`; value type inferred from `default`. */
+    channel<TName extends string, TValue = unknown>(name: TName, definition: ChannelInput<TValue>): GraphBuilder<TState & {
+        [K in TName]: TValue;
+    }>;
+    /** Declare an append-reduced `messages` channel (the conversational default). */
+    messagesChannel<TName extends string = "messages">(name?: TName): GraphBuilder<TState & {
+        [K in TName]: Message[];
+    }>;
+    /** Shared node-registration path: dedupe, register the handler, default the entry. */
+    private pushNode;
+    /** Declare a channel only if it hasn't been declared yet (for node helpers that need one). */
+    private ensureChannel;
+    /** Add a node. Pass a handler for the common action case, or a config object. */
+    node(id: string, handlerOrConfig: TypedNodeHandler<TState> | NodeInput<TState>): this;
+    /** Convenience for a `human-gate` node that suspends the run for approval. */
+    humanGate(id: string, options?: {
+        label?: string;
+    }): this;
+    /**
+     * Add an agent node: a ReAct agent driven by an LLM gateway. Its result lands in
+     * `config.outputChannel` (default `"agentResult"`), which is auto-declared and
+     * added to the typed state. Route on `result.requiresHumanReview` to gate
+     * sensitive tool use.
+     */
+    agentNode<TOut extends string = typeof DEFAULT_AGENT_OUTPUT_CHANNEL>(id: string, config: AgentNodeConfig & {
+        outputChannel?: TOut;
+    }): GraphBuilder<TState & {
+        [K in TOut]: AgentResult;
+    }>;
+    /**
+     * Add a tool node: executes the tool calls emitted by the last AI message in the
+     * `messages` channel (auto-declared as an append-reduced messages channel).
+     */
+    toolNode(id: string, config: ToolNodeConfig): GraphBuilder<TState & {
+        messages: Message[];
+    }>;
+    /**
+     * Add a **component node**: a pure (no-LLM) compute building block from
+     * {@link import("./components.js").components} (e.g. `promptBuilder`, `router`,
+     * `retriever`). The node carries the Phase C carrier (`{ kind, params }`) so it runs
+     * natively on the Rust engine, *and* registers the descriptor's equivalent TS handler
+     * so the TS fallback path stays faithful when the native addon is absent.
+     *
+     * On the Rust path the component takes precedence over the JS seam even though its id
+     * is also a JS node id — the bridge routes a `componentNodes` entry to the native
+     * handler. So the node always runs the same logic on either engine.
+     *
+     * ```ts
+     * createGraph({ name: "p" })
+     *   .channel("name", { type: "string", default: "" })
+     *   .channel("prompt", { type: "string", default: "" })
+     *   .component("build", components.promptBuilder({ template: "Hi {{name}}", into: "prompt" }));
+     * ```
+     */
+    component(id: string, descriptor: ComponentDescriptor, options?: {
+        label?: string;
+    }): this;
+    /** Add an unconditional edge from one node to another. */
+    edge(from: string, to: string): this;
+    /**
+     * Add a conditional edge guarded by a named predicate. The predicate is
+     * registered under `conditionName` and evaluated against the live (typed) state.
+     */
+    conditionalEdge(from: string, to: string, conditionName: string, predicate: TypedCondition<TState>): this;
+    /** Override the entry node (defaults to the first node added). */
+    entry(nodeId: string): this;
+    private buildDefinition;
+    /** Validate and compile, returning a {@link Result} instead of throwing. */
+    safeCompile(): Result<CompiledGraph<TState>, GraphCompileError>;
+    /** Validate and compile into a runnable graph. Throws {@link GraphCompileError} on failure. */
+    compile(): CompiledGraph<TState>;
+}
+/** Entry point: start building a graph. */
+declare const createGraph: (options: CreateGraphOptions) => GraphBuilder<EmptyChannels>;
+
+/**
+ * Canonical example graphs authored with the SDK. Shipped so the Studio can render
+ * them and the control plane can seed them — one source of truth for both. Only the
+ * `.definition` (plain data) is meant to cross boundaries.
+ */
+type ExampleGraph = {
+    slug: string;
+    name: string;
+    description: string;
+    definition: GraphDefinition;
+};
+/** Build the example graph definitions. Pure — no LLM call, no I/O. */
+declare const exampleGraphs: () => ExampleGraph[];
+
+/**
+ * The Doc-QA REFERENCE GRAPH — a complete input → output retrieval-augmented
+ * question-answering pipeline, composed entirely from the catalog (pure components +
+ * one prebuilt-style agent), authored once and runnable two ways:
+ *
+ *   1. as a {@link CompiledGraph} via {@link buildDocQaReference} — runs on the engine
+ *      (Rust when the `@adriane-ai/napi` addon is present, else the TS fallback);
+ *   2. as a plain {@link GraphDefinition} via {@link docQaReferenceDefinition} — every
+ *      node carries the shared `node.metadata.component` / `node.metadata.agent`
+ *      carrier, so the control plane can persist it, the Studio can render it, and the
+ *      catalog run path (`runCatalogGraph`) can execute it on the Rust engine.
+ *
+ * ── THE PIPELINE ──────────────────────────────────────────────────────────────
+ *   INPUT { question, documents }
+ *     → clean      (textCleaner)        normalise the raw documents text
+ *     → split      (documentSplitter)   chunk it into passages
+ *     → retrieve   (retriever)          deterministic mock-embedding top-k over the corpus
+ *     → rerank     (reranker)           reorder the hits against the question
+ *     → prompt     (promptBuilder)      build a grounded prompt from context + question
+ *     → answer     (AGENT, balanced)    a grounded RAG answerer writes its AgentResult
+ *     → extract    (fieldExtractor)     reduce AgentResult.reasoning to the final answer text
+ *     → assemble   (answerBuilder)      answer text + numbered citations → OUTPUT { answer }
+ *   OUTPUT { answer }
+ *
+ * Single input set, single output channel. Deterministic OFFLINE (a mock gateway, no
+ * keys) and live-capable (Mistral when MISTRAL_API_KEY is present — the balanced tier
+ * resolves to a concrete Mistral model on the Rust path).
+ *
+ * The retriever scores against a fixed corpus baked into its params (the Rust
+ * `retriever` component's `docs` are configuration, not a channel). The `documents`
+ * INPUT channel feeds the clean → split ingestion-prep stages so the graph exercises a
+ * real document-preparation front-end; the corpus the retriever ranks is the same
+ * knowledge the documents describe, kept in params so the run is fully reproducible.
+ */
+
+/** The default knowledge corpus the retriever ranks against. */
+declare const DEFAULT_REFERENCE_CORPUS: RetrieverDoc[];
+/** Options for {@link buildDocQaReference} / {@link docQaReferenceDefinition}. */
+type DocQaReferenceOptions = {
+    /**
+     * The LLM gateway the answerer agent runs on (TS-engine path). Defaults to a
+     * deterministic mock so the graph runs end-to-end with no provider keys. The Rust
+     * engine path builds its own gateway from env (Mistral when MISTRAL_API_KEY is set,
+     * else a deterministic mock), independent of this.
+     */
+    llm?: LLMGateway;
+    /** The corpus the retriever ranks against. Defaults to {@link DEFAULT_REFERENCE_CORPUS}. */
+    corpus?: RetrieverDoc[];
+    /** How many documents the retriever keeps before reranking. Defaults to 3. */
+    k?: number;
+    /** The answerer's capability tier. Defaults to `"balanced"`. */
+    tier?: ModelTier;
+    /** The LLM provider slot (and the slot the default mock registers under). Defaults to `"mistral"`. */
+    provider?: "openai" | "anthropic" | "mistral";
+};
+/**
+ * Build the Doc-QA reference graph as a runnable {@link CompiledGraph}. Drive it with
+ * a single input set and read the single output channel:
+ *
+ * ```ts
+ * const app = buildDocQaReference();
+ * const out = await app.run({ question: "How does Adriane resume after a crash?", documents: "…" });
+ * console.log(out.channels.answer);
+ * ```
+ */
+declare const buildDocQaReference: (options?: DocQaReferenceOptions) => CompiledGraph;
+/**
+ * The Doc-QA reference graph as a plain {@link GraphDefinition} carrying the shared
+ * `node.metadata.component` / `node.metadata.agent` carrier on every node. This is the
+ * form the control plane persists, the Studio renders, and `runCatalogGraph` executes
+ * on the Rust engine. Pure data — no handler closures, no LLM gateway.
+ */
+declare const docQaReferenceDefinition: (options?: DocQaReferenceOptions) => GraphDefinition;
+
+/**
+ * Prebuilt, tier-tagged micro-agent graphs. Each factory returns a runnable
+ * {@link CompiledGraph} pre-wired with its capability {@link ModelTier} (matching the
+ * Rust `PrebuiltAgent` definitions in `crates/components`), so the concrete model is
+ * resolved by the {@link ModelPolicy} from the providers actually available — on Rust
+ * by the bridge, on the TS fallback path by the SDK.
+ *
+ * A prebuilt agent is a one-agent graph, except {@link prebuilt.ragAnswerer}, which
+ * composes the `retriever` + `reranker` components with an agent step.
+ *
+ * ```ts
+ * import { prebuilt } from "@adriane-ai/graph-sdk";
+ *
+ * const result = await prebuilt.summarizer().run({ question: "long text…" });
+ * console.log(result.channels.summary);
+ * ```
+ *
+ * By default each agent runs on a deterministic mock gateway (registered under the
+ * nominal provider) so a prebuilt graph runs end-to-end with no provider keys. Supply
+ * `llm` to run against a real gateway, `model` to pin a concrete model, or
+ * `tierOverride` to change the capability tier.
+ */
+
+/** Light options accepted by every prebuilt-agent factory. */
+type PrebuiltOptions = {
+    /**
+     * The LLM gateway the agent runs on. Defaults to a deterministic mock gateway
+     * registered under the nominal provider, so the graph runs with no provider keys.
+     */
+    llm?: LLMGateway;
+    /** Override the capability tier the agent's model is resolved from. */
+    tierOverride?: ModelTier;
+    /**
+     * Pin a concrete model, bypassing tier resolution (the explicit-override
+     * precedence: an explicit model always wins over the tier).
+     */
+    model?: string;
+    /**
+     * The provider slot for the request (and the slot the default mock gateway
+     * registers under). Defaults to `"anthropic"`. The actual adapter is the mock
+     * unless a custom `llm` is supplied.
+     */
+    provider?: LLMProvider;
+};
+/** Options for {@link prebuilt.ragAnswerer}: the simple options plus its retrieval corpus. */
+type RagAnswererOptions = PrebuiltOptions & {
+    /** The corpus the retriever scores against. Defaults to a small built-in set. */
+    docs?: RetrieverDoc[];
+    /** How many documents the retriever keeps before reranking. Defaults to 4. */
+    k?: number;
+    /** Channel the question is read from (the retriever query). Defaults to `"question"`. */
+    questionChannel?: string;
+};
+/**
+ * The prebuilt micro-agent surface. Each factory returns a runnable
+ * {@link CompiledGraph} pre-wired with the agent's tier (matching the Rust
+ * `PrebuiltAgent` definitions).
+ */
+declare const prebuilt: {
+    /** Condense input text into a short, faithful summary (writes `summary`). */
+    readonly summarizer: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Assign the input to one label from a fixed set (writes `label`). */
+    readonly classifier: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Extract structured fields from text as JSON (writes `extracted`). */
+    readonly extractor: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Generate a SQL query from a natural-language request (writes `sql`). */
+    readonly sqlGenerator: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Answer a question grounded in retrieved documents (retriever + reranker + agent). */
+    readonly ragAnswerer: (options?: RagAnswererOptions) => CompiledGraph;
+    /** Decide on a refund, gated behind human approval before the `refund` tool runs. */
+    readonly refundApprover: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Translate input text into a target language (fast; writes `translation`). */
+    readonly translator: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Classify the emotional tone of the input (fast; writes `sentiment`). */
+    readonly sentimentAnalyzer: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Extract named entities from text as a JSON array (fast; writes `entities`). */
+    readonly entityExtractor: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Redact personally identifiable information from text (fast; writes `redacted`). */
+    readonly piiRedactor: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Map the input to a single conversational intent label (fast; writes `intent`). */
+    readonly intentClassifier: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Generate a short, descriptive title for the input (fast; writes `title`). */
+    readonly titleGenerator: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Extract the key terms from the input as a JSON array (fast; writes `keywords`). */
+    readonly keywordExtractor: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Answer a question directly and concisely (balanced; writes `answer`). */
+    readonly questionAnswerer: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Review a code snippet or diff for correctness and quality (frontier; writes `review`). */
+    readonly codeReviewer: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Polish prose for clarity, grammar, flow, and tone (creative; writes `edited`). */
+    readonly copyEditor: (options?: PrebuiltOptions) => CompiledGraph;
+};
+
+/**
+ * Real text embeddings as an exported SDK helper (NOT a catalog component kind).
+ *
+ * {@link createEmbeddings} returns an {@link Embeddings} whose `embed` turns a batch of
+ * texts into dense vectors. The default transport POSTs to the Mistral embeddings API
+ * (`/embeddings` with `{ model, input }` and a `Bearer` key), parsing `data[].embedding`.
+ * The {@link CreateEmbeddingsOptions.transport} hook overrides the network call so a test
+ * can return deterministic vectors with no real network. This is the embedding backbone
+ * behind {@link import("./semantic-retriever.js").semanticRetriever}.
+ *
+ * ```ts
+ * import { createEmbeddings } from "@adriane-ai/graph-sdk";
+ *
+ * const embeddings = createEmbeddings({ apiKey: process.env.MISTRAL_API_KEY });
+ * const [a, b] = await embeddings.embed(["hello", "world"]);
+ * ```
+ */
+/** An embedder: turn a batch of texts into one dense vector each (order-preserving). */
+type Embeddings = {
+    /** Embed `texts` into a `number[][]` of the same length and order. */
+    embed(texts: string[]): Promise<number[][]>;
+};
+/**
+ * The transport an embeddings client posts through: it receives the assembled request
+ * body and must resolve to the parsed JSON response (the `{ data: [{ embedding }] }`
+ * shape the Mistral embeddings API returns). The real default builds this from `fetch`;
+ * a test injects a fake to stay offline.
+ */
+type EmbeddingsTransport = (body: EmbeddingsRequestBody) => Promise<unknown> | unknown;
+/** The request body POSTed to the embeddings endpoint (`{ model, input }`). */
+type EmbeddingsRequestBody = {
+    model: string;
+    input: string[];
+};
+/** Options for {@link createEmbeddings}. */
+type CreateEmbeddingsOptions = {
+    /** The embeddings provider. Only `"mistral"` is wired today (the default). */
+    provider?: "mistral";
+    /** API key. Defaults to `process.env.MISTRAL_API_KEY`. Required unless `transport` is injected. */
+    apiKey?: string;
+    /** Embedding model. Defaults to `"mistral-embed"`. */
+    model?: string;
+    /** API base URL. Defaults to `"https://api.mistral.ai/v1"`. */
+    baseUrl?: string;
+    /**
+     * An injectable transport overriding the default `fetch`-based call. Receives the
+     * request body and returns the parsed JSON response. Inject a fake to keep a test
+     * offline (or to point at a stub) — when set, no API key is required.
+     */
+    transport?: EmbeddingsTransport;
+};
+/** Raised when no API key and no transport were supplied, so a real call is impossible. */
+declare class MissingEmbeddingsKeyError extends Error {
+    constructor();
+}
+/** Raised when the embeddings response doesn't carry the expected `data[].embedding` shape. */
+declare class EmbeddingsResponseError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Create an {@link Embeddings} client. With the default transport it POSTs to the
+ * Mistral embeddings API (`{baseUrl||'https://api.mistral.ai/v1'}/embeddings`) with
+ * `{ model: model||'mistral-embed', input: texts }` and `Authorization: Bearer
+ * (apiKey || process.env.MISTRAL_API_KEY)`, parsing `data[].embedding`. Inject
+ * `transport` to override that for offline tests. Throws {@link MissingEmbeddingsKeyError}
+ * when neither a key nor a transport is available.
+ */
+declare const createEmbeddings: (options?: CreateEmbeddingsOptions) => Embeddings;
+
+/**
+ * A small embedding-backed vector store as an exported SDK helper (NOT a catalog
+ * component kind). {@link createVectorStore} keeps `{ id, content, embedding, metadata? }`
+ * items and answers nearest-neighbour {@link VectorStore.query} calls by cosine
+ * similarity (descending). In-memory by default; when `persistPath` is set the store is
+ * persisted to / loaded from a round-trippable JSON file (synchronous `fs`). The exported
+ * {@link cosineSimilarity} powers the ranking and is reusable on its own.
+ *
+ * ```ts
+ * import { createVectorStore } from "@adriane-ai/graph-sdk";
+ *
+ * const store = createVectorStore();
+ * store.upsert([{ id: "a", content: "hello", embedding: [1, 0] }]);
+ * const hits = store.query([1, 0], 1); // [{ id: "a", content: "hello", score: 1 }]
+ * ```
+ */
+/** An item stored in the vector store: an id, its text, its embedding and optional metadata. */
+type VectorStoreItem = {
+    id: string;
+    content: string;
+    embedding: number[];
+    metadata?: Record<string, unknown>;
+};
+/** A single nearest-neighbour result: the item (minus its embedding) plus a cosine score. */
+type VectorStoreMatch = {
+    id: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+};
+/** The vector store surface returned by {@link createVectorStore}. */
+type VectorStore = {
+    /** Insert or replace items by `id` (last write wins); persists when `persistPath` is set. */
+    upsert(items: VectorStoreItem[]): void;
+    /** Return the top-`k` items by cosine similarity to `embedding`, highest score first. */
+    query(embedding: number[], k: number): VectorStoreMatch[];
+    /** The number of items currently held. */
+    size(): number;
+};
+/** Options for {@link createVectorStore}. */
+type CreateVectorStoreOptions = {
+    /**
+     * When set, the store loads its items from this JSON file on creation (if present) and
+     * rewrites it on every {@link VectorStore.upsert}. The file is a round-trippable JSON
+     * array of {@link VectorStoreItem}. Omit for a purely in-memory store.
+     */
+    persistPath?: string;
+};
+/**
+ * Cosine similarity of two vectors. Compares over the shorter length (missing
+ * components count as 0) and returns `0` when either vector has zero magnitude, so a
+ * degenerate input never produces `NaN`.
+ */
+declare const cosineSimilarity: (a: number[], b: number[]) => number;
+/**
+ * Create a {@link VectorStore}. In-memory by default; with `persistPath` it loads any
+ * existing JSON file on creation and rewrites it on every upsert (round-trippable).
+ */
+declare const createVectorStore: (options?: CreateVectorStoreOptions) => VectorStore;
+
+/**
+ * A semantic (vector-store) retrieval connector as an exported SDK helper — the "real
+ * embeddings" sibling of the deterministic mock `components.retriever`. It is NOT a new
+ * catalog component kind: {@link semanticRetriever} returns a plain {@link NodeHandler}
+ * added with {@link import("./builder.js").GraphBuilder.node} (the same vendor-I/O shape
+ * as `components.httpFetch` / `components.webSearch`), so on the Rust engine it runs over
+ * the async JS seam (`on_node`) like any other JS node.
+ *
+ * On each run it (optionally) embeds `docs` into the {@link VectorStore}, embeds the
+ * query, then writes the top-`k` `{ id, content, score }` matches to the `into` channel.
+ * `embeddings` defaults to a real Mistral client ({@link createEmbeddings}); inject a
+ * fake {@link Embeddings} to keep a test offline and deterministic.
+ *
+ * ```ts
+ * import { createGraph, semanticRetriever } from "@adriane-ai/graph-sdk";
+ *
+ * createGraph({ name: "semantic" })
+ *   .channel("q", { type: "string", default: "" })
+ *   .channel("hits", { type: "json", default: [] })
+ *   .node("retrieve", semanticRetriever({
+ *     queryFrom: "q",
+ *     into: "hits",
+ *     k: 3,
+ *     docs: [{ id: "d1", content: "Adriane is a graph runtime." }],
+ *     embeddings: fakeEmbeddings // deterministic in tests
+ *   }));
+ * ```
+ */
+
+/** A candidate document to embed into the store before querying. */
+type SemanticRetrieverDoc = {
+    id: string;
+    content: string;
+};
+/** Params for {@link semanticRetriever}. */
+type SemanticRetrieverParams = {
+    /** A literal query (mutually exclusive with `queryFrom`). */
+    query?: string;
+    /** A channel whose value supplies the query (takes precedence when its channel is set). */
+    queryFrom?: string;
+    /** Channel receiving the top-`k` `{ id, content, score }` array. */
+    into: string;
+    /** Number of results to keep. Defaults to 4. */
+    k?: number;
+    /**
+     * Documents to embed into the store before querying. Each run embeds and upserts these
+     * (idempotent by id). Omit to query against an already-populated injected `store`.
+     */
+    docs?: SemanticRetrieverDoc[];
+    /**
+     * The vector store to upsert into / query. Defaults to a fresh in-memory store created
+     * per factory call. Inject a shared/persistent store to reuse embeddings across runs.
+     */
+    store?: VectorStore;
+    /**
+     * The embeddings client. Defaults to a real Mistral client ({@link createEmbeddings}).
+     * Inject a fake (deterministic vectors) to keep a test offline.
+     */
+    embeddings?: Embeddings;
+};
+/**
+ * Build the semantic-retriever node handler. Each invocation embeds any supplied `docs`
+ * into the store, embeds the resolved query, and writes the top-`k`
+ * {@link VectorStoreMatch} array (`{ id, content, score }`) to `into`. Throws no special
+ * error class — it surfaces the underlying embeddings error if the real client can't run
+ * (no key / no transport), which is the honest failure mode for a real connector.
+ */
+declare const semanticRetriever: (params: SemanticRetrieverParams) => NodeHandler;
+
+/**
+ * The static catalog metadata that backs the API's `/catalog` endpoint: one entry per
+ * component, prebuilt agent and capability tier. This is the SDK's source of truth for
+ * the building-block library; the API validates these arrays against the
+ * `@adriane-ai/contracts` catalog DTOs and forwards them to Studio unchanged.
+ *
+ * The arrays mirror, one-for-one:
+ *  - the 30 component factories in {@link import("./components.js").components} (28 pure
+ *    Rust-backed components + 2 vendor-I/O integration components), with their real
+ *    factory params;
+ *  - the 16 prebuilt micro-agent definitions (the Rust `PrebuiltAgent` table);
+ *  - the 4 capability tiers, each carrying the {@link DEFAULT_TIER_TABLE} per-provider
+ *    recommended models.
+ *
+ * The shapes are deliberately plain data (no closures) so they map 1:1 onto the
+ * contracts DTOs and serialize over the wire as-is.
+ */
+
+/** The category buckets a component falls into in the library. */
+type ComponentCategory = "prompt" | "validation" | "parsing" | "routing" | "retrieval" | "text" | "data" | "integration" | "splitter" | "generation" | "evaluation" | "writer";
+/** A single parameter a component factory accepts. */
+type ComponentParamMeta = {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+};
+/** One entry in the component library: a `kind` plus its presentation + params. */
+type ComponentCatalogEntry = {
+    /** The component kind — a {@link ComponentKind} for pure components, or an integration name. */
+    kind: ComponentKind | "httpFetch" | "webSearch";
+    title: string;
+    category: ComponentCategory;
+    description: string;
+    params: ComponentParamMeta[];
+    /** `true` for the vendor-I/O integration components (httpFetch / webSearch). */
+    integration: boolean;
+};
+/** One entry in the prebuilt-agent catalog, mirroring the Rust `PrebuiltAgent` table. */
+type PrebuiltAgentCatalogEntry = {
+    name: string;
+    title: string;
+    description: string;
+    tier: ModelTier;
+    tools: string[];
+    suspendForApproval: boolean;
+    outputChannel: string;
+};
+/** Describes one capability tier plus its recommended per-provider models. */
+type ModelTierInfo = {
+    tier: ModelTier;
+    description: string;
+    /** `provider -> model` recommended defaults for this tier. */
+    models: Record<string, string>;
+};
+/**
+ * The 30 component catalog entries: 28 pure Rust-backed components (whose `kind`
+ * matches {@link ComponentKind} / `ComponentRegistry::kinds()`) plus 2 vendor-I/O
+ * integration components. Params mirror the real factory `*Params` types in
+ * `./components.ts`.
+ */
+declare const componentCatalog: readonly ComponentCatalogEntry[];
+/**
+ * The 16 prebuilt micro-agent catalog entries, mirroring the Rust `PrebuiltAgent`
+ * table (`crates/components/src/prebuilt.rs`) and the SDK `prebuilt-agents.ts` `DEFS`:
+ * name, tier, description, tools, suspend flag and output channel.
+ */
+declare const prebuiltCatalog: readonly PrebuiltAgentCatalogEntry[];
+/**
+ * The 4 capability tiers, each carrying its description and the per-provider
+ * recommended models from {@link DEFAULT_TIER_TABLE} (anthropic / mistral / ollama).
+ * Derived from the gateway table so the catalog tracks the source of truth.
+ */
+declare const tierCatalog: readonly ModelTierInfo[];
+
+/** True when graph validation is being served by the Rust core. */
+declare const rustValidatorActive: () => boolean;
+
+/** True when the native addon exposes the async run bridge (execution can use Rust). */
+declare const rustEngineAvailable: () => boolean;
+/**
+ * One granted tool on the approve path, with the governance provenance the Rust
+ * guard-rail validates (matches Rust `ApprovedTool`, camelCase): the principal who
+ * *requested* the approval and the (distinct) principal who *resolved* it. The bridge
+ * rejects the resume if `resolvedBy` is empty or equals `requestedBy` (no self-approval).
+ */
+type ApprovedToolWire = {
+    name: string;
+    requestedBy: string;
+    resolvedBy: string;
+};
+
+/**
+ * Run a **catalog graph** on the Rust engine.
+ *
+ * A catalog graph is a plain {@link GraphDefinition} (e.g. one authored in the Studio
+ * graph editor, persisted as data, with no in-process TS handlers) whose nodes carry
+ * the SHARED CARRIER in `node.metadata`:
+ *
+ *   - a COMPONENT node carries `node.metadata.component = { kind, params }`
+ *   - an AGENT node carries `node.metadata.agent = { provider?, model?, tier?, system?,
+ *     toolNames?, maxIterations?, suspendForApproval?, approvalToolNames?, outputChannel? }`
+ *
+ * This is the seam a control plane uses to EXECUTE a graph built from
+ * the catalog: it reads each node's metadata, assembles the engine's
+ * `EngineSpec.componentNodes` + `agents` maps + the `jsNodeIds` for plain
+ * action/tool nodes, and drives the run on the **Rust engine** via `@adriane-ai/napi`.
+ *
+ * Unlike {@link import("./builder.js").GraphBuilder}, there are no TS handler closures
+ * here — components and agents run **natively** in Rust, and plain action/tool nodes
+ * are inert JS seams (they return an empty channel update). The carrier IS the wiring.
+ *
+ * The carrier readers below mirror the canonical Zod schema in
+ * `@adriane-ai/contracts` (`node-metadata.ts`); the SDK stays dependency-free of the
+ * contracts package, so the narrowing is duplicated structurally here. The control
+ * plane is free to validate the carrier with the contracts schema before handing the
+ * definition to this runner.
+ */
+
+/** The component carrier on `node.metadata.component`. Mirrors the contracts schema. */
+type ComponentCarrier = {
+    kind: string;
+    params: Record<string, unknown>;
+};
+/** The agent carrier on `node.metadata.agent`. Mirrors the contracts schema. */
+type AgentCarrier = {
+    provider?: string;
+    model?: string;
+    tier?: ModelTier;
+    system?: string;
+    toolNames?: string[];
+    maxIterations?: number;
+    suspendForApproval?: boolean;
+    approvalToolNames?: string[];
+    outputChannel?: string;
+};
+/** Outcome of a catalog-graph run: the terminal/suspended state and a flat status. */
+type CatalogRunOutcome = {
+    /** The final (or suspended) graph state, channels included. */
+    state: GraphState;
+    /** `"running" | "suspended" | "completed" | "failed"` — the state's status. */
+    status: string;
+    /** True when execution ran on the Rust engine (always, since this seam requires it). */
+    usedRustEngine: true;
+};
+/** Options for {@link runCatalogGraph} / {@link resumeCatalogGraph}. */
+type RunCatalogGraphOptions = {
+    /** A stable run id. Defaults to a generated one. */
+    runId?: RunId;
+    /** Initial channel data seeding the run. */
+    initialData?: Record<string, unknown>;
+    /** Subscribe to forwarded run-lifecycle events (every node transition). */
+    onEvent?: (event: RunEvent) => void;
+    /**
+     * Route the run's approvals through an {@link ApprovalEngine}. When present, the
+     * agents run natively on Rust as usual, but the moment the run suspends for approval
+     * the seam files one request per gated tool (`requestedBy = nodeId`, the agent's own
+     * subject) and stashes the engine ids in the `__approvalIds` channel of the returned
+     * state — so a human resolves them out of band (the engine forbids self-approval) and
+     * the control plane only ever resumes with engine-approved tools. Absent: the run is
+     * ungoverned (the legacy channel-only behaviour).
+     */
+    approvalEngine?: ApprovalEngine;
+};
+/** Raised when the native engine is unavailable — catalog graphs require it. */
+declare class RustEngineUnavailableError extends Error {
+    constructor();
+}
+/** Narrow a node's open metadata bag to its COMPONENT carrier, if present and valid. */
+declare const readComponentCarrier: (metadata: Record<string, unknown> | undefined) => ComponentCarrier | undefined;
+/** Narrow a node's open metadata bag to its AGENT carrier, if present and valid. */
+declare const readAgentCarrier: (metadata: Record<string, unknown> | undefined) => AgentCarrier | undefined;
+/**
+ * Run a catalog {@link GraphDefinition} (whose nodes carry `node.metadata.component`
+ * and `node.metadata.agent`) to completion or suspension on the **Rust engine**.
+ *
+ * Throws {@link RustEngineUnavailableError} when the native addon is absent.
+ */
+declare const runCatalogGraph: (definition: GraphDefinition, options?: RunCatalogGraphOptions) => Promise<CatalogRunOutcome>;
+/**
+ * Resume a previously-suspended catalog run (e.g. past a human gate) from its
+ * serialized {@link GraphState}, on the **Rust engine**. The bridge seeds its
+ * checkpointer with this state and resumes from it.
+ *
+ * Throws {@link RustEngineUnavailableError} when the native addon is absent.
+ */
+declare const resumeCatalogGraph: (definition: GraphDefinition, state: GraphState, options?: Pick<RunCatalogGraphOptions, "onEvent" | "approvalEngine"> & {
+    /**
+     * Human-granted tools to unlock on resume, each carrying its `{ name, requestedBy,
+     * resolvedBy }` provenance. Passed straight through to the Rust bridge, which
+     * re-validates the no-self-approval invariant per tool on `Entry::Resume` and writes
+     * only the validated names into `__approvedTools`. A control plane
+     * is the authority on which tools were approved (drawn from the ApprovalEngine), but
+     * the engine re-checks the provenance here — defence in depth on the PRODUCTION
+     * resume path. Omitted/empty: an ordinary resume that unlocks no tools.
+     */
+    approvedTools?: ApprovedToolWire[];
+}) => Promise<CatalogRunOutcome>;
+/** Type guard a node carries either catalog carrier. Useful to decide the run path. */
+declare const isCatalogGraph: (definition: GraphDefinition) => boolean;
+
+export { AGENT_APPROVAL_INTERRUPT, type AIMessage, APPROVAL_IDS_CHANNEL, APPROVED_TOOLS_CHANNEL, AdrianeSdkError, type AgentApprovalBinding, type AgentCarrier, type AgentNodeConfig, type AgentPromptSource, type AgentResult, type AnswerBuilderParams, AnthropicProviderAdapter, type ApproveAndResumeOptions, type ApprovedToolWire, type Bm25RetrieverParams, type CatalogRunOutcome, type ChannelInput, type ChannelReducer, type ChannelUpdate, type ChannelValues, type ChatMessageBuilderParams, type ChatMessageSpec, type Command, CompiledGraph, type CompiledGraphParts, type ComponentCarrier, type ComponentCatalogEntry, type ComponentCategory, type ComponentDescriptor, type ComponentKind, type ComponentParamMeta, type ConditionFn, type ConditionalRouterBranch, type ConditionalRouterParams, type CreateEmbeddingsOptions, type CreateGraphOptions, type CreateVectorStoreOptions, type CsvParserParams, DEFAULT_AGENT_OUTPUT_CHANNEL, DEFAULT_PREFERENCE, DEFAULT_REFERENCE_CORPUS, DEFAULT_TIER_TABLE, type DeduplicatorParams, DefaultLLMGateway, type DocQaReferenceOptions, type DocumentJoinerParams, type DocumentSplitterParams, type DocumentWriterParams, DuplicateNodeError, DynamicInterrupt, type Embeddings, type EmbeddingsRequestBody, EmbeddingsResponseError, type EmbeddingsTransport, type EmptyChannels, type EvaluatorParams, type ExampleGraph, type FieldMapperParams, GraphBuilder, GraphCompileError, type GraphDefinition, type GraphState, type GraphStatus, type HtmlToTextParams, type HttpFetchImpl, type HttpFetchParams, type HttpFetchRequestInit, type HttpFetchResponseLike, type HttpFetchResult, InMemoryCheckpointer, InMemoryPromptRegistry, InMemoryToolRegistry, type InitialData, type IntegrationComponentHandler, type JsonValidatorParams, type KeywordRetrieverParams, type LLMGateway, type LLMProvider, type LLMResponse, type LLMStreamChunk, type LLMToolCall, type LanguageDetectorParams, type LexicalDoc, type ListJoinerParams, MODEL_TIERS, type MergeRankerParams, type Message, type MessageId, type MetadataFilterParams, MissingEmbeddingsKeyError, MissingHandlerError, MockLLMProviderAdapter, type ModelChoice, ModelPolicy, type ModelTier, type ModelTierInfo, type NodeHandler, type NodeId, type NodeInput, type OpenAIChatRequestBody, type OpenAIChatResponse, type OpenAICompatibleAdapterOptions, OpenAICompatibleProviderAdapter, type OpenAICompatibleTransportPort, type OutputParserParams, type PrebuiltAgentCatalogEntry, type PrebuiltOptions, type PredicateOp, type PromptBuilderParams, type PromptRegistry, type RagAnswererOptions, type RegexExtractorParams, type RerankerParams, type ResolveOverride, type Result, type RetrieverDoc, type RetrieverParams, type RouterParams, type RouterRule, type RunCatalogGraphOptions, type RunEvent, type RunId, type RunOptions, type RustAgentConfig, type RustComponentConfig, RustEngineUnavailableError, type RustToolBinding, type SemanticRetrieverDoc, type SemanticRetrieverParams, type SentenceWindowSplitterParams, type StreamAgentConfig, type StreamEvent, type StreamMode, type TextCleanerParams, type TierModelTable, type ToolCall, type ToolDefinition, type ToolId, type ToolNodeConfig, type ToolRegistry, type TruncatorParams, type TypedCondition, type TypedGraphState, type TypedNodeHandler, type VectorStore, type VectorStoreItem, type VectorStoreMatch, type WebSearchImpl, type WebSearchOutcome, type WebSearchParams, type WebSearchResult, type WebSearchTransport, buildDocQaReference, componentCatalog, components, cosineSimilarity, createAgentNodeHandler, createEmbeddings, createGraph, createToolNodeHandler, createVectorStore, docQaReferenceDefinition, exampleGraphs, isCatalogGraph, prebuilt, prebuiltCatalog, readAgentCarrier, readComponentCarrier, resumeCatalogGraph, runCatalogGraph, rustEngineAvailable, rustValidatorActive, semanticRetriever, streamAgentTokens, tierCatalog, toAgentApprovalBinding, toRustAgentConfig };