pi-daddy 0.28.0 → 0.32.0

package/dist/governance/ledger-events.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The v3 runtime-event half of the ledger: workspace leases and child lifecycle, with
+ * their builders. Split out of `./ledger.ts` only to stay under the 400-line module ceiling this
+ * project enforces mechanically; `./ledger.ts` re-exports everything here, so "the ledger module"
+ * remains one import.
+ */
+import { LEDGER_VERSION, type LedgerEventBase, type GrantRecord } from "./ledger.ts";
+import type { ExecutorKind } from "../kernel/delegate-types.ts";
+import type { CorrelationMetadata } from "../kernel/correlation.ts";
+import type { StructuredRefusal } from "../kernel/refusals.ts";
+export declare const WORKSPACE_ACCESSES: readonly ["read", "write"];
+export type WorkspaceAccess = (typeof WORKSPACE_ACCESSES)[number];
+export declare const WORKSPACE_RECOVERY_VALUES: readonly [false, true, "unknown"];
+export type WorkspaceRecovery = (typeof WORKSPACE_RECOVERY_VALUES)[number];
+export declare const CHILD_LIFECYCLE_STATES: readonly ["starting", "running", "completed", "failed"];
+export type ChildLifecycleState = (typeof CHILD_LIFECYCLE_STATES)[number];
+/** The complete Node signal vocabulary accepted by a v3 child-lifecycle event. */
+export declare const CHILD_PROCESS_SIGNALS: readonly ["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"];
+export type ChildProcessSignal = (typeof CHILD_PROCESS_SIGNALS)[number];
+/**
+ * `released` is a handover this owner performed. FOUR members were added by the 0.18.0 review pass, and
+ * they were not all previously recorded the same way — `uncontended` was recorded as an *acquisition*, and
+ * `lost` was recorded as nothing at all, because the old `release()` threw before the append ran:
+ *   `lost`     the kernel lock went away under a live governed writer — NOT the same fact as a user
+ *              cancelling, which is what it used to be indistinguishable from (R-103);
+ *   `retained` the lease was deliberately kept because a herdr writer tab would not close, so the
+ *              successor's `recovered: true` would otherwise blame a healthy path (R-104);
+ *   `uncontended` a read lease took no kernel lock at all, so counting it as an acquisition
+ *              overstated how many exclusions the kernel actually performed (R-105).
+ */
+export declare const WORKSPACE_LEASE_OUTCOMES: readonly ["acquired", "uncontended", "refused", "released", "released-unrecorded", "lost", "retained", "timeout", "recovered"];
+export type WorkspaceLeaseOutcome = (typeof WORKSPACE_LEASE_OUTCOMES)[number];
+export interface WorkspaceLeaseEvent extends LedgerEventBase {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "workspace_lease";
+    executionId: string;
+    parentExecutionId: string | null;
+    childId: string;
+    workspaceId: string;
+    root: string;
+    access: WorkspaceAccess;
+    outcome: WorkspaceLeaseOutcome;
+    /** `"unknown"` when the prior owner's record was unreadable — not evidence of a clean handover. */
+    recovered?: WorkspaceRecovery;
+    releaseReason?: string;
+    refusal?: StructuredRefusal;
+}
+export interface ChildLifecycleEvent extends LedgerEventBase {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "child_lifecycle";
+    executionId: string;
+    parentExecutionId: string | null;
+    childId: string;
+    state: ChildLifecycleState;
+    executor: ExecutorKind;
+    /** Bound after which a non-terminal start is known to be incomplete. */
+    deadlineAt?: string;
+    /** Herdr runtime identity is observational and never an enforcement boundary. */
+    herdrPaneId?: string;
+    herdrAgentName?: string;
+    exitCode?: number | null;
+    signal?: ChildProcessSignal | null;
+    timedOut?: true;
+    aborted?: true;
+    truncated?: true;
+    reason?: string;
+    /** The inactivity bound (ms) that governed this child beside the `deadlineAt` ceiling (PR 3e). */
+    idleTimeoutMs?: number;
+}
+export type CapabilityDecisionEvent = GrantRecord & {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "capability_decision";
+    executionId: string;
+    parentExecutionId: string | null;
+    taskDigest: string;
+};
+export type RuntimeLedgerEvent = CapabilityDecisionEvent | WorkspaceLeaseEvent | ChildLifecycleEvent;
+export declare function buildWorkspaceLeaseEvent(args: {
+    executionId: string;
+    parentExecutionId: string | null;
+    childId: string;
+    workspaceId: string;
+    root: string;
+    access: WorkspaceAccess;
+    outcome: WorkspaceLeaseOutcome;
+    recovered?: WorkspaceRecovery;
+    releaseReason?: string;
+    refusal?: StructuredRefusal;
+    correlation?: CorrelationMetadata;
+    now: Date;
+}): WorkspaceLeaseEvent;
+export declare function buildChildLifecycleEvent(args: {
+    executionId: string;
+    parentExecutionId: string | null;
+    childId: string;
+    state: ChildLifecycleState;
+    executor: ExecutorKind;
+    deadlineAt?: string;
+    idleTimeoutMs?: number;
+    herdrPaneId?: string;
+    herdrAgentName?: string;
+    exitCode?: number | null;
+    signal?: ChildProcessSignal | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    truncated?: boolean;
+    reason?: string;
+    correlation?: CorrelationMetadata;
+    now: Date;
+}): ChildLifecycleEvent;
+//# sourceMappingURL=ledger-events.d.ts.map

package/dist/governance/ledger-events.d.ts.map

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

package/dist/governance/ledger-events.js

@@ -0,0 +1,129 @@
+/**
+ * The v3 runtime-event half of the ledger: workspace leases and child lifecycle, with
+ * their builders. Split out of `./ledger.ts` only to stay under the 400-line module ceiling this
+ * project enforces mechanically; `./ledger.ts` re-exports everything here, so "the ledger module"
+ * remains one import.
+ */
+import { LEDGER_VERSION } from "./ledger.js";
+import { assertExecutionId } from "../kernel/execution-id.js";
+import { assertLedgerV3Wire } from "./ledger-v3-validation.js";
+export const WORKSPACE_ACCESSES = ["read", "write"];
+export const WORKSPACE_RECOVERY_VALUES = [false, true, "unknown"];
+export const CHILD_LIFECYCLE_STATES = ["starting", "running", "completed", "failed"];
+/** The complete Node signal vocabulary accepted by a v3 child-lifecycle event. */
+export const CHILD_PROCESS_SIGNALS = [
+    "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",
+];
+/**
+ * `released` is a handover this owner performed. FOUR members were added by the 0.18.0 review pass, and
+ * they were not all previously recorded the same way — `uncontended` was recorded as an *acquisition*, and
+ * `lost` was recorded as nothing at all, because the old `release()` threw before the append ran:
+ *   `lost`     the kernel lock went away under a live governed writer — NOT the same fact as a user
+ *              cancelling, which is what it used to be indistinguishable from (R-103);
+ *   `retained` the lease was deliberately kept because a herdr writer tab would not close, so the
+ *              successor's `recovered: true` would otherwise blame a healthy path (R-104);
+ *   `uncontended` a read lease took no kernel lock at all, so counting it as an acquisition
+ *              overstated how many exclusions the kernel actually performed (R-105).
+ */
+export const WORKSPACE_LEASE_OUTCOMES = [
+    "acquired",
+    "uncontended",
+    "refused",
+    "released",
+    "released-unrecorded",
+    "lost",
+    "retained",
+    "timeout",
+    "recovered",
+];
+export function buildWorkspaceLeaseEvent(args) {
+    assertEventIdentity(args);
+    return assertLedgerV3Wire({
+        ledgerVersion: LEDGER_VERSION,
+        event: "workspace_lease",
+        ts: args.now.toISOString(),
+        executionId: args.executionId,
+        parentExecutionId: args.parentExecutionId,
+        childId: args.childId,
+        workspaceId: args.workspaceId,
+        root: args.root,
+        access: args.access,
+        outcome: args.outcome,
+        // `!== undefined`, not truthiness. `recovered: false` — a POSITIVE assertion that the predecessor
+        // handed over cleanly — was dropped while the truthy `"unknown"` survived, so absence meant both
+        // "clean" and "never supplied". R-100's whole argument is that absence of evidence is not evidence,
+        // and this was the one line discarding the evidence.
+        ...(args.recovered !== undefined ? { recovered: args.recovered } : {}),
+        ...(args.releaseReason ? { releaseReason: args.releaseReason } : {}),
+        ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
+        ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+    });
+}
+export function buildChildLifecycleEvent(args) {
+    assertEventIdentity(args);
+    return assertLedgerV3Wire({
+        ledgerVersion: LEDGER_VERSION,
+        event: "child_lifecycle",
+        ts: args.now.toISOString(),
+        executionId: args.executionId,
+        parentExecutionId: args.parentExecutionId,
+        childId: args.childId,
+        state: args.state,
+        executor: args.executor,
+        ...(args.deadlineAt ? { deadlineAt: args.deadlineAt } : {}),
+        ...(args.idleTimeoutMs !== undefined ? { idleTimeoutMs: args.idleTimeoutMs } : {}),
+        ...(args.herdrPaneId ? { herdrPaneId: args.herdrPaneId } : {}),
+        ...(args.herdrAgentName ? { herdrAgentName: args.herdrAgentName } : {}),
+        ...(args.exitCode !== undefined ? { exitCode: args.exitCode } : {}),
+        ...(args.signal !== undefined ? { signal: args.signal } : {}),
+        ...(args.timedOut ? { timedOut: true } : {}),
+        ...(args.aborted ? { aborted: true } : {}),
+        ...(args.truncated ? { truncated: true } : {}),
+        ...(args.reason ? { reason: args.reason } : {}),
+        ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+    });
+}
+function assertEventIdentity(args) {
+    assertExecutionId(args.executionId);
+    if (args.parentExecutionId !== null)
+        assertExecutionId(args.parentExecutionId, "parentExecutionId");
+    if (args.parentExecutionId === args.executionId)
+        throw new TypeError("an execution cannot be its own parent");
+}
+//# sourceMappingURL=ledger-events.js.map

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

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

package/dist/governance/ledger-report.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 type { ApprovalSource } from "../kernel/approval.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;
+    };
+    /** Events of a kind an earlier version wrote and this one no longer builds; valid history, not corruption. */
+    retired: 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/governance/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;
+}
+export declare function verifyLedger(path: string): Promise<LedgerReport>;
+//# sourceMappingURL=ledger-report.d.ts.map

package/dist/governance/ledger-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-report.d.ts","sourceRoot":"","sources":["../../src/governance/ledger-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAQ5D,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAC;IAChB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACpF,8GAA8G;IAC9G,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,yFAAyF;IACzF,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,SAAS,EAAE;QACT,2FAA2F;QAC3F,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACzC,2EAA2E;QAC3E,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACjD,0GAA0G;QAC1G,YAAY,EAAE,MAAM,CAAC;QACrB,uFAAuF;QACvF,WAAW,EAAE,MAAM,CAAC;QACpB;;;;;;;;WAQG;QACH,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,EAAE,EAAE,OAAO,CAAC;CACb;AA4DD,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAkNtE"}