cool-workflow 0.1.81 → 0.1.82

package/dist/scheduler.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Scheduler = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const state_1 = require("./state");
@@ -233,19 +234,48 @@ function matchesCron(value, expr, min, max) {
         return Number.isInteger(parsed) && parsed >= min && parsed <= max && parsed === value;
     });
 }
+// Deterministic jitter (replay-determinism self-audit): the jittered Date is NOT a
+// runtime-only sleep — it lands in persisted/replayed state (task.nextRunAt and,
+// transitively, the schedule store), so a Math.random() offset broke replay
+// determinism. The spread (0..jitterSeconds) is now derived from a content hash of
+// the base instant, so the same base time + jitter window always yields the same
+// offset; distinct base times still spread out across the window. The base Date is
+// itself an edge timestamp that is recorded once.
 function addJitter(date, jitterSeconds) {
     if (!jitterSeconds)
         return date;
-    const offset = Math.floor(Math.random() * (jitterSeconds + 1)) * 1000;
-    return new Date(date.getTime() + offset);
+    const digest = node_crypto_1.default.createHash("sha256").update(`${date.getTime()}`).digest();
+    const seconds = digest.readUInt32BE(0) % (jitterSeconds + 1);
+    return new Date(date.getTime() + seconds * 1000);
 }
+// Deterministic schedule id (replay-determinism self-audit): the stamp is an edge
+// timestamp (recorded once), but the former Math.random() suffix made each
+// persisted schedule id non-reproducible. The suffix is now a content hash of the
+// schedule's deterministic identity (kind + the recorded stamp), so re-deriving the
+// id for a recorded schedule yields the byte-identical value while schedules created
+// at distinct instants still get distinct ids. Mirrors src/worker-isolation/paths.ts.
+let scheduleIdSequence = 0;
 function createScheduleId(kind) {
     const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
-    return `${kind}-${stamp}-${Math.random().toString(36).slice(2, 8)}`;
+    // Second-resolution stamp: two schedules of the same kind created within one
+    // second would otherwise collide on an identical id. process.pid + a monotonic
+    // counter break the tie across concurrent processes and within one process,
+    // deterministically (not a PRNG).
+    scheduleIdSequence += 1;
+    const suffix = node_crypto_1.default.createHash("sha256").update(`${kind}:${stamp}:${process.pid}:${scheduleIdSequence}`).digest("hex").slice(0, 6);
+    return `${kind}-${stamp}-${suffix}`;
 }
+// Deterministic schedule-run (history) id — same rationale as createScheduleId. The
+// history record stamp differs from the owning schedule's, so the hashed identity
+// (kind + run stamp) stays distinct from the schedule id while remaining a pure
+// function of already-recorded state.
+let scheduleRunIdSequence = 0;
 function createScheduleRunId(kind) {
     const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
-    return `run-${kind}-${stamp}-${Math.random().toString(36).slice(2, 8)}`;
+    // pid + counter break same-kind/same-second collisions (see createScheduleId).
+    scheduleRunIdSequence += 1;
+    const suffix = node_crypto_1.default.createHash("sha256").update(`run:${kind}:${stamp}:${process.pid}:${scheduleRunIdSequence}`).digest("hex").slice(0, 6);
+    return `run-${kind}-${stamp}-${suffix}`;
 }
 function requiredString(value, name) {
     const text = stringOption(value);

package/dist/topology.js

@@ -17,6 +17,8 @@ exports.showTopologyRun = showTopologyRun;
 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 pipeline_contract_1 = require("./pipeline-contract");
 const state_node_1 = require("./state-node");
 const trust_audit_1 = require("./trust-audit");
@@ -186,10 +188,16 @@ function applyTopology(run, topologyId, input = {}) {
     const definition = validation.definition;
     const state = ensureTopologyState(run);
     (0, multi_agent_1.ensureMultiAgentState)(run);
-    const id = input.id || `${definition.id}-${timestampId()}`;
+    const taskIds = selectedTaskIds(run, input.taskIds);
+    // Default id is a DETERMINISTIC content-hash (replay determinism): two `topology
+    // apply` invocations WITHOUT --id over the same definition/tasks/run produce a
+    // byte-identical id. Same sha256/stableStringify the kernel uses for node ids
+    // (state-node/createNodeId) and ledger record ids. `state.runs.length` is the
+    // stable sequence so repeated applies on the same run get distinct ids without a
+    // wall-clock stamp. input.id stays an explicit override.
+    const id = input.id || topologyRunId(definition, taskIds, run.id, state.runs.length);
     if (state.runs.some((record) => record.id === id))
         throw new Error(`Duplicate MultiAgentTopologyRun id: ${id}`);
-    const taskIds = selectedTaskIds(run, input.taskIds);
     const board = (0, coordinator_1.resolveBlackboard)(run, {
         id: input.blackboardId || `${id}-blackboard`,
         title: `${definition.title} Blackboard`,
@@ -514,8 +522,21 @@ function statusToNodeStatus(status) {
 function issue(code, message, path) {
     return { code, message, path };
 }
-function timestampId() {
-    return new Date().toISOString().replace(/[-:.]/g, "").slice(0, 15).toLowerCase();
+// Deterministic default topology-run id (F2, replay determinism): no wall-clock.
+// Bound to a short sha256 of canonical content — definition id, the SORTED role and
+// selected-task ids, the workflow run id, and a stable sequence (the count of
+// topology runs already on this run). Same sha256/stableStringify the kernel uses
+// for node ids and ledger record hashes, so two replays without --id reach a
+// byte-identical fingerprint, while distinct applies on one run stay distinct.
+function topologyRunId(definition, taskIds, runId, sequence) {
+    const digest = (0, execution_backend_1.sha256)((0, telemetry_attestation_1.stableStringify)({
+        definitionId: definition.id,
+        roleIds: [...definition.roles.map((role) => role.id)].sort(),
+        taskIds: [...taskIds].sort(),
+        runId,
+        sequence
+    }));
+    return `${definition.id}-${digest.replace("sha256:", "").slice(0, 16)}`;
 }
 function countBy(items, pick) {
     const counts = {};

package/dist/trust-audit.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TRUST_AUDIT_SCHEMA_VERSION = void 0;
+exports.CORRELATION_ID_FIELDS = exports.TRUST_AUDIT_SCHEMA_VERSION = void 0;
 exports.trustAuditGenesis = trustAuditGenesis;
 exports.verifyTrustAudit = verifyTrustAudit;
 exports.ensureTrustAudit = ensureTrustAudit;
@@ -152,6 +152,65 @@ function verifyTrustAudit(run) {
     }
     return { present: events.length > 0, verified, eventCount: events.length, chained, unchained, corruptLines, checks };
 }
+// ---- Correlation-id fields (single source of truth, F12) -------------------
+// These id fields are plain pass-throughs that flow input -> persisted event ->
+// summary index unchanged. They were previously re-listed by hand in three
+// places (recordTrustAuditEvent, the index writer, and partially in
+// multi-agent-trust), so adding a new correlation id meant editing every list and
+// silently dropping it from the index when one was missed. They now live in ONE
+// array; both spread sites pick from it via pickCorrelationIds, so a new id is
+// added in exactly one place.
+//
+// SERIALIZATION-PRESERVING by design: this is a plain key-copy with NO transform,
+// so the persisted JSON for these keys is byte-identical to the old hand-spread
+// (compact() still drops the undefined ones). The hash chain that binds these
+// fields is therefore unaffected. Fields needing derivation/normalization
+// (feedbackIds, sandboxProfileId, policyRef, multiAgentPolicyRef, normalizedPath,
+// envVars, …) are intentionally NOT here — they keep their bespoke handling at the
+// call site.
+exports.CORRELATION_ID_FIELDS = [
+    "candidateId",
+    "scoreId",
+    "selectionId",
+    "commitId",
+    "multiAgentRunId",
+    "agentRoleId",
+    "agentGroupId",
+    "agentMembershipId",
+    "agentFanoutId",
+    "agentFaninId",
+    "blackboardId",
+    "blackboardTopicId",
+    "blackboardMessageId",
+    "blackboardContextId",
+    "blackboardArtifactRefId",
+    "blackboardSnapshotId",
+    "coordinatorDecisionId",
+    "topologyId",
+    "topologyRunId"
+];
+/** Copy exactly the correlation-id keys (and no others) from `source`, preserving
+ *  each value verbatim (including `undefined`, which compact()/JSON.stringify drop
+ *  identically to the prior per-key spread). Spread the result; do not transform. */
+function pickCorrelationIds(source) {
+    const picked = {};
+    for (const field of exports.CORRELATION_ID_FIELDS)
+        picked[field] = source[field];
+    return picked;
+}
+// The summary index has always carried every correlation id EXCEPT scoreId (the
+// per-candidate score lives in the candidates[] rows, not the flat event index).
+// Pin that exception in ONE place so the index stays byte-identical while still
+// inheriting any NEW id from CORRELATION_ID_FIELDS automatically.
+const INDEX_OMITTED_CORRELATION_IDS = new Set(["scoreId"]);
+/** Correlation ids for the summary index: the full pick minus the keys the index
+ *  has historically omitted (see INDEX_OMITTED_CORRELATION_IDS). */
+function indexCorrelationIds(event) {
+    const picked = pickCorrelationIds(event);
+    for (const field of INDEX_OMITTED_CORRELATION_IDS)
+        delete picked[field];
+    return picked;
+}
 function ensureTrustAudit(run) {
     const auditDir = auditRoot(run);
     node_fs_1.default.mkdirSync(auditDir, { recursive: true });
@@ -177,25 +236,11 @@ function recordTrustAuditEvent(run, input) {
         taskId: input.taskId,
         nodeId: input.nodeId,
         feedbackIds: input.feedbackIds?.filter(Boolean).sort(),
-        candidateId: input.candidateId,
-        scoreId: input.scoreId,
-        selectionId: input.selectionId,
-        commitId: input.commitId,
-        multiAgentRunId: input.multiAgentRunId,
-        agentRoleId: input.agentRoleId,
-        agentGroupId: input.agentGroupId,
-        agentMembershipId: input.agentMembershipId,
-        agentFanoutId: input.agentFanoutId,
-        agentFaninId: input.agentFaninId,
-        blackboardId: input.blackboardId,
-        blackboardTopicId: input.blackboardTopicId,
-        blackboardMessageId: input.blackboardMessageId,
-        blackboardContextId: input.blackboardContextId,
-        blackboardArtifactRefId: input.blackboardArtifactRefId,
-        blackboardSnapshotId: input.blackboardSnapshotId,
-        coordinatorDecisionId: input.coordinatorDecisionId,
-        topologyId: input.topologyId,
-        topologyRunId: input.topologyRunId,
+        // Plain correlation-id pass-throughs (candidateId … topologyRunId) come from the
+        // single CORRELATION_ID_FIELDS list. Key order is preserved (the list is in the
+        // same order the keys used to be hand-written), so the persisted JSON — and thus
+        // the eventHash chain — is byte-identical.
+        ...pickCorrelationIds(input),
         sandboxProfileId: input.sandboxProfileId || input.policySnapshot?.id,
         policyRef: input.policyRef || (input.policySnapshot?.id ? `run.sandboxProfiles.${input.policySnapshot.id}` : undefined),
         multiAgentPolicyRef: input.policyRef,
@@ -351,24 +396,11 @@ function summarizeTrustAudit(run) {
             source: event.source,
             workerId: event.workerId,
             taskId: event.taskId,
-            candidateId: event.candidateId,
-            selectionId: event.selectionId,
-            commitId: event.commitId,
-            multiAgentRunId: event.multiAgentRunId,
-            agentRoleId: event.agentRoleId,
-            agentGroupId: event.agentGroupId,
-            agentMembershipId: event.agentMembershipId,
-            agentFanoutId: event.agentFanoutId,
-            agentFaninId: event.agentFaninId,
-            blackboardId: event.blackboardId,
-            blackboardTopicId: event.blackboardTopicId,
-            blackboardMessageId: event.blackboardMessageId,
-            blackboardContextId: event.blackboardContextId,
-            blackboardArtifactRefId: event.blackboardArtifactRefId,
-            blackboardSnapshotId: event.blackboardSnapshotId,
-            coordinatorDecisionId: event.coordinatorDecisionId,
-            topologyId: event.topologyId,
-            topologyRunId: event.topologyRunId,
+            // Same single CORRELATION_ID_FIELDS list the record path uses, so the index
+            // can never silently omit a correlation id that the event carries. (The index
+            // historically omitted scoreId; that is preserved below by deleting it after
+            // the pick, keeping this writer's output byte-identical.)
+            ...indexCorrelationIds(event),
             sandboxProfileId: event.sandboxProfileId,
             policyRef: event.policyRef,
             multiAgentPolicyRef: event.multiAgentPolicyRef

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.81";
+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;