pi-daddy 0.28.0 → 0.32.0

package/dist/governance/ledger-v3-validation.js

@@ -0,0 +1,353 @@
+import { normaliseCorrelation } from "../kernel/correlation.js";
+import { isExecutionId } from "../kernel/execution-id.js";
+import { REFUSAL_CODES } from "../kernel/refusals.js";
+import { isLedgerCapabilityIdentifier, isLedgerDisplayIdentifier } from "../kernel/ledger-identifiers.js";
+/**
+ * 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 const RETIRED_LEDGER_EVENT_KINDS = new Set(["check_receipt", "workflow_fact"]);
+export function isRetiredLedgerEvent(event) {
+    return typeof event.event === "string" && RETIRED_LEDGER_EVENT_KINDS.has(event.event);
+}
+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",
+        "idleTimeoutMs",
+        "herdrPaneId",
+        "herdrAgentName",
+        "correlation",
+    ]),
+};
+export function isLedgerObject(value) {
+    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) {
+    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) {
+    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) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function optional(event, field, valid) {
+    return !Object.hasOwn(event, field) || valid(event[field]);
+}
+function stringMap(value, valid) {
+    return isLedgerObject(value) && Object.values(value).every(valid);
+}
+function capabilityMap(value, valid) {
+    return (isLedgerObject(value) && Object.keys(value).every(isLedgerCapabilityIdentifier) && Object.values(value).every(valid));
+}
+function validCorrelation(value) {
+    if (!isLedgerObject(value))
+        return false;
+    try {
+        const normalised = normaliseCorrelation(value);
+        // `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) {
+    if (!isLedgerObject(value) || Object.keys(value).some((key) => !["code", "message", "details"].includes(key)))
+        return false;
+    if (!REFUSAL_CODES.includes(value.code) || 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) {
+    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) {
+    return (isLedgerObject(value) &&
+        Object.keys(value).every((key) => ["max", "remaining"].includes(key)) &&
+        Number.isInteger(value.max) &&
+        value.max >= 0 &&
+        Number.isInteger(value.remaining) &&
+        value.remaining >= 0);
+}
+function validateBase(event) {
+    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) {
+    if (!isLedgerDisplayIdentifier(event.parentId) || !Number.isInteger(event.depth) || event.depth < 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) {
+    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) {
+    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, "idleTimeoutMs", (value) => Number.isInteger(value) && value > 0) ||
+        !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;
+}
+/** Exact, content-free runtime validation for one closed ledger v3 event. */
+export function validateLedgerV3Event(event) {
+    if (event.ledgerVersion !== 3)
+        return "unsupported ledger version";
+    const kind = event.event;
+    if (isRetiredLedgerEvent(event))
+        return null; // historical; accepted as written, never validated field by field
+    if (typeof kind !== "string" || !Object.hasOwn(FIELDS, kind))
+        return "unknown ledger event discriminator";
+    const allowed = FIELDS[kind];
+    if (Object.keys(event).some((field) => !allowed.has(field)))
+        return "ledger v3 contains an unsupported field";
+    const base = validateBase(event);
+    if (base)
+        return base;
+    if (kind === "capability_decision")
+        return validateCapabilityDecision(event);
+    if (kind === "workspace_lease")
+        return validateWorkspaceLease(event);
+    return validateChildLifecycle(event);
+}
+/** Ensure a public builder cannot emit bytes the closed v3 reader would reject. */
+export function assertLedgerV3Wire(event) {
+    let wire;
+    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;
+}
+//# sourceMappingURL=ledger-v3-validation.js.map

package/dist/governance/ledger-v3-validation.js.map

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

package/dist/governance/ledger.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Append-only grant ledger.
+ *
+ * Exists because pi-fabric's persisted execution trace records `args: {}` — it captures *that* a child
+ * ran, not *what it was authorised to do* (docs/probes/pi-fabric-eval probe 5). Without this record
+ * you cannot answer "what was this sub-agent permitted to do?" after the fact, which is the whole
+ * point of a governance layer.
+ *
+ * `denied` is the field that earns the file: an agent repeatedly requesting capabilities it does not
+ * hold is an escalation attempt, and it is invisible without a record.
+ *
+ * PRIVACY: capability ids, counts, and identifiers only. Never prompts, tool arguments, or results.
+ *
+ * ADR-0018 makes the boundary explicit rather than leaving it to be inferred, because a record now carries
+ * something about the child's instructions. **`definitionDigest` is an identifier**: a SHA-256 of an
+ * operator-authored file already committed to a repository, which names a version without reproducing it.
+ * **The task is not recorded, anywhere, ever** — it is assembled by the model from the parent's context and
+ * can carry anything the parent could see, so a ledger holding it would be a secrets sink. That half of
+ * "what was this child told to do?" is out of the ledger by decision, not by omission.
+ */
+import type { Capability, ResolveResult } from "../kernel/resolve.ts";
+import type { ExecutorKind } from "../kernel/delegate-types.ts";
+import type { DefinitionDigest } from "../kernel/definitions.ts";
+import type { ApprovalScope, ApprovalSource } from "../kernel/approval.ts";
+import type { PromptOutcomeKind } from "./approval-prompt.ts";
+import type { CorrelationMetadata } from "../kernel/correlation.ts";
+import type { StructuredRefusal } from "../kernel/refusals.ts";
+import type { RuntimeLedgerEvent } from "./ledger-events.ts";
+export declare const LEDGER_VERSION: 3;
+export declare const LEDGER_EVENT_KINDS: readonly ["capability_decision", "workspace_lease", "child_lifecycle"];
+export type LedgerEventKind = (typeof LEDGER_EVENT_KINDS)[number];
+export declare const LEDGER_GATE_OUTCOMES: readonly ["declined", "dismissed", "no-ui", "error"];
+export type LedgerGateOutcome = (typeof LEDGER_GATE_OUTCOMES)[number];
+export interface LedgerEventBase {
+    /** Optional only on the legacy-compatible `GrantRecord` public type; every v3 event builder writes it. */
+    ledgerVersion?: typeof LEDGER_VERSION;
+    event?: LedgerEventKind;
+    ts: string;
+    /** Unique execution occurrence. Optional only for legacy, unversioned GrantRecord values. */
+    executionId?: string;
+    /** Explicit execution parent; null means the delegating session is not itself a governed child. */
+    parentExecutionId?: string | null;
+    childId?: string;
+    correlation?: CorrelationMetadata;
+}
+export interface GrantRecord extends LedgerEventBase {
+    /**
+     * Present only when a trusted `taskDigest` was supplied — that is what makes a line v3. `buildRecord`
+     * does NOT always emit it, and the comment here used to say it did while the emission site 200 lines
+     * down said the opposite. Two comments asserting contradictory facts about one field is R-28's shape.
+     */
+    event?: "capability_decision";
+    parentId: string;
+    childId: string;
+    depth: number;
+    agentType?: string;
+    requested: Capability[];
+    parentGrant: Capability[];
+    effective: Capability[];
+    denied: Capability[];
+    clipped: Capability[];
+    gatedBlocked: Capability[];
+    /** True when the spawn was refused outright rather than narrowed. */
+    blocked: boolean;
+    /** Present when the spawn was refused, or when resolution failed. */
+    reason?: string;
+    /**
+     * Gated capabilities satisfied for this spawn.
+     *
+     * The ledger used to have ONE flavour of no. It now has three, and they call for different responses:
+     *  - `denied` non-empty            -> an agent asked for more than it holds. ESCALATION ATTEMPT.
+     *  - `humanDenied`                 -> a person was asked and said no. WORKING AS DESIGNED.
+     *  - `gatedBlocked` with no source -> nobody was there to ask. A background run hit a gate; the fix is
+     *                                     an operator pre-approving it, not an incident.
+     */
+    approved?: Capability[];
+    approvalSource?: ApprovalSource;
+    /**
+     * WHERE each approved capability's yes came from — one entry per capability (R-46).
+     *
+     * `approvalSource` above is a single scalar and was written for a set: gate `tool:bash` and `tool:write`,
+     * let a persisted entry cover `bash` while a human clicks *Allow once* for `write`, and the record read
+     * `approved: ["tool:bash","tool:write"], approvalSource: "prompt"` — **asserting a human was asked about
+     * `tool:bash`, which they were not.** The ledger's whole job is answering "did a human authorise this?",
+     * so over-claiming in that direction is the worst available failure.
+     *
+     * The scalar is kept and is now written **only when every approved capability shares one source**, so a
+     * reader of old and new lines alike can trust it; when sources differ it is omitted and this map carries
+     * the truth. Two fields, one of which is a safe summary of the other — not two competing answers.
+     */
+    approvalSources?: Record<Capability, ApprovalSource>;
+    /**
+     * How far each prompted capability's yes reaches (F5). Same shape and same reason as `approvalSources`:
+     * `approvalScope` below is a **derived summary**, emitted only when every prompted capability shares one
+     * scope. This field decides propagation — `inheritApprovals` drops `once` — so a scalar that described
+     * one capability while claiming to describe the set was not merely a reporting defect.
+     */
+    approvalScopes?: Record<Capability, ApprovalScope>;
+    /** Persisted approval expiry, by capability. Session-scoped approvals have no wall-clock expiry. */
+    approvalExpiresAt?: Record<Capability, string>;
+    /** Count bounds where one exists. A consumed `once` approval records `{max:1, remaining:0}`. */
+    approvalUses?: Record<Capability, {
+        max: number;
+        remaining: number;
+    }>;
+    /** Present only when the source was a live prompt, and only when one scope covers the whole set. */
+    approvalScope?: ApprovalScope;
+    /** A human was asked and declined. Distinct from `denied`, which is an escalation attempt. */
+    humanDenied?: true;
+    /**
+     * WHY a gate went unsatisfied, when the answer was not a yes.
+     *
+     * `PromptOutcomeKind` has five members and this record kept exactly one of them (`humanDenied`, from
+     * `declined`). So `no-ui`, `dismissed` (a timeout or an abort) and `error` produced **identical** records
+     * — `gatedBlocked` non-empty, no `approvalSource`, `blocked: true` — and the only thing separating them
+     * was free-text `reason`, written for a human at the call site. Given a failed run, *"was there an
+     * operator who timed out, or was there nobody to ask?"* was not answerable from any field, and the fix
+     * for each is different: one is a queue or a longer `PI_DADDY_APPROVAL_TIMEOUT`, the other is an
+     * operator pre-approving.
+     *
+     * The discriminant was already computed and thrown away. ADR-0026 leans on this vocabulary being able to
+     * say *"nobody was there to ask"* and be believed, so it is recorded rather than inferred.
+     *
+     * **Privacy is unchanged**: this is a fixed five-member enum, not text — nothing model-authored, nothing
+     * a task could carry. The prompt has five outcomes, but `granted` is deliberately omitted from the
+     * four-member ledger enum because the approval source/scope fields already record a yes.
+     */
+    gateOutcome?: LedgerGateOutcome;
+    /**
+     * WHICH operator-authored instructions this child was given (ADR-0018).
+     *
+     * Identifies, never reproduces: matching digests prove two children ran the same text, and a digest that
+     * no longer matches the file proves the definition changed since. **It says nothing about whether those
+     * instructions were correct or whether the child obeyed them** — it identifies text, it does not evaluate
+     * it. Absent for a `tools:`-style delegation, which has no definition.
+     */
+    definitionDigest?: DefinitionDigest;
+    /**
+     * WHERE this child ran — ADR-0031.
+     *
+     * **Required rather than optional**, which is unusual in this record and deliberate. Before ADR-0031 the
+     * executor was a variable an operator set, so "which one ran?" was answerable from configuration after the
+     * fact. It is now decided by a **runtime probe** at session start, so nothing outside the record preserves
+     * the answer — and the two paths do not produce the same argv, because the herdr plan withholds `--print`
+     * (`delegationContext.interactive`). A trail that cannot say where a child ran cannot be read back
+     * reliably, and reading it back is the only reason it exists.
+     *
+     * Written on refusals too, including the tripwire's: the honest value there is the executor the session
+     * *would* have used, because a refused spawn has no executor of its own.
+     */
+    executor: ExecutorKind;
+    /**
+     * The child whose OUTPUT composed this child's task — ADR-0033.
+     *
+     * **Optional, unlike `executor`, and the asymmetry is deliberate.** A non-chained spawn has no prior author, and
+     * an empty string would assert one. Present only on chain steps after the first.
+     *
+     * Why it is recorded at all: a chain makes step N's task the output of a governed child, and ADR-0033's chosen
+     * handoff is *framing* rather than enforcement. So "who wrote this instruction?" is exactly the question that
+     * decision makes worth asking, and it is unanswerable from any other field — `agentType` names the definition,
+     * `definitionDigest` names its instructions, and neither says where the TASK came from.
+     */
+    taskFrom?: string;
+    /** Unique occurrence whose output composed this task; taskFrom remains the readable logical position. */
+    taskFromExecutionId?: string;
+    /** Trusted SHA-256 of the exact task; task text remains forbidden (ADR-0034). */
+    taskDigest?: string;
+    /** Stable machine-readable refusal accompanying `reason`. */
+    refusal?: StructuredRefusal;
+}
+export interface LedgerOptions {
+    /** Path to the JSONL file. Parent directories are created on demand. */
+    path: string;
+    /**
+     * When true, a ledger write failure throws instead of being swallowed.
+     *
+     * Default is `true` and that is deliberate: for a security control, an unrecorded grant should fail
+     * closed. Set false only where the ledger is advisory.
+     */
+    strict?: boolean;
+    /**
+     * Called when a NON-strict append failed. Required in spirit rather than in types: a caller that opts
+     * out of failing closed still has to say something, or the ledger silently develops holes.
+     */
+    onFailure?: (error: unknown) => void;
+}
+export declare function buildRecord(args: {
+    /** Required whenever taskDigest makes this an explicit v3 event. */
+    executionId?: string;
+    /** Required (including explicit null) whenever taskDigest makes this an explicit v3 event. */
+    parentExecutionId?: string | null;
+    parentId: string;
+    childId: string;
+    depth: number;
+    agentType?: string;
+    requested: Capability[];
+    parentGrant: Capability[];
+    result: ResolveResult;
+    blocked: boolean;
+    reason?: string;
+    approved?: Capability[];
+    approvalSources?: Record<Capability, ApprovalSource>;
+    approvalScopes?: Record<Capability, ApprovalScope>;
+    approvalExpiresAt?: Record<Capability, string>;
+    approvalUses?: Record<Capability, {
+        max: number;
+        remaining: number;
+    }>;
+    humanDenied?: boolean;
+    gateOutcome?: PromptOutcomeKind;
+    definitionDigest?: DefinitionDigest;
+    /** Where the child ran (ADR-0031). Required: the probe's answer survives nowhere else. */
+    executor: ExecutorKind;
+    /** The logical child whose output composed this task (ADR-0033). */
+    taskFrom?: string;
+    /** The unique occurrence whose output composed this task. */
+    taskFromExecutionId?: string;
+    taskDigest?: string;
+    correlation?: CorrelationMetadata;
+    refusal?: StructuredRefusal;
+    now: Date;
+}): GrantRecord;
+export { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from "./file-lock.ts";
+export { verifyLedger, type LedgerReport } from "./ledger-report.ts";
+/**
+ * Serialise appends across processes.
+ *
+ * **Why the ledger needs it.** For most of this package's life cardinality was bounded to one by `delegate`
+ * being blocking, so there was never a second writer. Fan-out removes that: `ENV_LEDGER` propagates to
+ * children, so a subtree can have many processes appending to one file.
+ *
+ * A ledger write that cannot take the lock **fails the delegation closed** — see `appendRecord`'s `strict`
+ * — because a child running with granted capabilities and no audit line is what the ledger exists to
+ * prevent. That is the opposite of what the approvals store does with the same lock, and deliberately so.
+ */
+/** The envelope kind for a governance event. Every LedgerEventKind maps; an unknown event shape is a `fact`. */
+export declare function recordKindForEvent(event: {
+    event?: string;
+}): RecordKind;
+export declare function appendLedgerEvent(options: LedgerOptions, event: RuntimeLedgerEvent | GrantRecord): Promise<void>;
+export declare function appendRecord(options: LedgerOptions, record: GrantRecord): Promise<void>;
+/** True when this record shows an agent asking for more than it holds. */
+export declare function isEscalationAttempt(record: GrantRecord): boolean;
+export { CHILD_LIFECYCLE_STATES, CHILD_PROCESS_SIGNALS, WORKSPACE_ACCESSES, WORKSPACE_LEASE_OUTCOMES, WORKSPACE_RECOVERY_VALUES, buildChildLifecycleEvent, buildWorkspaceLeaseEvent, type CapabilityDecisionEvent, type ChildLifecycleEvent, type ChildLifecycleState, type ChildProcessSignal, type RuntimeLedgerEvent, type WorkspaceAccess, type WorkspaceLeaseEvent, type WorkspaceLeaseOutcome, type WorkspaceRecovery, } from "./ledger-events.ts";
+import { type RecordKind } from "./record.ts";
+/**
+ * One-time import of a pre-format ledger (`.pi/grants.jsonl` written before ADR-0076 PR 3d) into a record
+ * envelope file. Each intact line becomes one record with an `imported` marker naming the source and line;
+ * the source is never modified. Import stops at the first unparsable source line and reports it, so a torn
+ * legacy tail is visible rather than silently dropped. Returns what happened; a target that already exists
+ * is left alone (`skipped: "target-exists"`).
+ */
+export declare function importLegacyLedger(sourcePath: string, targetPath: string): Promise<{
+    imported: number;
+    stoppedAt: number | null;
+    skipped: "target-exists" | "source-missing" | null;
+}>;
+//# sourceMappingURL=ledger.d.ts.map

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

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