cool-workflow 0.1.98 → 0.2.0

package/dist/state.js

@@ -1,367 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CURRENT_RUN_STATE_SCHEMA_VERSION = void 0;
-exports.createRunPaths = createRunPaths;
-exports.ensureRunDirs = ensureRunDirs;
-exports.loadRunFromCwd = loadRunFromCwd;
-exports.loadRunStateFile = loadRunStateFile;
-exports.checkRunStateFile = checkRunStateFile;
-exports.migrateRunStateFile = migrateRunStateFile;
-exports.saveCheckpoint = saveCheckpoint;
-exports.compactCheckpoint = compactCheckpoint;
-exports.readJson = readJson;
-exports.writeJson = writeJson;
-exports.durableAppendFileSync = durableAppendFileSync;
-exports.realResolve = realResolve;
-exports.isContainedPath = isContainedPath;
-exports.withFileLock = withFileLock;
-exports.safeFileName = safeFileName;
-exports.assertSafeRunId = assertSafeRunId;
-exports.hashArtifactFile = hashArtifactFile;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const state_migrations_1 = require("./state-migrations");
-const version_1 = require("./version");
-Object.defineProperty(exports, "CURRENT_RUN_STATE_SCHEMA_VERSION", { enumerable: true, get: function () { return version_1.CURRENT_RUN_STATE_SCHEMA_VERSION; } });
-const execution_backend_1 = require("./execution-backend");
-function createRunPaths(runDir) {
-    return {
-        runDir,
-        state: node_path_1.default.join(runDir, "state.json"),
-        report: node_path_1.default.join(runDir, "report.md"),
-        tasksDir: node_path_1.default.join(runDir, "tasks"),
-        resultsDir: node_path_1.default.join(runDir, "results"),
-        dispatchesDir: node_path_1.default.join(runDir, "dispatches"),
-        artifactsDir: node_path_1.default.join(runDir, "artifacts"),
-        commitsDir: node_path_1.default.join(runDir, "commits"),
-        stateNodesDir: node_path_1.default.join(runDir, "nodes"),
-        feedbackDir: node_path_1.default.join(runDir, "feedback"),
-        auditDir: node_path_1.default.join(runDir, "audit"),
-        workersDir: node_path_1.default.join(runDir, "workers"),
-        candidatesDir: node_path_1.default.join(runDir, "candidates"),
-        multiAgentDir: node_path_1.default.join(runDir, "multi-agent"),
-        blackboardDir: node_path_1.default.join(runDir, "blackboard"),
-        topologiesDir: node_path_1.default.join(runDir, "topologies")
-    };
-}
-function ensureRunDirs(paths) {
-    for (const dir of [
-        paths.runDir,
-        paths.tasksDir,
-        paths.resultsDir,
-        paths.dispatchesDir,
-        paths.artifactsDir,
-        paths.commitsDir,
-        paths.stateNodesDir,
-        paths.feedbackDir,
-        paths.auditDir || node_path_1.default.join(paths.runDir, "audit"),
-        paths.workersDir || node_path_1.default.join(paths.runDir, "workers"),
-        paths.candidatesDir || node_path_1.default.join(paths.runDir, "candidates"),
-        paths.multiAgentDir || node_path_1.default.join(paths.runDir, "multi-agent"),
-        paths.blackboardDir || node_path_1.default.join(paths.runDir, "blackboard"),
-        paths.topologiesDir || node_path_1.default.join(paths.runDir, "topologies")
-    ]) {
-        node_fs_1.default.mkdirSync(dir, { recursive: true });
-    }
-}
-function loadRunFromCwd(runId, cwd = process.cwd()) {
-    if (!runId)
-        throw new Error("Missing run id");
-    assertSafeRunId(runId);
-    const statePath = node_path_1.default.join(cwd, ".cw", "runs", runId, "state.json");
-    const result = loadRunStateFile(statePath, { dryRun: true });
-    if (result.report.status === "unsupported") {
-        throw new Error(`Unsupported CW run state: ${result.report.errors.join("; ")}`);
-    }
-    return result.run;
-}
-function loadRunStateFile(statePath, options = {}) {
-    const result = (0, state_migrations_1.migrateRunState)(readJson(statePath), {
-        statePath,
-        dryRun: options.dryRun === undefined ? true : options.dryRun
-    });
-    if (result.report.status === "unsupported")
-        return result;
-    return result;
-}
-function checkRunStateFile(statePath) {
-    return loadRunStateFile(statePath, { dryRun: true });
-}
-function migrateRunStateFile(statePath, options = {}) {
-    const result = loadRunStateFile(statePath, { dryRun: !options.write });
-    if (result.report.status !== "unsupported" && options.write && result.report.writeRequired) {
-        writeJson(statePath, result.run);
-    }
-    return result;
-}
-function saveCheckpoint(run) {
-    run.updatedAt = new Date().toISOString();
-    // state.json is the single source of truth — write it DURABLY with a lock
-    // so concurrent processes never lose an update (v0.1.95).
-    withFileLock(run.paths.state, () => {
-        writeJson(run.paths.state, run, { durable: true });
-    });
-}
-/** Compact a run checkpoint by stripping empty optional arrays and null values
- *  that don't carry semantic meaning (v0.1.60). The normalization layer
- *  (normalizeRunState) backfills these on load, so stripping them saves disk
- *  without losing information. Returns the number of keys stripped. */
-function compactCheckpoint(run) {
-    const optionalArrays = [
-        "nodes", "contracts", "feedback", "workers", "sandboxProfiles",
-        "candidates", "candidateSelections"
-    ];
-    let stripped = 0;
-    const state = run;
-    for (const key of optionalArrays) {
-        if (Array.isArray(state[key]) && state[key].length === 0) {
-            delete state[key];
-            stripped++;
-        }
-    }
-    if (stripped > 0)
-        saveCheckpoint(run);
-    return stripped;
-}
-function readJson(file) {
-    if (!node_fs_1.default.existsSync(file))
-        throw new Error(`File not found: ${file}`);
-    try {
-        return JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Invalid JSON in ${file}: ${message}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// Atomic, optionally-durable JSON write (v0.1.40, closes the prior P1).
-//
-// ORDER IS THE SAFETY PROPERTY: write to a unique temp file, then rename over the
-// target. `rename(2)` is atomic on POSIX, so a crash/`ENOSPC` mid-write can never
-// leave a truncated `state.json` that throws `Invalid JSON` on reload — a reader
-// always sees EITHER the old bytes OR the new bytes, never a torn file. With
-// `{ durable: true }` we additionally fsync the file (and best-effort the dir)
-// before/after the rename so the bytes survive power loss — used for AUTHORITATIVE
-// state (state.json, registry overlays, the scheduler store, reclaimed.json). The
-// fsync is skipped for high-frequency derived/rebuildable writes so the atomic
-// rename (the actual torn-write fix) stays cheap everywhere.
-// ---------------------------------------------------------------------------
-let atomicWriteCounter = 0;
-function writeJson(file, value, options = {}) {
-    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
-    const tmp = `${file}.tmp.${process.pid}.${atomicWriteCounter++}`;
-    const fd = node_fs_1.default.openSync(tmp, "w");
-    try {
-        node_fs_1.default.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-        if (options.durable)
-            node_fs_1.default.fsyncSync(fd);
-    }
-    finally {
-        node_fs_1.default.closeSync(fd);
-    }
-    try {
-        node_fs_1.default.renameSync(tmp, file);
-    }
-    catch (error) {
-        try {
-            node_fs_1.default.rmSync(tmp, { force: true });
-        }
-        catch {
-            /* best-effort temp cleanup */
-        }
-        throw error;
-    }
-    if (options.durable) {
-        try {
-            const dirFd = node_fs_1.default.openSync(node_path_1.default.dirname(file), "r");
-            try {
-                node_fs_1.default.fsyncSync(dirFd);
-            }
-            finally {
-                node_fs_1.default.closeSync(dirFd);
-            }
-        }
-        catch {
-            /* directory fsync is best-effort (not supported on every platform) */
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Durable append (v0.1.40 self-audit P1) — append a line and fsync it before
-// returning. The trust-audit event log is the ONE artifact whose loss breaks
-// audit-completeness/non-repudiation, so unlike high-frequency derived writes it
-// must survive power loss. `appendFileSync` alone does NOT fsync, so a crash
-// after it returns could drop the most recent event while durable state.json
-// advanced past it. We open O_APPEND, write, fsync the fd, then close.
-// ---------------------------------------------------------------------------
-function durableAppendFileSync(file, data) {
-    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
-    const fd = node_fs_1.default.openSync(file, "a");
-    try {
-        node_fs_1.default.writeFileSync(fd, data, "utf8");
-        node_fs_1.default.fsyncSync(fd);
-    }
-    finally {
-        node_fs_1.default.closeSync(fd);
-    }
-}
-// ---------------------------------------------------------------------------
-// Symlink-hardened path containment (v0.1.40 self-audit P1) — `path.resolve()`
-// only normalizes `.`/`..` textually; it does NOT follow symlinks, so a planted
-// symlink whose textual path sits "inside" an allowed root but whose real target
-// escapes it would pass a `startsWith` containment check. `realResolve` resolves
-// the deepest EXISTING ancestor with `realpathSync` (which follows symlinks) and
-// re-joins the not-yet-created remainder, so a not-yet-created file is still
-// pinned to its real parent. `isContainedPath` realpaths BOTH sides so the
-// comparison stays consistent on platforms where the temp root itself is a
-// symlink (e.g. macOS /tmp -> /private/tmp).
-// ---------------------------------------------------------------------------
-function realResolve(target) {
-    let current = node_path_1.default.resolve(target);
-    const tail = [];
-    // Walk up to the deepest existing ancestor, realpath it, then re-append the tail.
-    for (;;) {
-        try {
-            const real = node_fs_1.default.realpathSync.native ? node_fs_1.default.realpathSync.native(current) : node_fs_1.default.realpathSync(current);
-            return tail.length ? node_path_1.default.join(real, ...tail.reverse()) : real;
-        }
-        catch {
-            const parent = node_path_1.default.dirname(current);
-            if (parent === current)
-                return node_path_1.default.resolve(target); // reached root; nothing existed
-            tail.push(node_path_1.default.basename(current));
-            current = parent;
-        }
-    }
-}
-function isContainedPath(candidate, allowed) {
-    const realCandidate = realResolve(candidate);
-    const realAllowed = realResolve(allowed);
-    return realCandidate === realAllowed || realCandidate.startsWith(realAllowed + node_path_1.default.sep);
-}
-// ---------------------------------------------------------------------------
-// Portable advisory file lock (v0.1.40) — serialize cross-process read-modify-
-// write on shared stores (home queue, scheduler store, archive overlay, the
-// per-run reclamation chain) so a concurrent writer can never lose a record.
-// O_EXCL (`wx`) is portable (no native flock); a stale holder is stolen so a
-// crashed process can never wedge the store forever.
-//
-// v0.1.95: the lock mtime is refreshed immediately before fn() runs, and
-// verified AFTER fn() returns — if another process stole the lock mid-operation
-// (the stale check fired and it overwrote our lock), the holder refuses to
-// release and throws. This guards long-running RMW operations (e.g. GC over a
-// large run) against mid-operation theft.
-// ---------------------------------------------------------------------------
-const FILE_LOCK_STALE_MS = 30_000;
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-/** Run `fn` while holding an advisory lock for `targetPath`; always released. */
-function withFileLock(targetPath, fn) {
-    const lock = `${targetPath}.lock`;
-    node_fs_1.default.mkdirSync(node_path_1.default.dirname(lock), { recursive: true });
-    const pid = String(process.pid);
-    let acquired = false;
-    for (let attempt = 0; attempt < 240 && !acquired; attempt++) {
-        try {
-            const fd = node_fs_1.default.openSync(lock, "wx");
-            node_fs_1.default.writeFileSync(fd, `${pid}@${new Date().toISOString()}\n`, "utf8");
-            node_fs_1.default.closeSync(fd);
-            acquired = true;
-        }
-        catch (error) {
-            if (!(error && typeof error === "object" && error.code === "EEXIST"))
-                throw error;
-            try {
-                if (Date.now() - node_fs_1.default.statSync(lock).mtimeMs > FILE_LOCK_STALE_MS) {
-                    node_fs_1.default.rmSync(lock, { force: true });
-                    continue;
-                }
-            }
-            catch {
-                continue;
-            }
-            sleepSync(25);
-        }
-    }
-    if (!acquired)
-        throw new Error(`could not acquire file lock for ${targetPath}`);
-    // Refresh mtime right before the critical section
-    try {
-        node_fs_1.default.utimesSync(lock, new Date(), new Date());
-    }
-    catch { /* best-effort */ }
-    try {
-        const result = fn();
-        // Verify lock was not stolen during fn(). The lock content may have changed
-        // if another process opened it with wx after stealing it. If our PID is not
-        // in the lock file, the lock was stolen — do NOT release the stolen lock
-        // (the thief owns it now, and releasing would corrupt its operation).
-        try {
-            const current = node_fs_1.default.readFileSync(lock, "utf8");
-            if (!current.startsWith(pid + "@")) {
-                throw new Error(`File lock for ${targetPath} was stolen during the critical section ` +
-                    `(lock now owned by another process). The operation may have lost ` +
-                    `cross-process isolation — increase FILE_LOCK_STALE_MS or split the work.`);
-            }
-        }
-        catch (checkError) {
-            if (checkError instanceof Error && checkError.message.includes("stolen"))
-                throw checkError;
-            /* lock vanished — another process already released it, nothing to clean up */
-        }
-        return result;
-    }
-    finally {
-        try {
-            // Only release if we still own the lock
-            const current = node_fs_1.default.readFileSync(lock, "utf8");
-            if (current.startsWith(pid + "@"))
-                node_fs_1.default.rmSync(lock, { force: true });
-        }
-        catch {
-            /* releasing a missing lock is fine */
-        }
-    }
-}
-function safeFileName(value) {
-    return String(value).replace(/[^a-zA-Z0-9_.:-]+/g, "_");
-}
-/** Refuse a run id that is not a single safe path segment, so an id taken from
- *  an untrusted source (an imported run archive / bundle) can never escape the
- *  runs directory via a separator or a `..`/`.` component (path traversal). A
- *  real run id is `${workflowId}-${stamp}-${suffix}` (createRunId), and a
- *  workflow id is alnum-bounded [a-z0-9.-] (validateWorkflowId) — all within
- *  [A-Za-z0-9._:-]. Sub-workflow ids also include `:` from the task id prefix.
- *  Because the charset already forbids any separator, the whole
- *  id is ONE path component, so the only values that could traverse are the
- *  components `.` and `..` themselves; an embedded `..` (e.g. a workflow id like
- *  `v1..2`) is a safe directory name and is allowed. A separator, an absolute
- *  path, or an empty value is refused, fail-closed. Returns the id on success so
- *  callers can use it inline. */
-function assertSafeRunId(value, context = "run id") {
-    if (typeof value !== "string" || value.length === 0) {
-        throw new Error(`Invalid ${context}: expected a non-empty string`);
-    }
-    if (!/^[A-Za-z0-9._:-]+$/.test(value) || value === "." || value === "..") {
-        throw new Error(`Unsafe ${context}: ${JSON.stringify(value)} must be a single path segment ([A-Za-z0-9._:-], not '.' or '..')`);
-    }
-    return value;
-}
-/** Compute and set SHA256 + sizeBytes on a StateArtifact from its file path
- *  (v0.1.73). Fails silently when the file doesn't exist — does not throw. */
-function hashArtifactFile(artifact) {
-    try {
-        const content = node_fs_1.default.readFileSync(artifact.path, "utf8");
-        artifact.sha256 = (0, execution_backend_1.sha256)(content);
-        artifact.sizeBytes = Buffer.byteLength(content, "utf8");
-    }
-    catch {
-        /* file missing — silently skip */
-    }
-    return artifact;
-}

package/dist/telemetry-ledger.js

@@ -1,196 +0,0 @@
-"use strict";
-// Telemetry attestation ledger (Track 1) — make the RECORDED attestation itself
-// tamper-evident, not just the in-flight signature.
-//
-// The executor's signature (telemetry-attestation.ts) proves the agent SAID a
-// given usage. This ledger proves CW RECORDED exactly that and nobody edited the
-// record afterward: an append-only, hash-chained overlay (`telemetry.json`, a
-// runDir peer of reclaimed.json), one entry per agent hop. Each entry chains to
-// the prior via prevHash; recordHash = sha256(canonical entry sans recordHash).
-// Flip a recorded verdict (`unattested`→`attested`), or edit a recorded usage
-// digest, and the chain no longer recomputes — `verifyTelemetryLedger` catches it.
-//
-// Same discipline as reclamation.ts's tombstone chain: APPEND-ONLY (never rewrite
-// a prior entry), DURABLE (temp→fsync→rename via writeJson), and verify recomputes
-// every hash independently — it never trusts the stored value.
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TelemetryLedgerCorruptError = exports.TELEMETRY_LEDGER_SCHEMA_VERSION = void 0;
-exports.telemetryLedgerPath = telemetryLedgerPath;
-exports.loadTelemetryLedger = loadTelemetryLedger;
-exports.genesisPrevHash = genesisPrevHash;
-exports.computeRecordHash = computeRecordHash;
-exports.reportedUsageDigest = reportedUsageDigest;
-exports.appendTelemetryAttestation = appendTelemetryAttestation;
-exports.verifyTelemetryLedger = verifyTelemetryLedger;
-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");
-exports.TELEMETRY_LEDGER_SCHEMA_VERSION = 1;
-function telemetryLedgerPath(run) {
-    return node_path_1.default.join(run.paths.runDir, "telemetry.json");
-}
-/** A telemetry ledger that EXISTS on disk but cannot be parsed (or whose shape is
- *  not a record array). This is exactly the corruption/truncation case the hash
- *  chain exists to catch — it must fail closed, never be silently treated as the
- *  "empty/absent" chain (which verifies as clean). */
-class TelemetryLedgerCorruptError extends Error {
-    file;
-    constructor(file) {
-        super(`Telemetry ledger exists but is corrupt (unparseable): ${file}`);
-        this.name = "TelemetryLedgerCorruptError";
-        this.file = file;
-    }
-}
-exports.TelemetryLedgerCorruptError = TelemetryLedgerCorruptError;
-/** Read the ledger, DISTINGUISHING absent (never written -> empty chain, fine)
- *  from corrupt (exists but unparseable/wrong shape -> fail closed). Conflating
- *  the two was the bug that let a corrupt overlay verify green and let an append
- *  silently re-genesis on top of it, discarding history. */
-function readTelemetryLedgerState(run) {
-    const file = telemetryLedgerPath(run);
-    if (!node_fs_1.default.existsSync(file))
-        return { status: "absent", ledger: { schemaVersion: 1, runId: run.id, records: [] } };
-    let parsed;
-    try {
-        parsed = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
-    }
-    catch {
-        return { status: "corrupt", file };
-    }
-    if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.records)) {
-        return { status: "corrupt", file };
-    }
-    return { status: "ok", ledger: { schemaVersion: 1, runId: run.id, records: parsed.records } };
-}
-/** Load the ledger for read/append. Absent -> empty chain. Corrupt -> THROWS, so
- *  an append can never silently re-genesis on a poisoned/edited file, and a read
- *  surfaces the corruption rather than swallowing it. */
-function loadTelemetryLedger(run) {
-    const state = readTelemetryLedgerState(run);
-    if (state.status === "corrupt")
-        throw new TelemetryLedgerCorruptError(state.file);
-    return state.ledger;
-}
-/** genesis prevHash for a run's chain (no prior record). */
-function genesisPrevHash(runId) {
-    return (0, execution_backend_1.sha256)(`cw-telemetry-ledger:${runId}`);
-}
-/** The canonical bytes a recordHash binds — every field except recordHash itself.
- *  Recomputed independently by verifyTelemetryLedger. */
-function recordHashInput(record) {
-    return (0, telemetry_attestation_1.stableStringify)({
-        schemaVersion: record.schemaVersion,
-        runId: record.runId,
-        recordId: record.recordId,
-        recordedAt: record.recordedAt,
-        workerId: record.workerId,
-        taskId: record.taskId,
-        promptDigest: record.promptDigest,
-        reportedUsageDigest: record.reportedUsageDigest,
-        ...(record.reportedUsage !== undefined ? { reportedUsage: record.reportedUsage } : {}),
-        usageSignature: record.usageSignature || null,
-        // Chain-bind resultDigest only when present, so a usage-only record's hash is
-        // byte-identical to a pre-result-coverage one (back-compat with old ledgers).
-        ...(record.resultDigest !== undefined ? { resultDigest: record.resultDigest } : {}),
-        attestation: record.attestation,
-        attestationReason: record.attestationReason || null,
-        prevHash: record.prevHash
-    });
-}
-function computeRecordHash(record) {
-    return (0, execution_backend_1.sha256)(recordHashInput(record));
-}
-/** sha256 of the canonical reported usage (compact, chainable). Absent usage gets
- *  the digest of `null`, so "the agent reported nothing" is itself bound. */
-function reportedUsageDigest(usage) {
-    return (0, execution_backend_1.sha256)((0, telemetry_attestation_1.stableStringify)(usage ?? null));
-}
-function recordId(seq) {
-    // Deterministic (FreeBSD-audit L13): the chain POSITION, not a process-global
-    // counter or wall-clock stamp — recordId is bound into the recordHash chain.
-    return `tel-${String(seq).padStart(3, "0")}`;
-}
-/** Append one attestation record DURABLY to the append-only chain, linking it to
- *  the prior record (or genesis). Returns the committed record. */
-function appendTelemetryAttestation(run, input) {
-    const ledger = loadTelemetryLedger(run);
-    const now = input.now || new Date().toISOString();
-    const prevHash = ledger.records.length ? ledger.records[ledger.records.length - 1].recordHash : genesisPrevHash(run.id);
-    const base = {
-        schemaVersion: 1,
-        runId: run.id,
-        recordId: recordId(ledger.records.length + 1),
-        recordedAt: now,
-        workerId: input.workerId,
-        taskId: input.taskId,
-        promptDigest: input.promptDigest,
-        reportedUsageDigest: reportedUsageDigest(input.reportedUsage),
-        // Store the raw usage verbatim, digest-bound, and hash-chained so the
-        // signature can be independently re-verified offline at `telemetry verify`.
-        ...(input.reportedUsage ? { reportedUsage: input.reportedUsage } : {}),
-        usageSignature: input.usageSignature,
-        // Present only for a result-bound signature, so usage-only records are
-        // byte-identical (and their recordHash unchanged) — back-compat.
-        ...(input.resultDigest ? { resultDigest: input.resultDigest } : {}),
-        attestation: input.attestation,
-        attestationReason: input.attestationReason,
-        prevHash
-    };
-    const record = { ...base, recordHash: computeRecordHash(base) };
-    ledger.records.push(record);
-    (0, state_1.writeJson)(telemetryLedgerPath(run), ledger, { durable: true });
-    return record;
-}
-/** Re-prove the whole telemetry chain for a run: prevHash linkage + per-record
- *  hash recompute. Recomputes every hash independently — never trusts the stored
- *  value — so an edited record/verdict is detected. An empty ledger verifies as
- *  present:false (nothing to prove), NOT a failure. */
-function verifyTelemetryLedger(run) {
-    const state = readTelemetryLedgerState(run);
-    if (state.status === "corrupt") {
-        // Fail closed: a ledger that exists but cannot be parsed is indistinguishable
-        // from a truncated/forged one — report it, never green it.
-        return {
-            present: true,
-            verified: false,
-            records: [],
-            checks: [{ name: "ledger-load", pass: false, code: "telemetry-ledger-corrupt" }],
-            attested: 0,
-            unattested: 0,
-            absent: 0
-        };
-    }
-    const records = state.ledger.records;
-    const checks = [];
-    const tally = { attested: 0, unattested: 0, absent: 0 };
-    for (const record of records)
-        tally[record.attestation] += 1;
-    if (!records.length) {
-        return { present: false, verified: true, records, checks, ...tally };
-    }
-    // (a) chain linkage: genesis = sha256("cw-telemetry-ledger:"+runId).
-    let chainOk = true;
-    for (let i = 0; i < records.length; i++) {
-        const expectedPrev = i === 0 ? genesisPrevHash(run.id) : records[i - 1].recordHash;
-        const pass = records[i].prevHash === expectedPrev;
-        if (!pass)
-            chainOk = false;
-        checks.push({ name: `chain-link[${i}]`, pass, code: pass ? undefined : "telemetry-chain-broken" });
-    }
-    // (b) per-record independent hash recompute (digest integrity).
-    let digestsOk = true;
-    for (let i = 0; i < records.length; i++) {
-        const { recordHash, ...rest } = records[i];
-        const recomputed = computeRecordHash(rest);
-        const pass = recomputed === recordHash;
-        if (!pass)
-            digestsOk = false;
-        checks.push({ name: `record-hash[${i}]`, pass, code: pass ? undefined : "telemetry-digest-mismatch" });
-    }
-    return { present: true, verified: chainOk && digestsOk, records, checks, ...tally };
-}