cool-workflow 0.1.97 → 0.2.0

package/dist/core/state/node-snapshot.js

@@ -0,0 +1,230 @@
+"use strict";
+// core/state/node-snapshot.ts — snapshotNode / diffNodeSnapshots /
+// replayNodeSnapshot / verifyNodeReplay.
+//
+// MILESTONE 3. Byte-exact port of the old build's src/node-snapshot.ts,
+// split into a PURE half (this file) and a shell half (shell/node-
+// store.ts, which supplies the actual `writeJson` persistence and file
+// scans for readNodeSnapshot/readNodeReplay). Every function here is pure
+// given `(run, clock)` — no direct fs/Date calls; `now` is always an
+// explicit parameter, `persist` is always a caller-supplied callback.
+//
+// RAW vs NORMALIZED fingerprints [v2/PLAN.md byte-compat item 8 — do not
+// merge these two code paths]:
+//   - `sourceFingerprint` is RAW: built from the node's raw id/status/
+//     updatedAt plus raw artifact/evidence id+path strings. ANY transition
+//     (even just `updatedAt` ticking) flips it — this is what freshness
+//     detection needs.
+//   - `body`/`outputFingerprint` are NORMALIZED via `projectNodeBody`/
+//     `replayStableStringify` (node-projection.ts): no timestamps, scrubbed
+//     paths, so replay output is byte-stable across recaptures of the same
+//     logical state.
+// These stay two separate functions (`sourceFingerprint` vs
+// `snapshotBody`/`outputFingerprint`'s computation) — never one call.
+//
+// Evidence: SPEC/state-core.md "src/node-snapshot.ts — snapshot / diff /
+// replay", "Raw vs. normalized fingerprints", "Snapshot freshness
+// fail-closed".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeSnapshotError = exports.NODE_SNAPSHOT_SCHEMA_VERSION = void 0;
+exports.findRunNode = findRunNode;
+exports.sourceFingerprint = sourceFingerprint;
+exports.snapshotNode = snapshotNode;
+exports.loadNodeSnapshot = loadNodeSnapshot;
+exports.diffNodeSnapshots = diffNodeSnapshots;
+exports.replayNodeSnapshot = replayNodeSnapshot;
+exports.verifyNodeReplay = verifyNodeReplay;
+const hash_1 = require("../hash");
+const node_projection_1 = require("./node-projection");
+exports.NODE_SNAPSHOT_SCHEMA_VERSION = 1;
+/** Structured fail-closed error (mirrors PipelineContractError's shape). */
+class NodeSnapshotError extends Error {
+    code;
+    freshness;
+    details;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "NodeSnapshotError";
+        this.code = code;
+        this.freshness = options.freshness;
+        this.details = options.details;
+    }
+}
+exports.NodeSnapshotError = NodeSnapshotError;
+const SNAPSHOT_SECTIONS = [
+    "status",
+    "inputs",
+    "outputs",
+    "artifacts",
+    "evidence",
+    "errors",
+    "links",
+    "metadata",
+];
+/** Look up a StateNode by id in `run.nodes`, or `undefined` if absent. Pure
+ *  data lookup — no fs. */
+function findRunNode(run, nodeId) {
+    return (run.nodes || []).find((candidate) => candidate.id === nodeId);
+}
+/** NORMALIZED projection of a node — timestamps/paths stripped, so it is
+ *  byte-stable across captures of the same logical state. */
+function snapshotBody(node) {
+    return (0, node_projection_1.projectNodeBody)(node);
+}
+/** RAW fingerprint (NOT normalized): any transition (updatedAt/status) or
+ *  artifact/evidence change flips it — this is how drift is detected. */
+function sourceFingerprint(node) {
+    return (0, hash_1.fingerprintStrings)([
+        `node:${node.id}:${node.status}:${node.updatedAt}`,
+        ...node.artifacts.map((artifact) => `artifact:${artifact.id}:${artifact.path}`),
+        ...node.evidence.map((evidence) => `evidence:${evidence.id}:${evidence.path || ""}`),
+    ]);
+}
+/** Snapshot one StateNode by id. Throws (fail closed) if the node is
+ *  absent. */
+function snapshotNode(run, nodeId, options = {}) {
+    const node = findRunNode(run, nodeId);
+    if (!node) {
+        throw new NodeSnapshotError("node-absent", `Cannot snapshot: node ${nodeId} not found in run ${run.id}`, {
+            freshness: "absent",
+        });
+    }
+    const fingerprint = sourceFingerprint(node);
+    const snapshot = {
+        schemaVersion: 1,
+        snapshotId: `snap-${safeFileNamePure(nodeId)}-${fingerprint.replace("sha256:", "").slice(0, 12)}`,
+        runId: run.id,
+        nodeId,
+        capturedAt: options.now || new Date(0).toISOString(),
+        sourceFingerprint: fingerprint,
+        body: snapshotBody(node),
+    };
+    if (options.persist !== false && typeof options.persist === "function")
+        options.persist(snapshot);
+    return snapshot;
+}
+/** Recompute freshness from the CURRENT source. `valid | stale | absent`. */
+function loadNodeSnapshot(run, snapshot, pathExists = () => true) {
+    const node = findRunNode(run, snapshot.nodeId);
+    if (!node) {
+        return { snapshot, freshness: "absent", reason: `source node ${snapshot.nodeId} is gone from run ${run.id}` };
+    }
+    const missingArtifact = node.artifacts.find((artifact) => artifact.path && !pathExists(artifact.path));
+    if (missingArtifact) {
+        return { snapshot, freshness: "absent", reason: `referenced artifact path is unreadable: ${missingArtifact.id}` };
+    }
+    if (sourceFingerprint(node) !== snapshot.sourceFingerprint) {
+        return { snapshot, freshness: "stale", reason: `source node ${snapshot.nodeId} changed since capture` };
+    }
+    return { snapshot, freshness: "valid" };
+}
+function sectionValue(body, section) {
+    if (section === "links")
+        return { parents: body.parents, children: body.children };
+    return body[section];
+}
+/** Stable, structural diff of two snapshots: 8 sections, in fixed order. */
+function diffNodeSnapshots(baseline, candidate) {
+    const sections = SNAPSHOT_SECTIONS.map((section) => {
+        const baselineValue = sectionValue(baseline.body, section);
+        const candidateValue = sectionValue(candidate.body, section);
+        const sameBytes = (0, node_projection_1.replayStableStringify)(baselineValue) === (0, node_projection_1.replayStableStringify)(candidateValue);
+        let change;
+        if (sameBytes)
+            change = "same";
+        else if (baselineValue === undefined)
+            change = "added";
+        else if (candidateValue === undefined)
+            change = "removed";
+        else
+            change = "changed";
+        const entry = { section, change };
+        if (change !== "same") {
+            entry.baseline = baselineValue;
+            entry.candidate = candidateValue;
+        }
+        return entry;
+    });
+    return {
+        schemaVersion: 1,
+        runId: baseline.runId,
+        baselineSnapshotId: baseline.snapshotId,
+        candidateSnapshotId: candidate.snapshotId,
+        baselineNodeId: baseline.nodeId,
+        candidateNodeId: candidate.nodeId,
+        changed: sections.some((entry) => entry.change !== "same"),
+        sections,
+    };
+}
+/** Deterministically replay one node from its snapshot, fail-closed on
+ *  drift: freshness not `valid` throws `snapshot-stale`/`snapshot-absent`
+ *  BEFORE any replay bytes are built. */
+function replayNodeSnapshot(run, snapshot, options = {}) {
+    const { freshness, reason } = loadNodeSnapshot(run, snapshot, options.pathExists);
+    if (freshness !== "valid") {
+        throw new NodeSnapshotError(freshness === "stale" ? "snapshot-stale" : "snapshot-absent", reason || `cannot replay a ${freshness} snapshot of node ${snapshot.nodeId}`, { freshness, details: { runId: run.id, nodeId: snapshot.nodeId } });
+    }
+    const body = (0, node_projection_1.normalizeValue)(snapshot.body);
+    const outputFingerprint = (0, hash_1.fingerprintStrings)([(0, node_projection_1.replayStableStringify)(body)]);
+    const replay = {
+        schemaVersion: 1,
+        replayId: `replay-${snapshot.snapshotId}-${outputFingerprint.replace("sha256:", "").slice(0, 8)}`,
+        runId: run.id,
+        nodeId: snapshot.nodeId,
+        snapshotId: snapshot.snapshotId,
+        replayedAt: options.now || new Date(0).toISOString(),
+        freshness: "valid",
+        contractValidated: Boolean(snapshot.body.contractId),
+        outputFingerprint,
+        body,
+    };
+    if (options.persist !== false && typeof options.persist === "function")
+        options.persist(replay);
+    return replay;
+}
+/** Compare a replay to a FRESH (non-persisted) snapshot of the source node;
+ *  pass = byte-identical normalized body. Never throws — a drifted source
+ *  is a `pass:false` finding, not an exception. */
+function verifyNodeReplay(run, replay, options = {}) {
+    const fresh = findRunNode(run, replay.nodeId);
+    if (!fresh) {
+        return {
+            schemaVersion: 1,
+            runId: run.id,
+            nodeId: replay.nodeId,
+            replayId: replay.replayId,
+            pass: false,
+            freshness: "absent",
+            findings: [{ id: "source-absent", severity: "error", category: "source", reason: `source node ${replay.nodeId} is gone` }],
+        };
+    }
+    const freshSnapshot = snapshotNode(run, replay.nodeId, { now: options.now, persist: false });
+    const diff = diffNodeSnapshots(freshSnapshot, { ...freshSnapshot, body: replay.body, snapshotId: replay.snapshotId });
+    const findings = diff.sections
+        .filter((section) => section.change !== "same")
+        .map((section) => ({
+        id: `drift:${section.section}`,
+        severity: "error",
+        category: section.section,
+        reason: `replay diverged from source in ${section.section}`,
+        baselineRef: replay.snapshotId,
+        replayRef: replay.replayId,
+    }));
+    return {
+        schemaVersion: 1,
+        runId: run.id,
+        nodeId: replay.nodeId,
+        replayId: replay.replayId,
+        pass: findings.length === 0,
+        freshness: "valid",
+        findings,
+    };
+}
+/** Pure re-implementation of shell/fs-atomic.ts's naming rule (replaces
+ *  every run of chars outside `[a-zA-Z0-9_.:-]` with a single `_`), needed
+ *  here purely as a STRING transform for id formatting — no fs. Kept in
+ *  sync with `safeFileName` by the same regex; both are pinned by the same
+ *  SPEC line (state-core.md's `safeFileName(value)`). */
+function safeFileNamePure(value) {
+    return value.replace(/[^a-zA-Z0-9_.:-]+/g, "_");
+}

package/dist/core/state/run-paths.js

@@ -0,0 +1,93 @@
+"use strict";
+// core/state/run-paths.ts — createRunPaths, ensureRunDirs.
+//
+// MILESTONE 3. Byte-exact port of the old build's src/state.ts:10-50.
+// `createRunPaths` is pure path math (core/); `ensureRunDirs` touches disk
+// (mkdirSync) so it lives here but is called from shell/run-store.ts, the
+// only place that actually creates a run directory tree.
+//
+// Evidence: SPEC/state-core.md "src/state.ts — persistence kernel" and "The
+// full .cw/runs/<run-id>/ layout".
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRunPaths = createRunPaths;
+exports.ensureRunDirs = ensureRunDirs;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** The 16-key RunPaths object, all joined under `runDir`. */
+function createRunPaths(runDir) {
+    return {
+        runDir,
+        state: path.join(runDir, "state.json"),
+        report: path.join(runDir, "report.md"),
+        tasksDir: path.join(runDir, "tasks"),
+        resultsDir: path.join(runDir, "results"),
+        dispatchesDir: path.join(runDir, "dispatches"),
+        artifactsDir: path.join(runDir, "artifacts"),
+        commitsDir: path.join(runDir, "commits"),
+        stateNodesDir: path.join(runDir, "nodes"),
+        feedbackDir: path.join(runDir, "feedback"),
+        auditDir: path.join(runDir, "audit"),
+        workersDir: path.join(runDir, "workers"),
+        candidatesDir: path.join(runDir, "candidates"),
+        multiAgentDir: path.join(runDir, "multi-agent"),
+        blackboardDir: path.join(runDir, "blackboard"),
+        topologiesDir: path.join(runDir, "topologies"),
+    };
+}
+/** `mkdirSync` (recursive) every dir this run needs. Missing optional dir
+ *  fields fall back to `path.join(runDir, "<name>")`, matching the old
+ *  build's defensive default (a RunPaths loaded from an old/partial
+ *  state.json may be missing an optional key). */
+function ensureRunDirs(paths) {
+    const dirs = [
+        paths.runDir,
+        paths.tasksDir,
+        paths.resultsDir,
+        paths.dispatchesDir,
+        paths.artifactsDir,
+        paths.commitsDir,
+        paths.stateNodesDir,
+        paths.feedbackDir,
+        paths.auditDir || path.join(paths.runDir, "audit"),
+        paths.workersDir || path.join(paths.runDir, "workers"),
+        paths.candidatesDir || path.join(paths.runDir, "candidates"),
+        paths.multiAgentDir || path.join(paths.runDir, "multi-agent"),
+        paths.blackboardDir || path.join(paths.runDir, "blackboard"),
+        paths.topologiesDir || path.join(paths.runDir, "topologies"),
+    ];
+    for (const dir of dirs)
+        fs.mkdirSync(dir, { recursive: true });
+}

package/dist/{schema-validate.js → core/state/schema-validate.js}

@@ -1,21 +1,14 @@
 "use strict";
-// Minimal, dependency-free structural schema validation (Track 3).
+// core/state/schema-validate.ts — dependency-free JSON-schema subset.
 //
-// CW declares an optional output `schema` per task (WorkflowTaskDefinition.schema);
-// this enforces it at result-acceptance time so CW only records structured output
-// it has actually validated — the other half of "auditable" (Track 1 proves the
-// telemetry is real; this proves the result SHAPE is what was declared).
+// MILESTONE 3. Byte-exact port of the old build's src/schema-validate.ts.
+// Deliberately a SUBSET of JSON Schema (type, const, enum, required,
+// properties, additionalProperties:false, items) — adds no runtime
+// dependency. Unsupported keywords are surfaced as a stderr diagnostic
+// (TTY only), never enforced.
 //
-// DELIBERATELY a subset of JSON Schema, NOT a full implementation: it adds NO
-// runtime dependency (the portability red line — CI runs on node/npm/git only).
-// Supported keywords cover structured-agent-output contracts:
-//   type (object|array|string|number|integer|boolean|null, or an array of them),
-//   enum, const, required, properties, additionalProperties (false), items.
-// Unsupported keywords ($ref, allOf/anyOf/oneOf, pattern, formats, numeric
-// bounds) are surfaced as WARNINGS (a constraint that wasn't checked), so the
-// operator can see their schema reliance is incomplete.
-// (If full JSON Schema is needed later, swap this module's impl for ajv behind
-// the same signature.)
+// Evidence: SPEC/state-core.md "src/schema-validate.ts — dependency-free
+// JSON-schema subset", "Schema-validator error strings".
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateAgainstSchema = validateAgainstSchema;
 function typeOf(value) {
@@ -23,7 +16,7 @@ function typeOf(value) {
         return "null";
     if (Array.isArray(value))
         return "array";
-    return typeof value; // object | string | number | boolean | undefined | function
+    return typeof value;
 }
 function matchesType(value, type) {
     switch (type) {
@@ -42,38 +35,53 @@ function matchesType(value, type) {
         case "null":
             return value === null;
         default:
-            return true; // unknown declared type ⇒ not enforced (never a false fail)
+            return true; // unknown declared type => not enforced (never a false fail)
     }
 }
-/** Validate `value` against `schema`. Returns a list of human-readable errors;
- *  empty ⇒ valid. Pure + deterministic; never throws on a malformed schema (an
- *  unparseable schema constraint is skipped, not treated as a failure). */
+const UNSUPPORTED_KEYWORDS = new Set([
+    "$ref",
+    "allOf",
+    "anyOf",
+    "oneOf",
+    "not",
+    "pattern",
+    "format",
+    "minimum",
+    "maximum",
+    "minLength",
+    "maxLength",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "contains",
+    "if",
+    "then",
+    "else",
+]);
+/** Validate `value` against `schema`. Returns a list of human-readable
+ *  errors; empty means valid. Pure + deterministic; never throws on a
+ *  malformed schema. */
 function validateAgainstSchema(value, schema, path = "$") {
     const errors = [];
     if (!schema || typeof schema !== "object")
         return errors;
-    // Unsupported keywords — surface as diagnostics (Rule of Silence: stderr)
-    const UNSUPPORTED = new Set(["$ref", "allOf", "anyOf", "oneOf", "not", "pattern", "format", "minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems", "uniqueItems", "contains", "if", "then", "else"]);
-    const unsupported = Object.keys(schema).filter((k) => UNSUPPORTED.has(k));
+    const unsupported = Object.keys(schema).filter((k) => UNSUPPORTED_KEYWORDS.has(k));
     if (unsupported.length && process.stderr.isTTY) {
         process.stderr.write(`[cw] schema at ${path}: unsupported keywords ignored: ${unsupported.join(", ")}\n`);
     }
-    // type
     if (schema.type !== undefined) {
         const types = Array.isArray(schema.type) ? schema.type.map(String) : [String(schema.type)];
         if (!types.some((t) => matchesType(value, t))) {
             errors.push(`${path}: expected type ${types.join("|")}, got ${typeOf(value)}`);
-            return errors; // type mismatch ⇒ downstream keyword checks would be noise
+            return errors; // type mismatch => downstream keyword checks would be noise
         }
     }
-    // const / enum
     if ("const" in schema && JSON.stringify(value) !== JSON.stringify(schema.const)) {
         errors.push(`${path}: expected const ${JSON.stringify(schema.const)}`);
     }
     if (Array.isArray(schema.enum) && !schema.enum.some((option) => JSON.stringify(option) === JSON.stringify(value))) {
         errors.push(`${path}: ${JSON.stringify(value)} is not one of ${JSON.stringify(schema.enum)}`);
     }
-    // object: required, properties, additionalProperties:false
     if (value !== null && typeof value === "object" && !Array.isArray(value)) {
         const obj = value;
         if (Array.isArray(schema.required)) {
@@ -94,7 +102,6 @@ function validateAgainstSchema(value, schema, path = "$") {
             }
         }
     }
-    // array: items (single schema applied to every element)
     if (Array.isArray(value) && schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
         value.forEach((element, index) => {
             errors.push(...validateAgainstSchema(element, schema.items, `${path}[${index}]`));

package/dist/core/state/schema.js

@@ -0,0 +1,50 @@
+"use strict";
+// core/state/schema.ts — the single field-list source for WorkflowRun.
+//
+// MILESTONE 3. Byte-exact port of the old build's src/run-state-schema.ts.
+// Both migrations.ts's validation AND (eventually) a build gate derive
+// their field knowledge from this module — a field added to WorkflowRun
+// must be added here too.
+//
+// Evidence: SPEC/state-core.md "src/run-state-schema.ts — the single
+// field-list source".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPTIONAL_TOP_LEVEL_KEYS = exports.REQUIRED_RECORD_KEYS = exports.REQUIRED_ARRAY_KEYS = exports.REQUIRED_TOP_LEVEL_KEYS = void 0;
+/** Top-level required keys of WorkflowRun — every key that must exist
+ *  after migration. */
+exports.REQUIRED_TOP_LEVEL_KEYS = [
+    "schemaVersion",
+    "id",
+    "createdAt",
+    "updatedAt",
+    "cwd",
+    "workflow",
+    "inputs",
+    "loopStage",
+    "phases",
+    "tasks",
+    "dispatches",
+    "commits",
+    "paths",
+];
+/** Top-level keys that must be arrays after migration. */
+exports.REQUIRED_ARRAY_KEYS = ["phases", "tasks", "dispatches", "commits"];
+/** Top-level keys that must be objects (Record) after migration. */
+exports.REQUIRED_RECORD_KEYS = ["workflow", "paths", "multiAgent", "blackboard", "topologies"];
+/** Keys from the WorkflowRun type that are OPTIONAL (exist at type level
+ *  but are not required by validateMigratedRunState). */
+exports.OPTIONAL_TOP_LEVEL_KEYS = [
+    "nodes",
+    "contracts",
+    "feedback",
+    "audit",
+    "workers",
+    "sandboxProfiles",
+    "customSandboxProfiles",
+    "candidates",
+    "candidateSelections",
+    "multiAgent",
+    "blackboard",
+    "topologies",
+    "collaboration",
+];