@relkit/langchain 0.0.0-stage → 0.7.11

package/dist/graph-continuation.d.ts

@@ -0,0 +1,43 @@
+/** Coordinates native graph resume requests with persisted waiting state and the invocation scope, preserving continuation failures and thread identity. */
+import { Command } from "@langchain/langgraph";
+import { Effect } from "effect";
+import { type GraphDescriptor } from "./define-graph.js";
+import type { CompiledGraph, GraphConfig } from "./graph-continuation.types.js";
+export type { GraphConfig } from "./graph-continuation.types.js";
+export { validateGraphResumeInput, validateGraphResumeInputEffect, } from "./graph-continuation-validation.js";
+export { waitingInterrupts, waitingInterruptsEffect } from "./graph-continuation-waiting.js";
+/** Builds a persistent graph run configuration.
+ * @param descriptor - Graph whose checkpointer determines thread requirements.
+ * @param threadId - Optional persistent thread identity.
+ * @returns An Effect with configuration or GraphContinuationFailure.
+ * @example Effect.runSync(graphConfigEffect(graph, "thread"));
+ */
+export declare const graphConfigEffect: (descriptor: GraphDescriptor<string, import("@relkit/schema").StandardSchemaV1<unknown, unknown>, import("@relkit/schema").StandardSchemaV1<unknown, unknown>, import("@langchain/langgraph").AnyStateSchema, readonly import("./define-graph.types.js").GraphNodeLike[]>, threadId?: string | undefined) => Effect.Effect<GraphConfig, import("./graph-continuation-error.js").GraphContinuationFailure, never>;
+/** Builds graph run configuration for existing synchronous callers.
+ * @param descriptor - Graph whose checkpointer determines thread requirements.
+ * @param threadId - Optional persistent thread identity.
+ * @returns Run configuration.
+ * @throws The original missing thread error.
+ * @example const config = graphConfig(graph, "thread");
+ */
+export declare function graphConfig(descriptor: GraphDescriptor, threadId?: string): GraphConfig;
+/** Validates a reply and constructs a native LangGraph resume command.
+ * @param graph - Compiled graph with the waiting snapshot.
+ * @param descriptor - Source graph descriptor.
+ * @param config - Persistent thread configuration.
+ * @param value - User reply or ordered replies.
+ * @returns An Effect with a native command or GraphContinuationFailure.
+ * @example Effect.runPromise(resumeCommandEffect(graph, descriptor, config, reply));
+ */
+export declare const resumeCommandEffect: (graph: any, descriptor: GraphDescriptor<string, import("@relkit/schema").StandardSchemaV1<unknown, unknown>, import("@relkit/schema").StandardSchemaV1<unknown, unknown>, import("@langchain/langgraph").AnyStateSchema, readonly import("./define-graph.types.js").GraphNodeLike[]>, config: GraphConfig, value: unknown) => Effect.Effect<Command<unknown, Record<string, unknown>, string>, import("./graph-continuation-error.js").GraphContinuationFailure, never>;
+/** Constructs a native resume command for existing Promise callers.
+ * @param graph - Compiled graph with the waiting snapshot.
+ * @param descriptor - Source graph descriptor.
+ * @param config - Persistent thread configuration.
+ * @param value - User reply or ordered replies.
+ * @returns A native LangGraph resume command.
+ * @throws The original state or continuation validation error.
+ * @example await resumeCommand(graph, descriptor, config, reply);
+ */
+export declare function resumeCommand(graph: CompiledGraph, descriptor: GraphDescriptor, config: GraphConfig, value: unknown): Promise<Command>;
+//# sourceMappingURL=graph-continuation.d.ts.map

package/dist/graph-continuation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-continuation.d.ts","sourceRoot":"","sources":["../src/graph-continuation.ts"],"names":[],"mappings":"AAAA,4JAA4J;AAE5J,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAKhF,YAAY,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EACL,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE7F;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,kZAa7B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,CAMvF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,0cAuB/B,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,aAAa,EACpB,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,OAAO,CAAC,CAMlB"}

package/dist/graph-continuation.js

@@ -0,0 +1,82 @@
+/** Coordinates native graph resume requests with persisted waiting state and the invocation scope, preserving continuation failures and thread identity. */
+import { Command } from "@langchain/langgraph";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { graphExecution } from "./define-graph.js";
+import { graphContinuationFailure } from "./graph-continuation-error.js";
+import { validateGraphResumeInputEffect } from "./graph-continuation-validation.js";
+import { waitingInterruptsEffect } from "./graph-continuation-waiting.js";
+export { validateGraphResumeInput, validateGraphResumeInputEffect, } from "./graph-continuation-validation.js";
+export { waitingInterrupts, waitingInterruptsEffect } from "./graph-continuation-waiting.js";
+/** Builds a persistent graph run configuration.
+ * @param descriptor - Graph whose checkpointer determines thread requirements.
+ * @param threadId - Optional persistent thread identity.
+ * @returns An Effect with configuration or GraphContinuationFailure.
+ * @example Effect.runSync(graphConfigEffect(graph, "thread"));
+ */
+export const graphConfigEffect = Effect.fn("Agents.graph.config")((descriptor, threadId) => Effect.try({
+    try: () => {
+        const persistent = graphExecution(descriptor).checkpointer !== undefined;
+        if (persistent && (typeof threadId !== "string" || threadId.length === 0)) {
+            throw new TypeError("Graph execution with a checkpointer requires threadId");
+        }
+        return threadId === undefined ? {} : { configurable: { thread_id: threadId } };
+    },
+    catch: graphContinuationFailure,
+}), (effect) => observeAgent("graph.config", effect));
+/** Builds graph run configuration for existing synchronous callers.
+ * @param descriptor - Graph whose checkpointer determines thread requirements.
+ * @param threadId - Optional persistent thread identity.
+ * @returns Run configuration.
+ * @throws The original missing thread error.
+ * @example const config = graphConfig(graph, "thread");
+ */
+export function graphConfig(descriptor, threadId) {
+    return Effect.runSync(graphConfigEffect(descriptor, threadId).pipe(Effect.catchTag("GraphContinuationFailure", (failure) => Effect.fail(failure.cause))));
+}
+/** Validates a reply and constructs a native LangGraph resume command.
+ * @param graph - Compiled graph with the waiting snapshot.
+ * @param descriptor - Source graph descriptor.
+ * @param config - Persistent thread configuration.
+ * @param value - User reply or ordered replies.
+ * @returns An Effect with a native command or GraphContinuationFailure.
+ * @example Effect.runPromise(resumeCommandEffect(graph, descriptor, config, reply));
+ */
+export const resumeCommandEffect = Effect.fn("Agents.graph.resumeCommand")(function* (graph, descriptor, config, value) {
+    yield* Effect.try({
+        try: () => {
+            if (graphExecution(descriptor).checkpointer === undefined) {
+                throw new TypeError("Graph resume requires a checkpointer");
+            }
+        },
+        catch: graphContinuationFailure,
+    });
+    const requests = yield* waitingInterruptsEffect(graph, descriptor, config);
+    const reply = yield* validateGraphResumeInputEffect(descriptor, requests, value);
+    return yield* Effect.try({
+        try: () => new Command({ resume: nativeResume(requests, reply) }),
+        catch: graphContinuationFailure,
+    });
+}, (effect) => observeAgent("graph.resume-command", effect));
+/** Constructs a native resume command for existing Promise callers.
+ * @param graph - Compiled graph with the waiting snapshot.
+ * @param descriptor - Source graph descriptor.
+ * @param config - Persistent thread configuration.
+ * @param value - User reply or ordered replies.
+ * @returns A native LangGraph resume command.
+ * @throws The original state or continuation validation error.
+ * @example await resumeCommand(graph, descriptor, config, reply);
+ */
+export function resumeCommand(graph, descriptor, config, value) {
+    return Effect.runPromise(resumeCommandEffect(graph, descriptor, config, value).pipe(Effect.catchTag("GraphContinuationFailure", (failure) => Effect.fail(failure.cause))));
+}
+function nativeResume(requests, value) {
+    const values = requests.length === 1 ? [value] : value;
+    const entries = requests.map((request, index) => {
+        if (request.id === undefined)
+            throw new TypeError("Graph interruption has no native ID");
+        return [request.id, values[index]];
+    });
+    return Object.fromEntries(entries);
+}
+//# sourceMappingURL=graph-continuation.js.map

package/dist/graph-continuation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-continuation.js","sourceRoot":"","sources":["../src/graph-continuation.ts"],"names":[],"mappings":"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"}

package/dist/graph-continuation.types.d.ts

@@ -0,0 +1,11 @@
+/** Coordinates native graph resume requests with persisted waiting state and the invocation scope, preserving continuation failures and thread identity. This companion preserves the native input and output types without starting runtime work. */
+import type { compileGraph } from "./graph-compile.js";
+/** LangGraph run configuration with an optional persistent thread identity. */
+export type GraphConfig = {} | {
+    readonly configurable: {
+        readonly thread_id: string;
+    };
+};
+/** Compiled graph accepted by continuation helpers. */
+export type CompiledGraph = ReturnType<typeof compileGraph>;
+//# sourceMappingURL=graph-continuation.types.d.ts.map

package/dist/graph-continuation.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-continuation.types.d.ts","sourceRoot":"","sources":["../src/graph-continuation.types.ts"],"names":[],"mappings":"AAAA,sPAAsP;AAEtP,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,EAAE,GAAG;IAAE,QAAQ,CAAC,YAAY,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEzF,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/graph-continuation.types.js

@@ -0,0 +1,3 @@
+/** Coordinates native graph resume requests with persisted waiting state and the invocation scope, preserving continuation failures and thread identity. This companion preserves the native input and output types without starting runtime work. */
+export {};
+//# sourceMappingURL=graph-continuation.types.js.map

package/dist/graph-continuation.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-continuation.types.js","sourceRoot":"","sources":["../src/graph-continuation.types.ts"],"names":[],"mappings":"AAAA,sPAAsP"}

package/dist/graph-definition.d.ts

@@ -0,0 +1,36 @@
+/** Validates graph structure and resolves authored node identities before native compilation, reporting missing or inconsistent graph definitions. */
+import { type AnyStateSchema } from "@langchain/langgraph";
+import { type StandardSchemaV1 } from "@relkit/schema";
+import { Effect } from "effect";
+import type { GraphNodeLike } from "./define-graph.js";
+import { type GraphEdgeBuilder, type GraphEdgeOperation } from "./graph-edges.js";
+/** Validates graph state, nodes, and edge declarations.
+ * @param state - Native graph state schema.
+ * @param input - Graph input schema.
+ * @param output - Graph output schema.
+ * @param sourceNodes - Authored node descriptors.
+ * @param edges - Edge builder callback.
+ * @returns An Effect with nodes, edges, and state keys or GraphDefinitionFailure.
+ * @example Effect.runSync(prepareGraphDefinitionEffect(state, input, output, nodes, edges));
+ */
+export declare const prepareGraphDefinitionEffect: (state: AnyStateSchema, input: StandardSchemaV1<unknown, unknown>, output: StandardSchemaV1<unknown, unknown>, sourceNodes: readonly GraphNodeLike[], edges: (builder: GraphEdgeBuilder<string, any>) => unknown) => Effect.Effect<{
+    readonly nodes: readonly GraphNodeLike[];
+    readonly operations: readonly GraphEdgeOperation<string, any>[];
+    readonly stateKeys: Set<string>;
+}, import("./define-graph-error.js").GraphDefinitionFailure, never>;
+/** Validates graph authoring for existing synchronous callers.
+ * @param state - Native graph state schema.
+ * @param input - Graph input schema.
+ * @param output - Graph output schema.
+ * @param sourceNodes - Authored node descriptors.
+ * @param edges - Edge builder callback.
+ * @returns Frozen nodes, ordered operations, and state keys.
+ * @throws The original graph authoring error.
+ * @example const prepared = prepareGraphDefinition(state, input, output, nodes, edges);
+ */
+export declare function prepareGraphDefinition(state: AnyStateSchema, input: StandardSchemaV1, output: StandardSchemaV1, sourceNodes: readonly GraphNodeLike[], edges: (builder: GraphEdgeBuilder<string, any>) => unknown): {
+    readonly nodes: readonly GraphNodeLike[];
+    readonly operations: readonly GraphEdgeOperation<string, any>[];
+    readonly stateKeys: Set<string>;
+};
+//# sourceMappingURL=graph-definition.d.ts.map

package/dist/graph-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-definition.d.ts","sourceRoot":"","sources":["../src/graph-definition.ts"],"names":[],"mappings":"AAAA,sJAAsJ;AAEtJ,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,yKAMpB,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO;oBA4C5C,SAAS,aAAa,EAAE;yBACnB,SAAS,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;wBAC3C,GAAG,CAAC,MAAM,CAAC;mEAvChC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,SAAS,aAAa,EAAE,EACrC,KAAK,EAAE,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,GACzD;IACD,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAChE,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACjC,CAMA"}

package/dist/graph-definition.js

@@ -0,0 +1,90 @@
+/** Validates graph structure and resolves authored node identities before native compilation, reporting missing or inconsistent graph definitions. */
+import { StateSchema } from "@langchain/langgraph";
+import { isFunctionGraphNode } from "@relkit/functions";
+import { getJsonSchema } from "@relkit/schema";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { isRecord } from "@relkit/agents/internal/agent-validation";
+import { assertGraphNodeDestinations, isGraphNodeDescriptor } from "./define-graph-node.js";
+import { graphDefinitionFailure } from "./define-graph-error.js";
+import { createGraphEdgeBuilder, } from "./graph-edges.js";
+import { isSubgraphNode } from "./graph-subgraph.js";
+/** Validates graph state, nodes, and edge declarations.
+ * @param state - Native graph state schema.
+ * @param input - Graph input schema.
+ * @param output - Graph output schema.
+ * @param sourceNodes - Authored node descriptors.
+ * @param edges - Edge builder callback.
+ * @returns An Effect with nodes, edges, and state keys or GraphDefinitionFailure.
+ * @example Effect.runSync(prepareGraphDefinitionEffect(state, input, output, nodes, edges));
+ */
+export const prepareGraphDefinitionEffect = Effect.fn("Agents.graph.prepareDefinition")((state, input, output, sourceNodes, edges) => Effect.try({
+    try: () => prepareGraphDefinitionCore(state, input, output, sourceNodes, edges),
+    catch: graphDefinitionFailure,
+}), (effect) => observeAgent("graph.prepare-definition", effect));
+/** Validates graph authoring for existing synchronous callers.
+ * @param state - Native graph state schema.
+ * @param input - Graph input schema.
+ * @param output - Graph output schema.
+ * @param sourceNodes - Authored node descriptors.
+ * @param edges - Edge builder callback.
+ * @returns Frozen nodes, ordered operations, and state keys.
+ * @throws The original graph authoring error.
+ * @example const prepared = prepareGraphDefinition(state, input, output, nodes, edges);
+ */
+export function prepareGraphDefinition(state, input, output, sourceNodes, edges) {
+    return Effect.runSync(prepareGraphDefinitionEffect(state, input, output, sourceNodes, edges).pipe(Effect.catchTag("GraphDefinitionFailure", (failure) => Effect.fail(failure.cause))));
+}
+function prepareGraphDefinitionCore(state, input, output, sourceNodes, edges) {
+    if (!StateSchema.isInstance(state))
+        throw new TypeError("Graph state must be a StateSchema");
+    if (!Array.isArray(sourceNodes) || sourceNodes.length === 0) {
+        throw new TypeError("Graph nodes must be a non-empty array");
+    }
+    const stateKeys = new Set(Object.keys(state.fields));
+    assertSelection(input, stateKeys, "input");
+    assertSelection(output, stateKeys, "output");
+    const nodes = Object.freeze([...sourceNodes]);
+    const nodeIds = new Set();
+    for (const node of nodes) {
+        if (!isGraphNodeDescriptor(node) && !isFunctionGraphNode(node) && !isSubgraphNode(node)) {
+            throw new TypeError("Graph nodes must be graph-node descriptors");
+        }
+        if (["__start__", "__end__", "__interrupt__"].includes(node.id)) {
+            throw new TypeError(`Graph node id "${node.id}" is reserved`);
+        }
+        if (stateKeys.has(node.id))
+            throw new TypeError(`Graph node id "${node.id}" collides with state`);
+        if (nodeIds.has(node.id))
+            throw new TypeError(`Duplicate graph node "${node.id}"`);
+        nodeIds.add(node.id);
+        assertSelection(node.input, stateKeys, `node "${node.id}" input`);
+        assertSelection(node.output, stateKeys, `node "${node.id}" output`);
+    }
+    for (const node of nodes) {
+        if (isGraphNodeDescriptor(node) || isSubgraphNode(node)) {
+            assertGraphNodeDestinations(node, nodeIds);
+        }
+    }
+    if (typeof edges !== "function")
+        throw new TypeError("Graph edges must be a function");
+    const recorded = createGraphEdgeBuilder(nodeIds);
+    edges(recorded.builder);
+    return {
+        nodes,
+        operations: Object.freeze([...recorded.operations]),
+        stateKeys,
+    };
+}
+function assertSelection(schema, stateKeys, name) {
+    const result = getJsonSchema(schema);
+    const projected = result.ok ? result.schema : undefined;
+    if (projected?.type !== "object" || !isRecord(projected.properties)) {
+        throw new TypeError(`Graph ${name} must expose an object JSON Schema`);
+    }
+    for (const key of Object.keys(projected.properties)) {
+        if (!stateKeys.has(key))
+            throw new TypeError(`Graph ${name} field "${key}" is not in state`);
+    }
+}
+//# sourceMappingURL=graph-definition.js.map

package/dist/graph-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-definition.js","sourceRoot":"","sources":["../src/graph-definition.ts"],"names":[],"mappings":"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"}

package/dist/graph-edge-destinations.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Validates native graph endpoints and conditional route results before execution.
+ * Mutation builders reuse the same endpoint and duplicate-edge rules.
+ */
+import { END, START } from "@langchain/langgraph";
+import { Effect } from "effect";
+/** Checks native route targets against registered nodes.
+ * @param value - One destination or a destination list.
+ * @param nodeIds - Registered node identities.
+ * @returns An Effect with void or GraphDefinitionFailure.
+ * @example Effect.runSync(assertGraphDestinationEffect("next", ids));
+ */
+export declare const assertGraphDestinationEffect: <Id extends string>(value: unknown, nodeIds: ReadonlySet<Id>) => Effect.Effect<void, import("./define-graph-error.js").GraphDefinitionFailure, never>;
+/** Checks native route targets for existing synchronous callers.
+ * @param value - One destination or a destination list.
+ * @param nodeIds - Registered node identities.
+ * @returns Nothing when all destinations are known.
+ * @throws The original invalid destination error.
+ * @example assertGraphDestination("next", ids);
+ */
+export declare function assertGraphDestination<Id extends string>(value: unknown, nodeIds: ReadonlySet<Id>): void;
+/** Validates dynamic route labels or node destinations.
+ * @param value - Route result.
+ * @param nodeIds - Registered node identities.
+ * @param destinations - Optional label mapping.
+ * @returns An Effect with void or GraphDefinitionFailure.
+ * @example Effect.runSync(validateGraphRouteEffect("yes", ids, { yes: "next" }));
+ */
+export declare const validateGraphRouteEffect: <Id extends string>(value: unknown, nodeIds: ReadonlySet<Id>, destinations?: Readonly<Record<string, "__end__" | Id>> | undefined) => Effect.Effect<void, import("./define-graph-error.js").GraphDefinitionFailure, never>;
+/** Validates dynamic routes for existing synchronous callers.
+ * @param value - Route result.
+ * @param nodeIds - Registered node identities.
+ * @param destinations - Optional label mapping.
+ * @returns Nothing when all route targets are valid.
+ * @throws The original invalid route error.
+ * @example validateGraphRoute("yes", ids, { yes: "next" });
+ */
+export declare function validateGraphRoute<Id extends string>(value: unknown, nodeIds: ReadonlySet<Id>, destinations?: Readonly<Record<string, Id | typeof END>>): void;
+export declare function copyDestinations<Id extends string>(value: Readonly<Record<string, Id | typeof END>>, nodeIds: ReadonlySet<Id>): Readonly<Record<string, Id | typeof END>>;
+export declare function assertEndpoint<Id extends string>(value: unknown, nodeIds: ReadonlySet<Id>, source: boolean): asserts value is Id | typeof START | typeof END;
+export declare function addUnique(signatures: Set<string>, signature: string): void;
+//# sourceMappingURL=graph-edge-destinations.d.ts.map

package/dist/graph-edge-destinations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edge-destinations.d.ts","sourceRoot":"","sources":["../src/graph-edge-destinations.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,GAAG,EAAE,KAAK,EAAQ,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,GACtC,EAAE,SAAS,MAAM,mIAMnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,SAAS,MAAM,EACtD,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,GACvB,IAAI,CAMN;AAaD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAClC,EAAE,SAAS,MAAM,wMAUnB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAClD,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,EACxB,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC,GACvD,IAAI,CAMN;AAoBD,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAChD,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC,EAChD,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,GAK6B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC,CAC/F;AAED,wBAAgB,cAAc,CAAC,EAAE,SAAS,MAAM,EAC9C,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,EACxB,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,KAAK,IAAI,EAAE,GAAG,OAAO,KAAK,GAAG,OAAO,GAAG,CAYjD;AAED,wBAAgB,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAG1E"}

package/dist/graph-edge-destinations.js

@@ -0,0 +1,100 @@
+/**
+ * Validates native graph endpoints and conditional route results before execution.
+ * Mutation builders reuse the same endpoint and duplicate-edge rules.
+ */
+import { END, START, Send } from "@langchain/langgraph";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { graphDefinitionFailure } from "./define-graph-error.js";
+/** Checks native route targets against registered nodes.
+ * @param value - One destination or a destination list.
+ * @param nodeIds - Registered node identities.
+ * @returns An Effect with void or GraphDefinitionFailure.
+ * @example Effect.runSync(assertGraphDestinationEffect("next", ids));
+ */
+export const assertGraphDestinationEffect = Effect.fn("Agents.graph.destination")((value, nodeIds) => Effect.try({
+    try: () => assertGraphDestinationCore(value, nodeIds),
+    catch: graphDefinitionFailure,
+}), (effect) => observeAgent("graph.destination", effect));
+/** Checks native route targets for existing synchronous callers.
+ * @param value - One destination or a destination list.
+ * @param nodeIds - Registered node identities.
+ * @returns Nothing when all destinations are known.
+ * @throws The original invalid destination error.
+ * @example assertGraphDestination("next", ids);
+ */
+export function assertGraphDestination(value, nodeIds) {
+    Effect.runSync(assertGraphDestinationEffect(value, nodeIds).pipe(Effect.catchTag("GraphDefinitionFailure", (failure) => Effect.fail(failure.cause))));
+}
+function assertGraphDestinationCore(value, nodeIds) {
+    const values = Array.isArray(value) ? value : [value];
+    for (const destination of values) {
+        const id = destination instanceof Send ? destination.node : destination;
+        assertEndpoint(id, nodeIds, false);
+    }
+}
+/** Validates dynamic route labels or node destinations.
+ * @param value - Route result.
+ * @param nodeIds - Registered node identities.
+ * @param destinations - Optional label mapping.
+ * @returns An Effect with void or GraphDefinitionFailure.
+ * @example Effect.runSync(validateGraphRouteEffect("yes", ids, { yes: "next" }));
+ */
+export const validateGraphRouteEffect = Effect.fn("Agents.graph.validateRoute")((value, nodeIds, destinations) => Effect.try({
+    try: () => validateGraphRouteCore(value, nodeIds, destinations),
+    catch: graphDefinitionFailure,
+}), (effect) => observeAgent("graph.validate-route", effect));
+/** Validates dynamic routes for existing synchronous callers.
+ * @param value - Route result.
+ * @param nodeIds - Registered node identities.
+ * @param destinations - Optional label mapping.
+ * @returns Nothing when all route targets are valid.
+ * @throws The original invalid route error.
+ * @example validateGraphRoute("yes", ids, { yes: "next" });
+ */
+export function validateGraphRoute(value, nodeIds, destinations) {
+    Effect.runSync(validateGraphRouteEffect(value, nodeIds, destinations).pipe(Effect.catchTag("GraphDefinitionFailure", (failure) => Effect.fail(failure.cause))));
+}
+function validateGraphRouteCore(value, nodeIds, destinations) {
+    for (const destination of Array.isArray(value) ? value : [value]) {
+        if (destination instanceof Send) {
+            assertGraphDestinationCore(destination, nodeIds);
+            continue;
+        }
+        if (destinations !== undefined && typeof destination === "string") {
+            if (Object.hasOwn(destinations, destination))
+                continue;
+            throw new TypeError(`Unknown graph route label "${destination}"`);
+        }
+        assertGraphDestinationCore(destination, nodeIds);
+    }
+}
+export function copyDestinations(value, nodeIds) {
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        throw new TypeError("Graph route destinations cannot be empty");
+    for (const [, destination] of entries)
+        assertEndpoint(destination, nodeIds, false);
+    return Object.freeze(Object.fromEntries(entries));
+}
+export function assertEndpoint(value, nodeIds, source) {
+    if (value === START) {
+        if (!source)
+            throw new TypeError("Graph START cannot be an edge destination");
+        return;
+    }
+    if (value === END) {
+        if (source)
+            throw new TypeError("Graph END cannot be an edge source");
+        return;
+    }
+    if (typeof value !== "string" || !nodeIds.has(value)) {
+        throw new TypeError(`Unknown graph node "${String(value)}"`);
+    }
+}
+export function addUnique(signatures, signature) {
+    if (signatures.has(signature))
+        throw new TypeError("Duplicate graph edge");
+    signatures.add(signature);
+}
+//# sourceMappingURL=graph-edge-destinations.js.map

package/dist/graph-edge-destinations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edge-destinations.js","sourceRoot":"","sources":["../src/graph-edge-destinations.ts"],"names":[],"mappings":"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"}

package/dist/graph-edge-mutations.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Applies validated edge mutations to one builder-owned operation log. Factories
+ * retain that builder's closure so duplicate checks and mutation order stay local.
+ */
+import { type LangGraphRunnableConfig } from "@langchain/langgraph";
+import type { MaybePromise } from "@relkit/contracts";
+import { Effect } from "effect";
+import type { GraphEdgeMutationContext } from "./graph-edge-mutations.types.js";
+/** Creates conditional mutations sharing one checked operation log.
+ * @param context - Registered nodes, duplicate signatures and builder identity.
+ * @returns The existing observable conditional mutation operation.
+ */
+export declare function conditionalEdgeMutation<Id extends string, State>(context: GraphEdgeMutationContext<Id, State>): (source: "__start__" | Id, route: (state: State, config: LangGraphRunnableConfig) => MaybePromise<unknown>, destinations?: Readonly<Record<string, "__end__" | Id>> | undefined) => Effect.Effect<import("./graph-edges.types.js").GraphEdgeBuilder<Id, State>, import("./define-graph-error.js").GraphDefinitionFailure, never>;
+/** Creates direct/join mutations sharing the same checked operation log.
+ * @param context - Registered nodes, duplicate signatures and builder identity.
+ * @returns The existing observable edge mutation operation.
+ */
+export declare function edgeMutation<Id extends string, State>(context: GraphEdgeMutationContext<Id, State>): (start: "__start__" | Id | readonly Id[], end: "__end__" | Id) => Effect.Effect<import("./graph-edges.types.js").GraphEdgeBuilder<Id, State>, import("./define-graph-error.js").GraphDefinitionFailure, never>;
+//# sourceMappingURL=graph-edge-mutations.d.ts.map

package/dist/graph-edge-mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edge-mutations.d.ts","sourceRoot":"","sources":["../src/graph-edge-mutations.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAc,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,KAAK,EAC9D,OAAO,EAAE,wBAAwB,CAAC,EAAE,EAAE,KAAK,CAAC,6CAMzB,KAAK,UAAU,uBAAuB,KAAK,YAAY,CAAC,OAAO,CAAC,uNAwBpF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,KAAK,EACnD,OAAO,EAAE,wBAAwB,CAAC,EAAE,EAAE,KAAK,CAAC,kNA6B7C"}

package/dist/graph-edge-mutations.js

@@ -0,0 +1,62 @@
+/**
+ * Applies validated edge mutations to one builder-owned operation log. Factories
+ * retain that builder's closure so duplicate checks and mutation order stay local.
+ */
+import { END, START } from "@langchain/langgraph";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { graphDefinitionFailure } from "./define-graph-error.js";
+import { assertEndpoint, copyDestinations, addUnique } from "./graph-edge-destinations.js";
+/** Creates conditional mutations sharing one checked operation log.
+ * @param context - Registered nodes, duplicate signatures and builder identity.
+ * @returns The existing observable conditional mutation operation.
+ */
+export function conditionalEdgeMutation(context) {
+    const { nodeIds, operations, signatures } = context;
+    return Effect.fn("Agents.graph.addConditionalEdge")((source, route, destinations) => Effect.try({
+        try: () => {
+            assertEndpoint(source, nodeIds, true);
+            if (typeof route !== "function")
+                throw new TypeError("Graph route must be a function");
+            const map = destinations === undefined ? undefined : copyDestinations(destinations, nodeIds);
+            addUnique(signatures, `conditional:${source}`);
+            operations.push(Object.freeze({
+                kind: "conditional",
+                source,
+                route,
+                ...(map === undefined ? {} : { destinations: map }),
+            }));
+            return context.builder();
+        },
+        catch: graphDefinitionFailure,
+    }), (effect) => observeAgent("graph.add-conditional-edge", effect));
+}
+/** Creates direct/join mutations sharing the same checked operation log.
+ * @param context - Registered nodes, duplicate signatures and builder identity.
+ * @returns The existing observable edge mutation operation.
+ */
+export function edgeMutation(context) {
+    const { nodeIds, operations, signatures } = context;
+    return Effect.fn("Agents.graph.addEdge")((start, end) => Effect.try({
+        try: () => {
+            const starts = Array.isArray(start) ? start : [start];
+            if (starts.length === 0 || new Set(starts).size !== starts.length) {
+                throw new TypeError("Graph edge sources must be a non-empty unique list");
+            }
+            for (const value of starts)
+                assertEndpoint(value, nodeIds, true);
+            assertEndpoint(end, nodeIds, false);
+            if (starts.length > 1 && end === END)
+                throw new TypeError("Graph join destination must be a node");
+            addUnique(signatures, `edge:${starts.join(",")}->${end}`);
+            operations.push(Object.freeze({
+                kind: "edge",
+                start: Array.isArray(start) ? Object.freeze([...start]) : start,
+                end,
+            }));
+            return context.builder();
+        },
+        catch: graphDefinitionFailure,
+    }), (effect) => observeAgent("graph.add-edge", effect));
+}
+//# sourceMappingURL=graph-edge-mutations.js.map

package/dist/graph-edge-mutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edge-mutations.js","sourceRoot":"","sources":["../src/graph-edge-mutations.ts"],"names":[],"mappings":"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"}

package/dist/graph-edge-mutations.types.d.ts

@@ -0,0 +1,9 @@
+/** One graph builder's private ordered mutation authority. */
+import type { GraphEdgeBuilder, GraphEdgeOperation } from "./graph-edges.types.js";
+export interface GraphEdgeMutationContext<Id extends string, State> {
+    readonly nodeIds: ReadonlySet<Id>;
+    readonly operations: GraphEdgeOperation<Id, State>[];
+    readonly signatures: Set<string>;
+    readonly builder: () => GraphEdgeBuilder<Id, State>;
+}
+//# sourceMappingURL=graph-edge-mutations.types.d.ts.map

package/dist/graph-edge-mutations.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edge-mutations.types.d.ts","sourceRoot":"","sources":["../src/graph-edge-mutations.types.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACnF,MAAM,WAAW,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,KAAK;IAChE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,gBAAgB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;CACrD"}

package/dist/graph-edge-mutations.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=graph-edge-mutations.types.js.map

package/dist/graph-edge-mutations.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edge-mutations.types.js","sourceRoot":"","sources":["../src/graph-edge-mutations.types.ts"],"names":[],"mappings":""}

package/dist/graph-edges.d.ts

@@ -0,0 +1,24 @@
+/** Defines typed native graph edge and routing descriptors whose endpoints are checked during graph assembly and compilation. */
+import { Effect } from "effect";
+import type { GraphEdgeBuilder, GraphEdgeOperation } from "./graph-edges.types.js";
+export type * from "./graph-edges.types.js";
+/** Creates an edge builder whose mutations run through Effect.
+ * @param nodeIds - Registered node identities.
+ * @returns An Effect with a builder and its ordered operation log.
+ * @example Effect.runSync(createGraphEdgeBuilderEffect(ids));
+ */
+export declare const createGraphEdgeBuilderEffect: <Id extends string, State>(nodeIds: ReadonlySet<Id>) => Effect.Effect<{
+    builder: Readonly<GraphEdgeBuilder<Id, State>>;
+    operations: GraphEdgeOperation<Id, State>[];
+}, never, never>;
+/** Creates an edge builder for existing synchronous graph authoring.
+ * @param nodeIds - Registered node identities.
+ * @returns A builder and its ordered operation log.
+ * @example const { builder, operations } = createGraphEdgeBuilder(ids);
+ */
+export declare function createGraphEdgeBuilder<Id extends string, State>(nodeIds: ReadonlySet<Id>): {
+    readonly builder: GraphEdgeBuilder<Id, State>;
+    readonly operations: readonly GraphEdgeOperation<Id, State>[];
+};
+export { assertGraphDestination, assertGraphDestinationEffect, validateGraphRoute, validateGraphRouteEffect, } from "./graph-edge-destinations.js";
+//# sourceMappingURL=graph-edges.d.ts.map

package/dist/graph-edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edges.d.ts","sourceRoot":"","sources":["../src/graph-edges.ts"],"names":[],"mappings":"AAAA,iIAAiI;AAMjI,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEnF,mBAAmB,wBAAwB,CAAC;AAC5C;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GACtC,EAAE,SAAS,MAAM,EAAE,KAAK;;;gBA0B1B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,KAAK,EAC7D,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,GACvB;IACD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC;CAC/D,CAEA;AAED,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,8BAA8B,CAAC"}