cool-workflow 0.1.97 → 0.2.0

package/dist/core/state/state-explosion/report.js

@@ -0,0 +1,187 @@
+"use strict";
+// core/state/state-explosion/report.ts — buildStateExplosionReport, the
+// operator-digest builder, and maybeCompactRun's PURE decision half.
+//
+// MILESTONE 4. Byte-exact port of the old build's `buildStateExplosion
+// Report`/`buildOperatorDigestWithContext` (src/state-explosion.ts) minus
+// the disk I/O — persistence (`refreshStateExplosionSummaries`'s writes,
+// `loadStateExplosionSummaryIndex`'s read) is shell/state-explosion-
+// cli.ts's job per v2/PLAN.md's core/shell split. This file only builds
+// the report VALUE from an in-memory run + an already-loaded index.
+//
+// See size.ts/graph.ts/digest.ts's own header notes on why `operatorDigest`
+// carries truthfully-empty `failures`/`evidenceDigest`/`trustDigest` at
+// this milestone (no multi-agent/trust records exist yet — milestone 9).
+//
+// Evidence: SPEC/state-core.md "buildStateExplosionReport(...)",
+// "maybeCompactRun(...) — best-effort ... ALL errors silently caught".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeStateSize = computeStateSize;
+exports.buildOperatorDigest = buildOperatorDigest;
+exports.buildStateExplosionReport = buildStateExplosionReport;
+exports.shouldCompactRun = shouldCompactRun;
+const hash_1 = require("../../hash");
+const size_1 = require("./size");
+const graph_1 = require("./graph");
+const digest_1 = require("./digest");
+const helpers_1 = require("./helpers");
+/** `computeStateSize(run, thresholds?)` — builds the graph view via
+ *  `runToGraphViewFromWorkflowRun` then delegates to
+ *  `computeStateSizeWithGraph`. Lives here (not size.ts) so size.ts stays
+ *  graph-builder-agnostic — see size.ts's own header note on this
+ *  module-boundary choice. */
+function computeStateSize(run, thresholds = size_1.DEFAULT_STATE_EXPLOSION_THRESHOLDS) {
+    return (0, size_1.computeStateSizeWithGraph)(run, thresholds, (0, graph_1.runToGraphViewFromWorkflowRun)(run));
+}
+function buildOperatorDigest(run, compact, blackboard, stateSize, now, operator) {
+    const hiddenSourceRecords = compact.syntheticNodes.map((syn) => ({
+        kind: syn.id.split(":summary:")[1] || syn.kind,
+        count: syn.collapsedNodeCount,
+        expansionCommand: syn.expansionCommand,
+    }));
+    const expansionCommands = (0, helpers_1.unique)([
+        `node scripts/cw.js multi-agent graph ${run.id} --view full --json`,
+        `node scripts/cw.js blackboard message list ${run.id} --topic <topic-id>`,
+        `node scripts/cw.js multi-agent graph ${run.id} --view critical-path`,
+        `node scripts/cw.js multi-agent failures ${run.id} --json`,
+        ...compact.syntheticNodes.map((syn) => syn.expansionCommand),
+    ]);
+    const evidence = operator?.evidence || [];
+    const adopted = evidence.filter((e) => e.status === "adopted");
+    const missing = evidence.filter((e) => e.status === "missing" || e.status === "pending" || e.status === "conflicting");
+    const rejected = evidence.filter((e) => e.status === "rejected");
+    return {
+        schemaVersion: size_1.STATE_EXPLOSION_SCHEMA_VERSION,
+        runId: run.id,
+        id: "operator-digest",
+        scope: "run",
+        sourceRecordIds: compact.sourceRecordIds,
+        sourceFingerprint: (0, hash_1.fingerprintStrings)([compact.sourceFingerprint, blackboard.sourceFingerprint, String(stateSize.total)]),
+        includedCount: compact.compactNodeCount,
+        omittedCount: compact.collapsedNodeCount,
+        importantRefs: compact.criticalPath,
+        evidenceRefs: (0, helpers_1.unique)(adopted.map((e) => e.ref || e.id)),
+        trustAuditEventRefs: (0, helpers_1.unique)(blackboard.trustAuditEventRefs),
+        generatedAt: now,
+        status: "valid",
+        deterministic: true,
+        // Prefer the operator summary's nextAction (it reflects the whole run's
+        // blocked/evidence state); fall back to the compact graph's own when no
+        // operator summary was threaded in.
+        nextAction: operator?.nextAction || compact.nextAction,
+        stateSize,
+        compactGraphRef: compact.id,
+        blackboardDigestRef: blackboard.id,
+        criticalPath: compact.criticalPath,
+        failures: (operator?.failures || []).map((f) => ({ id: f.id, kind: f.kind, status: f.status, reason: f.reason, nextCommand: f.nextCommand })),
+        evidenceDigest: {
+            adopted: adopted.length,
+            missing: missing.length,
+            rejected: rejected.length,
+            entries: [...adopted, ...missing].slice(0, 40).map((e) => ({
+                id: e.id,
+                label: `${e.ref || e.id} (${e.status})`,
+                status: e.status,
+                sourceIds: [e.sourceId || e.id].filter(Boolean),
+                evidenceRefs: [e.ref || e.id].filter(Boolean),
+                expansionCommand: `node scripts/cw.js multi-agent evidence ${run.id} --json`,
+            })),
+        },
+        trustDigest: {
+            events: operator?.trustEvents || 0,
+            policyViolations: blackboard.policyViolations.length,
+            judgeRationales: blackboard.judgeRationale.length,
+            entries: (0, helpers_1.unique)([...blackboard.policyViolations.map((p) => p.id), ...blackboard.judgeRationale.map((j) => j.id)]),
+        },
+        hiddenSourceRecords,
+        expansionCommands,
+    };
+}
+function currentEntryFingerprint(entry, records) {
+    if (entry.scope === "blackboard")
+        return records.blackboardDigest.sourceFingerprint;
+    if (entry.id.startsWith("graph-")) {
+        if (entry.id === records.compactGraph.id)
+            return records.compactGraph.sourceFingerprint;
+        return undefined;
+    }
+    if (entry.id === "operator-digest")
+        return records.operatorDigest.sourceFingerprint;
+    return undefined;
+}
+/** Builds the full `StateExplosionReport` VALUE (no disk I/O) from an
+ *  in-memory run plus an already-loaded persisted index (or none).
+ *
+ *  `options.graphView` lets a caller that already ran
+ *  `runToGraphViewFromWorkflowRun(run)` this same tick (e.g.
+ *  `refreshStateExplosionSummaries`) hand that value in, so this function
+ *  does not build the graph view a second time. Mirrors the old build's
+ *  `StateExplosionBuildContext` memoization — one graph build per refresh,
+ *  not one per derived view. */
+function buildStateExplosionReport(run, options = {}) {
+    const thresholds = options.thresholds || size_1.DEFAULT_STATE_EXPLOSION_THRESHOLDS;
+    const now = options.now || new Date().toISOString();
+    const graphView = options.graphView || (0, graph_1.runToGraphViewFromWorkflowRun)(run);
+    const stateSize = (0, size_1.computeStateSizeWithGraph)(run, thresholds, graphView);
+    const compactGraph = (0, graph_1.buildCompactGraphFromView)(run.id, graphView, "compact", { thresholds, now });
+    const criticalPathGraph = (0, graph_1.buildCompactGraphFromView)(run.id, graphView, "critical-path", { thresholds, now });
+    // `run.blackboard` is `unknown[]`-typed at this milestone (core/state/
+    // types.ts's MultiAgentState/BlackboardState header note — real record
+    // shapes land with milestone 9); this cast is the one bridge point
+    // between "genuinely empty today" and "typed once milestone 9 writes
+    // real records", matching digest.ts's own DigestTopic/Message/... shapes.
+    const blackboardDigest = (0, digest_1.summarizeBlackboardDigest)({
+        id: run.id,
+        blackboard: run.blackboard,
+    }, undefined, now);
+    const operatorDigest = buildOperatorDigest(run, compactGraph, blackboardDigest, stateSize, now, options.operator);
+    const currentFingerprint = (0, hash_1.fingerprintStrings)([
+        compactGraph.sourceFingerprint,
+        blackboardDigest.sourceFingerprint,
+        operatorDigest.sourceFingerprint,
+        String(stateSize.total),
+    ]);
+    const persisted = options.index;
+    const staleScopes = [];
+    let status = persisted ? "valid" : "absent";
+    if (persisted) {
+        if (persisted.sourceFingerprint !== currentFingerprint)
+            status = "stale";
+        for (const entry of persisted.entries) {
+            const current = currentEntryFingerprint(entry, { compactGraph, blackboardDigest, operatorDigest });
+            if (current && current !== entry.sourceFingerprint)
+                staleScopes.push(`${entry.scope}:${entry.id}`);
+        }
+        if (staleScopes.length)
+            status = "stale";
+    }
+    const nextAction = status === "stale" || status === "absent" ? `node scripts/cw.js summary refresh ${run.id}` : operatorDigest.nextAction;
+    return {
+        schemaVersion: size_1.STATE_EXPLOSION_SCHEMA_VERSION,
+        runId: run.id,
+        generatedAt: now,
+        stateSize,
+        freshness: {
+            status,
+            persistedFingerprint: persisted?.sourceFingerprint,
+            currentFingerprint,
+            staleScopes: staleScopes.sort(),
+        },
+        index: persisted,
+        compactGraph,
+        criticalPathGraph,
+        blackboardDigest,
+        operatorDigest,
+        hiddenSourceRecords: operatorDigest.hiddenSourceRecords,
+        expansionCommands: operatorDigest.expansionCommands,
+        nextAction,
+    };
+}
+/** The pure decision half of `maybeCompactRun`: true when the caller
+ *  should refresh summaries. The actual refresh (disk write) + the "catch
+ *  ALL errors" best-effort wrapper live in shell/state-explosion-cli.ts,
+ *  since only that layer can fail on real disk I/O. */
+function shouldCompactRun(run, thresholds = size_1.DEFAULT_STATE_EXPLOSION_THRESHOLDS) {
+    const graphView = (0, graph_1.runToGraphViewFromWorkflowRun)(run);
+    return (0, size_1.computeStateSizeWithGraph)(run, thresholds, graphView).compactionRecommended;
+}

package/dist/{state-explosion → core/state/state-explosion}/size.js

@@ -1,9 +1,30 @@
 "use strict";
+// core/state/state-explosion/size.ts — computeStateSizeWithGraph,
+// DEFAULT_STATE_EXPLOSION_THRESHOLDS.
+//
+// MILESTONE 4 (v2/PLAN.md build order, step 4). Byte-exact port of the old
+// build's src/state-explosion/size.ts. The counts are the same 12
+// categories the old build reads off `run.multiAgent`/`run.blackboard`
+// (loose `unknown[]`-typed record arrays at this milestone — see core/
+// state/types.ts's header note; their per-record shapes land with
+// milestone 9), so this file needs no reshape once those arrays start
+// carrying real records.
+//
+// `computeStateSize` (the old build's one-arg convenience wrapper that
+// ALSO builds the graph) is NOT defined here — the old build's own module
+// boundary already has size.ts call the graph builder from a DIFFERENT
+// file (multi-agent-operator-ux.ts); this file mirrors that by staying
+// graph-builder-agnostic (`computeStateSizeWithGraph` takes the graph
+// view as a plain parameter) and core/state/state-explosion/report.ts
+// (which already imports both this file and graph.ts) supplies the
+// one-arg convenience wrapper instead, avoiding a size.ts <-> graph.ts
+// import cycle.
+//
+// Evidence: SPEC/state-core.md "src/state-explosion.ts + src/state-
+// explosion/* — derived summary layer", "computeStateSize(...)".
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS = exports.STATE_EXPLOSION_SCHEMA_VERSION = void 0;
-exports.computeStateSize = computeStateSize;
 exports.computeStateSizeWithGraph = computeStateSizeWithGraph;
-const multi_agent_operator_ux_1 = require("../multi-agent-operator-ux");
 exports.STATE_EXPLOSION_SCHEMA_VERSION = 1;
 exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS = {
     graphNodes: 40,
@@ -11,11 +32,8 @@ exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS = {
     blackboardMessages: 25,
     blackboardRecords: 40,
     collapseBucket: 6,
-    totalRecords: 80
+    totalRecords: 80,
 };
-function computeStateSize(run, thresholds = exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS) {
-    return computeStateSizeWithGraph(run, thresholds, (0, multi_agent_operator_ux_1.buildMultiAgentOperatorGraph)(run));
-}
 function computeStateSizeWithGraph(run, thresholds, graph) {
     const ma = run.multiAgent || { runs: [], roles: [], groups: [], memberships: [], fanouts: [], fanins: [] };
     const bb = run.blackboard || { topics: [], messages: [], contexts: [], artifacts: [], snapshots: [], decisions: [] };
@@ -33,7 +51,7 @@ function computeStateSizeWithGraph(run, thresholds, graph) {
         snapshots: (bb.snapshots || []).length,
         decisions: (bb.decisions || []).length,
         graphNodes: graph.nodes.length,
-        graphEdges: graph.edges.length
+        graphEdges: graph.edges.length,
     };
     const total = counts.multiAgentRuns +
         counts.roles +

package/dist/{state-node.js → core/state/state-node.js}

@@ -1,7 +1,18 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+// core/state/state-node.ts — StateNode lifecycle and pipeline-contract gates.
+//
+// MILESTONE 3. Byte-exact port of the old build's src/state-node.ts, split
+// into a PURE half (this file: create/transition/validate/link/record —
+// everything that does not touch disk) and a shell half
+// (shell/node-store.ts: writeRunNode, the only disk write). `appendRunNode`
+// mutates `run.nodes` in place (pure data mutation, no fs) and then calls
+// out to a caller-supplied persist function so this file itself never
+// imports fs.
+//
+// Evidence: SPEC/state-core.md "src/state-node.ts — StateNode lifecycle and
+// contract gates", "StateNode transition matrix", "Deterministic id
+// fallback", "Contract gates" (v2/PLAN.md byte-compat item 7 — the double
+// commit gate).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PipelineContractError = exports.PIPELINE_CONTRACT_SCHEMA_VERSION = exports.STATE_NODE_SCHEMA_VERSION = void 0;
 exports.createStateNode = createStateNode;
@@ -12,37 +23,36 @@ exports.recordNodeError = recordNodeError;
 exports.linkStateNodes = linkStateNodes;
 exports.appendRunNode = appendRunNode;
 exports.upsertRunContract = upsertRunContract;
-exports.writeRunNode = writeRunNode;
 exports.artifactExists = artifactExists;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const state_1 = require("./state");
-const execution_backend_1 = require("./execution-backend");
-const telemetry_attestation_1 = require("./telemetry-attestation");
+const hash_1 = require("../hash");
 exports.STATE_NODE_SCHEMA_VERSION = 1;
 exports.PIPELINE_CONTRACT_SCHEMA_VERSION = 1;
 class PipelineContractError extends Error {
     structured;
-    constructor(error) {
+    /** `error.at` wins when the caller already has one (e.g. re-wrapping a
+     *  structured error); `now` is the explicit clock value for a fresh one;
+     *  the real clock is read ONLY when neither is given, matching
+     *  node-snapshot.ts's `options.now` fallback pattern. */
+    constructor(error, now) {
         super(error.message);
         this.name = "PipelineContractError";
-        this.structured = {
-            ...error,
-            at: error.at || new Date().toISOString()
-        };
+        this.structured = { ...error, at: error.at || now || new Date().toISOString() };
     }
 }
 exports.PipelineContractError = PipelineContractError;
-function createStateNode(input) {
-    const now = new Date().toISOString();
+/** `now` is the explicit clock value; the real clock is read ONLY when it
+ *  is omitted, matching node-snapshot.ts's `options.now` fallback so a
+ *  caller that always passes `now` gets byte-stable createdAt/updatedAt. */
+function createStateNode(input, now) {
+    const at = now || new Date().toISOString();
     return {
         schemaVersion: exports.STATE_NODE_SCHEMA_VERSION,
         id: input.id || createNodeId(input),
         kind: input.kind,
         status: input.status || "pending",
         loopStage: input.loopStage,
-        createdAt: now,
-        updatedAt: now,
+        createdAt: at,
+        updatedAt: at,
         inputs: input.inputs || {},
         outputs: input.outputs || {},
         artifacts: input.artifacts || [],
@@ -51,44 +61,34 @@ function createStateNode(input) {
         parents: input.parents || [],
         children: input.children || [],
         contractId: input.contractId,
-        metadata: input.metadata
+        metadata: input.metadata,
     };
 }
-function transitionStateNode(node, input) {
+/** The full transition matrix PLUS the second gate: `committed` is refused
+ *  unless the node is already `verified` (checked AFTER the matrix, its own
+ *  error code `commit-without-verifier`). An illegal transition throws
+ *  BEFORE the node changes. */
+function transitionStateNode(node, input, now) {
     if (!isLegalTransition(node.status, input.status)) {
-        throw contractError("illegal-transition", `State node ${node.id} cannot transition from ${node.status} to ${input.status}`, {
-            nodeId: node.id,
-            details: {
-                from: node.status,
-                to: input.status
-            }
-        });
+        throw contractError("illegal-transition", `State node ${node.id} cannot transition from ${node.status} to ${input.status}`, { nodeId: node.id, details: { from: node.status, to: input.status } });
     }
     if (input.status === "committed" && node.status !== "verified") {
-        throw contractError("commit-without-verifier", `State node ${node.id} cannot be committed before it is verified`, {
-            nodeId: node.id,
-            details: {
-                from: node.status,
-                to: input.status
-            }
-        });
+        throw contractError("commit-without-verifier", `State node ${node.id} cannot be committed before it is verified`, { nodeId: node.id, details: { from: node.status, to: input.status } });
     }
     return {
         ...node,
         status: input.status,
         loopStage: input.loopStage || node.loopStage,
-        updatedAt: new Date().toISOString(),
+        updatedAt: now || new Date().toISOString(),
         outputs: input.outputs ? { ...node.outputs, ...input.outputs } : node.outputs,
         artifacts: input.artifacts ? mergeById(node.artifacts, input.artifacts) : node.artifacts,
         evidence: input.evidence ? mergeById(node.evidence, input.evidence) : node.evidence,
-        metadata: input.metadata ? { ...(node.metadata || {}), ...input.metadata } : node.metadata
+        metadata: input.metadata ? { ...(node.metadata || {}), ...input.metadata } : node.metadata,
     };
 }
 function validatePipelineContract(contract) {
     if (contract.schemaVersion !== exports.PIPELINE_CONTRACT_SCHEMA_VERSION) {
-        throw contractError("invalid-contract-schema", `Pipeline contract ${contract.id || "(missing id)"} has unsupported schemaVersion`, {
-            details: { schemaVersion: contract.schemaVersion }
-        });
+        throw contractError("invalid-contract-schema", `Pipeline contract ${contract.id || "(missing id)"} has unsupported schemaVersion`, { details: { schemaVersion: contract.schemaVersion } });
     }
     if (!contract.id)
         throw contractError("invalid-contract-id", "Pipeline contract id is required");
@@ -106,97 +106,81 @@ function validatePipelineContract(contract) {
     }
     if (contract.compatibility.minSchemaVersion > exports.STATE_NODE_SCHEMA_VERSION) {
         throw contractError("incompatible-contract", `Pipeline contract ${contract.id} requires newer StateNode schema`, {
-            details: contract.compatibility
+            details: contract.compatibility,
         });
     }
 }
-function assertNodeSatisfiesContract(node, contract, stageId) {
+/** `pathExists` defaults to a function that always returns `true` (no path
+ *  ever "missing") ONLY when the caller genuinely has no filesystem to
+ *  check against; every real caller (shell/) passes `fs.existsSync` so the
+ *  `missing-artifact-path` gate behaves exactly like the old build. Kept as
+ *  an explicit parameter (never a top-level `require("node:fs")`) so this
+ *  stays a pure core/ module per v2/PLAN.md's core/shell split. */
+function assertNodeSatisfiesContract(node, contract, stageId, pathExists = () => true) {
     validatePipelineContract(contract);
     const stage = contract.stages.find((candidate) => candidate.id === stageId);
     if (!stage) {
-        throw contractError("unknown-contract-stage", `Pipeline contract ${contract.id} has no stage ${stageId}`, {
-            nodeId: node.id
-        });
+        throw contractError("unknown-contract-stage", `Pipeline contract ${contract.id} has no stage ${stageId}`, { nodeId: node.id });
     }
     if (!stage.acceptedInputKinds.includes(node.kind)) {
         throw contractError("unexpected-node-kind", `Stage ${stage.id} does not accept node kind ${node.kind}`, {
             nodeId: node.id,
-            details: { expected: stage.acceptedInputKinds, actual: node.kind }
+            details: { expected: stage.acceptedInputKinds, actual: node.kind },
         });
     }
     if (!stage.acceptedInputStatuses.includes(node.status)) {
         throw contractError("unexpected-node-status", `Stage ${stage.id} does not accept node status ${node.status}`, {
             nodeId: node.id,
-            details: { expected: stage.acceptedInputStatuses, actual: node.status }
+            details: { expected: stage.acceptedInputStatuses, actual: node.status },
         });
     }
-    assertRequiredArtifacts(node, stage);
+    assertRequiredArtifacts(node, stage, pathExists);
     assertRequiredEvidence(node, stage, contract);
     assertVerifierGate(node, stage, contract);
 }
-function recordNodeError(node, error) {
+function recordNodeError(node, error, now) {
+    const at = now || new Date().toISOString();
     return {
         ...node,
         status: "failed",
-        updatedAt: new Date().toISOString(),
-        errors: [
-            ...node.errors,
-            {
-                ...error,
-                at: error.at || new Date().toISOString(),
-                nodeId: error.nodeId || node.id
-            }
-        ]
+        updatedAt: at,
+        errors: [...node.errors, { ...error, at: error.at || at, nodeId: error.nodeId || node.id }],
     };
 }
-function linkStateNodes(parent, child) {
+function linkStateNodes(parent, child, now) {
+    const at = now || new Date().toISOString();
     return [
-        {
-            ...parent,
-            updatedAt: new Date().toISOString(),
-            children: unique([...parent.children, child.id])
-        },
-        {
-            ...child,
-            updatedAt: new Date().toISOString(),
-            parents: unique([...child.parents, parent.id])
-        }
+        { ...parent, updatedAt: at, children: unique([...parent.children, child.id]) },
+        { ...child, updatedAt: at, parents: unique([...child.parents, parent.id]) },
     ];
 }
-function appendRunNode(run, node) {
-    // Mutate run.nodes in place rather than rebuilding the whole array on every
-    // append. The old code did `nodes.map(...)` / `[...nodes, node]` per call, so a
-    // run that appends N nodes allocated arrays of size 1..N — O(N^2) churn + GC on
-    // a hot path (every dispatch/result/blackboard node). In place: O(1) per append
-    // for the common new-node case, and the resulting array — content AND order — is
-    // byte-identical to before (push appends at the end, replace keeps the slot), so
-    // the persisted state.json is unchanged. appendRunNode is the only writer of
-    // run.nodes, so the array reference stays stable across a run.
+/** Upsert `node` into `run.nodes` IN PLACE (replace at the same index when
+ *  the id exists, else push at the end — the array reference is stable).
+ *  `persist` is a caller-supplied side effect (shell/node-store.ts's
+ *  `writeRunNode`) so this pure module never imports fs itself. */
+function appendRunNode(run, node, persist) {
     const nodes = run.nodes || (run.nodes = []);
     const index = nodes.findIndex((candidate) => candidate.id === node.id);
     if (index >= 0)
         nodes[index] = node;
     else
         nodes.push(node);
-    writeRunNode(run, node);
+    if (persist)
+        persist(run, node);
     return node;
 }
 function upsertRunContract(run, contract) {
     validatePipelineContract(contract);
     const contracts = run.contracts || [];
     const index = contracts.findIndex((candidate) => candidate.id === contract.id);
-    run.contracts =
-        index >= 0 ? contracts.map((candidate) => (candidate.id === contract.id ? contract : candidate)) : [...contracts, contract];
+    run.contracts = index >= 0 ? contracts.map((candidate) => (candidate.id === contract.id ? contract : candidate)) : [...contracts, contract];
     return contract;
 }
-function writeRunNode(run, node) {
-    const dir = run.paths.stateNodesDir || node_path_1.default.join(run.paths.runDir, "nodes");
-    const file = node_path_1.default.join(dir, `${(0, state_1.safeFileName)(node.id)}.json`);
-    (0, state_1.writeJson)(file, node);
-    return file;
-}
-function artifactExists(artifact) {
-    return Boolean(artifact.path && node_fs_1.default.existsSync(artifact.path));
+/** `Boolean(artifact.path && <exists>)` — the existence check itself is
+ *  supplied by the caller (shell) so this stays pure; callers pass
+ *  `fs.existsSync` in practice. */
+function artifactExists(artifact, exists) {
+    return Boolean(artifact.path && exists(artifact.path));
 }
 function validateStage(contract, stage, seen) {
     if (!stage.id)
@@ -216,20 +200,20 @@ function validateStage(contract, stage, seen) {
         throw contractError("invalid-contract-stage-output", `Stage ${stage.id} producedOutputKind is required`);
     }
 }
-function assertRequiredArtifacts(node, stage) {
+function assertRequiredArtifacts(node, stage, pathExists) {
     for (const required of stage.requiredArtifacts || []) {
         const artifact = node.artifacts.find((candidate) => candidate.id === required || candidate.kind === required);
         if (!artifact) {
             throw contractError("missing-required-artifact", `Node ${node.id} is missing required artifact ${required}`, {
                 nodeId: node.id,
-                details: { requiredArtifact: required }
+                details: { requiredArtifact: required },
             });
         }
-        if (!artifactExists(artifact)) {
+        if (!artifactExists(artifact, pathExists)) {
             throw contractError("missing-artifact-path", `Node ${node.id} artifact ${artifact.id} path does not exist`, {
                 nodeId: node.id,
                 path: artifact.path,
-                details: { artifactId: artifact.id }
+                details: { artifactId: artifact.id },
             });
         }
     }
@@ -240,7 +224,7 @@ function assertRequiredEvidence(node, stage, contract) {
     if ((requiredEvidence.length || contractRequiresEvidence) && !node.evidence.length) {
         throw contractError("missing-required-evidence", `Node ${node.id} is missing required evidence`, {
             nodeId: node.id,
-            details: { requiredEvidence }
+            details: { requiredEvidence },
         });
     }
     for (const required of requiredEvidence) {
@@ -248,7 +232,7 @@ function assertRequiredEvidence(node, stage, contract) {
         if (!evidence) {
             throw contractError("missing-required-evidence", `Node ${node.id} is missing required evidence ${required}`, {
                 nodeId: node.id,
-                details: { requiredEvidence: required }
+                details: { requiredEvidence: required },
             });
         }
     }
@@ -262,15 +246,16 @@ function assertVerifierGate(node, stage, contract) {
     if (!acceptedStatuses.includes(node.status)) {
         throw contractError("verifier-gate-blocked", `Stage ${stage.id} requires verifier status ${acceptedStatuses.join(", ")}`, {
             nodeId: node.id,
-            details: { actual: node.status, accepted: acceptedStatuses }
+            details: { actual: node.status, accepted: acceptedStatuses },
         });
     }
     if ((gate?.requiredEvidence || contract.evidencePolicy?.requireEvidence) && !node.evidence.length) {
-        throw contractError("verifier-gate-missing-evidence", `Stage ${stage.id} requires evidence before commit`, {
-            nodeId: node.id
-        });
+        throw contractError("verifier-gate-missing-evidence", `Stage ${stage.id} requires evidence before commit`, { nodeId: node.id });
     }
 }
+/** The transition matrix: `same -> same` is always legal (checked first via
+ *  `from === to`), plus the table below. `committed` is terminal (empty
+ *  array). */
 function isLegalTransition(from, to) {
     if (from === to)
         return true;
@@ -282,31 +267,23 @@ function isLegalTransition(from, to) {
         blocked: ["pending", "failed"],
         verified: ["committed", "rejected"],
         rejected: ["pending", "failed"],
-        committed: []
+        committed: [],
     };
     return allowed[from].includes(to);
 }
 function contractError(code, message, options = {}) {
-    return new PipelineContractError({
-        code,
-        message,
-        ...options
-    });
+    return new PipelineContractError({ code, message, ...options });
 }
-// Deterministic id (FreeBSD-audit L12/L13): no wall-clock stamp, no PRNG suffix.
-// Almost every node is created WITH an explicit, already-deterministic id
-// (e.g. `${run.id}:result:${task.id}`); this fallback only fires for ad-hoc nodes
-// minted without an id. We bind the id to a short sha256 of the node's stable
-// content (kind + loopStage + canonical inputs/outputs/contract), so the same
-// logical node yields a byte-identical id across runs and replay reaches the same
-// fingerprint. Two nodes with identical content collapse to the same id by design.
+/** Deterministic id fallback: no wall-clock, no random. A node minted
+ *  without an explicit id gets `"<kind>-" + <first 16 hex of sha256(...)>`.
+ *  Two nodes with the same content collapse to ONE id by design. */
 function createNodeId(input) {
-    const digest = (0, execution_backend_1.sha256)((0, telemetry_attestation_1.stableStringify)({
+    const digest = (0, hash_1.sha256)((0, hash_1.stableStringify)({
         kind: input.kind,
         loopStage: input.loopStage,
         contractId: input.contractId ?? null,
         inputs: input.inputs ?? null,
-        outputs: input.outputs ?? null
+        outputs: input.outputs ?? null,
     }));
     return `${input.kind}-${digest.replace("sha256:", "").slice(0, 16)}`;
 }

package/dist/core/state/types.js

@@ -0,0 +1,19 @@
+"use strict";
+// core/state/types.ts — the state-kernel's own type set.
+//
+// MILESTONE 3 (v2/PLAN.md build order, step 3). Scoped to exactly what
+// state-core.md's public surface needs: WorkflowRun and everything it
+// carries, StateNode + its snapshot/replay/diff family, the pipeline
+// contract shape, and the small persisted-record shapes validation.ts
+// guards. Later milestones (multi-agent, blackboard, topology, worker,
+// candidate, trust) add their OWN richer types under their own module —
+// this file only carries the FIELD SET this milestone's schema/migration/
+// node-lifecycle/snapshot code actually reads or writes, ported from the
+// old build's src/types/*.ts. Optional subsystem state (multiAgent,
+// blackboard, topologies, collaboration, workers, etc.) is typed loosely
+// here (its own schemaVersion + array keys only) since normalizeRunState
+// only ever fills defaults/shape-checks those fields at this milestone;
+// the richer per-record shapes land with their owning milestone.
+//
+// Pure types — no runtime cost, no imports beyond each other.
+Object.defineProperty(exports, "__esModule", { value: true });