cool-workflow 0.1.97 → 0.2.0

package/dist/{telemetry-attestation.js → core/trust/telemetry-attestation.js}

@@ -1,31 +1,54 @@
 "use strict";
-// Telemetry attestation (Track 1) — make "auditable" a FACT, not a claim.
+// core/trust/telemetry-attestation.ts — ed25519 usage/result attestation.
 //
-// The agent self-reports its token usage on stdout (parseAgentReport). A control
-// plane that records that number verbatim is recording a CLAIM: a tampered or
-// fabricated usage survives untouched. This module is the verify gate that turns
-// the claim into an attestation:
+// MILESTONE 8. The AGENT (executor) signs; CW only VERIFIES with an
+// operator-given PUBLIC key — CW holds no private key, ever. Uses
+// node:crypto's built-in ed25519 sign/verify (no npm dependency).
 //
-//   - The EXECUTOR signs a canonical payload binding {usage, runId, taskId,
-//     promptDigest} with its private key (ed25519). The binding context is what
-//     stops one task's signature being replayed onto another.
-//   - CW VERIFIES that signature against an operator-provisioned PUBLIC key.
-//     CW holds ONLY the public key — it can verify, but can neither forge a
-//     signature nor (the red line) call a model to measure usage itself. A
-//     third-party auditor with the same public key can re-verify independently.
+// `crypto.verify`/`crypto.createPublicKey` are allowed here per
+// v2/PLAN.md's lint carve-out for this exact file (Target shape,
+// core/trust/telemetry-attestation.ts comment) — this remains otherwise
+// pure (no fs, no process.env, no clock; `resolveTrustPublicKey`'s lazy
+// `require("node:fs")` is the one exception, ported byte-identically
+// from the old build's own lazy-require pattern so a bundle that never
+// resolves a key path pays no fs cost).
 //
-// HONEST CEILING [load-bearing]: a signature proves the usage came from the
-// keyholder and was not tampered in transit — NON-REPUDIABLE ATTRIBUTION, not
-// ground-truth measurement. A dishonest keyholder can still sign a lie, but the
-// lie is now cryptographically bound to its signer. That is strictly stronger
-// than self-signed sha256 (which any party can recompute) and is the most a
-// delegating control-plane can claim without measuring (which it must not).
-//
-// Default is honest: no signature ⇒ `unattested`, no usage ⇒ `absent`. Usage is
-// NEVER silently recorded as trusted.
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+// Evidence: SPEC/ledger-trust.md "The signing model", "Attestation
+// verify", byte-compat items 2 and 11;
+// plugins/cool-workflow/src/telemetry-attestation.ts:1-319.
+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.stableStringify = stableStringify;
 exports.canonicalTelemetryPayload = canonicalTelemetryPayload;
@@ -34,9 +57,17 @@ exports.verifyTelemetryAttestation = verifyTelemetryAttestation;
 exports.resolveTrustPublicKey = resolveTrustPublicKey;
 exports.signTelemetry = signTelemetry;
 exports.verifyTelemetrySignatures = verifyTelemetrySignatures;
-const node_crypto_1 = __importDefault(require("node:crypto"));
-/** Deterministic, key-sorted JSON so signer and verifier hash byte-identical
- *  input regardless of object key order. */
+const crypto = __importStar(require("node:crypto"));
+/** `src/telemetry-attestation.ts`'s `stableStringify` — sorts keys
+ *  recursively, AND maps a top-level `undefined` input to the literal
+ *  string `"null"`. Divergent from `core/hash.ts`'s
+ *  `ledgerStableStringify` exactly at the top-level-undefined edge (see
+ *  v2/PLAN.md byte-compat item 2). Re-exported under this file's own
+ *  name (rather than importing `telemetryStableStringify` from
+ *  core/hash.ts) because SPEC/ledger-trust.md's "Exported functions"
+ *  list names `stableStringify` as a real export of THIS module — the
+ *  two are byte-identical behavior, kept as separate named exports per
+ *  their separate call sites. */
 function stableStringify(value) {
     if (value === null || typeof value !== "object")
         return JSON.stringify(value) ?? "null";
@@ -54,10 +85,10 @@ function canonicalTelemetryPayload(usage, ctx) {
         runId: ctx.runId,
         taskId: ctx.taskId,
         promptDigest: ctx.promptDigest,
-        // Present ONLY when the signer covered the result. Omitting the key keeps the
-        // canonical bytes byte-identical to the original 4-field payload, so every
-        // pre-result-coverage signature still verifies (POLA / back-compat).
-        ...(ctx.resultDigest !== undefined ? { resultDigest: ctx.resultDigest } : {})
+        // Present ONLY when the signer covered the result — omitting the key
+        // keeps the canonical bytes byte-identical to the original 4-field
+        // payload, so every pre-result-coverage signature still verifies.
+        ...(ctx.resultDigest !== undefined ? { resultDigest: ctx.resultDigest } : {}),
     });
 }
 function messageOf(error) {
@@ -72,9 +103,9 @@ function numberAt(usage, ...keys) {
     }
     return undefined;
 }
-/** Map the agent's free-form usage report onto UsageRecord token buckets, tolerating
- *  snake_case / camelCase variants (input_tokens vs inputTokens, etc.). CW never
- *  invents a number — an unreported bucket stays undefined, never zero. */
+/** Map the agent's free-form usage report onto token buckets, tolerating
+ *  snake_case / camelCase variants. CW never invents a number — an
+ *  unreported bucket stays `undefined`, never 0. */
 function normalizeReportedUsage(usage) {
     if (!usage)
         return {};
@@ -83,11 +114,15 @@ function normalizeReportedUsage(usage) {
         outputTokens: numberAt(usage, "outputTokens", "output_tokens", "completionTokens", "completion_tokens"),
         cacheReadTokens: numberAt(usage, "cacheReadTokens", "cache_read_tokens", "cacheReadInputTokens", "cache_read_input_tokens"),
         cacheWriteTokens: numberAt(usage, "cacheWriteTokens", "cache_write_tokens", "cacheCreationInputTokens", "cache_creation_input_tokens"),
-        totalTokens: numberAt(usage, "totalTokens", "total_tokens")
+        totalTokens: numberAt(usage, "totalTokens", "total_tokens"),
     };
 }
-/** Verify the agent's signed usage against the operator-provisioned public key.
- *  Pure + deterministic (no clock, no env). Returns a status, never throws. */
+/** Verify the agent's signed usage against the operator-provisioned
+ *  public key. Two-arm check (v2/PLAN.md byte-compat item 11): try the
+ *  5-field payload (with resultDigest) first; on a miss, retry the
+ *  4-field payload (old signers still verify). `coversResult` is set
+ *  ONLY on a first-arm match — a 4-field fallback match never covers the
+ *  result, even when a resultDigest sits on the record. Never throws. */
 function verifyTelemetryAttestation(usage, signatureB64, trustPublicKeyPem, ctx) {
     if (!usage || Object.keys(usage).length === 0) {
         return { status: "absent", reason: "agent reported no usage" };
@@ -100,7 +135,7 @@ function verifyTelemetryAttestation(usage, signatureB64, trustPublicKeyPem, ctx)
     }
     let publicKey;
     try {
-        publicKey = node_crypto_1.default.createPublicKey(trustPublicKeyPem);
+        publicKey = crypto.createPublicKey(trustPublicKeyPem);
     }
     catch (error) {
         return { status: "unattested", reason: `trust key unreadable: ${messageOf(error)}` };
@@ -114,18 +149,18 @@ function verifyTelemetryAttestation(usage, signatureB64, trustPublicKeyPem, ctx)
     catch {
         return { status: "unattested", reason: "signature is not valid base64" };
     }
-    const matches = (c) => node_crypto_1.default.verify(null, Buffer.from(canonicalTelemetryPayload(usage, c), "utf8"), publicKey, signature);
+    const matches = (c) => crypto.verify(null, Buffer.from(canonicalTelemetryPayload(usage, c), "utf8"), publicKey, signature);
     let ok = false;
     let coversResult = false;
     try {
         ok = matches(ctx);
-        // A match on the first arm (which carries resultDigest when CW has one) means
-        // the signature covered the result — the findings — not just the usage.
+        // A match on the first arm (which carries resultDigest when CW has
+        // one) means the signature covered the result, not just the usage.
         coversResult = ok && ctx.resultDigest !== undefined;
-        // Back-compat: a signer that predates result coverage signed only the 4-field
-        // payload, so on a miss retry WITHOUT resultDigest. A NEW signer who covered
-        // the result fails BOTH arms when the result is edited (its resultDigest no
-        // longer matches), so result tampering is still caught.
+        // Back-compat: a signer that predates result coverage signed only
+        // the 4-field payload, so on a miss retry WITHOUT resultDigest. A NEW
+        // signer who covered the result fails BOTH arms when the result is
+        // edited (its resultDigest no longer matches).
         if (!ok && ctx.resultDigest !== undefined)
             ok = matches({ ...ctx, resultDigest: undefined });
     }
@@ -136,9 +171,10 @@ function verifyTelemetryAttestation(usage, signatureB64, trustPublicKeyPem, ctx)
         ? { status: "attested", algorithm: "ed25519", ...(coversResult ? { coversResult: true } : {}) }
         : { status: "unattested", reason: "signature does not match reported usage (tampered, replayed, or wrong key)" };
 }
-/** Resolve a trust key from a config value that is EITHER an inline PEM or a path
- *  to a `.pem` file. Returns undefined when absent/unreadable (⇒ `unattested`,
- *  never a hard throw). CW only ever loads a PUBLIC key here. */
+/** Resolve a trust key from a config value that is EITHER an inline PEM
+ *  or a path to a `.pem` file. Returns undefined when absent/unreadable
+ *  (⇒ `unattested`, never a hard throw). CW only ever loads a PUBLIC key
+ *  here. */
 function resolveTrustPublicKey(value) {
     if (!value)
         return undefined;
@@ -148,7 +184,9 @@ function resolveTrustPublicKey(value) {
     if (trimmed.includes("BEGIN") && trimmed.includes("KEY"))
         return trimmed;
     try {
-        // Lazy require so a bundle that never resolves a key path pays no fs cost.
+        // Lazy require so a bundle that never resolves a key path pays no
+        // fs cost — byte-identical pattern to the old build's own lazy
+        // require here.
         const fs = require("node:fs");
         if (fs.existsSync(trimmed))
             return fs.readFileSync(trimmed, "utf8");
@@ -159,18 +197,16 @@ function resolveTrustPublicKey(value) {
     return undefined;
 }
 // ---------------------------------------------------------------------------
-// EXECUTOR-SIDE HELPER — the CW RUNTIME NEVER CALLS THIS.
-// Provided for signing wrappers around `claude -p`/endpoints and for tests. It
-// touches a private key, never a model, so it does not cross the red line; it is
-// kept here only so signer and verifier share one canonicalization.
+// EXECUTOR-SIDE HELPER — the CW RUNTIME NEVER CALLS THIS. Provided for
+// signing wrappers and tests; touches a private key, never a model.
 // ---------------------------------------------------------------------------
 function signTelemetry(usage, privateKeyPem, ctx) {
     const payload = Buffer.from(canonicalTelemetryPayload(usage, ctx), "utf8");
-    const key = node_crypto_1.default.createPrivateKey(privateKeyPem);
-    return node_crypto_1.default.sign(null, payload, key).toString("base64");
+    const key = crypto.createPrivateKey(privateKeyPem);
+    return crypto.sign(null, payload, key).toString("base64");
 }
 function stableDigest(value) {
-    return `sha256:${node_crypto_1.default.createHash("sha256").update(stableStringify(value), "utf8").digest("hex")}`;
+    return `sha256:${crypto.createHash("sha256").update(stableStringify(value), "utf8").digest("hex")}`;
 }
 function verifyTelemetrySignatures(records, trustPublicKeyPem) {
     const checks = [];
@@ -188,16 +224,11 @@ function verifyTelemetrySignatures(records, trustPublicKeyPem) {
             continue;
         }
         if (!record.reportedUsage) {
-            // A claimed-`attested` record with no re-verifiable raw usage cannot be
-            // independently checked — fail closed rather than trust the stored verdict.
             failed += 1;
             checks.push({ name: `signature[${i}]`, pass: false, code: "telemetry-usage-unavailable" });
             continue;
         }
         if (record.reportedUsageDigest !== stableDigest(record.reportedUsage)) {
-            // The raw usage is stored so a public-key verifier can re-run ed25519.
-            // The hash-chained record binds its digest; verify the two still match
-            // before trusting the raw payload for signature re-verification.
             failed += 1;
             checks.push({ name: `signature[${i}]`, pass: false, code: "telemetry-usage-digest-mismatch" });
             continue;
@@ -206,16 +237,11 @@ function verifyTelemetrySignatures(records, trustPublicKeyPem) {
             runId: record.runId,
             taskId: record.taskId,
             promptDigest: record.promptDigest,
-            // Result-bound records carry the signed digest; verifyTelemetryAttestation
-            // reconstructs the 5-field payload (and falls back to 4-field for old records).
-            resultDigest: record.resultDigest
+            resultDigest: record.resultDigest,
         });
         if (result.status === "attested") {
             reverified += 1;
             checks.push({ name: `signature[${i}]`, pass: true });
-            // Only a signature that actually COVERED the result digest anchors it — a
-            // 4-field fallback (coversResult false) must not let an injected resultDigest
-            // be trusted downstream.
             if (result.coversResult && record.resultDigest) {
                 resultBound.push({ taskId: record.taskId, resultDigest: record.resultDigest });
             }
@@ -227,7 +253,7 @@ function verifyTelemetrySignatures(records, trustPublicKeyPem) {
                 pass: false,
                 code: result.reason && result.reason.startsWith("trust key unreadable")
                     ? "telemetry-pubkey-unreadable"
-                    : "telemetry-signature-mismatch"
+                    : "telemetry-signature-mismatch",
             });
         }
     }

package/dist/core/trust/telemetry-ledger.js

@@ -0,0 +1,127 @@
+"use strict";
+// core/trust/telemetry-ledger.ts — the hash-chained telemetry
+// attestation ledger's PURE half: genesisPrevHash, computeRecordHash,
+// reportedUsageDigest, verifyTelemetryLedger. Directory/file IO
+// (telemetryLedgerPath, loadTelemetryLedger, appendTelemetryAttestation)
+// lives in shell/telemetry-ledger-io.ts.
+//
+// MILESTONE 8. Byte-exact port of the old build's src/telemetry-ledger.ts
+// verify-side logic. Uses core/hash.ts's `sha256`/`telemetryStableStringify`
+// (see v2/PLAN.md byte-compat item 2's key-omission-vs-null rule).
+//
+// Evidence: SPEC/ledger-trust.md "Telemetry ledger record", byte-compat
+// items 2 and 12; plugins/cool-workflow/src/telemetry-ledger.ts:1-224.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryLedgerCorruptError = exports.TELEMETRY_LEDGER_SCHEMA_VERSION = void 0;
+exports.genesisPrevHash = genesisPrevHash;
+exports.computeRecordHash = computeRecordHash;
+exports.reportedUsageDigest = reportedUsageDigest;
+exports.recordId = recordId;
+exports.verifyTelemetryLedgerRecords = verifyTelemetryLedgerRecords;
+exports.corruptTelemetryLedgerVerification = corruptTelemetryLedgerVerification;
+const hash_1 = require("../hash");
+exports.TELEMETRY_LEDGER_SCHEMA_VERSION = 1;
+/** 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;
+/** genesis prevHash for a run's chain (no prior record). */
+function genesisPrevHash(runId) {
+    return (0, hash_1.sha256)(`cw-telemetry-ledger:${runId}`);
+}
+/** The canonical bytes a recordHash binds — every field except
+ *  recordHash itself. `reportedUsage`/`resultDigest` are OMITTED (not
+ *  `null`) when absent, so a usage-only record's hash is byte-identical
+ *  to a pre-result-coverage one (back-compat with old ledgers) — see
+ *  v2/PLAN.md byte-compat item 2. */
+function recordHashInput(record) {
+    return (0, hash_1.telemetryStableStringify)({
+        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,
+        ...(record.resultDigest !== undefined ? { resultDigest: record.resultDigest } : {}),
+        attestation: record.attestation,
+        attestationReason: record.attestationReason || null,
+        prevHash: record.prevHash,
+    });
+}
+function computeRecordHash(record) {
+    return (0, hash_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, hash_1.sha256)((0, hash_1.telemetryStableStringify)(usage ?? null));
+}
+/** Deterministic (chain POSITION, not a process-global counter or
+ *  wall-clock stamp): `tel-` + chain position, zero-padded to 3. */
+function recordId(seq) {
+    return `tel-${String(seq).padStart(3, "0")}`;
+}
+/** Re-prove the whole telemetry chain for a run: prevHash linkage +
+ *  per-record hash recompute. Recomputes every hash independently —
+ *  never trusts the stored value. An empty ledger verifies as
+ *  present:false (nothing to prove), NOT a failure. Pure: takes the
+ *  already-loaded record array plus the run id, never touches disk. */
+function verifyTelemetryLedgerRecords(runId, 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.
+    let chainOk = true;
+    for (let i = 0; i < records.length; i++) {
+        const expectedPrev = i === 0 ? genesisPrevHash(runId) : 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 };
+}
+/** The corrupt-ledger verification shape (present:true, verified:false,
+ *  one `ledger-load`/`telemetry-ledger-corrupt` failed check). Shared
+ *  constant so both the CLI-facing shell reader and any pure caller
+ *  report the exact same shape for a corrupt file. */
+function corruptTelemetryLedgerVerification() {
+    return {
+        present: true,
+        verified: false,
+        records: [],
+        checks: [{ name: "ledger-load", pass: false, code: "telemetry-ledger-corrupt" }],
+        attested: 0,
+        unattested: 0,
+        absent: 0,
+    };
+}

package/dist/core/types.js

@@ -0,0 +1,20 @@
+"use strict";
+// src/core/types.ts — barrel for cross-cutting pure type modules under
+// src/core/types/. Mirrors the src/cli.ts + src/cli/ convention: a thin
+// top-level file next to the directory it fronts.
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/boundary"), exports);

package/dist/core/version.js

@@ -0,0 +1,16 @@
+"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;
+// core/version.ts — the one version string `cw version` prints.
+//
+// Pure. POLA: keep the exact same version marker the old build reports, so
+// `cw version` output does not change bytes just because the code under it
+// was rebuilt. See SPEC/cli-surface.md "Exact outputs > Version" and
+// conformance/cases/version-basic.case.js (regex `/^\d+\.\d+\.\d+\n$/`).
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.2.0";
+// State-kernel schema version constants (SPEC/state-core.md "Version
+// constants"). Pinned to the old build's src/version.ts byte-for-byte.
+exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
+exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
+exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;
+exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = 0;