patchwork-os 1.2.0-beta.2.canary.684 → 1.2.0-beta.2.canary.687

package/dist/butler/outcomeShadowLog.d.ts

@@ -100,3 +100,18 @@ export interface ShadowSummary {
 export declare function summariseShadowLog(opts?: {
     dir?: string;
 }): ShadowSummary;
+/**
+ * Parse well-formed rows out of raw ledger text.
+ *
+ * The single parse rule, shared by the summary and by promotion. Two readers of
+ * one append-only file with two copies of "what counts as a row" is how a
+ * report and the thing it reports on come to disagree — and here the report is
+ * what a person reads before deciding to promote.
+ *
+ * Malformed lines are SKIPPED and counted in nothing: a half-written row from
+ * an interrupted append is not evidence, and must not inflate a number someone
+ * is about to make a trust decision on.
+ */
+export declare function parseShadowRows(text: string): ShadowOutcomeRow[];
+/** Every well-formed row in the ledger, oldest first. */
+export declare function readShadowRows(dir?: string): ShadowOutcomeRow[];

package/dist/butler/outcomeShadowLog.js

@@ -130,6 +130,28 @@ export function summariseShadowLog(opts = {}) {
         return empty;
     }
     const out = { ...empty };
+    for (const row of parseShadowRows(text)) {
+        out.total++;
+        out[row.disposition]++;
+        if (row.wouldCountAsEvidence)
+            out.wouldCount++;
+    }
+    return out;
+}
+/**
+ * Parse well-formed rows out of raw ledger text.
+ *
+ * The single parse rule, shared by the summary and by promotion. Two readers of
+ * one append-only file with two copies of "what counts as a row" is how a
+ * report and the thing it reports on come to disagree — and here the report is
+ * what a person reads before deciding to promote.
+ *
+ * Malformed lines are SKIPPED and counted in nothing: a half-written row from
+ * an interrupted append is not evidence, and must not inflate a number someone
+ * is about to make a trust decision on.
+ */
+export function parseShadowRows(text) {
+    const rows = [];
     for (const line of text.split("\n")) {
         if (!line.trim())
             continue;
@@ -145,11 +167,22 @@ export function summariseShadowLog(opts = {}) {
             row.disposition !== "unknown") {
             continue;
         }
-        out.total++;
-        out[row.disposition]++;
-        if (row.wouldCountAsEvidence)
-            out.wouldCount++;
+        if (typeof row.ref !== "string" || !row.ref)
+            continue;
+        rows.push(row);
+    }
+    return rows;
+}
+/** Every well-formed row in the ledger, oldest first. */
+export function readShadowRows(dir) {
+    const p = shadowLogPath(dir);
+    if (!existsSync(p))
+        return [];
+    try {
+        return parseShadowRows(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return [];
     }
-    return out;
 }
 //# sourceMappingURL=outcomeShadowLog.js.map

package/dist/butler/outcomeShadowLog.js.map

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

package/dist/butler/promoteShadowOutcomes.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Promote graded Butler shadow rows into the trust ledger — flag-gated, OFF.
+ *
+ * ## Why this is a separate module and not a branch in the ingester
+ *
+ * `outcomeIngester.ts` and `errandOutcomeGrader.ts` each carry a test asserting
+ * they cannot reach `OutcomeStore` — not "do not call it", but *do not import
+ * anything that could*. That is what makes "shadow-only" a structural fact
+ * rather than a promise, and it is why a reviewer can read the grader without
+ * checking whether some path in it writes evidence.
+ *
+ * Adding promotion there would have meant deleting those guards. This module
+ * exists so they stay exactly as they are: the grader stays a pure function of
+ * observed state, the ingester stays unable to write trust, and the single
+ * place that can is this one, which does nothing else.
+ *
+ * ## Operator path only
+ *
+ * Not registered as a recipe tool, and a test asserts it. A recipe step runs AS
+ * the worker, so a worker able to reach this could promote its own filings —
+ * manufacturing the evidence that raises its own dial. Same reasoning as
+ * `outcomes confirm|reject`, which is also operator-only for exactly this.
+ *
+ * ## Flag-gated OFF, and the flag is about EVIDENCE, not about code
+ *
+ * Promotion is one-way in the way that matters: once a row is folded, the dial
+ * it moved cannot be un-moved by deleting the row, because trust replay has
+ * already absorbed it into a checkpoint. So the gate is not "is the code
+ * finished" — it is "is there enough evidence to start counting this channel".
+ *
+ * At the time of writing the shadow ledger holds ONE confirmed row. That is a
+ * real positive act, correctly attributed, and it is one row. The flag exists so
+ * the code can be reviewed, tested and merged now, and the trust decision made
+ * later on more of them, by a person, deliberately.
+ *
+ * ## What is promoted, and what is refused
+ *
+ * Only `confirmed` and `junk` — the two dispositions that represent a POSITIVE
+ * ACT by the operator. `unknown` is never promoted under any flag, because
+ * "nobody has acted yet" is not evidence in either direction, and folding it as
+ * good is the trust-by-neglect defect closed four times already in this
+ * subsystem (#1064, #1318/#1319, #1320, #1322).
+ *
+ * ## `origin: "ingester"`, never `"manual"`
+ *
+ * `OutcomeStore` treats a `"manual"` disposition as STICKY against later
+ * ingester writes, because it represents a human's explicit judgment. Nothing
+ * here is that: it is an automated grade derived from an HTTP response. Marking
+ * these `"manual"` would let an automated observation permanently override an
+ * operator who had explicitly ruled the other way — precisely inverting the
+ * precedence the field exists to protect.
+ */
+/** Feature flag. Absent or anything but a truthy value ⇒ promotion refuses. */
+export declare const BUTLER_PROMOTE_FLAG = "PATCHWORK_FLAG_BUTLER_PROMOTE";
+export interface PromoteOptions {
+    /** `~/.patchwork` override (tests). */
+    patchworkDir: string;
+    /** Clock, injected so a written record is reproducible in tests. */
+    now?: number;
+    /** Report only; write nothing. Independent of the flag. */
+    dryRun?: boolean;
+    /** Flag override, injected rather than read from the environment in tests. */
+    enabled?: boolean;
+}
+export interface PromoteResult {
+    /** Every graded row considered — the DENOMINATOR, always reported. */
+    rows: number;
+    /** Rows whose disposition is `confirmed` or `junk`. */
+    promotable: number;
+    /** Rows withheld because the grader said `unknown`. */
+    withheld: number;
+    /** Rows written to the outcome log. Zero on a dry run or with the flag off. */
+    promoted: number;
+    /** Rows already carrying the same disposition in the trust ledger. */
+    alreadyRecorded: number;
+    /** Rows whose stored ref could not be turned back into a key, with why. */
+    unkeyable: {
+        ref: string;
+        reason: string;
+    }[];
+    /** True when nothing was written because the flag is off. */
+    blockedByFlag: boolean;
+}
+/**
+ * Split a stored `"<tool>:<id>"` key back into its parts.
+ *
+ * On the FIRST colon, which is the inverse of how `canonicalActionRef` joins
+ * them. Tool ids in this repo are dot-separated (`todoist.create_task`) and
+ * never contain a colon, while connector ids routinely do — so splitting on the
+ * last colon, or on every colon, would silently rekey the action and attach a
+ * confirmation to nothing.
+ *
+ * A URL-shaped key is refused rather than split. Those belong to the legacy
+ * `issueUrl` namespace, which `canonicalActionRef` explicitly refuses to
+ * produce; treating one as a `ref` here would write a row under a key no reader
+ * looks for.
+ */
+export declare function splitStoredRef(stored: string): {
+    tool: string;
+    id: string;
+} | {
+    error: string;
+};
+/**
+ * Fold graded shadow rows into the trust ledger.
+ *
+ * Idempotent: a row whose disposition already matches what the ledger holds is
+ * counted as `alreadyRecorded` and NOT rewritten. `upsert` appends, so
+ * re-running without this would grow the file the autonomy gate reads with rows
+ * that say nothing new — and that file's byte cap is already what starves trust
+ * evidence (#1337).
+ */
+export declare function promoteShadowOutcomes(opts: PromoteOptions): PromoteResult;
+/**
+ * Render the result.
+ *
+ * Leads with the denominator and never prints a bare promoted count, for the
+ * same reason the privacy shadow report refuses to: "3 promoted" reads as a
+ * measure of the channel's health when it partly measures how little was
+ * observed.
+ */
+export declare function formatPromoteResult(r: PromoteResult): string;

package/dist/butler/promoteShadowOutcomes.js

@@ -0,0 +1,184 @@
+/**
+ * Promote graded Butler shadow rows into the trust ledger — flag-gated, OFF.
+ *
+ * ## Why this is a separate module and not a branch in the ingester
+ *
+ * `outcomeIngester.ts` and `errandOutcomeGrader.ts` each carry a test asserting
+ * they cannot reach `OutcomeStore` — not "do not call it", but *do not import
+ * anything that could*. That is what makes "shadow-only" a structural fact
+ * rather than a promise, and it is why a reviewer can read the grader without
+ * checking whether some path in it writes evidence.
+ *
+ * Adding promotion there would have meant deleting those guards. This module
+ * exists so they stay exactly as they are: the grader stays a pure function of
+ * observed state, the ingester stays unable to write trust, and the single
+ * place that can is this one, which does nothing else.
+ *
+ * ## Operator path only
+ *
+ * Not registered as a recipe tool, and a test asserts it. A recipe step runs AS
+ * the worker, so a worker able to reach this could promote its own filings —
+ * manufacturing the evidence that raises its own dial. Same reasoning as
+ * `outcomes confirm|reject`, which is also operator-only for exactly this.
+ *
+ * ## Flag-gated OFF, and the flag is about EVIDENCE, not about code
+ *
+ * Promotion is one-way in the way that matters: once a row is folded, the dial
+ * it moved cannot be un-moved by deleting the row, because trust replay has
+ * already absorbed it into a checkpoint. So the gate is not "is the code
+ * finished" — it is "is there enough evidence to start counting this channel".
+ *
+ * At the time of writing the shadow ledger holds ONE confirmed row. That is a
+ * real positive act, correctly attributed, and it is one row. The flag exists so
+ * the code can be reviewed, tested and merged now, and the trust decision made
+ * later on more of them, by a person, deliberately.
+ *
+ * ## What is promoted, and what is refused
+ *
+ * Only `confirmed` and `junk` — the two dispositions that represent a POSITIVE
+ * ACT by the operator. `unknown` is never promoted under any flag, because
+ * "nobody has acted yet" is not evidence in either direction, and folding it as
+ * good is the trust-by-neglect defect closed four times already in this
+ * subsystem (#1064, #1318/#1319, #1320, #1322).
+ *
+ * ## `origin: "ingester"`, never `"manual"`
+ *
+ * `OutcomeStore` treats a `"manual"` disposition as STICKY against later
+ * ingester writes, because it represents a human's explicit judgment. Nothing
+ * here is that: it is an automated grade derived from an HTTP response. Marking
+ * these `"manual"` would let an automated observation permanently override an
+ * operator who had explicitly ruled the other way — precisely inverting the
+ * precedence the field exists to protect.
+ */
+import { OutcomeStore } from "../workers/outcomeStore.js";
+import { readShadowRows, wouldCountAsEvidence, } from "./outcomeShadowLog.js";
+/** Feature flag. Absent or anything but a truthy value ⇒ promotion refuses. */
+export const BUTLER_PROMOTE_FLAG = "PATCHWORK_FLAG_BUTLER_PROMOTE";
+function flagEnabled(opts) {
+    if (opts.enabled !== undefined)
+        return opts.enabled;
+    const v = process.env[BUTLER_PROMOTE_FLAG];
+    return v === "1" || v?.toLowerCase() === "true";
+}
+/**
+ * Split a stored `"<tool>:<id>"` key back into its parts.
+ *
+ * On the FIRST colon, which is the inverse of how `canonicalActionRef` joins
+ * them. Tool ids in this repo are dot-separated (`todoist.create_task`) and
+ * never contain a colon, while connector ids routinely do — so splitting on the
+ * last colon, or on every colon, would silently rekey the action and attach a
+ * confirmation to nothing.
+ *
+ * A URL-shaped key is refused rather than split. Those belong to the legacy
+ * `issueUrl` namespace, which `canonicalActionRef` explicitly refuses to
+ * produce; treating one as a `ref` here would write a row under a key no reader
+ * looks for.
+ */
+export function splitStoredRef(stored) {
+    if (/^https?:\/\//i.test(stored)) {
+        return {
+            error: "URL-shaped key belongs to the legacy issueUrl namespace, not the tool/id one",
+        };
+    }
+    const i = stored.indexOf(":");
+    if (i <= 0 || i === stored.length - 1) {
+        return { error: "not in '<tool>:<id>' form" };
+    }
+    return { tool: stored.slice(0, i), id: stored.slice(i + 1) };
+}
+/**
+ * Fold graded shadow rows into the trust ledger.
+ *
+ * Idempotent: a row whose disposition already matches what the ledger holds is
+ * counted as `alreadyRecorded` and NOT rewritten. `upsert` appends, so
+ * re-running without this would grow the file the autonomy gate reads with rows
+ * that say nothing new — and that file's byte cap is already what starves trust
+ * evidence (#1337).
+ */
+export function promoteShadowOutcomes(opts) {
+    const rows = readShadowRows(opts.patchworkDir);
+    const enabled = flagEnabled(opts);
+    const result = {
+        rows: rows.length,
+        promotable: 0,
+        withheld: 0,
+        promoted: 0,
+        alreadyRecorded: 0,
+        unkeyable: [],
+        blockedByFlag: !enabled,
+    };
+    const store = new OutcomeStore(opts.patchworkDir);
+    const now = opts.now ?? Date.now();
+    // Last grade wins per ref. The ledger is append-only and an errand is
+    // observed repeatedly, so the same ref legitimately appears many times —
+    // promoting each one would write the same fact over and over, and an older
+    // grade could land after a newer one.
+    const latest = new Map();
+    for (const row of rows) {
+        const prev = latest.get(row.ref);
+        if (!prev || row.gradedAt >= prev.gradedAt)
+            latest.set(row.ref, row);
+    }
+    for (const row of latest.values()) {
+        if (!wouldCountAsEvidence(row.disposition)) {
+            result.withheld++;
+            continue;
+        }
+        result.promotable++;
+        const parts = splitStoredRef(row.ref);
+        if ("error" in parts) {
+            // Reported, never dropped. A row that cannot be keyed is a measurement
+            // gap, and a run that silently skipped some looks identical to a clean one.
+            result.unkeyable.push({ ref: row.ref, reason: parts.error });
+            continue;
+        }
+        if (store.getDispositionForRef(parts) === row.disposition) {
+            result.alreadyRecorded++;
+            continue;
+        }
+        if (!enabled || opts.dryRun)
+            continue;
+        store.upsert({
+            ref: parts,
+            disposition: row.disposition,
+            checkedAt: now,
+            ...(row.recipe ? { recipeName: row.recipe } : {}),
+            // NOT "manual" — see the header. This is an automated grade, and marking
+            // it manual would make it sticky against a human who ruled otherwise.
+            origin: "ingester",
+        });
+        result.promoted++;
+    }
+    return result;
+}
+/**
+ * Render the result.
+ *
+ * Leads with the denominator and never prints a bare promoted count, for the
+ * same reason the privacy shadow report refuses to: "3 promoted" reads as a
+ * measure of the channel's health when it partly measures how little was
+ * observed.
+ */
+export function formatPromoteResult(r) {
+    const lines = [];
+    lines.push(`[butler-promote] ${r.rows} graded row(s) in the shadow ledger`);
+    lines.push(`  ${r.promotable} promotable (confirmed or junk) · ${r.withheld} withheld as unknown`);
+    if (r.alreadyRecorded > 0) {
+        lines.push(`  ${r.alreadyRecorded} already recorded with the same verdict`);
+    }
+    for (const u of r.unkeyable) {
+        lines.push(`  unkeyable ${u.ref}: ${u.reason}`);
+    }
+    lines.push("");
+    if (r.blockedByFlag) {
+        lines.push(`  NOTHING WAS WRITTEN — ${BUTLER_PROMOTE_FLAG} is not set, so this run`);
+        lines.push("  was a report. Promotion moves the trust dial and a folded");
+        lines.push("  row cannot be un-folded by deleting it, so it is off until");
+        lines.push("  a person turns it on against evidence they have read.");
+    }
+    else {
+        lines.push(`  ${r.promoted} row(s) written to the trust ledger.`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=promoteShadowOutcomes.js.map

package/dist/butler/promoteShadowOutcomes.js.map

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

package/dist/index.js

@@ -4672,6 +4672,29 @@ if (process.argv[2] === "butler") {
                 }
                 process.exit(0);
             }
+            if (args[0] === "promote") {
+                // The ONE path that turns a graded Butler row into trust evidence, and
+                // it is off unless PATCHWORK_FLAG_BUTLER_PROMOTE is set. Operator path
+                // only, for the same reason `outcomes confirm` is: a recipe step runs
+                // AS the worker, so a worker able to reach this would manufacture the
+                // evidence that raises its own dial.
+                const { formatPromoteResult, promoteShadowOutcomes } = await import("./butler/promoteShadowOutcomes.js");
+                const { patchworkHome } = await import("./patchworkHome.js");
+                const res = promoteShadowOutcomes({
+                    patchworkDir: patchworkHome(),
+                    dryRun: args.includes("--dry-run"),
+                });
+                if (args.includes("--json")) {
+                    process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(formatPromoteResult(res));
+                }
+                // Exit 0 either way: "the flag is off" is the CONFIGURED state, not a
+                // failure, and a non-zero exit would make a cron wrapper report a
+                // problem every time it ran as designed.
+                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
@@ -4719,13 +4742,19 @@ if (process.argv[2] === "butler") {
                 }
                 process.exit(0);
             }
-            process.stderr.write("Usage: patchwork butler <shadow|ingest|observe> [--json]\n\n" +
+            process.stderr.write("Usage: patchwork butler <shadow|ingest|observe|promote> [--json]\n\n" +
                 "  shadow                       summarise the graded shadow ledger\n" +
                 "  ingest [--file <path>|-]     grade a JSON array of observations\n" +
                 "  observe [--file <path>]      discover errands from the run log,\n" +
                 "                               look up live Todoist state, then grade\n" +
                 "         [--stale-after-days N]\n\n" +
-                "  Shadow-only: nothing here writes the trust ledger.\n");
+                "  promote [--dry-run]          fold confirmed/junk grades into the\n" +
+                "                               trust ledger. Requires\n" +
+                "                               PATCHWORK_FLAG_BUTLER_PROMOTE=1;\n" +
+                "                               reports without writing otherwise.\n\n" +
+                "  shadow/ingest/observe are shadow-only and write no trust evidence.\n" +
+                "  `promote` is the single path that does, and it never promotes an\n" +
+                "  `unknown` grade under any flag.\n");
             process.exit(2);
         }
         catch (err) {