cool-workflow 0.1.98 → 0.2.0

package/dist/core/pipeline/runner.js

@@ -0,0 +1,230 @@
+"use strict";
+// core/pipeline/runner.ts — findRunnablePipelineStages, runPipelineStage
+// (pure transform), advancePipeline, failPipelineStage.
+//
+// MILESTONE 6+7 (combined). Byte-exact port of the old build's
+// src/pipeline-runner.ts, split so this file stays PURE (no fs — actual
+// disk writes are the caller's `persist` callback, threaded through from
+// shell/). The real per-stage disk write (node file + checkpoint) is
+// shell/run-store.ts + shell/node-store.ts; this file only mutates the
+// in-memory `run` object and returns what happened.
+//
+// Evidence: SPEC/pipeline-run.md "Pipeline kernel — src/pipeline-
+// runner.ts".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRunContract = getRunContract;
+exports.getRunNode = getRunNode;
+exports.findRunnablePipelineStages = findRunnablePipelineStages;
+exports.runPipelineStage = runPipelineStage;
+exports.advancePipeline = advancePipeline;
+exports.failPipelineStage = failPipelineStage;
+const state_node_1 = require("../state/state-node");
+const contract_1 = require("./contract");
+/** `getRunContract(run, contractId?)` — with no id, uses the default
+ *  contract id; upserts the default contract onto the run if absent. An
+ *  unknown non-default id throws. A found contract is re-validated. */
+function getRunContract(run, contractId) {
+    const id = contractId || contract_1.DEFAULT_PIPELINE_CONTRACT_ID;
+    const contracts = run.contracts || [];
+    const found = contracts.find((c) => c.id === id);
+    if (found) {
+        (0, state_node_1.validatePipelineContract)(found);
+        return found;
+    }
+    if (id === contract_1.DEFAULT_PIPELINE_CONTRACT_ID) {
+        return (0, state_node_1.upsertRunContract)(run, (0, contract_1.createDefaultPipelineContract)());
+    }
+    throw new Error(`Unknown pipeline contract for run ${run.id}: ${id}`);
+}
+/** `getRunNode(run, nodeId)` — finds a node or throws. */
+function getRunNode(run, nodeId) {
+    const node = (run.nodes || []).find((n) => n.id === nodeId);
+    if (!node)
+        throw new Error(`Unknown state node for run ${run.id}: ${nodeId}`);
+    return node;
+}
+/** Byte-exact port of the old build's `hasRequiredEvidence`: a stage's own
+ *  `requiredEvidence` list AND the contract-wide
+ *  `evidencePolicy.requireEvidence` flag both gate this pre-filter, exactly
+ *  like assertRequiredEvidence's stricter check in state-node.ts — so a
+ *  node findRunnablePipelineStages reports "runnable" never fails this
+ *  same check again inside runPipelineStage. */
+function evidenceSatisfied(node, stage, contract) {
+    const requiredEvidence = stage.requiredEvidence || [];
+    const contractRequiresEvidence = Boolean(contract.evidencePolicy?.requireEvidence);
+    if ((requiredEvidence.length || contractRequiresEvidence) && !node.evidence.length)
+        return false;
+    for (const required of requiredEvidence) {
+        const matches = node.evidence.filter((e) => e.id === required || e.source === required);
+        if (!matches.length)
+            return false;
+    }
+    return true;
+}
+function artifactsSatisfied(node, stage, pathExists) {
+    for (const required of stage.requiredArtifacts || []) {
+        const artifact = node.artifacts.find((a) => a.id === required || a.kind === required);
+        if (!artifact)
+            return false;
+        if (artifact.path && !pathExists(artifact.path))
+            return false;
+    }
+    return true;
+}
+function verifierGatePasses(node, stage, contract) {
+    const gate = stage.verifierGate;
+    const commitRequiresGate = Boolean(contract.commitPolicy?.requiresVerifierGate) && stage.producedOutputKind === "commit";
+    if (!gate?.required && !commitRequiresGate)
+        return true;
+    const acceptedStatuses = gate?.acceptedStatuses || contract.commitPolicy?.acceptedVerifierStatuses || ["verified"];
+    if (!acceptedStatuses.includes(node.status))
+        return false;
+    if ((gate?.requiredEvidence || contract.evidencePolicy?.requireEvidence) && !node.evidence.length)
+        return false;
+    return true;
+}
+/** `findRunnablePipelineStages(run, contract?)` — every node x every
+ *  stage, kept only when kind/status/artifacts/evidence/verifier-gate all
+ *  pass. */
+function findRunnablePipelineStages(run, contract, pathExists = () => true) {
+    const resolvedContract = contract || getRunContract(run);
+    const out = [];
+    for (const node of run.nodes || []) {
+        for (const stage of resolvedContract.stages) {
+            if (!stage.acceptedInputKinds.includes(node.kind))
+                continue;
+            if (!stage.acceptedInputStatuses.includes(node.status))
+                continue;
+            if (!artifactsSatisfied(node, stage, pathExists))
+                continue;
+            if (!evidenceSatisfied(node, stage, resolvedContract))
+                continue;
+            if (!verifierGatePasses(node, stage, resolvedContract))
+                continue;
+            out.push({
+                runId: run.id,
+                contractId: resolvedContract.id,
+                stageId: stage.id,
+                inputNodeId: node.id,
+                outputKind: stage.producedOutputKind,
+            });
+        }
+    }
+    return out;
+}
+/** `runPipelineStage(run, stageId, inputNodeId, options?)` — the one-step
+ *  engine. Mutates `run.nodes` in place (via appendRunNode/persist) and
+ *  returns the result envelope. A thrown PipelineContractError becomes
+ *  `failPipelineStage`; any other error re-throws untouched. */
+function runPipelineStage(run, stageId, inputNodeId, options = {}, runnerOptions = {}) {
+    const contract = getRunContract(run, runnerOptions.contractId);
+    const inputNode = getRunNode(run, inputNodeId);
+    const pathExists = runnerOptions.pathExists || (() => true);
+    try {
+        (0, state_node_1.assertNodeSatisfiesContract)(inputNode, contract, stageId, pathExists);
+    }
+    catch (error) {
+        if (error instanceof state_node_1.PipelineContractError) {
+            return failPipelineStage(run, stageId, inputNode, error, runnerOptions);
+        }
+        throw error;
+    }
+    const stage = contract.stages.find((s) => s.id === stageId);
+    const targetStatus = options.outputStatus || (stage.producedOutputKind === "commit" ? "committed" : "completed");
+    const initialStatus = targetStatus === "committed" ? "verified" : "pending";
+    let outputNode = (0, state_node_1.createStateNode)({
+        id: options.outputNodeId,
+        kind: stage.producedOutputKind,
+        status: initialStatus,
+        loopStage: options.loopStage || inputNode.loopStage,
+        inputs: options.inputs,
+        outputs: options.outputs,
+        artifacts: options.artifacts,
+        evidence: options.evidence,
+        contractId: contract.id,
+        metadata: options.metadata,
+    });
+    if (targetStatus !== initialStatus) {
+        outputNode = (0, state_node_1.transitionStateNode)(outputNode, {
+            status: targetStatus,
+            loopStage: options.loopStage,
+            outputs: options.outputs,
+            artifacts: options.artifacts,
+            evidence: options.evidence,
+            metadata: options.metadata,
+        });
+    }
+    const persistNode = options.persist === false || runnerOptions.persist === false ? undefined : runnerOptions.persistNode;
+    const [linkedInput, linkedOutput] = (0, state_node_1.linkStateNodes)(inputNode, outputNode);
+    (0, state_node_1.appendRunNode)(run, linkedInput, persistNode);
+    (0, state_node_1.appendRunNode)(run, linkedOutput, persistNode);
+    if (options.persist !== false && runnerOptions.persist !== false && runnerOptions.saveCheckpoint) {
+        runnerOptions.saveCheckpoint(run);
+    }
+    return {
+        status: "advanced",
+        runId: run.id,
+        stageId,
+        inputNodeId: inputNode.id,
+        outputNodeId: linkedOutput.id,
+        outputKind: stage.producedOutputKind,
+    };
+}
+/** `advancePipeline(run, options?)` — first runnable stage list; empty ⇒
+ *  idle. First "advanced" result stops. A "failed" result stops unless
+ *  `contract.failurePolicy.autoAdvance`. */
+function advancePipeline(run, runnerOptions = {}) {
+    const contract = getRunContract(run, runnerOptions.contractId);
+    const stages = findRunnablePipelineStages(run, contract, runnerOptions.pathExists);
+    if (!stages.length)
+        return { status: "idle", stages: [] };
+    let lastFailure;
+    for (const candidate of stages) {
+        const result = runPipelineStage(run, candidate.stageId, candidate.inputNodeId, {}, runnerOptions);
+        if (result.status === "advanced") {
+            return { ...result, stages };
+        }
+        lastFailure = { ...result, stages };
+        if (!contract.failurePolicy?.autoAdvance)
+            return lastFailure;
+    }
+    return lastFailure || { status: "idle", stages };
+}
+function failPipelineStage(run, stageId, inputNode, error, options = {}) {
+    const contract = getRunContract(run, options.contractId);
+    const stage = contract.stages.find((s) => s.id === stageId);
+    const structured = error instanceof state_node_1.PipelineContractError
+        ? error.structured
+        : {
+            code: "pipeline-stage-error",
+            message: error instanceof Error ? error.message : String(error),
+            at: options.now || new Date().toISOString(),
+            nodeId: inputNode.id,
+            retryable: stage?.failure?.retryable ?? contract.failurePolicy?.retryableByDefault ?? false,
+        };
+    const preserve = options.preserveFailureNode ?? stage?.failure?.preserveFailureNode ?? contract.failurePolicy?.preserveFailureNodes ?? false;
+    if (!preserve) {
+        return { status: "failed", runId: run.id, stageId, inputNodeId: inputNode.id, error: structured };
+    }
+    const persistNode = options.persist === false ? undefined : options.persistNode;
+    let errorNode = (0, state_node_1.recordNodeError)((0, state_node_1.createStateNode)({
+        // Honor a caller-supplied failure node id when given (shell binds it to
+        // the caller's outputNodeId); else auto-mint (`error-<hash>`).
+        ...(options.failureNodeId ? { id: options.failureNodeId } : {}),
+        kind: stage?.failure?.failureKind || "error",
+        status: "pending",
+        loopStage: inputNode.loopStage,
+        contractId: contract.id,
+        // `pipelineStage` names the stage that failed so collectRunErrors's
+        // dedup key matches the feedback recorded here (both key on stageId).
+        // Byte-behavior port of the old build's failed-node metadata.
+        metadata: { pipelineStage: stageId, preserved: true },
+    }), structured);
+    const [linkedInput, linkedError] = (0, state_node_1.linkStateNodes)(inputNode, errorNode);
+    (0, state_node_1.appendRunNode)(run, linkedInput, persistNode);
+    (0, state_node_1.appendRunNode)(run, linkedError, persistNode);
+    errorNode = linkedError;
+    if (options.recordFeedback)
+        options.recordFeedback(run, structured, errorNode.id);
+    return { status: "failed", runId: run.id, stageId, inputNodeId: inputNode.id, outputNodeId: errorNode.id, error: structured };
+}

package/dist/{contract-migration.js → core/state/contract-migration.js}

@@ -1,62 +1,31 @@
 "use strict";
-// Contract Migration Tooling (v0.1.36) — a first-class, declared migration
-// subsystem over the existing run-state migration pipeline, extended to the
-// workflow-app schema.
+// core/state/contract-migration.ts — declared migration registry + prover.
 //
-// BSD discipline:
-//  - MECHANISM, not policy: a declared registry of edges per contract is the
-//    single source for "what versions exist and how to advance them". The caller
-//    names the contract + snapshot; nothing guesses.
-//  - FAIL CLOSED ON REACHABILITY [load-bearing]: before transforming, resolve the
-//    full chain detected -> CURRENT. Below minimum, above current, or no chained
-//    path REFUSES with a named unsupported verdict and NO write — never a
-//    best-effort partial migration.
-//  - REUSE, don't fork: run-state edges ARE RUN_STATE_MIGRATIONS; the chain runner
-//    wraps the existing migrateRunState. No transform logic is duplicated.
-//  - APPEND-ONLY / NON-DESTRUCTIVE: the prover proves every source key survives,
-//    the result validates at CURRENT, re-running is idempotent, and the source
-//    snapshot is byte-immutable (hash-before == hash-after).
-//  - DETERMINISTIC: proofs are sha256-fingerprinted; no wall-clock in the payload.
+// MILESTONE 3. Byte-exact port of the old build's src/contract-migration.ts
+// (renamed target per v2/PLAN.md's module layout note — listed there as
+// `pipeline/contract-migration.ts`, kept here under state/ since every
+// symbol it needs — RUN_STATE_MIGRATIONS, migrateRunState,
+// findMigrationPath — is this milestone's own state kernel and nothing in
+// `pipeline/` exists yet). Pure: proofs are sha256-fingerprinted; no
+// wall-clock in the payload.
 //
-// See docs/contract-migration-tooling.7.md.
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+// Evidence: SPEC/state-core.md "src/contract-migration.ts — declared
+// migration registry + prover", "MigrationVerdict / MigrationProof JSON",
+// "Contract-migration prover invariants".
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONTRACT_MIGRATION_SCHEMA_VERSION = void 0;
 exports.listMigrationContracts = listMigrationContracts;
 exports.resolveChain = resolveChain;
 exports.checkMigration = checkMigration;
 exports.proveMigration = proveMigration;
-const node_crypto_1 = __importDefault(require("node:crypto"));
-const version_1 = require("./version");
-const state_migrations_1 = require("./state-migrations");
+const hash_1 = require("../hash");
+const version_1 = require("../version");
+const migrations_1 = require("./migrations");
 exports.CONTRACT_MIGRATION_SCHEMA_VERSION = 1;
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-/** Deterministic, key-sorted, EXACT content hash (not normalized — used to prove
- *  the source snapshot was not mutated). */
-function stableHash(value) {
-    const sort = (v) => Array.isArray(v)
-        ? v.map(sort)
-        : isRecord(v)
-            ? Object.keys(v)
-                .sort()
-                .reduce((out, key) => {
-                out[key] = sort(v[key]);
-                return out;
-            }, {})
-            : v;
-    return `sha256:${node_crypto_1.default.createHash("sha256").update(JSON.stringify(sort(value))).digest("hex")}`;
-}
-// ---------------------------------------------------------------------------
-// The declared registry. run-state edges ARE RUN_STATE_MIGRATIONS (no fork). The
-// workflow-app contract is declared with its current version; it has no edges yet
-// (only schema 1 exists) — an older app fails closed with a precise reason rather
-// than being silently accepted or flatly rejected.
-// ---------------------------------------------------------------------------
-const RUN_STATE_EDGES = state_migrations_1.RUN_STATE_MIGRATIONS.map((step) => ({
+const RUN_STATE_EDGES = migrations_1.RUN_STATE_MIGRATIONS.map((step) => ({
     contract: "run-state",
     from: step.from,
     to: step.to,
@@ -64,8 +33,8 @@ const RUN_STATE_EDGES = state_migrations_1.RUN_STATE_MIGRATIONS.map((step) => ({
     proof: {
         invariant: `run-state ${step.from} -> ${step.to}: adds defaults only, drops no existing key`,
         addsDefaulted: ["schemaVersion"],
-        dropsNothing: true
-    }
+        dropsNothing: true,
+    },
 }));
 function listMigrationContracts() {
     return [
@@ -73,14 +42,14 @@ function listMigrationContracts() {
             contract: "run-state",
             currentVersion: version_1.CURRENT_RUN_STATE_SCHEMA_VERSION,
             minVersion: version_1.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION,
-            edges: RUN_STATE_EDGES
+            edges: RUN_STATE_EDGES,
         },
         {
             contract: "workflow-app",
             currentVersion: version_1.WORKFLOW_APP_SCHEMA_VERSION,
             minVersion: version_1.WORKFLOW_APP_SCHEMA_VERSION,
-            edges: []
-        }
+            edges: [],
+        },
     ];
 }
 function getContract(contractId) {
@@ -95,20 +64,27 @@ function detectVersion(contractId, snapshot) {
         return declared;
     return contractId === "run-state" ? version_1.LEGACY_RUN_STATE_SCHEMA_VERSION : 0;
 }
-/** Fail-closed reachability: detected -> current using the DAG path resolver. */
+/** Fail-closed reachability: detected -> current using the DAG path
+ *  resolver (run-state) or a simple edge walk (workflow-app). */
 function resolveChain(contract, detected) {
     if (detected < contract.minVersion) {
-        return { reachable: false, chain: [], error: `${contract.contract} schemaVersion ${detected} is below the minimum supported ${contract.minVersion}` };
+        return {
+            reachable: false,
+            chain: [],
+            error: `${contract.contract} schemaVersion ${detected} is below the minimum supported ${contract.minVersion}`,
+        };
     }
     if (detected > contract.currentVersion) {
-        return { reachable: false, chain: [], error: `${contract.contract} schemaVersion ${detected} is newer than this runtime (${contract.currentVersion})` };
+        return {
+            reachable: false,
+            chain: [],
+            error: `${contract.contract} schemaVersion ${detected} is newer than this runtime (${contract.currentVersion})`,
+        };
     }
-    // Use the run-state migration DAG path resolver when applicable
     if (contract.contract === "run-state") {
-        const resolved = (0, state_migrations_1.findMigrationPath)(state_migrations_1.RUN_STATE_MIGRATIONS, detected, contract.currentVersion);
+        const resolved = (0, migrations_1.findMigrationPath)(migrations_1.RUN_STATE_MIGRATIONS, detected, contract.currentVersion);
         if (!resolved.reachable)
             return { reachable: false, chain: [], error: resolved.error };
-        // Derive the version chain from the path
         const chain = [detected];
         let v = detected;
         for (const step of resolved.path) {
@@ -117,13 +93,15 @@ function resolveChain(contract, detected) {
         }
         return { reachable: true, chain };
     }
-    // workflow-app: no edges yet, simple check
     if (contract.edges.length === 0) {
         if (detected === contract.currentVersion)
             return { reachable: true, chain: [detected] };
-        return { reachable: false, chain: [], error: `${contract.contract} schemaVersion ${detected} is not current (${contract.currentVersion}) and no migration edges exist` };
+        return {
+            reachable: false,
+            chain: [],
+            error: `${contract.contract} schemaVersion ${detected} is not current (${contract.currentVersion}) and no migration edges exist`,
+        };
     }
-    // Generic edge-based chain resolution
     const chain = [detected];
     let version = detected;
     while (version < contract.currentVersion) {
@@ -136,7 +114,8 @@ function resolveChain(contract, detected) {
     }
     return { reachable: true, chain };
 }
-/** Dry-run verdict: detect, resolve, and (run-state) run the migration to report. */
+/** Dry-run verdict: detect, resolve, and (run-state) run the migration to
+ *  report. */
 function checkMigration(contractId, snapshot) {
     const contract = getContract(contractId);
     const detectedVersion = detectVersion(contractId, snapshot);
@@ -147,23 +126,37 @@ function checkMigration(contractId, snapshot) {
         detectedVersion,
         currentVersion: contract.currentVersion,
         reachable: resolved.reachable,
-        chain: resolved.chain
+        chain: resolved.chain,
     };
     if (!resolved.reachable) {
         return { ...base, status: "unsupported", changes: 0, errors: [resolved.error || "unreachable"] };
     }
     if (contractId === "run-state") {
-        const { report } = (0, state_migrations_1.migrateRunState)(snapshot, { dryRun: true });
+        const { report } = (0, migrations_1.migrateRunState)(snapshot, { dryRun: true });
         return { ...base, status: report.status, changes: report.changes.length, errors: report.errors };
     }
-    // workflow-app: reachable + no edges => detected === current.
     return { ...base, status: "current", changes: 0, errors: [] };
 }
-/** Round-trip / non-destruction prover. Fail-closed: an unsupported verdict never
- *  transforms and never claims a positive proof. */
+/** Append-only proof: every key in the source survives into the output
+ *  (recursive). */
+function keysSurvive(source, output) {
+    if (!isRecord(source))
+        return true;
+    if (!isRecord(output))
+        return false;
+    for (const key of Object.keys(source)) {
+        if (!(key in output))
+            return false;
+        if (!keysSurvive(source[key], output[key]))
+            return false;
+    }
+    return true;
+}
+/** Round-trip / non-destruction prover. Fail-closed: an unsupported
+ *  verdict never transforms and never claims a positive proof. */
 function proveMigration(contractId, snapshot) {
     const verdict = checkMigration(contractId, snapshot);
-    const sourceHash = stableHash(snapshot);
+    const sourceHash = (0, hash_1.stableHash)(snapshot);
     const errors = [...verdict.errors];
     let validatesAtCurrent = false;
     let appendOnly = false;
@@ -171,27 +164,24 @@ function proveMigration(contractId, snapshot) {
     let result = snapshot;
     if (verdict.status !== "unsupported") {
         if (contractId === "run-state") {
-            const migrated = (0, state_migrations_1.migrateRunState)(snapshot);
+            const migrated = (0, migrations_1.migrateRunState)(snapshot);
             result = migrated.run;
             validatesAtCurrent =
-                migrated.report.status !== "unsupported" &&
-                    isRecord(result) &&
-                    result.schemaVersion === version_1.CURRENT_RUN_STATE_SCHEMA_VERSION;
+                migrated.report.status !== "unsupported" && isRecord(result) && result.schemaVersion === version_1.CURRENT_RUN_STATE_SCHEMA_VERSION;
             appendOnly = keysSurvive(snapshot, result);
-            const reRun = (0, state_migrations_1.migrateRunState)(result, { dryRun: true });
+            const reRun = (0, migrations_1.migrateRunState)(result, { dryRun: true });
             idempotent = reRun.report.changes.length === 0 && reRun.report.status === "current";
         }
         else {
-            // workflow-app at current: pass-through, nothing to transform.
             validatesAtCurrent = verdict.status === "current";
             appendOnly = true;
             idempotent = true;
         }
     }
-    const sourceImmutable = stableHash(snapshot) === sourceHash;
-    const resultHash = stableHash(result);
+    const sourceImmutable = (0, hash_1.stableHash)(snapshot) === sourceHash;
+    const resultHash = (0, hash_1.stableHash)(result);
     const pass = validatesAtCurrent && appendOnly && idempotent && sourceImmutable && errors.length === 0;
-    const fingerprint = stableHash({
+    const fingerprint = (0, hash_1.stableHash)({
         contract: contractId,
         detectedVersion: verdict.detectedVersion,
         chain: verdict.chain,
@@ -201,7 +191,7 @@ function proveMigration(contractId, snapshot) {
         idempotent,
         sourceImmutable,
         sourceHash,
-        resultHash
+        resultHash,
     });
     return {
         schemaVersion: 1,
@@ -215,20 +205,6 @@ function proveMigration(contractId, snapshot) {
         sourceHash,
         resultHash,
         fingerprint,
-        errors
+        errors,
     };
 }
-/** Append-only proof: every key in the source survives into the output (recursive). */
-function keysSurvive(source, output) {
-    if (!isRecord(source))
-        return true;
-    if (!isRecord(output))
-        return false;
-    for (const key of Object.keys(source)) {
-        if (!(key in output))
-            return false;
-        if (!keysSurvive(source[key], output[key]))
-            return false;
-    }
-    return true;
-}