cool-workflow 0.1.80 → 0.1.82

package/dist/validation.js

@@ -0,0 +1,328 @@
+"use strict";
+// Fail-closed shape guards for persisted per-record types (F5, integrity boundary).
+//
+// `JSON.parse(...) as T` is a LIE: the cast asserts a shape TypeScript never
+// checked at runtime, so a corrupt/forged/old-schema record flows in as if it
+// were a valid T and is used/upserted unvalidated. These guards re-establish the
+// integrity boundary at the read edge: after parse, the raw value is structurally
+// validated against the type def in src/types/* BEFORE it is trusted.
+//
+// Two callers, two error semantics — both fail closed, neither fabricates:
+//   - validate*()      throw a descriptive Error on mismatch (for readers that
+//                      already let parse errors propagate / require the record).
+//   - tryValidate*()   return null on mismatch (for best-effort readers that
+//                      swallow parse errors and SKIP the record — the downstream
+//                      gate then fails closed on the absence). Never throws.
+//
+// Dependency-light by construction: imports ONLY from ./types. No fs, no clock,
+// no randomness — pure structural checks, safe in replay/core paths.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordValidationError = void 0;
+exports.validateWorkerScope = validateWorkerScope;
+exports.tryValidateWorkerScope = tryValidateWorkerScope;
+exports.validateNodeSnapshot = validateNodeSnapshot;
+exports.tryValidateNodeSnapshot = tryValidateNodeSnapshot;
+exports.validateNodeReplayRun = validateNodeReplayRun;
+exports.tryValidateNodeReplayRun = tryValidateNodeReplayRun;
+exports.validateCandidateScore = validateCandidateScore;
+exports.tryValidateCandidateScore = tryValidateCandidateScore;
+exports.validateCandidateRecord = validateCandidateRecord;
+exports.tryValidateCandidateRecord = tryValidateCandidateRecord;
+// ---------------------------------------------------------------------------
+// Primitive predicates — small, total, never throw.
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isObjectArray(value) {
+    return Array.isArray(value) && value.every((entry) => isRecord(entry));
+}
+const WORKER_STATUSES = new Set([
+    "allocated",
+    "running",
+    "completed",
+    "failed",
+    "rejected",
+    "verified",
+    "orphaned"
+]);
+const SCORE_VERDICTS = new Set(["pass", "warn", "fail"]);
+const CANDIDATE_STATUSES = new Set([
+    "registered",
+    "scored",
+    "selected",
+    "rejected",
+    "verified",
+    "failed"
+]);
+const CANDIDATE_KINDS = new Set(["worker-output", "result", "artifact", "manual", "release"]);
+const SNAPSHOT_FRESHNESS = new Set(["valid", "stale", "absent"]);
+/** Descriptive integrity error — the message names the type and the field that
+ *  broke, so a corrupt record is diagnosable from logs alone. */
+class RecordValidationError extends Error {
+    code = "record-shape-invalid";
+    typeName;
+    field;
+    constructor(typeName, reason, field) {
+        super(`Invalid persisted ${typeName}: ${reason}`);
+        this.name = "RecordValidationError";
+        this.typeName = typeName;
+        this.field = field;
+    }
+}
+exports.RecordValidationError = RecordValidationError;
+// ---------------------------------------------------------------------------
+// WorkerScope — worker-isolation.ts:309 / :905
+// Required (per src/types/worker.ts WorkerScope): schemaVersion===1, id, runId,
+// taskId, createdAt, updatedAt, status (enum), workerDir, inputPath, resultPath,
+// artifactsDir, logsDir are strings; allowedPaths string[]; feedbackIds string[];
+// errors object[]. Optional fields are not enforced (additive, may be absent).
+// ---------------------------------------------------------------------------
+function workerScopeReason(value) {
+    if (!isRecord(value))
+        return { reason: "not an object" };
+    if (value.schemaVersion !== 1)
+        return { field: "schemaVersion", reason: "must equal 1" };
+    const requiredStrings = [
+        "id",
+        "runId",
+        "taskId",
+        "createdAt",
+        "updatedAt",
+        "workerDir",
+        "inputPath",
+        "resultPath",
+        "artifactsDir",
+        "logsDir"
+    ];
+    for (const field of requiredStrings) {
+        if (!isString(value[field]))
+            return { field: field, reason: "must be a string" };
+    }
+    if (!isString(value.status) || !WORKER_STATUSES.has(value.status)) {
+        return { field: "status", reason: "must be a valid WorkerIsolationStatus" };
+    }
+    if (!isStringArray(value.allowedPaths))
+        return { field: "allowedPaths", reason: "must be a string[]" };
+    if (!isStringArray(value.feedbackIds))
+        return { field: "feedbackIds", reason: "must be a string[]" };
+    if (!isObjectArray(value.errors))
+        return { field: "errors", reason: "must be a StateNodeError[]" };
+    return undefined;
+}
+/** Throw-on-mismatch guard for WorkerScope (callers that require the record). */
+function validateWorkerScope(value) {
+    const problem = workerScopeReason(value);
+    if (problem)
+        throw new RecordValidationError("WorkerScope", problem.reason, problem.field);
+    return value;
+}
+/** Best-effort variant: returns null on mismatch (caller skips the record). */
+function tryValidateWorkerScope(value) {
+    return workerScopeReason(value) ? null : value;
+}
+// ---------------------------------------------------------------------------
+// NodeSnapshotBody — shared by NodeSnapshot.body and NodeReplayRun.body.
+// Required (per src/types/state-node.ts): id, kind, status, loopStage strings;
+// inputs/outputs records; artifacts/evidence/errors object arrays;
+// parents/children string arrays.
+// ---------------------------------------------------------------------------
+function nodeSnapshotBodyReason(value, prefix) {
+    if (!isRecord(value))
+        return { field: prefix, reason: "must be a NodeSnapshotBody object" };
+    const requiredStrings = ["id", "kind", "status", "loopStage"];
+    for (const field of requiredStrings) {
+        if (!isString(value[field]))
+            return { field: `${prefix}.${String(field)}`, reason: "must be a string" };
+    }
+    if (!isRecord(value.inputs))
+        return { field: `${prefix}.inputs`, reason: "must be an object" };
+    if (!isRecord(value.outputs))
+        return { field: `${prefix}.outputs`, reason: "must be an object" };
+    if (!isObjectArray(value.artifacts))
+        return { field: `${prefix}.artifacts`, reason: "must be a StateArtifact[]" };
+    if (!isObjectArray(value.evidence))
+        return { field: `${prefix}.evidence`, reason: "must be a StateEvidence[]" };
+    if (!isObjectArray(value.errors))
+        return { field: `${prefix}.errors`, reason: "must be a StateNodeError[]" };
+    if (!isStringArray(value.parents))
+        return { field: `${prefix}.parents`, reason: "must be a string[]" };
+    if (!isStringArray(value.children))
+        return { field: `${prefix}.children`, reason: "must be a string[]" };
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// NodeSnapshot — node-snapshot.ts:121
+// Required: schemaVersion===1, snapshotId, runId, nodeId, capturedAt,
+// sourceFingerprint strings; body a valid NodeSnapshotBody.
+// ---------------------------------------------------------------------------
+function nodeSnapshotReason(value) {
+    if (!isRecord(value))
+        return { reason: "not an object" };
+    if (value.schemaVersion !== 1)
+        return { field: "schemaVersion", reason: "must equal 1" };
+    const requiredStrings = ["snapshotId", "runId", "nodeId", "capturedAt", "sourceFingerprint"];
+    for (const field of requiredStrings) {
+        if (!isString(value[field]))
+            return { field: field, reason: "must be a string" };
+    }
+    return nodeSnapshotBodyReason(value.body, "body");
+}
+/** Throw-on-mismatch guard for NodeSnapshot (read edge requires the record). */
+function validateNodeSnapshot(value) {
+    const problem = nodeSnapshotReason(value);
+    if (problem)
+        throw new RecordValidationError("NodeSnapshot", problem.reason, problem.field);
+    return value;
+}
+/** Best-effort variant: returns null on mismatch. */
+function tryValidateNodeSnapshot(value) {
+    return nodeSnapshotReason(value) ? null : value;
+}
+// ---------------------------------------------------------------------------
+// NodeReplayRun — node-snapshot.ts:133
+// Required: schemaVersion===1, replayId, runId, nodeId, snapshotId, replayedAt,
+// outputFingerprint strings; freshness enum; contractValidated boolean; body a
+// valid NodeSnapshotBody.
+// ---------------------------------------------------------------------------
+function nodeReplayRunReason(value) {
+    if (!isRecord(value))
+        return { reason: "not an object" };
+    if (value.schemaVersion !== 1)
+        return { field: "schemaVersion", reason: "must equal 1" };
+    const requiredStrings = [
+        "replayId",
+        "runId",
+        "nodeId",
+        "snapshotId",
+        "replayedAt",
+        "outputFingerprint"
+    ];
+    for (const field of requiredStrings) {
+        if (!isString(value[field]))
+            return { field: field, reason: "must be a string" };
+    }
+    if (!isString(value.freshness) || !SNAPSHOT_FRESHNESS.has(value.freshness)) {
+        return { field: "freshness", reason: "must be a valid NodeSnapshotFreshness" };
+    }
+    if (typeof value.contractValidated !== "boolean") {
+        return { field: "contractValidated", reason: "must be a boolean" };
+    }
+    return nodeSnapshotBodyReason(value.body, "body");
+}
+/** Throw-on-mismatch guard for NodeReplayRun (read edge requires the record). */
+function validateNodeReplayRun(value) {
+    const problem = nodeReplayRunReason(value);
+    if (problem)
+        throw new RecordValidationError("NodeReplayRun", problem.reason, problem.field);
+    return value;
+}
+/** Best-effort variant: returns null on mismatch. */
+function tryValidateNodeReplayRun(value) {
+    return nodeReplayRunReason(value) ? null : value;
+}
+// ---------------------------------------------------------------------------
+// CandidateScore — multi-agent-operator-ux.ts:502 / evidence-reasoning.ts:750
+// Required (per src/types/candidate.ts): schemaVersion===1, id, candidateId,
+// runId, createdAt, scorer strings; criteria record of numbers; total/maxTotal/
+// normalized finite numbers; verdict enum; evidence/artifacts object arrays.
+// ---------------------------------------------------------------------------
+function isNumberRecord(value) {
+    return isRecord(value) && Object.values(value).every((entry) => isFiniteNumber(entry));
+}
+function candidateScoreReason(value) {
+    if (!isRecord(value))
+        return { reason: "not an object" };
+    if (value.schemaVersion !== 1)
+        return { field: "schemaVersion", reason: "must equal 1" };
+    const requiredStrings = ["id", "candidateId", "runId", "createdAt", "scorer"];
+    for (const field of requiredStrings) {
+        if (!isString(value[field]))
+            return { field: field, reason: "must be a string" };
+    }
+    if (!isNumberRecord(value.criteria))
+        return { field: "criteria", reason: "must be a Record<string, number>" };
+    if (!isFiniteNumber(value.total))
+        return { field: "total", reason: "must be a finite number" };
+    if (!isFiniteNumber(value.maxTotal))
+        return { field: "maxTotal", reason: "must be a finite number" };
+    if (!isFiniteNumber(value.normalized))
+        return { field: "normalized", reason: "must be a finite number" };
+    if (!isString(value.verdict) || !SCORE_VERDICTS.has(value.verdict)) {
+        return { field: "verdict", reason: "must be a valid CandidateScoreVerdict" };
+    }
+    if (!isObjectArray(value.evidence))
+        return { field: "evidence", reason: "must be a StateEvidence[]" };
+    if (!isObjectArray(value.artifacts))
+        return { field: "artifacts", reason: "must be a StateArtifact[]" };
+    return undefined;
+}
+/** Throw-on-mismatch guard for CandidateScore (callers that require the record). */
+function validateCandidateScore(value) {
+    const problem = candidateScoreReason(value);
+    if (problem)
+        throw new RecordValidationError("CandidateScore", problem.reason, problem.field);
+    return value;
+}
+/** Best-effort variant: returns null on mismatch (caller skips the record so the
+ *  downstream score gate fails closed on its absence). */
+function tryValidateCandidateScore(value) {
+    return candidateScoreReason(value) ? null : value;
+}
+// ---------------------------------------------------------------------------
+// CandidateRecord — candidate-scoring.ts getCandidate / loadCandidatesFromDisk.
+// Required (per src/types/candidate.ts): schemaVersion===1, id, runId, createdAt,
+// updatedAt strings; kind/status enums; artifacts/evidence object arrays;
+// scores/feedbackIds string arrays. Optional ids (workerId/taskId/…) not enforced.
+// A corrupt/forged candidate record must NOT flow into the run as a trusted T —
+// the gate that backs commit selection reads these fields, so we fail closed at
+// the read edge instead of upserting an unvalidated cast.
+// ---------------------------------------------------------------------------
+function candidateRecordReason(value) {
+    if (!isRecord(value))
+        return { reason: "not an object" };
+    if (value.schemaVersion !== 1)
+        return { field: "schemaVersion", reason: "must equal 1" };
+    const requiredStrings = ["id", "runId", "createdAt", "updatedAt"];
+    for (const field of requiredStrings) {
+        if (!isString(value[field]))
+            return { field: field, reason: "must be a string" };
+    }
+    if (!isString(value.kind) || !CANDIDATE_KINDS.has(value.kind)) {
+        return { field: "kind", reason: "must be a valid CandidateKind" };
+    }
+    if (!isString(value.status) || !CANDIDATE_STATUSES.has(value.status)) {
+        return { field: "status", reason: "must be a valid CandidateStatus" };
+    }
+    if (!isObjectArray(value.artifacts))
+        return { field: "artifacts", reason: "must be a StateArtifact[]" };
+    if (!isObjectArray(value.evidence))
+        return { field: "evidence", reason: "must be a StateEvidence[]" };
+    if (!isStringArray(value.scores))
+        return { field: "scores", reason: "must be a string[]" };
+    if (!isStringArray(value.feedbackIds))
+        return { field: "feedbackIds", reason: "must be a string[]" };
+    return undefined;
+}
+/** Throw-on-mismatch guard for CandidateRecord (callers that require the record
+ *  at the disk read edge — getCandidate / loadCandidatesFromDisk). */
+function validateCandidateRecord(value) {
+    const problem = candidateRecordReason(value);
+    if (problem)
+        throw new RecordValidationError("CandidateRecord", problem.reason, problem.field);
+    return value;
+}
+/** Best-effort variant: returns null on mismatch (caller skips the record so the
+ *  downstream selection gate fails closed on its absence). */
+function tryValidateCandidateRecord(value) {
+    return candidateRecordReason(value) ? null : value;
+}

package/dist/version.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA_VERSION = exports.CURRENT_RUN_STATE_SCHEMA_VERSION = exports.WORKFLOW_APP_SCHEMA_VERSION = exports.CURRENT_COOL_WORKFLOW_VERSION = void 0;
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.80";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.82";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

package/dist/worker-isolation/helpers.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.structuredError = structuredError;
+exports.isBoundaryViolation = isBoundaryViolation;
+exports.isStateNodeError = isStateNodeError;
+exports.mergeScopes = mergeScopes;
+exports.unique = unique;
+exports.compactMetadata = compactMetadata;
+exports.countBy = countBy;
+function structuredError(code, message, options = {}) {
+    return {
+        code,
+        message,
+        at: new Date().toISOString(),
+        path: options.path,
+        retryable: options.retryable,
+        details: options.details
+    };
+}
+function isBoundaryViolation(value) {
+    return Boolean(value && typeof value === "object" && "allowedPaths" in value && "message" in value);
+}
+function isStateNodeError(value) {
+    return Boolean(value && typeof value === "object" && "code" in value && "message" in value);
+}
+function mergeScopes(left, right) {
+    const merged = [...left];
+    for (const scope of right) {
+        const index = merged.findIndex((candidate) => candidate.id === scope.id);
+        if (index >= 0)
+            merged[index] = scope;
+        else
+            merged.push(scope);
+    }
+    return merged;
+}
+function unique(values) {
+    return Array.from(new Set(values.filter(Boolean)));
+}
+function compactMetadata(value) {
+    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined);
+    return entries.length ? Object.fromEntries(entries) : undefined;
+}
+function countBy(items, key) {
+    const counts = {};
+    for (const item of items) {
+        const value = key(item);
+        counts[value] = (counts[value] || 0) + 1;
+    }
+    return counts;
+}

package/dist/worker-isolation/paths.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKER_MANIFEST_FILE = exports.WORKER_SCOPE_FILE = void 0;
+exports.manifestPath = manifestPath;
+exports.workerScopePath = workerScopePath;
+exports.workerArtifacts = workerArtifacts;
+exports.createWorkerId = createWorkerId;
+// Path, artifact, and id derivation for worker isolation. Pure functions of a
+// WorkerScope (or run + taskId) — no run-state mutation, no disk I/O. Carved out
+// of worker-isolation.ts following the established router pattern
+// (run-registry/{format,policy}.ts, orchestrator/*-operations.ts).
+//
+// BEHAVIOR-PRESERVING — pure code movement, zero logic change. Re-exported from
+// worker-isolation.ts so the public surface is byte-unchanged.
+const node_path_1 = __importDefault(require("node:path"));
+const state_1 = require("../state");
+exports.WORKER_SCOPE_FILE = "worker.json";
+exports.WORKER_MANIFEST_FILE = "manifest.json";
+function manifestPath(scope) {
+    return node_path_1.default.join(scope.workerDir, exports.WORKER_MANIFEST_FILE);
+}
+function workerScopePath(scope) {
+    return node_path_1.default.join(scope.workerDir, exports.WORKER_SCOPE_FILE);
+}
+function workerArtifacts(scope) {
+    return [
+        { id: "worker", kind: "json", path: workerScopePath(scope) },
+        { id: "worker-manifest", kind: "json", path: manifestPath(scope) },
+        { id: "worker-input", kind: "markdown", path: scope.inputPath }
+    ];
+}
+// Deterministic worker id (v0.1.40 self-audit P2): a wall-clock stamp + Math.random()
+// made every dispatch mint a different id, so audit references were not reproducible
+// across re-runs of the same inputs. The id is now derived from the task plus a
+// per-task sequence (count of worker scopes already allocated for that task + 1),
+// so re-running the same workflow yields byte-identical worker ids while retries of
+// the SAME task still get a fresh, unique id. (workerId is excluded from the
+// snapshot source fingerprint, so this does not change replay digests.)
+function createWorkerId(run, taskId) {
+    const prefix = `worker-${(0, state_1.safeFileName)(taskId)}-`;
+    const seq = (run.workers || []).filter((scope) => scope.id.startsWith(prefix)).length + 1;
+    return `${prefix}${String(seq).padStart(4, "0")}`;
+}