pi-daddy 0.28.0 → 0.32.0

package/dist/governance/ledger-report.js

@@ -0,0 +1,294 @@
+/**
+ * Reading a ledger back — integrity, instruction versions, and the ADR-0020 approval tally.
+ *
+ * Split from `ledger.ts` when the file-size guard refused it at 419 lines. The seam is real rather than
+ * arbitrary: `ledger.ts` **writes** one record at a time and fails closed when it cannot, while everything
+ * here **reads** a whole file and must never fail at all — a report is a diagnostic, and a diagnostic that
+ * throws on damaged input is useless on exactly the input it exists for. Every defect this half has had
+ * (R-63's bias, R-64's three malformed shapes) was a *reporting* defect, and none of them could have
+ * touched the write path.
+ *
+ * Re-exported from `./ledger` so the published subpath is unchanged.
+ */
+import { readFile } from "node:fs/promises";
+import { DELEGATE_SUBJECT } from "../kernel/approval.js";
+import { isEscalationAttempt } from "./ledger.js";
+import { isExecutionId } from "../kernel/execution-id.js";
+import { isRetiredLedgerEvent, validateLedgerV3Event } from "./ledger-v3-validation.js";
+import { readRecords } from "./record.js";
+/**
+ * Read the ledger back and report what is wrong with it.
+ *
+ * **This is the gap that mattered most.** `appendRecord`'s strict mode catches write *errors*, never
+ * corruption, and nothing in this package had ever read a ledger back — so a torn line was silently
+ * indistinguishable from a spawn that never happened. An audit trail whose damage is invisible is not a
+ * compensating control, and ADR-0008 leans on the ledger as exactly that.
+ *
+ * Deliberately reports rather than repairs. A corrupt line is evidence; rewriting the file to make it parse
+ * would destroy the one artifact an investigation has.
+ */
+// Keyed by the UNION, not by `string`. Typed loosely, adding a `WorkspaceLeaseOutcome` member without a
+// counter compiled fine and then made `verifyLedger` file the package's own valid event as CORRUPTION —
+// the worst available outcome for an integrity signal, since real damage becomes noise.
+const LEASE_OUTCOME_COUNTERS = {
+    acquired: "acquired",
+    uncontended: "uncontended",
+    refused: "refused",
+    released: "released",
+    "released-unrecorded": "releasedUnrecorded",
+    lost: "lost",
+    retained: "retained",
+    timeout: "timeout",
+    recovered: "recovered",
+};
+function requireVersioned(event, fields) {
+    if ((event.ledgerVersion !== 2 && event.ledgerVersion !== 3) ||
+        typeof event.ts !== "string" ||
+        fields.some((field) => typeof event[field] !== "string" || event[field] === "")) {
+        throw new Error("invalid versioned ledger event");
+    }
+    if (event.ledgerVersion === 3 &&
+        (!isExecutionId(event.executionId) || (event.parentExecutionId !== null && !isExecutionId(event.parentExecutionId)))) {
+        throw new Error("invalid v3 execution identity");
+    }
+}
+function requireCapabilityDecision(event) {
+    requireVersioned(event, ["parentId", "childId", "executor", "taskDigest"]);
+    for (const field of ["requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked"]) {
+        if (!Array.isArray(event[field]) || !event[field].every((value) => typeof value === "string")) {
+            throw new Error("invalid capability decision arrays");
+        }
+    }
+    if (!Number.isInteger(event.depth) ||
+        typeof event.blocked !== "boolean" ||
+        !/^[a-f0-9]{64}$/i.test(String(event.taskDigest))) {
+        throw new Error("invalid capability decision identity");
+    }
+}
+export async function verifyLedger(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                exists: false,
+                records: 0,
+                events: 0,
+                workspaceLeases: {
+                    acquired: 0,
+                    uncontended: 0,
+                    refused: 0,
+                    released: 0,
+                    releasedUnrecorded: 0,
+                    lost: 0,
+                    retained: 0,
+                    timeout: 0,
+                    recovered: 0,
+                },
+                lifecycle: { starting: 0, running: 0, completed: 0, failed: 0 },
+                retired: 0,
+                corrupt: [],
+                escalationAttempts: 0,
+                executors: { herdr: 0, process: 0, unknown: 0 },
+                definitions: [],
+                approvals: {
+                    bySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
+                    distinctBySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
+                    unattributed: 0,
+                    humanDenied: 0,
+                    humanDeniedPairs: 0,
+                },
+                ok: true,
+            };
+        }
+        throw error;
+    }
+    const corrupt = [];
+    // Keyed by name+digest: one name with two entries is the signal that the definition changed mid-ledger.
+    const digests = new Map();
+    let records = 0;
+    let events = 0;
+    const workspaceLeases = {
+        acquired: 0,
+        uncontended: 0,
+        refused: 0,
+        released: 0,
+        releasedUnrecorded: 0,
+        lost: 0,
+        retained: 0,
+        timeout: 0,
+        recovered: 0,
+    };
+    const lifecycle = { starting: 0, running: 0, completed: 0, failed: 0 };
+    let retired = 0;
+    let escalationAttempts = 0;
+    const executors = { herdr: 0, process: 0, unknown: 0 };
+    const bySource = { prompt: 0, session: 0, persisted: 0, inherited: 0 };
+    // `capability@subject` seen per source, so the report can state a bound as well as a raw count.
+    const distinct = {
+        prompt: new Set(),
+        session: new Set(),
+        persisted: new Set(),
+        inherited: new Set(),
+    };
+    let unattributed = 0;
+    let humanDenied = 0;
+    const deniedPairs = new Set();
+    // ADR-0076 PR 3d: lines are record envelopes; every intact record before the first damage is reported, and
+    // the damage itself is one corrupt entry. Record sequence equals line number because records are contiguous.
+    const read = readRecords(text);
+    read.records.forEach((record, index) => {
+        try {
+            const event = record.body;
+            if (event.ledgerVersion !== undefined) {
+                if (event.event === undefined)
+                    throw new Error("versioned ledger line has no event discriminator");
+                if (event.ledgerVersion !== 2 && event.ledgerVersion !== 3)
+                    throw new Error("unsupported ledger version");
+                if (event.ledgerVersion === 3 && validateLedgerV3Event(event))
+                    throw new Error("invalid ledger v3 event");
+            }
+            if (event.event === "workspace_lease") {
+                requireVersioned(event, ["childId", "workspaceId", "root", "access"]);
+                const outcome = typeof event.outcome === "string" ? event.outcome : "";
+                // Explicit map, not a name match: the ledger's outcome vocabulary and these counter names are
+                // allowed to differ, and a valid event must never be counted as corruption because a counter
+                // happens to be spelled differently.
+                const counter = Object.hasOwn(LEASE_OUTCOME_COUNTERS, outcome)
+                    ? LEASE_OUTCOME_COUNTERS[outcome]
+                    : undefined;
+                if (!counter)
+                    throw new Error("invalid workspace lease event");
+                workspaceLeases[counter] += 1;
+                events += 1;
+                return;
+            }
+            if (event.event === "child_lifecycle") {
+                requireVersioned(event, ["childId", "executor"]);
+                const state = typeof event.state === "string" ? event.state : "";
+                if (!Object.hasOwn(lifecycle, state))
+                    throw new Error("invalid child lifecycle event");
+                lifecycle[state] += 1;
+                events += 1;
+                return;
+            }
+            if (event.ledgerVersion === 3 && isRetiredLedgerEvent(event)) {
+                // Written by 0.30.0 or earlier; counted, never treated as corruption (see RETIRED_LEDGER_EVENT_KINDS).
+                retired += 1;
+                events += 1;
+                return;
+            }
+            if (event.event === "check_receipt") {
+                // v2 receipts predate the retired set and keep the field check they always had.
+                requireVersioned(event, ["childId", "receiptId", "workspaceId", "checkId", "treeSha"]);
+                retired += 1;
+                events += 1;
+                return;
+            }
+            if (event.event !== undefined && event.event !== "capability_decision")
+                throw new Error("unknown ledger event");
+            const parsed = event;
+            if (event.event === "capability_decision")
+                requireCapabilityDecision(event);
+            if (!Array.isArray(parsed.denied))
+                throw new Error("not a grant record");
+            records += 1;
+            events += 1;
+            if (isEscalationAttempt(parsed))
+                escalationAttempts += 1;
+            const executor = parsed.executor;
+            if (executor === "herdr")
+                executors.herdr += 1;
+            else if (executor === "process")
+                executors.process += 1;
+            else
+                executors.unknown += 1;
+            if (parsed.humanDenied) {
+                humanDenied += 1;
+                const subject = parsed.agentType === undefined || parsed.agentType === "delegate" ? DELEGATE_SUBJECT : parsed.agentType;
+                for (const capability of parsed.gatedBlocked ?? [])
+                    deniedPairs.add(`${capability}@${subject}`);
+            }
+            // A **plain, non-empty** object. Three shapes were accepted here that must not be, all of them
+            // reachable from a torn, hand-edited or foreign line — which is the input class `verifyLedger` exists
+            // for, so "this package never writes that" is not a defence:
+            //   - `{}` beside a non-empty `approved` counted NOWHERE, silently shrinking the sample the comment
+            //     below promises to keep visible;
+            //   - an ARRAY passed `typeof === "object"` and was tallied with numeric indices as capability names;
+            //   - `null` is an object.
+            const rawSources = parsed.approvalSources;
+            const sources = rawSources && typeof rawSources === "object" && !Array.isArray(rawSources) && Object.keys(rawSources).length > 0
+                ? rawSources
+                : undefined;
+            if (sources) {
+                // The subject half of `capability@subject`. `agentType` is the definition's name, or the literal
+                // `"delegate"` for the `tools:` form — which is NOT `DELEGATE_SUBJECT`, the `<delegate>` the approval
+                // layer keys on. Mapped here rather than at the write site so old ledgers read correctly too.
+                // **Stated limit:** a definition genuinely named `delegate` is indistinguishable from the `tools:`
+                // form in this field, and their two distinct approvals count as one pair. `DELEGATE_SUBJECT`'s own
+                // angle brackets exist to make that collision impossible, and the ledger drops them.
+                const subject = parsed.agentType === undefined || parsed.agentType === "delegate" ? DELEGATE_SUBJECT : parsed.agentType;
+                for (const [capability, source] of Object.entries(sources)) {
+                    // `Object.hasOwn`, never `in`: `in` walks the prototype, so a source of `"toString"` or
+                    // `"valueOf"` passed the check, wrote a STRING into a counter, made `attributed` a string, and
+                    // deleted the entire measurement from the report while marking an intact ledger corrupt.
+                    // An unrecognised source is counted as unattributed rather than dropped: a tally that silently
+                    // ignores what it does not understand reports a smaller sample as a cleaner one.
+                    if (Object.hasOwn(bySource, source)) {
+                        bySource[source] += 1;
+                        distinct[source].add(`${capability}@${subject}`);
+                    }
+                    else
+                        unattributed += 1;
+                }
+            }
+            else if (parsed.approved && parsed.approved.length > 0) {
+                unattributed += parsed.approved.length;
+            }
+            const d = parsed.definitionDigest;
+            if (d?.name && d.sha256) {
+                const key = `${d.name}\u0000${d.sha256}`;
+                const seen = digests.get(key);
+                if (seen)
+                    seen.spawns += 1;
+                else
+                    digests.set(key, { name: d.name, source: d.source, sha256: d.sha256, spawns: 1 });
+            }
+        }
+        catch {
+            // Content-free by contract: a torn or foreign line can contain exactly the task/output material the
+            // ledger and dashboard promise never to expose. The line number locates the evidence without copying it.
+            corrupt.push({ line: index + 1, reason: "invalid ledger line" });
+        }
+    });
+    if (read.damage)
+        corrupt.push({ line: read.damage.line, reason: `ledger damaged: ${read.damage.reason}` });
+    return {
+        exists: true,
+        records,
+        events,
+        workspaceLeases,
+        lifecycle,
+        retired,
+        corrupt,
+        escalationAttempts,
+        executors,
+        definitions: [...digests.values()].sort((a, b) => a.name.localeCompare(b.name) || a.sha256.localeCompare(b.sha256)),
+        approvals: {
+            bySource,
+            distinctBySource: {
+                prompt: distinct.prompt.size,
+                session: distinct.session.size,
+                persisted: distinct.persisted.size,
+                inherited: distinct.inherited.size,
+            },
+            unattributed,
+            humanDenied,
+            humanDeniedPairs: deniedPairs.size,
+        },
+        ok: corrupt.length === 0,
+    };
+}
+//# sourceMappingURL=ledger-report.js.map

package/dist/governance/ledger-report.js.map

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

package/dist/governance/ledger-v3-validation.d.ts

@@ -0,0 +1,21 @@
+export type LedgerV3Object = Record<string, unknown>;
+/**
+ * Event kinds that 0.30.0 and earlier wrote and 0.31.0 no longer builds (the check runner and workflow facts were
+ * deleted). A ledger is append-only, so a line written then is still a valid line now: readers accept these
+ * discriminators as historical and count them, and nothing here can produce a new one. Removing a kind from this
+ * set turns an operator's existing record into "corrupt" on upgrade, which is the failure this set exists to prevent.
+ */
+export declare const RETIRED_LEDGER_EVENT_KINDS: ReadonlySet<string>;
+export declare function isRetiredLedgerEvent(event: {
+    event?: unknown;
+}): boolean;
+export declare function isLedgerObject(value: unknown): value is LedgerV3Object;
+export declare function isNonEmptyString(value: unknown): value is string;
+/** Ledger timestamp profile: JSON Schema `date-time`, narrowed to seconds 00-59 for JS date arithmetic. */
+export declare function isTimestamp(value: unknown): value is string;
+export declare function isStringArray(value: unknown): value is string[];
+/** Exact, content-free runtime validation for one closed ledger v3 event. */
+export declare function validateLedgerV3Event(event: LedgerV3Object): string | null;
+/** Ensure a public builder cannot emit bytes the closed v3 reader would reject. */
+export declare function assertLedgerV3Wire<T extends object>(event: T): T;
+//# sourceMappingURL=ledger-v3-validation.d.ts.map

package/dist/governance/ledger-v3-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-v3-validation.d.ts","sourceRoot":"","sources":["../../src/governance/ledger-v3-validation.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAA+C,CAAC;AAC3G,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAExE;AAsID,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAItE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED,2GAA2G;AAC3G,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAkB3D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,EAAE,CAE/D;AA6KD,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAY1E;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAWhE"}