patchwork-os 1.2.0-beta.2.canary.646 → 1.2.0-beta.2.canary.648

package/dist/butler/errandOutcomeGrader.d.ts

@@ -66,6 +66,27 @@ export interface ObservedErrandArtifact {
     deleted?: boolean;
     /** When the errand created the artifact. */
     createdAt?: number;
+    /**
+     * Was the artifact's CURRENT state actually looked up?
+     *
+     * This exists because `stale-unactioned → junk` is only sound when a
+     * completion COULD have been seen. The rule converts silence into a
+     * negative, and silence is only evidence if somebody was listening.
+     *
+     * An ingester that derives artifacts from the local run log knows when each
+     * one was created and nothing whatever about what the operator later did
+     * with it. Feeding those to the grader without this flag would mark every
+     * errand older than the horizon `junk` — not because the operator ignored
+     * it, but because nobody ever asked. That is the trust-by-neglect defect
+     * (#1064, #1318/#1319, #1320, #1322) with its sign flipped: instead of
+     * flattering a worker for unexamined actions it slanders one, which is
+     * worse, because the worker cannot appeal a verdict nobody looked at.
+     *
+     * Absent or false ⇒ the staleness branch is skipped entirely and the result
+     * is `unknown` / `not-observed`. Only an observation channel that could
+     * have reported `completed: true` may set this.
+     */
+    stateObserved?: boolean;
 }
 export interface GradeOptions {
     /** Clock. Injected so grading is reproducible in replay. */

package/dist/butler/errandOutcomeGrader.js

@@ -69,6 +69,12 @@ export function gradeErrandOutcome(observed, opts) {
         // silence has become meaningful. Withhold.
         return { disposition: "unknown", reason: "not-observed" };
     }
+    if (observed.stateObserved !== true) {
+        // We know when it was created but never checked what became of it. Age
+        // alone cannot distinguish "the operator ignored it" from "nobody looked",
+        // and only the first is evidence. See `stateObserved`.
+        return { disposition: "unknown", reason: "not-observed" };
+    }
     const staleAfter = opts.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
     const age = opts.now - observed.createdAt;
     if (age >= staleAfter) {

package/dist/butler/errandOutcomeGrader.js.map

@@ -1 +1 @@
-{"version":3,"file":"errandOutcomeGrader.js","sourceRoot":"","sources":["../../src/butler/errandOutcomeGrader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,0CAA0C;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AA+C/D;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgC,EAChC,IAAkB;IAElB,yEAAyE;IACzE,6EAA6E;IAC7E,6EAA6E;IAC7E,yCAAyC;IACzC,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC3D,CAAC;IAED,yEAAyE;IACzE,mCAAmC;IACnC,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrC,2EAA2E;QAC3E,2CAA2C;QAC3C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,IAAI,sBAAsB,CAAC;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC;IAC1C,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;QACtB,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"errandOutcomeGrader.js","sourceRoot":"","sources":["../../src/butler/errandOutcomeGrader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,0CAA0C;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAoE/D;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgC,EAChC,IAAkB;IAElB,yEAAyE;IACzE,6EAA6E;IAC7E,6EAA6E;IAC7E,yCAAyC;IACzC,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC3D,CAAC;IAED,yEAAyE;IACzE,mCAAmC;IACnC,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrC,2EAA2E;QAC3E,2CAA2C;QAC3C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAC5D,CAAC;IAED,IAAI,QAAQ,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;QACpC,uEAAuE;QACvE,2EAA2E;QAC3E,uDAAuD;QACvD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,IAAI,sBAAsB,CAAC;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC;IAC1C,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;QACtB,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AAC3D,CAAC"}

package/dist/butler/outcomeIngester.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Butler errand outcome ingester — grade a batch of observations into the
+ * SHADOW ledger, and nothing else.
+ *
+ * ## What this is for
+ *
+ * `errandOutcomeGrader.ts` is a pure function and `outcomeShadowLog.ts` is an
+ * append-only file. Between them there was nothing: the grader was merged
+ * unwired, so no row had ever been written and the measurement the shadow
+ * phase exists to produce did not exist. This is the missing middle.
+ *
+ * ## Where it may be called from, and where it may not
+ *
+ * Operator paths ONLY — the Bearer-authenticated HTTP route and the CLI, the
+ * same shape as `outcomes confirm`. It is deliberately NOT registered in the
+ * recipe tool registry, and there is a test asserting that.
+ *
+ * The reason is the one that makes `outcomes confirm` a CLI verb rather than a
+ * recipe step: a worker must not be able to grade its own filings. A recipe
+ * step runs as the worker. If grading were reachable from one, a worker whose
+ * errands nobody ever looks at could emit `completed: true` for each of them
+ * and manufacture the evidence that raises its own trust dial. That is not a
+ * hypothetical class of bug in this subsystem — it is the same defect as
+ * #1064, #1318/#1319, #1320 and #1322, which is four times.
+ *
+ * ## No model in the loop
+ *
+ * Every disposition here comes from `gradeErrandOutcome`, a pure function of
+ * observed state and two timestamps. A prior LLM judge in this repo flipped
+ * verdicts between runs on identical inputs; a trust ledger you cannot replay
+ * is not evidence, it is an opinion with a timestamp.
+ *
+ * ## It cannot promote
+ *
+ * This module imports `appendShadowOutcome` and does not import `OutcomeStore`
+ * at all, so there is no code path from here into `outcome-log.jsonl`. That is
+ * structural, not a convention — promotion needs a measured before/after on
+ * the real log, exactly as #1319 required, and until somebody has READ these
+ * rows the grader has not earned the right to be evidence.
+ */
+import { type GradeOptions, type ObservedErrandArtifact } from "./errandOutcomeGrader.js";
+import { type ShadowSummary } from "./outcomeShadowLog.js";
+/** One artifact to grade, plus the key it joins on. */
+export interface ErrandObservation extends ObservedErrandArtifact {
+    /**
+     * `canonicalActionRef` form (`"<tool>:<id>"`, or a URL for legacy rows).
+     *
+     * Required. A graded row under a key the fold could not resolve is a
+     * measurement of nothing — it would sit in the shadow ledger inflating the
+     * counts somebody reads before deciding to promote.
+     */
+    ref: string;
+    /** The recipe that filed it, for attribution during review. */
+    recipe?: string;
+}
+export interface IngestResult {
+    /** Observations accepted and written. */
+    graded: number;
+    /** Rejected before grading, with why. Never silently dropped. */
+    skipped: {
+        ref?: string;
+        reason: "missing-ref" | "duplicate-ref";
+    }[];
+    /** Per-disposition counts for THIS batch (not the whole ledger). */
+    batch: {
+        confirmed: number;
+        junk: number;
+        unknown: number;
+    };
+    /** The whole ledger after the write — what a reviewer actually acts on. */
+    ledger: ShadowSummary;
+}
+export interface IngestOptions extends GradeOptions {
+    /** Shadow-ledger directory override. Tests pass a temp dir. */
+    dir?: string;
+}
+/**
+ * Grade every observation and append a shadow row per accepted one.
+ *
+ * Duplicate refs within a batch are skipped rather than written twice: the
+ * ledger is append-only and the summary counts rows, so a batch that repeated
+ * a ref would overstate the evidence available. Duplicates ACROSS batches are
+ * deliberately not deduped — successive observations of the same artifact over
+ * time are the point, and collapsing them would erase the history that shows
+ * an errand going from open to completed.
+ */
+export declare function ingestErrandOutcomes(observations: readonly ErrandObservation[], opts: IngestOptions): IngestResult;
+/**
+ * Render the ledger for a human — the "READ the shadow rows" half.
+ *
+ * States the promotion bar in the output rather than in a doc nobody opens
+ * next to the number, because the number's whole purpose is to be weighed
+ * against it.
+ */
+export declare function formatShadowSummary(s: ShadowSummary): string;

package/dist/butler/outcomeIngester.js

@@ -0,0 +1,117 @@
+/**
+ * Butler errand outcome ingester — grade a batch of observations into the
+ * SHADOW ledger, and nothing else.
+ *
+ * ## What this is for
+ *
+ * `errandOutcomeGrader.ts` is a pure function and `outcomeShadowLog.ts` is an
+ * append-only file. Between them there was nothing: the grader was merged
+ * unwired, so no row had ever been written and the measurement the shadow
+ * phase exists to produce did not exist. This is the missing middle.
+ *
+ * ## Where it may be called from, and where it may not
+ *
+ * Operator paths ONLY — the Bearer-authenticated HTTP route and the CLI, the
+ * same shape as `outcomes confirm`. It is deliberately NOT registered in the
+ * recipe tool registry, and there is a test asserting that.
+ *
+ * The reason is the one that makes `outcomes confirm` a CLI verb rather than a
+ * recipe step: a worker must not be able to grade its own filings. A recipe
+ * step runs as the worker. If grading were reachable from one, a worker whose
+ * errands nobody ever looks at could emit `completed: true` for each of them
+ * and manufacture the evidence that raises its own trust dial. That is not a
+ * hypothetical class of bug in this subsystem — it is the same defect as
+ * #1064, #1318/#1319, #1320 and #1322, which is four times.
+ *
+ * ## No model in the loop
+ *
+ * Every disposition here comes from `gradeErrandOutcome`, a pure function of
+ * observed state and two timestamps. A prior LLM judge in this repo flipped
+ * verdicts between runs on identical inputs; a trust ledger you cannot replay
+ * is not evidence, it is an opinion with a timestamp.
+ *
+ * ## It cannot promote
+ *
+ * This module imports `appendShadowOutcome` and does not import `OutcomeStore`
+ * at all, so there is no code path from here into `outcome-log.jsonl`. That is
+ * structural, not a convention — promotion needs a measured before/after on
+ * the real log, exactly as #1319 required, and until somebody has READ these
+ * rows the grader has not earned the right to be evidence.
+ */
+import { gradeErrandOutcome, } from "./errandOutcomeGrader.js";
+import { appendShadowOutcome, summariseShadowLog, } from "./outcomeShadowLog.js";
+/**
+ * Grade every observation and append a shadow row per accepted one.
+ *
+ * Duplicate refs within a batch are skipped rather than written twice: the
+ * ledger is append-only and the summary counts rows, so a batch that repeated
+ * a ref would overstate the evidence available. Duplicates ACROSS batches are
+ * deliberately not deduped — successive observations of the same artifact over
+ * time are the point, and collapsing them would erase the history that shows
+ * an errand going from open to completed.
+ */
+export function ingestErrandOutcomes(observations, opts) {
+    const skipped = [];
+    const batch = { confirmed: 0, junk: 0, unknown: 0 };
+    const seen = new Set();
+    let graded = 0;
+    for (const obs of observations) {
+        const ref = typeof obs.ref === "string" ? obs.ref.trim() : "";
+        if (!ref) {
+            skipped.push({ reason: "missing-ref" });
+            continue;
+        }
+        if (seen.has(ref)) {
+            skipped.push({ ref, reason: "duplicate-ref" });
+            continue;
+        }
+        seen.add(ref);
+        const { disposition, reason } = gradeErrandOutcome(obs, opts);
+        appendShadowOutcome({
+            ref,
+            disposition,
+            reason,
+            gradedAt: opts.now,
+            ...(obs.recipe ? { recipe: obs.recipe } : {}),
+        }, { dir: opts.dir });
+        batch[disposition]++;
+        graded++;
+    }
+    return {
+        graded,
+        skipped,
+        batch,
+        ledger: summariseShadowLog({ dir: opts.dir }),
+    };
+}
+/**
+ * Render the ledger for a human — the "READ the shadow rows" half.
+ *
+ * States the promotion bar in the output rather than in a doc nobody opens
+ * next to the number, because the number's whole purpose is to be weighed
+ * against it.
+ */
+export function formatShadowSummary(s) {
+    if (s.total === 0) {
+        return [
+            "[butler-shadow] no graded rows yet.",
+            "",
+            "  Nothing has been measured, so nothing may be promoted. Run the",
+            "  ingester against real errand observations first.",
+        ].join("\n");
+    }
+    const pct = (n) => `${((n / s.total) * 100).toFixed(1)}%`;
+    return [
+        `[butler-shadow] ${s.total} graded row(s):`,
+        `  confirmed  ${s.confirmed} (${pct(s.confirmed)})`,
+        `  junk       ${s.junk} (${pct(s.junk)})`,
+        `  unknown    ${s.unknown} (${pct(s.unknown)}) — withheld by the fold`,
+        "",
+        `  ${s.wouldCount} row(s) (${pct(s.wouldCount)}) would have become evidence.`,
+        "",
+        "  These rows moved nothing. Before promoting, check a sample against the",
+        "  real errands they describe — a disposition that reads plausibly in",
+        "  aggregate can still be wrong on every individual row.",
+    ].join("\n");
+}
+//# sourceMappingURL=outcomeIngester.js.map

package/dist/butler/outcomeIngester.js.map

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

package/dist/index.js

@@ -215,6 +215,7 @@ const KNOWN_SUBCOMMANDS = [
     "approvals",
     "gate",
     "outcomes",
+    "butler",
     // Dispatched at `process.argv[2] === "tools"` (and `help`) but absent from
     // this array until 2026-08. The comment below calls this "the dispatch
     // source", and it was not: `patchwork tool` could never be corrected to
@@ -4230,6 +4231,88 @@ if (process.argv[2] === "gate") {
         }
     })();
 }
+// Handle butler subcommand — SHADOW-only errand outcome grading.
+//
+// Operator path, like `outcomes` above and for the same reason: a recipe step
+// runs AS the worker, so grading reachable from one would let a worker
+// manufacture the evidence that raises its own trust dial. Nothing here writes
+// the trust ledger — rows go to the Butler shadow ledger and move nothing.
+if (process.argv[2] === "butler") {
+    const args = process.argv.slice(3);
+    (async () => {
+        try {
+            const { formatShadowSummary, ingestErrandOutcomes } = await import("./butler/outcomeIngester.js");
+            const { summariseShadowLog } = await import("./butler/outcomeShadowLog.js");
+            if (args[0] === "shadow") {
+                const summary = summariseShadowLog();
+                if (args.includes("--json")) {
+                    process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(`${formatShadowSummary(summary)}\n`);
+                }
+                process.exit(0);
+            }
+            if (args[0] === "ingest") {
+                // Observations come from a file or stdin as a JSON array. They are NOT
+                // gathered here: reading the operator's trackers is a connector
+                // concern, and inventing an observation the ingester did not actually
+                // make is precisely what `stateObserved` exists to prevent.
+                const fileIdx = args.indexOf("--file");
+                const src = fileIdx !== -1 && args[fileIdx + 1] ? args[fileIdx + 1] : "-";
+                const { readFileSync } = await import("node:fs");
+                const raw = src === "-"
+                    ? readFileSync(0, "utf-8")
+                    : readFileSync(src, "utf-8");
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch (err) {
+                    process.stderr.write(`[butler] observations are not valid JSON: ${err.message}\n`);
+                    process.exit(2);
+                }
+                if (!Array.isArray(parsed)) {
+                    process.stderr.write("[butler] expected a JSON array\n");
+                    process.exit(2);
+                }
+                const daysIdx = args.indexOf("--stale-after-days");
+                const days = daysIdx !== -1 && args[daysIdx + 1]
+                    ? Number(args[daysIdx + 1])
+                    : undefined;
+                const res = ingestErrandOutcomes(parsed, {
+                    now: Date.now(),
+                    ...(days !== undefined && Number.isFinite(days)
+                        ? { staleAfterMs: days * 24 * 60 * 60 * 1000 }
+                        : {}),
+                });
+                if (args.includes("--json")) {
+                    process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(`[butler] graded ${res.graded} observation(s): ` +
+                        `${res.batch.confirmed} confirmed, ${res.batch.junk} junk, ` +
+                        `${res.batch.unknown} unknown.\n`);
+                    for (const s of res.skipped) {
+                        process.stdout.write(`[butler]   skipped ${s.ref ?? "(no ref)"}: ${s.reason}\n`);
+                    }
+                    process.stdout.write(`\n${formatShadowSummary(res.ledger)}\n`);
+                }
+                process.exit(0);
+            }
+            process.stderr.write("Usage: patchwork butler <shadow|ingest> [--json]\n\n" +
+                "  shadow                       summarise the graded shadow ledger\n" +
+                "  ingest [--file <path>|-]     grade a JSON array of observations\n" +
+                "         [--stale-after-days N]\n\n" +
+                "  Shadow-only: nothing here writes the trust ledger.\n");
+            process.exit(2);
+        }
+        catch (err) {
+            process.stderr.write(`[butler] ${err.message}\n`);
+            process.exit(2);
+        }
+    })();
+}
 // Handle outcomes subcommand — operator positive-act confirmation of worker
 // filings (confirm/reject/list). Writes to ~/.patchwork/outcome-log.jsonl, the
 // same store the trust ramp reads; it is NOT a recipe step, so a worker cannot