pi-daddy 0.28.0 → 0.32.1

package/src/ledger-report.ts

@@ -1,357 +0,0 @@
-/**
- * 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 type { Capability } from "./resolve.ts";
-import { DELEGATE_SUBJECT } from "./approval.ts";
-import type { ApprovalSource } from "./approval.ts";
-import type { GrantRecord } from "./ledger.ts";
-import { isEscalationAttempt } from "./ledger.ts";
-import type { WorkspaceLeaseOutcome } from "./ledger-events.ts";
-import { isExecutionId } from "./execution-id.ts";
-import { validateLedgerV3Event } from "./ledger-v3-validation.ts";
-
-export interface LedgerReport {
-  /** False when the file is absent — a configuration state, not damage. */
-  exists: boolean;
-  /** Capability-decision records (legacy, v2, or v3). */
-  records: number;
-  /** Every parsed ledger event, including lifecycle and lease events. */
-  events: number;
-  workspaceLeases: {
-    acquired: number; uncontended: number; refused: number; released: number;
-    releasedUnrecorded: number; lost: number; retained: number; timeout: number; recovered: number;
-  };
-  lifecycle: { starting: number; running: number; completed: number; failed: number };
-  /** Planned/observed/controller-validated facts; never counted as enforced child executions. */
-  workflowFacts: number;
-  /** Lines that did not, with 1-based line numbers so the report is actionable. */
-  corrupt: Array<{ line: number; reason: string }>;
-  /** Records where an agent asked for more than it held — ADR-0008's designated signal. */
-  escalationAttempts: number;
-  /**
-   * How many records ran under each executor, plus how many name none — ADR-0031.
-   *
-   * **Added because the field was written and never read, which is R-51's shape exactly.** R-51 was
-   * `definitionDigest`: recorded from the start, absent from every report, so the questions ADR-0018 advertised
-   * needed hand-written `jq`. `executor` arrived the same way — `src/ledger.ts` justifies making it *required*
-   * with "reading it back is the only reason it exists", and nothing read it back. `docs/SPEC.md` claims the
-   * executor is "announced three times… per child in the ledger"; without this the third announcement was to
-   * `jq` only.
-   *
-   * `unknown` counts pre-0.16 lines, which have no such field. Reported rather than folded into `process`,
-   * because "written before the executor was recorded" and "ran as a subprocess" are different facts.
-   */
-  executors: { herdr: number; process: number; unknown: number };
-  /**
-   * Every distinct set of instructions this ledger saw run, with how many spawns used it (R-51).
-   *
-   * ADR-0018 advertises that a record answers *"did these four children run the same instructions?"* and
-   * *"has this definition changed since?"* — and until this existed **nothing read `definitionDigest` at
-   * all**, so both questions required hand-written `jq` and the second was not even reproducible with
-   * `sha256sum`, because the digest covers the body and not the frontmatter. A field no tool reads is a
-   * field that quietly becomes decoration.
-   *
-   * Grouped by `name` + `sha256`, so two entries with one name are exactly the evidence that a definition
-   * changed mid-ledger. Sorted by name then digest so two runs of the same fan-out produce a diffable
-   * report, like the ids themselves.
-   */
-  definitions: Array<{ name: string; source: string; sha256: string; spawns: number }>;
-  /**
-   * Where the yes came from, per approved capability, tallied across the whole ledger.
-   *
-   * **This is the measurement ADR-0020 asks for.** That ADR keeps the persistence layer on R-25's fatigue
-   * argument with *no number behind it*, and named the evidence that would settle it: counting `persisted`
-   * against `prompt` over a few weeks of real use. It also said this "needs no new machinery" — true of the
-   * data and false of the answer, which required hand-written `jq`. Same shape as R-51: a field no tool
-   * reads becomes decoration, and a measurement nobody can run does not get run.
-   *
-   * **`bySource` counts RECORDS and is an upper bound, not an answer.** Deleting the persistence layer does
-   * not turn every `persisted` record back into a prompt: precedence is `inherited → session → persisted →
-   * prompt`, and `session` approvals live in memory and do not depend on the store at all. So a session that
-   * spawns `deploy` twenty times under one persisted entry writes twenty `persisted` records, while without
-   * the store it would raise **one** prompt and satisfy the other nineteen from the session cache. Reporting
-   * twenty prompts avoided would overstate the layer's value twentyfold, on the one number that decides
-   * whether to keep it — the same direction of bias `unattributed` exists to avoid, arrived at a different way.
-   *
-   * `distinctBySource` is the closer estimate: distinct `capability@subject` pairs, which bounds the cost of
-   * deletion at one prompt per pair per session. The ledger carries no session id, so the exact figure is not
-   * computable from it; both numbers are printed and labelled rather than one being presented as the truth.
-   *
-   * Counted from `approvalSources` **only**. `approvalSource` is deliberately not used as a fallback: before
-   * 0.11.1 that scalar was written for the whole set even when the sources differed (R-46), so folding it in
-   * would report humans as having been asked about capabilities they were never asked about — biasing the
-   * one direction this measurement must not be biased in. Those records are counted as `unattributed`
-   * instead, so the sample size is visible rather than silently smaller.
-   */
-  approvals: {
-    /** Raw record counts. An UPPER bound on prompts avoided — see above before quoting one. */
-    bySource: Record<ApprovalSource, number>;
-    /** Distinct `capability@subject` pairs per source. The closer estimate. */
-    distinctBySource: Record<ApprovalSource, number>;
-    /** Records carrying approvals from before per-capability sources existed. Not attributable; see above. */
-    unattributed: number;
-    /** Records where a human was asked and said no — the fatigue argument's other half. */
-    humanDenied: number;
-    /**
-     * Distinct `capability@subject` pairs a human declined.
-     *
-     * Same reason `distinctBySource` exists: R-29 shares a decline across every concurrent caller, so one
-     * click of *Deny* under an eight-wide fan-out writes eight `humanDenied` records. Reporting the raw
-     * count as "times a human declined" is the per-record bias R-63 removed from `persisted`, left in place
-     * on the number that argues hardest FOR the layer — which is the direction that flatters this package's
-     * own gating and therefore the one to be most careful with.
-     */
-    humanDeniedPairs: number;
-  };
-  ok: boolean;
-}
-
-/**
- * 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: Record<WorkspaceLeaseOutcome, keyof LedgerReport["workspaceLeases"]> = {
-  acquired: "acquired",
-  uncontended: "uncontended",
-  refused: "refused",
-  released: "released",
-  "released-unrecorded": "releasedUnrecorded",
-  lost: "lost",
-  retained: "retained",
-  timeout: "timeout",
-  recovered: "recovered",
-};
-
-function requireVersioned(event: Record<string, unknown>, fields: string[]): void {
-  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: Record<string, unknown>): void {
-  requireVersioned(event, ["parentId", "childId", "executor", "taskDigest"]);
-  for (const field of ["requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked"]) {
-    if (!Array.isArray(event[field]) || !(event[field] as unknown[]).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: string): Promise<LedgerReport> {
-  let text: string;
-  try {
-    text = await readFile(path, "utf8");
-  } catch (error) {
-    if ((error as { code?: string }).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 },
-        workflowFacts: 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: Array<{ line: number; reason: string }> = [];
-  // Keyed by name+digest: one name with two entries is the signal that the definition changed mid-ledger.
-  const digests = new Map<string, { name: string; source: string; sha256: string; spawns: number }>();
-  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 workflowFacts = 0;
-  let escalationAttempts = 0;
-  const executors = { herdr: 0, process: 0, unknown: 0 };
-  const bySource: Record<ApprovalSource, number> = { 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: Record<ApprovalSource, Set<string>> = {
-    prompt: new Set(),
-    session: new Set(),
-    persisted: new Set(),
-    inherited: new Set(),
-  };
-  let unattributed = 0;
-  let humanDenied = 0;
-  const deniedPairs = new Set<string>();
-
-  const lines = text.split("\n");
-  lines.forEach((raw, index) => {
-    // A trailing newline yields one empty final element, which is normal rather than damage.
-    if (raw.trim().length === 0) return;
-    try {
-      const event = JSON.parse(raw) as Record<string, unknown>;
-      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 === "workflow_fact") {
-        // v2 has no workflow facts; the exact v3 validator above already checked its vocabulary,
-        // correlation and provenance/state relation.
-        if (event.ledgerVersion !== 3) throw new Error("invalid workflow fact event");
-        workflowFacts += 1;
-        events += 1;
-        return;
-      }
-      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 as WorkspaceLeaseOutcome]
-          : 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 as keyof typeof lifecycle] += 1;
-        events += 1;
-        return;
-      }
-      if (event.event === "check_receipt") {
-        requireVersioned(event, ["childId", "receiptId", "workspaceId", "checkId", "treeSha"]);
-        events += 1;
-        return;
-      }
-      if (event.event !== undefined && event.event !== "capability_decision") throw new Error("unknown ledger event");
-      const parsed = event as unknown as GrantRecord;
-      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 as { executor?: unknown }).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" });
-    }
-  });
-
-  return {
-    exists: true,
-    records,
-    events,
-    workspaceLeases,
-    lifecycle,
-    workflowFacts,
-    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,
-  };
-}

package/src/ledger-v3-validation.ts

@@ -1,266 +0,0 @@
-import { normaliseCorrelation, type CorrelationMetadata } from "./correlation.ts";
-import { isExecutionId } from "./execution-id.ts";
-import { REFUSAL_CODES } from "./refusals.ts";
-import { isWorkflowFactId, isWorkflowIdentifier, workflowFactStateMatches } from "./workflow-fact-id.ts";
-import { isLedgerCapabilityIdentifier, isLedgerDisplayIdentifier } from "./ledger-identifiers.ts";
-
-export type LedgerV3Object = Record<string, unknown>;
-
-const SHA256_RE = /^[a-f0-9]{64}$/i;
-const EXECUTORS = new Set(["process", "herdr"]);
-const APPROVAL_SOURCES = new Set(["prompt", "session", "persisted", "inherited"]);
-const APPROVAL_SCOPES = new Set(["once", "session", "always"]);
-const GATE_OUTCOMES = new Set(["declined", "dismissed", "no-ui", "error"]);
-const LEASE_OUTCOMES = new Set([
-  "acquired", "uncontended", "refused", "released", "released-unrecorded", "lost", "retained", "timeout", "recovered",
-]);
-const PROCESS_SIGNALS = new Set([
-  "SIGABRT", "SIGALRM", "SIGBUS", "SIGCHLD", "SIGCONT", "SIGFPE", "SIGHUP", "SIGILL", "SIGINT", "SIGIO",
-  "SIGIOT", "SIGKILL", "SIGPIPE", "SIGPOLL", "SIGPROF", "SIGPWR", "SIGQUIT", "SIGSEGV", "SIGSTKFLT",
-  "SIGSTOP", "SIGSYS", "SIGTERM", "SIGTRAP", "SIGTSTP", "SIGTTIN", "SIGTTOU", "SIGUNUSED", "SIGURG",
-  "SIGUSR1", "SIGUSR2", "SIGVTALRM", "SIGWINCH", "SIGXCPU", "SIGXFSZ", "SIGBREAK", "SIGLOST", "SIGINFO",
-]);
-
-const FIELDS = {
-  capability_decision: new Set([
-    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "parentId", "childId", "depth",
-    "agentType", "requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked", "blocked",
-    "reason", "approved", "approvalSource", "approvalSources", "approvalScopes", "approvalExpiresAt",
-    "approvalUses", "approvalScope", "humanDenied", "gateOutcome", "definitionDigest", "executor", "taskFrom",
-    "taskFromExecutionId", "taskDigest", "correlation", "refusal",
-  ]),
-  workspace_lease: new Set([
-    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "workspaceId", "root",
-    "access", "outcome", "recovered", "releaseReason", "refusal", "correlation",
-  ]),
-  child_lifecycle: new Set([
-    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "state", "executor",
-    "exitCode", "signal", "timedOut", "aborted", "truncated", "reason", "deadlineAt", "herdrPaneId",
-    "herdrAgentName", "correlation",
-  ]),
-  check_receipt: new Set([
-    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "receiptId", "workspaceId",
-    "checkId", "treeSha", "correlation",
-  ]),
-  workflow_fact: new Set([
-    "ledgerVersion", "event", "ts", "factId", "source", "provenance", "kind", "subject", "state", "correlation",
-  ]),
-} as const;
-type EventKind = keyof typeof FIELDS;
-
-export function isLedgerObject(value: unknown): value is LedgerV3Object {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-
-export function isNonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.length > 0;
-}
-
-/** Ledger timestamp profile: JSON Schema `date-time`, narrowed to seconds 00-59 for JS date arithmetic. */
-export function isTimestamp(value: unknown): value is string {
-  if (typeof value !== "string") return false;
-  const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|([+-])(\d{2}):(\d{2}))$/.exec(value);
-  if (!match) return false;
-  const [, yearText, monthText, dayText, hourText, minuteText, secondText, , offsetHourText, offsetMinuteText] = match;
-  const year = Number(yearText);
-  const month = Number(monthText);
-  const day = Number(dayText);
-  const hour = Number(hourText);
-  const minute = Number(minuteText);
-  const second = Number(secondText);
-  if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59) return false;
-  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
-  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
-  if (day < 1 || day > days[month - 1]) return false;
-  return offsetHourText === undefined || (Number(offsetHourText) <= 23 && Number(offsetMinuteText) <= 59);
-}
-
-export function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-
-function optional(event: LedgerV3Object, field: string, valid: (value: unknown) => boolean): boolean {
-  return !Object.hasOwn(event, field) || valid(event[field]);
-}
-
-function stringMap(value: unknown, valid: (entry: unknown) => boolean): boolean {
-  return isLedgerObject(value) && Object.values(value).every(valid);
-}
-
-function capabilityMap(value: unknown, valid: (entry: unknown) => boolean): boolean {
-  return isLedgerObject(value) && Object.keys(value).every(isLedgerCapabilityIdentifier) && Object.values(value).every(valid);
-}
-
-function validCorrelation(value: unknown): boolean {
-  if (!isLedgerObject(value)) return false;
-  try {
-    const normalised = normaliseCorrelation(value as CorrelationMetadata);
-    // `normaliseCorrelation` drops nulls. The closed schema does not, so equality is part of validation.
-    return JSON.stringify(normalised) === JSON.stringify(value);
-  } catch {
-    return false;
-  }
-}
-
-function validRefusal(value: unknown): boolean {
-  if (!isLedgerObject(value) || Object.keys(value).some((key) => !["code", "message", "details"].includes(key))) return false;
-  if (!REFUSAL_CODES.includes(value.code as never) || typeof value.message !== "string") return false;
-  return optional(value, "details", (details) => isLedgerObject(details) && Object.values(details).every(
-    (entry) => entry === null || ["string", "number", "boolean"].includes(typeof entry),
-  ));
-}
-
-function validDefinitionDigest(value: unknown): boolean {
-  return isLedgerObject(value) &&
-    Object.keys(value).every((key) => ["name", "source", "sha256"].includes(key)) &&
-    typeof value.name === "string" && typeof value.source === "string" && SHA256_RE.test(String(value.sha256));
-}
-
-function validApprovalUse(value: unknown): boolean {
-  return isLedgerObject(value) && Object.keys(value).every((key) => ["max", "remaining"].includes(key)) &&
-    Number.isInteger(value.max) && (value.max as number) >= 0 &&
-    Number.isInteger(value.remaining) && (value.remaining as number) >= 0;
-}
-
-function validateBase(event: LedgerV3Object): string | null {
-  if (!isTimestamp(event.ts)) return "ts must be an RFC 3339 timestamp";
-  if (!isExecutionId(event.executionId)) return "executionId is missing or invalid";
-  if (event.parentExecutionId !== null && !isExecutionId(event.parentExecutionId)) {
-    return "parentExecutionId must be an execution id or null";
-  }
-  if (event.parentExecutionId === event.executionId) return "an execution cannot be its own parent";
-  if (!isLedgerDisplayIdentifier(event.childId)) return "childId is missing or invalid";
-  return null;
-}
-
-function validateCapabilityDecision(event: LedgerV3Object): string | null {
-  if (!isLedgerDisplayIdentifier(event.parentId) || !Number.isInteger(event.depth) || (event.depth as number) < 0) {
-    return "capability decision identity is invalid";
-  }
-  for (const field of ["requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked"]) {
-    if (!isStringArray(event[field]) || !event[field].every(isLedgerCapabilityIdentifier)) {
-      return `capability decision ${field} must contain capability identifiers`;
-    }
-  }
-  if (typeof event.blocked !== "boolean" || !EXECUTORS.has(String(event.executor)) || !SHA256_RE.test(String(event.taskDigest))) {
-    return "capability decision required fields are invalid";
-  }
-  if (!optional(event, "agentType", isLedgerDisplayIdentifier) ||
-      !optional(event, "reason", (value) => typeof value === "string") ||
-      !optional(event, "approved", (value) => isStringArray(value) && value.every(isLedgerCapabilityIdentifier)) ||
-      !optional(event, "approvalSource", (value) => APPROVAL_SOURCES.has(String(value))) ||
-      !optional(event, "approvalSources", (value) => capabilityMap(value, (entry) => APPROVAL_SOURCES.has(String(entry)))) ||
-      !optional(event, "approvalScopes", (value) => capabilityMap(value, (entry) => APPROVAL_SCOPES.has(String(entry)))) ||
-      !optional(event, "approvalExpiresAt", (value) => capabilityMap(value, isTimestamp)) ||
-      !optional(event, "approvalUses", (value) => capabilityMap(value, validApprovalUse)) ||
-      !optional(event, "approvalScope", (value) => APPROVAL_SCOPES.has(String(value))) ||
-      !optional(event, "humanDenied", (value) => value === true) ||
-      !optional(event, "gateOutcome", (value) => GATE_OUTCOMES.has(String(value))) ||
-      !optional(event, "definitionDigest", validDefinitionDigest) ||
-      !optional(event, "taskFrom", isLedgerDisplayIdentifier) ||
-      !optional(event, "taskFromExecutionId", isExecutionId) ||
-      !optional(event, "correlation", validCorrelation) ||
-      !optional(event, "refusal", validRefusal)) {
-    return "capability decision optional fields are invalid";
-  }
-  return null;
-}
-
-function validateWorkspaceLease(event: LedgerV3Object): string | null {
-  if (!isLedgerDisplayIdentifier(event.workspaceId) || !isNonEmptyString(event.root) ||
-      !["read", "write"].includes(String(event.access)) || !LEASE_OUTCOMES.has(String(event.outcome))) {
-    return "workspace lease required fields are invalid";
-  }
-  if (!optional(event, "recovered", (value) => value === true || value === false || value === "unknown") ||
-      !optional(event, "releaseReason", (value) => typeof value === "string") ||
-      !optional(event, "refusal", validRefusal) || !optional(event, "correlation", validCorrelation)) {
-    return "workspace lease optional fields are invalid";
-  }
-  return null;
-}
-
-function validateChildLifecycle(event: LedgerV3Object): string | null {
-  if (!["starting", "running", "completed", "failed"].includes(String(event.state)) || !EXECUTORS.has(String(event.executor))) {
-    return "child lifecycle required fields are invalid";
-  }
-  if (["starting", "running"].includes(String(event.state)) && !isTimestamp(event.deadlineAt)) {
-    return "deadlineAt is required and must be an RFC 3339 timestamp for a non-terminal lifecycle";
-  }
-  if (!optional(event, "deadlineAt", isTimestamp) ||
-      !optional(event, "exitCode", (value) => value === null || Number.isInteger(value)) ||
-      !optional(event, "signal", (value) => value === null || PROCESS_SIGNALS.has(String(value))) ||
-      !optional(event, "timedOut", (value) => value === true) ||
-      !optional(event, "aborted", (value) => value === true) ||
-      !optional(event, "truncated", (value) => value === true) ||
-      !optional(event, "reason", (value) => typeof value === "string") ||
-      !optional(event, "correlation", validCorrelation)) {
-    return "child lifecycle optional fields are invalid";
-  }
-  if (!optional(event, "herdrPaneId", isLedgerDisplayIdentifier) ||
-      !optional(event, "herdrAgentName", isLedgerDisplayIdentifier)) {
-    return "Herdr runtime identity is invalid";
-  }
-  if (Object.hasOwn(event, "herdrPaneId") !== Object.hasOwn(event, "herdrAgentName")) {
-    return "Herdr runtime identity must be paired";
-  }
-  if (Object.hasOwn(event, "herdrPaneId") && event.executor !== "herdr") {
-    return "Herdr runtime identity requires the Herdr executor";
-  }
-  return null;
-}
-
-function validateCheckReceipt(event: LedgerV3Object): string | null {
-  if (!SHA256_RE.test(String(event.receiptId)) || !isLedgerDisplayIdentifier(event.workspaceId) ||
-      !isLedgerDisplayIdentifier(event.checkId) || !isNonEmptyString(event.treeSha) ||
-      !optional(event, "correlation", validCorrelation)) {
-    return "check receipt required fields are invalid";
-  }
-  return null;
-}
-
-function validateWorkflowFact(event: LedgerV3Object): string | null {
-  if (!isTimestamp(event.ts) || !isWorkflowFactId(event.factId) ||
-      !isWorkflowIdentifier(event.source) || !isWorkflowIdentifier(event.subject) ||
-      !["planned", "observed", "controller_validated"].includes(String(event.provenance)) ||
-      !["workflow_phase", "inline_skill", "transition"].includes(String(event.kind)) ||
-      !["pending", "observed", "started", "completed", "blocked"].includes(String(event.state)) ||
-      !validCorrelation(event.correlation) ||
-      !isNonEmptyString((event.correlation as LedgerV3Object).run_id)) {
-    return "workflow fact required fields are invalid";
-  }
-  return workflowFactStateMatches(event.provenance, event.state)
-    ? null
-    : "workflow fact provenance contradicts its state";
-}
-
-/** Exact, content-free runtime validation for one closed ledger v3 event. */
-export function validateLedgerV3Event(event: LedgerV3Object): string | null {
-  if (event.ledgerVersion !== 3) return "unsupported ledger version";
-  const kind = event.event;
-  if (typeof kind !== "string" || !Object.hasOwn(FIELDS, kind)) return "unknown ledger event discriminator";
-  const allowed = FIELDS[kind as EventKind];
-  if (Object.keys(event).some((field) => !allowed.has(field))) return "ledger v3 contains an unsupported field";
-  if (kind === "workflow_fact") return validateWorkflowFact(event);
-  const base = validateBase(event);
-  if (base) return base;
-  if (kind === "capability_decision") return validateCapabilityDecision(event);
-  if (kind === "workspace_lease") return validateWorkspaceLease(event);
-  if (kind === "child_lifecycle") return validateChildLifecycle(event);
-  return validateCheckReceipt(event);
-}
-
-/** Ensure a public builder cannot emit bytes the closed v3 reader would reject. */
-export function assertLedgerV3Wire<T extends object>(event: T): T {
-  let wire: unknown;
-  try {
-    wire = JSON.parse(JSON.stringify(event));
-  } catch (error) {
-    throw new TypeError(`invalid ledger v3 event: ${String(error)}`);
-  }
-  if (!isLedgerObject(wire)) throw new TypeError("invalid ledger v3 event: event is not a JSON object");
-  const invalid = validateLedgerV3Event(wire);
-  if (invalid) throw new TypeError(`invalid ledger v3 event: ${invalid}`);
-  return event;
-}