patchwork-os 1.2.0-beta.2.canary.745 → 1.2.0-beta.2.canary.747

package/dist/evidenceCoverage.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `patchwork evidence` — how much of the evidence spine can actually be joined?
+ *
+ * CLAUDE.md's Evidence Spine section tells the next session to re-measure this
+ * before scoping a cross-ledger reader, and says why in its own words: two of
+ * its load-bearing claims "went stale or were wrong within two days". Doing that
+ * measurement took a bespoke throwaway script every time. This makes it a verb.
+ *
+ * ## It reports denominators. It is NOT the reader.
+ *
+ * The spine's rule is "do NOT build the readers ahead of the evidence" — a
+ * cross-ledger graph built now would be a view over data that does not exist,
+ * and the shape of the view would then dictate the shape of the evidence,
+ * backwards. So this answers the question that comes FIRST: how many rows carry
+ * a correlation id at all, and how many runs appear in more than one ledger.
+ * Measured 2026-08-26 on the reference machine, the answer was ZERO runs in
+ * both — which is the fact that keeps the reader unbuilt.
+ *
+ * ## Absent is not zero
+ *
+ * A ledger that does not exist is reported ABSENT, never as `0 rows`. They are
+ * different facts: `butler/permission_exercises.jsonl` is absent because no
+ * standing permission has ever been granted, and that absence is CORRECT rather
+ * than a gap to plumb. Rendering it as a zero row would invite someone to go and
+ * "fix" it.
+ *
+ * ## Counts only, never contents
+ *
+ * These ledgers hold real task titles, captured output tails and third-party
+ * record ids, and a correlation id IS a run's `taskId`. So nothing here prints a
+ * row, an id, or any value — only counts and the file name. The house rule is
+ * that a measurement may leave the machine and the rows may not.
+ */
+/** Ledgers on the spine, with where each lives relative to `$PATCHWORK_HOME`. */
+export declare const SPINE_LEDGERS: ReadonlyArray<{
+    key: string;
+    file: string;
+}>;
+export interface LedgerCoverage {
+    key: string;
+    file: string;
+    /** True when the file does not exist. Distinct from `rows === 0`. */
+    absent: boolean;
+    rows: number;
+    /** Rows carrying a `correlationId` — the joinable population. */
+    joinable: number;
+    /** Distinct correlation ids, i.e. how many runs this ledger can speak about. */
+    distinctRuns: number;
+    /** Lines that would not parse. Reported, never silently skipped. */
+    corrupt: number;
+}
+export interface PairCoverage {
+    a: string;
+    b: string;
+    shared: number;
+}
+export interface EvidenceCoverage {
+    dir: string;
+    ledgers: LedgerCoverage[];
+    /** Only pairs where BOTH sides have at least one joinable row. */
+    pairs: PairCoverage[];
+    /** Runs reachable in more than one ledger — what a reader could traverse. */
+    runsInMoreThanOneLedger: number;
+}
+export declare function evidenceCoverage(dir?: string): EvidenceCoverage;
+export declare function formatEvidenceCoverage(c: EvidenceCoverage): string;

package/dist/evidenceCoverage.js

@@ -0,0 +1,188 @@
+/**
+ * `patchwork evidence` — how much of the evidence spine can actually be joined?
+ *
+ * CLAUDE.md's Evidence Spine section tells the next session to re-measure this
+ * before scoping a cross-ledger reader, and says why in its own words: two of
+ * its load-bearing claims "went stale or were wrong within two days". Doing that
+ * measurement took a bespoke throwaway script every time. This makes it a verb.
+ *
+ * ## It reports denominators. It is NOT the reader.
+ *
+ * The spine's rule is "do NOT build the readers ahead of the evidence" — a
+ * cross-ledger graph built now would be a view over data that does not exist,
+ * and the shape of the view would then dictate the shape of the evidence,
+ * backwards. So this answers the question that comes FIRST: how many rows carry
+ * a correlation id at all, and how many runs appear in more than one ledger.
+ * Measured 2026-08-26 on the reference machine, the answer was ZERO runs in
+ * both — which is the fact that keeps the reader unbuilt.
+ *
+ * ## Absent is not zero
+ *
+ * A ledger that does not exist is reported ABSENT, never as `0 rows`. They are
+ * different facts: `butler/permission_exercises.jsonl` is absent because no
+ * standing permission has ever been granted, and that absence is CORRECT rather
+ * than a gap to plumb. Rendering it as a zero row would invite someone to go and
+ * "fix" it.
+ *
+ * ## Counts only, never contents
+ *
+ * These ledgers hold real task titles, captured output tails and third-party
+ * record ids, and a correlation id IS a run's `taskId`. So nothing here prints a
+ * row, an id, or any value — only counts and the file name. The house rule is
+ * that a measurement may leave the machine and the rows may not.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { patchworkHome } from "./patchworkHome.js";
+/** Ledgers on the spine, with where each lives relative to `$PATCHWORK_HOME`. */
+export const SPINE_LEDGERS = [
+    { key: "gate decisions", file: "worker_gate_decisions.jsonl" },
+    { key: "boundary receipts", file: "boundary_receipts.jsonl" },
+    { key: "privacy shadow", file: "privacy_shadow.jsonl" },
+    { key: "outcomes", file: "outcome-log.jsonl" },
+    { key: "approvals", file: "approval_log.jsonl" },
+    { key: "permission exercises", file: "butler/permission_exercises.jsonl" },
+];
+function scan(dir, key, file) {
+    const full = path.join(dir, file);
+    if (!existsSync(full)) {
+        return {
+            cov: {
+                key,
+                file,
+                absent: true,
+                rows: 0,
+                joinable: 0,
+                distinctRuns: 0,
+                corrupt: 0,
+            },
+            ids: new Set(),
+        };
+    }
+    let text = "";
+    try {
+        text = readFileSync(full, "utf-8");
+    }
+    catch {
+        // Unreadable is not absent — say so by reporting it as present with a
+        // corrupt count rather than pretending the file is not there.
+        return {
+            cov: {
+                key,
+                file,
+                absent: false,
+                rows: 0,
+                joinable: 0,
+                distinctRuns: 0,
+                corrupt: 1,
+            },
+            ids: new Set(),
+        };
+    }
+    const ids = new Set();
+    let rows = 0;
+    let joinable = 0;
+    let corrupt = 0;
+    for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(t);
+        }
+        catch {
+            corrupt++;
+            continue;
+        }
+        rows++;
+        const c = parsed.correlationId;
+        if (typeof c === "string" && c !== "") {
+            joinable++;
+            ids.add(c);
+        }
+    }
+    return {
+        cov: {
+            key,
+            file,
+            absent: false,
+            rows,
+            joinable,
+            distinctRuns: ids.size,
+            corrupt,
+        },
+        ids,
+    };
+}
+export function evidenceCoverage(dir = patchworkHome()) {
+    const ledgers = [];
+    const idsByKey = new Map();
+    for (const { key, file } of SPINE_LEDGERS) {
+        const { cov, ids } = scan(dir, key, file);
+        ledgers.push(cov);
+        idsByKey.set(key, ids);
+    }
+    const pairs = [];
+    const withIds = [...idsByKey.entries()].filter(([, s]) => s.size > 0);
+    for (let i = 0; i < withIds.length; i++) {
+        for (let j = i + 1; j < withIds.length; j++) {
+            const [a, sa] = withIds[i];
+            const [b, sb] = withIds[j];
+            let shared = 0;
+            for (const id of sa)
+                if (sb.has(id))
+                    shared++;
+            pairs.push({ a, b, shared });
+        }
+    }
+    const seen = new Map();
+    for (const [, s] of idsByKey) {
+        for (const id of s)
+            seen.set(id, (seen.get(id) ?? 0) + 1);
+    }
+    let runsInMoreThanOneLedger = 0;
+    for (const [, n] of seen)
+        if (n > 1)
+            runsInMoreThanOneLedger++;
+    return { dir, ledgers, pairs, runsInMoreThanOneLedger };
+}
+export function formatEvidenceCoverage(c) {
+    const L = [];
+    L.push("[evidence] how much of the spine can be joined?");
+    L.push(`  ${c.dir}`);
+    L.push("");
+    for (const l of c.ledgers) {
+        if (l.absent) {
+            // Absence can be the CORRECT state — no standing permission has ever been
+            // granted, so its ledger not existing is not a gap to plumb.
+            L.push(`  ABSENT   ${l.file}`);
+            continue;
+        }
+        // Always the denominator first: "14 joinable" reads as coverage,
+        // "14 of 170" is the fact.
+        L.push(`  ${String(l.joinable).padStart(5)} of ${String(l.rows).padEnd(6)} rows carry a run id` +
+            `  (${l.distinctRuns} distinct run${l.distinctRuns === 1 ? "" : "s"})  ${l.file}` +
+            (l.corrupt > 0 ? `  [${l.corrupt} unparseable]` : ""));
+    }
+    L.push("");
+    if (c.pairs.length === 0) {
+        L.push("  No two ledgers both carry run ids yet, so nothing can be joined.");
+    }
+    else {
+        L.push("  Runs shared between ledgers:");
+        for (const p of c.pairs) {
+            L.push(`    ${p.shared}  ${p.a} ↔ ${p.b}`);
+        }
+    }
+    L.push("");
+    L.push(`  A cross-ledger reader could traverse ${c.runsInMoreThanOneLedger} run(s) today.`);
+    if (c.runsInMoreThanOneLedger === 0) {
+        L.push("  That is the number that keeps the evidence graph unbuilt — a reader now");
+        L.push("  would be a view over data that does not exist, and its shape would then");
+        L.push("  dictate the shape of the evidence rather than the other way round.");
+    }
+    L.push("");
+    return `${L.join("\n")}\n`;
+}
+//# sourceMappingURL=evidenceCoverage.js.map

package/dist/evidenceCoverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidenceCoverage.js","sourceRoot":"","sources":["../src/evidenceCoverage.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -180,6 +180,7 @@ async function downloadVsixFromOpenVsx() {
 // same list is also used by the unknown-command suggester at L2570.
 const KNOWN_SUBCOMMANDS = [
     "init",
+    "evidence",
     "patchwork-init",
     "start-all",
     "install-extension",
@@ -4000,12 +4001,32 @@ Options:
     process.exit(0);
 }
 // `patchwork doctor` — run CLI-safe bridge health checks.
-if (process.argv[2] === "doctor") {
-    const args = process.argv.slice(3);
+// `doctor health` — the config-sanity checks.
+//
+// These lived on a SECOND top-level `argv[2] === "doctor"` block that could
+// never produce output: the deployment-freshness block below also matched, and
+// won every time. `runDoctor` had one production caller and it was unreachable,
+// while its tests passed because they call it directly with a mocked
+// `runBridgeHealthChecks` — logic proven, wiring never exercised. `--help`
+// printed THIS block's text, so the documented behaviour of `patchwork doctor`
+// described checks that did not run and omitted `--expect-running`, the flag
+// that does.
+//
+// Given a subcommand rather than folded into `doctor`: that verb's exit code is
+// load-bearing (it is run straight after a kickstart, and `patchwork doctor &&
+// echo deployed` is a real shape), so making a failing config check newly able
+// to fail it would change a contract people already depend on.
+if (process.argv[2] === "doctor" && process.argv[3] === "health") {
+    const args = process.argv.slice(4);
     if (args.includes("--help") || args.includes("-h")) {
-        process.stdout.write("Usage: patchwork doctor [--workspace <path>] [--port <n>] [--json]\n\n" +
-            "Runs bridge health checks (workspace, git, lock file, automation policy).\n" +
-            "Exits 1 if any check fails.\n");
+        process.stdout.write("Usage: patchwork doctor health [--workspace <path>] [--port <n>] [--json]\n\n" +
+            "Bridge config health: workspace, git binary, lock file, automation policy.\n" +
+            "Exits 1 if any check fails.\n\n" +
+            "  --port <n>   check the lock of a RUNNING bridge. Without it the lock check\n" +
+            "               looks for one belonging to THIS process, which is a CLI and\n" +
+            "               never a bridge, so it warns. That warning means 'you did not\n" +
+            "               say which bridge', not 'your bridge is broken'.\n\n" +
+            "For 'is the running code the installed code?', use `patchwork doctor`.\n");
         process.exit(0);
     }
     (async () => {
@@ -4125,6 +4146,48 @@ if (process.argv[2] === "shadow-scan") {
         }
     })();
 }
+// `patchwork evidence` — how much of the evidence spine can be joined?
+//
+// CLAUDE.md tells the next session to re-measure this before scoping a
+// cross-ledger reader, and records that its own figures went stale within two
+// days. That measurement was a bespoke throwaway script every time.
+//
+// Reports DENOMINATORS. It is not the reader, and building the reader is
+// exactly what the spine's own rule defers until there is evidence to read.
+if (process.argv[2] === "evidence") {
+    const args = process.argv.slice(3);
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write("Usage: patchwork evidence [--dir <path>] [--json]\n\n" +
+            "How much of the evidence spine can actually be joined: per ledger, how many\n" +
+            "rows carry a run id (correlationId) out of how many rows, and how many runs\n" +
+            "appear in more than one ledger.\n\n" +
+            "Read-only. Prints COUNTS ONLY — never a row, an id or any value, because a\n" +
+            "correlationId is a run's taskId and these ledgers hold real task titles and\n" +
+            "third-party record ids. A measurement may leave the machine; the rows may not.\n\n" +
+            "  --dir <path>  ledger directory (default: $PATCHWORK_HOME)\n" +
+            "  --json        emit the raw report\n");
+        process.exit(0);
+    }
+    (async () => {
+        try {
+            const dirIdx = args.indexOf("--dir");
+            const dir = dirIdx !== -1 ? args[dirIdx + 1] : undefined;
+            const { evidenceCoverage, formatEvidenceCoverage } = await import("./evidenceCoverage.js");
+            const report = dir ? evidenceCoverage(dir) : evidenceCoverage();
+            process.stdout.write(args.includes("--json")
+                ? `${JSON.stringify(report, null, 2)}\n`
+                : formatEvidenceCoverage(report));
+            // Always 0: this is a REPORT, not a gate. Zero joinable rows is a true
+            // and expected state early on, and exiting non-zero for it would make a
+            // correct answer look like a failure.
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
 // Handle workers subcommand — read-only worker trust-dial (shadow). Replays the
 // recipe run log + gate decision log through the (worker × action-class) ramp
 // and prints the dial + a "ramp would vs gate did" comparison. Changes nothing.
@@ -4463,12 +4526,30 @@ if (process.argv[2] === "members") {
 // installed? Every check in this repo verifies the repository. On 2026-08-19
 // both live bridges were found running neither the privacy code nor `butler`,
 // merged and wired and green throughout.
-if (process.argv[2] === "doctor") {
+if (process.argv[2] === "doctor" && process.argv[3] !== "health") {
     const args = process.argv.slice(3);
+    if (args.includes("--help") || args.includes("-h")) {
+        // Previously this block had no --help of its own, so the OTHER doctor
+        // answered it and described the wrong command.
+        process.stdout.write("Usage: patchwork doctor [--expect-running [N]] [--json]\n\n" +
+            "Is the running code the installed code? Compares each bridge lock's\n" +
+            "startedAt against the installed build's mtime. Deliberately NOT a version\n" +
+            "comparison: a stale process and a fresh one report the same version,\n" +
+            "because a version marks a release and not a build.\n\n" +
+            "  --expect-running [N]  require at least N live bridges (bare = 1). Absent,\n" +
+            "                        ZERO bridges is HEALTHY — 'nothing is running' is\n" +
+            "                        legitimate, and a check whose denominator is the\n" +
+            "                        locks it found cannot see one that is absent.\n" +
+            "  --json                emit the raw report\n\n" +
+            "For workspace / git / lock-file / automation-policy checks, use\n" +
+            "`patchwork doctor health`.\n");
+        process.exit(0);
+    }
     (async () => {
         const { readdirSync, readFileSync, statSync } = await import("node:fs");
         const { join } = await import("node:path");
         const os = await import("node:os");
+        const { fileURLToPath } = await import("node:url");
         const { assessDeploymentFreshness, formatFreshness } = await import("./deploymentFreshness.js");
         // The installed build we are comparing against. Falls back to this
         // process's own dist when the global package is absent (running from a
@@ -4476,7 +4557,13 @@ if (process.argv[2] === "doctor") {
         let buildTimeMs;
         for (const candidate of [
             join(process.env.npm_config_prefix ?? "/opt/homebrew", "lib/node_modules/patchwork-os/dist/index.js"),
-            new URL("./index.js", import.meta.url).pathname,
+            // `fileURLToPath`, NOT `.pathname`. On Windows a file URL's pathname is
+            // `/D:/a/...` — a leading slash before the drive letter — which statSync
+            // cannot open, so this fallback never resolved there and `patchwork
+            // doctor` from a checkout always exited 2 with "could not locate an
+            // installed build". Found by the dispatch test added alongside this, on
+            // the Windows CI cells only.
+            fileURLToPath(new URL("./index.js", import.meta.url)),
         ]) {
             try {
                 buildTimeMs = statSync(candidate).mtimeMs;