@kindgi/flow 0.1.3 → 0.1.4-rc.0

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export type { BackoffShape, ConvergenceMode, EdgePolicy, Expr, FanoutBranch, Fan
 export { CONVERGENCE_MODES, EDGE_POLICY_PRIORITY_DEFAULT, EDGE_POLICY_PRIORITY_MAX, EDGE_POLICY_PRIORITY_MIN, END_NODE, LOOP_END_NODE, LOOP_START_NODE, OPERATORS, SENTINEL_IDS, START_NODE, SUBGRAPH_CONVERGENCE_MODES, isFanoutNode, isLeafNode, isLoopNode, isSubflowNode, } from './types.js';
 export type { CycleError, DuplicateEdgeError, DuplicateNodeError, FlowError, InvalidEdgePolicyError, InvalidFanoutNodeError, InvalidFlowOutputError, InvalidMappingError, InvalidPredicateError, InvalidSubflowNodeError, LoopBodyCycleError, LoopBodyEdgeReferenceError, LoopBodyMissingStartError, LoopConcurrencyError, LoopMaxIterationsError, LoopOutputSchemaError, LoopVariantMismatchError, MissingStartEdgeError, ReservedIdError, SchemaValidationError, UnknownNodeReferenceError, } from './errors.js';
 export { GRAPH_SCHEMA_URI, loadFlow } from './loader.js';
+export { flowPinsDigest, flowRefs, withVersions } from './pins.js';
+export type { FlowPins, FlowRefs, FlowVersionOverrides } from './pins.js';
 export { defineFlow } from './define.js';
 export type { FlowSpec } from './define.js';
 export { evaluateExpr, MISSING_PATH, resolveMapping, resolvePath } from './evaluator.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,YAAY,EACZ,eAAe,EACf,UAAU,EACV,IAAI,EACJ,YAAY,EACZ,UAAU,EACV,eAAe,EACf,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,OAAO,EACP,OAAO,EACP,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACxB,QAAQ,EACR,aAAa,EACb,eAAe,EACf,SAAS,EACT,YAAY,EACZ,UAAU,EACV,0BAA0B,EAC1B,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACzF,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,YAAY,EACZ,eAAe,EACf,UAAU,EACV,IAAI,EACJ,YAAY,EACZ,UAAU,EACV,eAAe,EACf,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,OAAO,EACP,OAAO,EACP,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACxB,QAAQ,EACR,aAAa,EACb,eAAe,EACf,SAAS,EACT,YAAY,EACZ,UAAU,EACV,0BAA0B,EAC1B,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACnE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACzF,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 export { CONVERGENCE_MODES, EDGE_POLICY_PRIORITY_DEFAULT, EDGE_POLICY_PRIORITY_MAX, EDGE_POLICY_PRIORITY_MIN, END_NODE, LOOP_END_NODE, LOOP_START_NODE, OPERATORS, SENTINEL_IDS, START_NODE, SUBGRAPH_CONVERGENCE_MODES, isFanoutNode, isLeafNode, isLoopNode, isSubflowNode, } from './types.js';
 export { GRAPH_SCHEMA_URI, loadFlow } from './loader.js';
+export { flowPinsDigest, flowRefs, withVersions } from './pins.js';
 export { defineFlow } from './define.js';
 export { evaluateExpr, MISSING_PATH, resolveMapping, resolvePath } from './evaluator.js';
 export { getEffectivePriority, schedulerTick } from './scheduler.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAgCjC,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACxB,QAAQ,EACR,aAAa,EACb,eAAe,EACf,SAAS,EACT,YAAY,EACZ,UAAU,EACV,0BAA0B,EAC1B,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AA0BpB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzF,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAgCjC,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACxB,QAAQ,EACR,aAAa,EACb,eAAe,EACf,SAAS,EACT,YAAY,EACZ,UAAU,EACV,0BAA0B,EAC1B,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AA0BpB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGnE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzF,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/pins.d.ts

@@ -0,0 +1,57 @@
+import { type Flow } from './types.js';
+/**
+ * The exact version of each block a flow version runs: its lockfile.
+ *
+ * A flow names its tools by id (a tool node's `ref`, a fanout branch's
+ * `handler`) and its agents by id, with an exact `config.version` or
+ * none. When a version of the flow is published, the runtime pins each
+ * tool, and each agent that names no version, to its latest version
+ * then, and every run of that flow version uses those versions. So a
+ * new tool or agent version reaches the flow only through a new flow
+ * version.
+ *
+ * Set by the runtime at publish, never authored. A flow version
+ * published before pins existed has none and binds the latest versions
+ * per run.
+ */
+export interface FlowPins {
+    /** Tool id → the exact version this flow version runs. */
+    readonly tools: Readonly<Record<string, string>>;
+    /** Agent id → the exact version its agent nodes that name none run. */
+    readonly agents: Readonly<Record<string, string>>;
+}
+/**
+ * `sha256:<hex>` of a flow version's pins' canonical JSON (keys sorted,
+ * no whitespace), as `pinsDigest` in `@kindgi/agents` is for an agent's.
+ */
+export declare function flowPinsDigest(pins: FlowPins): string;
+/** The blocks a flow runs that its pins name: tool ids, and agent ids with no version. */
+export interface FlowRefs {
+    readonly tools: readonly string[];
+    readonly agents: readonly string[];
+}
+/**
+ * Every tool a flow runs (tool nodes and fanout branches, in loop bodies
+ * too: what the runtime binds) and every agent it runs at no named
+ * version, each id once, sorted.
+ */
+export declare function flowRefs(flow: Flow): FlowRefs;
+/** Exact versions to run a flow version with, over its pins: the shape of a comparison's override. */
+export interface FlowVersionOverrides {
+    readonly tools?: Readonly<Record<string, string>>;
+    readonly agents?: Readonly<Record<string, string>>;
+}
+/**
+ * The flow version with some of its blocks run at other exact versions,
+ * without publishing a new flow version: what a comparison or a replay
+ * runs ("this flow, but `acme.scorer` at 0.4.0").
+ *
+ * One mechanism with the pins: the overrides go into `pins` (over the
+ * version's own), and an agent node that names its own `config.version`
+ * gets the override there too, since a node's own version wins over a
+ * pin. `pinsDigest` is recomputed, so it names what runs. A flow version
+ * published before pins gets pins of the overrides only; its other
+ * blocks bind their latest versions, as before.
+ */
+export declare function withVersions(flow: Flow, overrides: FlowVersionOverrides): Flow;
+//# sourceMappingURL=pins.d.ts.map

package/dist/pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../src/pins.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,IAAI,EAA2C,MAAM,YAAY,CAAC;AAEhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAGrD;AAED,0FAA0F;AAC1F,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAK7C;AAWD,sGAAsG;AACtG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,oBAAoB,GAAG,IAAI,CAY9E"}

package/dist/pins.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { createHash } from 'node:crypto';
+import { canonicalize } from '@kindgi/schema';
+import { isFanoutNode, isLoopNode } from './types.js';
+/**
+ * `sha256:<hex>` of a flow version's pins' canonical JSON (keys sorted,
+ * no whitespace), as `pinsDigest` in `@kindgi/agents` is for an agent's.
+ */
+export function flowPinsDigest(pins) {
+    const canonical = canonicalize({ tools: pins.tools, agents: pins.agents });
+    return `sha256:${createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+/**
+ * Every tool a flow runs (tool nodes and fanout branches, in loop bodies
+ * too: what the runtime binds) and every agent it runs at no named
+ * version, each id once, sorted.
+ */
+export function flowRefs(flow) {
+    const tools = new Set();
+    const agents = new Set();
+    collectRefs(flow.nodes, tools, agents);
+    return { tools: [...tools].sort(), agents: [...agents].sort() };
+}
+function collectRefs(nodes, tools, agents) {
+    for (const node of nodes) {
+        if (isLoopNode(node))
+            collectRefs(node.body.nodes, tools, agents);
+        else if (isFanoutNode(node))
+            for (const branch of node.branches)
+                tools.add(branch.handler);
+        else if (node.kind === 'tool')
+            tools.add(node.ref);
+        else if (node.kind === 'agent' && node.config?.version === undefined)
+            agents.add(node.ref);
+    }
+}
+/**
+ * The flow version with some of its blocks run at other exact versions,
+ * without publishing a new flow version: what a comparison or a replay
+ * runs ("this flow, but `acme.scorer` at 0.4.0").
+ *
+ * One mechanism with the pins: the overrides go into `pins` (over the
+ * version's own), and an agent node that names its own `config.version`
+ * gets the override there too, since a node's own version wins over a
+ * pin. `pinsDigest` is recomputed, so it names what runs. A flow version
+ * published before pins gets pins of the overrides only; its other
+ * blocks bind their latest versions, as before.
+ */
+export function withVersions(flow, overrides) {
+    const pins = {
+        tools: { ...(flow.pins?.tools ?? {}), ...(overrides.tools ?? {}) },
+        agents: { ...(flow.pins?.agents ?? {}), ...(overrides.agents ?? {}) },
+    };
+    const agents = overrides.agents ?? {};
+    return {
+        ...flow,
+        nodes: overrideNamedAgentVersions(flow.nodes, agents),
+        pins,
+        pinsDigest: flowPinsDigest(pins),
+    };
+}
+function overrideNamedAgentVersions(nodes, agents) {
+    return nodes.map((node) => {
+        if (isLoopNode(node)) {
+            return {
+                ...node,
+                body: { ...node.body, nodes: overrideNamedAgentVersions(node.body.nodes, agents) },
+            };
+        }
+        const version = node.kind === 'agent' ? agents[node.ref] : undefined;
+        if (node.kind !== 'agent' || version === undefined || node.config?.version === undefined) {
+            return node;
+        }
+        return { ...node, config: { ...node.config, version } };
+    });
+}
+//# sourceMappingURL=pins.js.map

package/dist/pins.js.map

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

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-import type { EdgeId, FlowId, NodeId } from '@kindgi/types';
+import type { EdgeId, FlowId, NodeId, VersionDerivation } from '@kindgi/types';
+import type { FlowPins } from './pins.js';
 /**
  * Path roots addressable in edge predicates.
  *
@@ -751,6 +752,20 @@ export interface Flow {
      * `$end` edge (the lowest-id taken one when several fire).
      */
     readonly output?: FlowOutputSpec;
+    /**
+     * The exact tool and agent versions this flow version runs, resolved by
+     * the runtime when the version was published (see `FlowPins`). Never
+     * authored: `loadFlow` refuses it. Absent on a flow version published
+     * before pins existed; it binds the latest versions per run.
+     */
+    readonly pins?: FlowPins;
+    /** `flowPinsDigest(pins)`, recorded when the version was published. */
+    readonly pinsDigest?: string;
+    /**
+     * Set by the runtime on a version a deploy registered under another
+     * number than the definition's (see `VersionDerivation`). Never authored.
+     */
+    readonly derivedFrom?: VersionDerivation;
 }
 /**
  * A flow's declared output: what the run returns, built from the

package/dist/types.d.ts.map

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

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiGjC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,OAAO;IACP,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,OAAO;IACP,KAAK;IACL,IAAI;IACJ,KAAK;CACG,CAAC;AA+MX;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,aAAa,EAAE,aAAa,EAAE,YAAY,CAAU,CAAC;AA2FvF;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,cAAc,EAAE,YAAY,CAAU,CAAC;AAuQlF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,GAAY,CAAC;AACtD,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAY,CAAC;AACrD,iEAAiE;AACjE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAU,CAAC;AA6HvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,QAAiB,CAAC;AAC5C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAe,CAAC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,aAAsB,CAAC;AACtD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAoB,CAAC;AAElD,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,CAAU,CAAC;AAE5F,4CAA4C;AAC5C,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;AAC9B,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChC,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC;AAClC,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC;AACpF,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAmGjC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,OAAO;IACP,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,OAAO;IACP,KAAK;IACL,IAAI;IACJ,KAAK;CACG,CAAC;AA+MX;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,aAAa,EAAE,aAAa,EAAE,YAAY,CAAU,CAAC;AA2FvF;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,cAAc,EAAE,YAAY,CAAU,CAAC;AAuQlF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,GAAY,CAAC;AACtD,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAY,CAAC;AACrD,iEAAiE;AACjE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAU,CAAC;AA2IvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,QAAiB,CAAC;AAC5C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAe,CAAC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,aAAsB,CAAC;AACtD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAoB,CAAC;AAElD,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,CAAU,CAAC;AAE5F,4CAA4C;AAC5C,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;AAC9B,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChC,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC;AAClC,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC;AACpF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/flow",
-  "version": "0.1.3",
+  "version": "0.1.4-rc.0",
   "description": "Flow model + predicate DSL for Kindgi™. Defines the task-flow shape (nodes, edges, conditional edges, data-flow mappings) executed by the kernel. Pure — no I/O, no database, no runtime. Ships types, a JSON-schema-validated loader (loadFlow / defineFlow), a predicate evaluator and mapping resolver (evaluateExpr / resolveMapping), and the scheduler tick (schedulerTick) the kernel uses to pick the nodes ready for concurrent execution.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,11 +30,11 @@
     "type-manifest.json"
   ],
   "dependencies": {
-    "@kindgi/schema": "0.1.3",
-    "@kindgi/types": "0.1.3"
+    "@kindgi/schema": "0.1.4-rc.0",
+    "@kindgi/types": "0.1.4-rc.0"
   },
   "devDependencies": {
-    "@kindgi/specs": "0.1.3",
+    "@kindgi/specs": "0.1.4-rc.0",
     "@types/node": "^22.10.5",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8"

package/src/index.ts

@@ -74,6 +74,8 @@ export type {
 } from './errors.js';
 
 export { GRAPH_SCHEMA_URI, loadFlow } from './loader.js';
+export { flowPinsDigest, flowRefs, withVersions } from './pins.js';
+export type { FlowPins, FlowRefs, FlowVersionOverrides } from './pins.js';
 
 export { defineFlow } from './define.js';
 export type { FlowSpec } from './define.js';

package/src/pins.ts

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { createHash } from 'node:crypto';
+
+import { canonicalize } from '@kindgi/schema';
+
+import { type Flow, type FlowNode, isFanoutNode, isLoopNode } from './types.js';
+
+/**
+ * The exact version of each block a flow version runs: its lockfile.
+ *
+ * A flow names its tools by id (a tool node's `ref`, a fanout branch's
+ * `handler`) and its agents by id, with an exact `config.version` or
+ * none. When a version of the flow is published, the runtime pins each
+ * tool, and each agent that names no version, to its latest version
+ * then, and every run of that flow version uses those versions. So a
+ * new tool or agent version reaches the flow only through a new flow
+ * version.
+ *
+ * Set by the runtime at publish, never authored. A flow version
+ * published before pins existed has none and binds the latest versions
+ * per run.
+ */
+export interface FlowPins {
+  /** Tool id → the exact version this flow version runs. */
+  readonly tools: Readonly<Record<string, string>>;
+  /** Agent id → the exact version its agent nodes that name none run. */
+  readonly agents: Readonly<Record<string, string>>;
+}
+
+/**
+ * `sha256:<hex>` of a flow version's pins' canonical JSON (keys sorted,
+ * no whitespace), as `pinsDigest` in `@kindgi/agents` is for an agent's.
+ */
+export function flowPinsDigest(pins: FlowPins): string {
+  const canonical = canonicalize({ tools: pins.tools, agents: pins.agents });
+  return `sha256:${createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+
+/** The blocks a flow runs that its pins name: tool ids, and agent ids with no version. */
+export interface FlowRefs {
+  readonly tools: readonly string[];
+  readonly agents: readonly string[];
+}
+
+/**
+ * Every tool a flow runs (tool nodes and fanout branches, in loop bodies
+ * too: what the runtime binds) and every agent it runs at no named
+ * version, each id once, sorted.
+ */
+export function flowRefs(flow: Flow): FlowRefs {
+  const tools = new Set<string>();
+  const agents = new Set<string>();
+  collectRefs(flow.nodes, tools, agents);
+  return { tools: [...tools].sort(), agents: [...agents].sort() };
+}
+
+function collectRefs(nodes: readonly FlowNode[], tools: Set<string>, agents: Set<string>): void {
+  for (const node of nodes) {
+    if (isLoopNode(node)) collectRefs(node.body.nodes, tools, agents);
+    else if (isFanoutNode(node)) for (const branch of node.branches) tools.add(branch.handler);
+    else if (node.kind === 'tool') tools.add(node.ref);
+    else if (node.kind === 'agent' && node.config?.version === undefined) agents.add(node.ref);
+  }
+}
+
+/** Exact versions to run a flow version with, over its pins: the shape of a comparison's override. */
+export interface FlowVersionOverrides {
+  readonly tools?: Readonly<Record<string, string>>;
+  readonly agents?: Readonly<Record<string, string>>;
+}
+
+/**
+ * The flow version with some of its blocks run at other exact versions,
+ * without publishing a new flow version: what a comparison or a replay
+ * runs ("this flow, but `acme.scorer` at 0.4.0").
+ *
+ * One mechanism with the pins: the overrides go into `pins` (over the
+ * version's own), and an agent node that names its own `config.version`
+ * gets the override there too, since a node's own version wins over a
+ * pin. `pinsDigest` is recomputed, so it names what runs. A flow version
+ * published before pins gets pins of the overrides only; its other
+ * blocks bind their latest versions, as before.
+ */
+export function withVersions(flow: Flow, overrides: FlowVersionOverrides): Flow {
+  const pins: FlowPins = {
+    tools: { ...(flow.pins?.tools ?? {}), ...(overrides.tools ?? {}) },
+    agents: { ...(flow.pins?.agents ?? {}), ...(overrides.agents ?? {}) },
+  };
+  const agents = overrides.agents ?? {};
+  return {
+    ...flow,
+    nodes: overrideNamedAgentVersions(flow.nodes, agents),
+    pins,
+    pinsDigest: flowPinsDigest(pins),
+  };
+}
+
+function overrideNamedAgentVersions(
+  nodes: readonly FlowNode[],
+  agents: Readonly<Record<string, string>>,
+): readonly FlowNode[] {
+  return nodes.map((node) => {
+    if (isLoopNode(node)) {
+      return {
+        ...node,
+        body: { ...node.body, nodes: overrideNamedAgentVersions(node.body.nodes, agents) },
+      };
+    }
+    const version = node.kind === 'agent' ? agents[node.ref] : undefined;
+    if (node.kind !== 'agent' || version === undefined || node.config?.version === undefined) {
+      return node;
+    }
+    return { ...node, config: { ...node.config, version } };
+  });
+}

package/src/types.ts

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { EdgeId, FlowId, NodeId } from '@kindgi/types';
+import type { EdgeId, FlowId, NodeId, VersionDerivation } from '@kindgi/types';
+
+import type { FlowPins } from './pins.js';
 
 /**
  * Path roots addressable in edge predicates.
@@ -799,6 +801,20 @@ export interface Flow {
    * `$end` edge (the lowest-id taken one when several fire).
    */
   readonly output?: FlowOutputSpec;
+  /**
+   * The exact tool and agent versions this flow version runs, resolved by
+   * the runtime when the version was published (see `FlowPins`). Never
+   * authored: `loadFlow` refuses it. Absent on a flow version published
+   * before pins existed; it binds the latest versions per run.
+   */
+  readonly pins?: FlowPins;
+  /** `flowPinsDigest(pins)`, recorded when the version was published. */
+  readonly pinsDigest?: string;
+  /**
+   * Set by the runtime on a version a deploy registered under another
+   * number than the definition's (see `VersionDerivation`). Never authored.
+   */
+  readonly derivedFrom?: VersionDerivation;
 }
 
 /**