pi-daddy 0.17.1 → 0.18.0

package/dist/delegation-approval.d.ts

@@ -0,0 +1,36 @@
+import { type InheritableApproval } from "./approval.ts";
+import { type ApprovalBinding, type CorrelationMetadata } from "./correlation.ts";
+import type { DefinitionDigest, SkillDefinition } from "./definitions.ts";
+import { type Capability, type ResolveResult } from "./resolve.ts";
+/**
+ * Resolve the approval half of one delegation after its requested capability set is known.
+ *
+ * Kept as one function because the ordering is security-relevant: compute the unapproved and potential
+ * effective sets first, derive the exact binding from those trusted values, then decide which approvals
+ * match. An approval must never define the scope against which it is checked.
+ */
+export declare function resolveDelegationApproval(input: {
+    task: string;
+    agent?: string;
+    requested: Capability[];
+    parentGrant: Capability[];
+    gated: Capability[];
+    approved?: InheritableApproval[];
+    spawned?: SkillDefinition;
+    definitionDigest?: DefinitionDigest;
+    /**
+     * Present iff this call is task-bound. Its VALUES never enter the binding — only its presence selects
+     * the exact-bound regime over the legacy subject-scoped one.
+     */
+    correlation?: CorrelationMetadata;
+    /** Trusted: an id that was resolved against the operator registry and leased. Never a caller claim. */
+    boundWorkspaceId?: string;
+    /** Caller-declared label. Narrows the binding only; asserts nothing about enforcement. */
+    boundContextId?: string;
+    parentId: string;
+}): {
+    result: ResolveResult;
+    approvalBinding?: ApprovalBinding;
+    bindingMismatch: boolean;
+};
+//# sourceMappingURL=delegation-approval.d.ts.map

package/dist/delegation-approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-approval.d.ts","sourceRoot":"","sources":["../src/delegation-approval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE3E,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAA2B,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAE5F;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CA6DzF"}

package/dist/delegation-approval.js

@@ -0,0 +1,67 @@
+import { DELEGATE_SUBJECT } from "./approval.js";
+import { agentCapability } from "./capabilities.js";
+import { approvalBindingsEqual, buildApprovalBinding, } from "./correlation.js";
+import { AGENT_WILDCARD, resolve } from "./resolve.js";
+/**
+ * Resolve the approval half of one delegation after its requested capability set is known.
+ *
+ * Kept as one function because the ordering is security-relevant: compute the unapproved and potential
+ * effective sets first, derive the exact binding from those trusted values, then decide which approvals
+ * match. An approval must never define the scope against which it is checked.
+ */
+export function resolveDelegationApproval(input) {
+    const subject = input.agent ?? DELEGATE_SUBJECT;
+    const unapproved = resolve({
+        requested: input.requested,
+        parentGrant: input.parentGrant,
+        gated: input.gated,
+        approved: [],
+    });
+    // ADR-0024: a definition's authorising id is gated as the PARENT's authority to run it now. It never
+    // joins requested/effective, because that would hand the child authority to recursively spawn itself.
+    let authorisingCapability;
+    if (input.spawned) {
+        const authorising = agentCapability(input.spawned.name);
+        if (input.gated.includes(authorising) || input.gated.includes(AGENT_WILDCARD)) {
+            authorisingCapability = authorising;
+            unapproved.gatedBlocked = [...unapproved.gatedBlocked, authorising];
+        }
+    }
+    const potential = resolve({
+        requested: input.requested,
+        parentGrant: input.parentGrant,
+        gated: input.gated,
+        // If the definition also declares its own authorising `agent:<name>`, the same approval unblocks
+        // that requested child capability too; excluding it here would bind a smaller set than we provision.
+        approved: unapproved.gatedBlocked,
+    });
+    const approvalBinding = input.correlation
+        ? buildApprovalBinding({
+            task: input.task,
+            requested: input.requested,
+            effective: potential.effective,
+            definitionSha256: input.definitionDigest?.sha256,
+            parentId: input.parentId,
+            workspaceId: input.boundWorkspaceId,
+            contextId: input.boundContextId,
+        })
+        : undefined;
+    const forSubject = (input.approved ?? []).filter((approval) => approval.subject === subject);
+    const approvedCapabilities = forSubject
+        .filter((approval) => approvalBinding
+        ? approvalBindingsEqual(approval.binding, approvalBinding)
+        : approval.binding === undefined)
+        .map((approval) => approval.capability);
+    const bindingMismatch = approvalBinding !== undefined && forSubject.some((approval) => approval.binding !== undefined && !approvalBindingsEqual(approval.binding, approvalBinding));
+    const result = resolve({
+        requested: input.requested,
+        parentGrant: input.parentGrant,
+        gated: input.gated,
+        approved: approvedCapabilities,
+    });
+    if (authorisingCapability && !approvedCapabilities.includes(authorisingCapability)) {
+        result.gatedBlocked = [...result.gatedBlocked, authorisingCapability];
+    }
+    return { result, ...(approvalBinding ? { approvalBinding } : {}), bindingMismatch };
+}
+//# sourceMappingURL=delegation-approval.js.map

package/dist/delegation-approval.js.map

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

package/dist/git-identity.d.ts

@@ -0,0 +1,13 @@
+import type { ValidatedWorkspace } from "./workspace.ts";
+export interface GitCandidateIdentity {
+    headSha: string;
+    treeSha: string;
+}
+/** Compute HEAD plus NON-IGNORED tracked/untracked candidate content without changing the real index.
+ *
+ * NOT the exact working tree: `git add -A` honours `.gitignore`, `core.excludesFile` and
+ * `$GIT_DIR/info/exclude`, and records only a gitlink for a submodule. And it is not read-only — it writes
+ * blob objects into the real `.git/objects`. `docs/SPEC.md` retracted the word "exact"; this comment said
+ * it for one more round. */
+export declare function computeGitCandidateIdentity(workspace: ValidatedWorkspace): Promise<GitCandidateIdentity>;
+//# sourceMappingURL=git-identity.d.ts.map

package/dist/git-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-identity.d.ts","sourceRoot":"","sources":["../src/git-identity.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAIzD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;4BAK4B;AAC5B,wBAAsB,2BAA2B,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA8B9G"}

package/dist/git-identity.js

@@ -0,0 +1,44 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { GovernanceRefusal, refusal } from "./refusals.js";
+const execFileAsync = promisify(execFile);
+/** Compute HEAD plus NON-IGNORED tracked/untracked candidate content without changing the real index.
+ *
+ * NOT the exact working tree: `git add -A` honours `.gitignore`, `core.excludesFile` and
+ * `$GIT_DIR/info/exclude`, and records only a gitlink for a submodule. And it is not read-only — it writes
+ * blob objects into the real `.git/objects`. `docs/SPEC.md` retracted the word "exact"; this comment said
+ * it for one more round. */
+export async function computeGitCandidateIdentity(workspace) {
+    const dir = await mkdtemp(join(tmpdir(), "pi-daddy-index-"));
+    const index = join(dir, "index");
+    const env = {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        LANG: process.env.LANG,
+        LC_ALL: process.env.LC_ALL,
+        TMPDIR: process.env.TMPDIR,
+        GIT_INDEX_FILE: index,
+    };
+    const git = async (args) => (await execFileAsync("git", ["-C", workspace.root, ...args], {
+        env, encoding: "utf8", maxBuffer: 16 * 1024 * 1024,
+    })).stdout.trim();
+    try {
+        const headSha = await git(["rev-parse", "HEAD"]);
+        await git(["read-tree", "HEAD"]);
+        await git(["add", "-A"]);
+        const treeSha = await git(["write-tree"]);
+        if (!/^[a-f0-9]{40,64}$/i.test(headSha) || !/^[a-f0-9]{40,64}$/i.test(treeSha))
+            throw new Error("Git returned an invalid object id");
+        return { headSha, treeSha };
+    }
+    catch (error) {
+        throw new GovernanceRefusal(refusal("CHECK_IDENTITY_UNAVAILABLE", `could not compute exact Git head/candidate-tree identity for workspace ${workspace.workspaceId} (${String(error)})`, { workspace_id: workspace.workspaceId }));
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=git-identity.js.map

package/dist/git-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-identity.js","sourceRoot":"","sources":["../src/git-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAO1C;;;;;4BAK4B;AAC5B,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,SAA6B;IAC7E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,GAAG,GAAsB;QAC7B,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI;QACtB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI;QACtB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI;QACtB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM;QAC1B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM;QAC1B,cAAc,EAAE,KAAK;KACtB,CAAC;IACF,MAAM,GAAG,GAAG,KAAK,EAAE,IAAc,EAAE,EAAE,CAAC,CAAC,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE;QACjG,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;KACnD,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAClB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;QACjD,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;QACjC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACzB,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACrI,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,OAAO,CACjC,4BAA4B,EAC5B,0EAA0E,SAAS,CAAC,WAAW,KAAK,MAAM,CAAC,KAAK,CAAC,GAAG,EACpH,EAAE,YAAY,EAAE,SAAS,CAAC,WAAW,EAAE,CACxC,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
 export { resolve, assertNarrowing, toPiToolsAllowlist, UNIVERSAL_CAPABILITIES, type Capability, type ResolveInput, type ResolveResult, } from "./resolve.ts";
-export { appendRecord, buildRecord, isEscalationAttempt, type GrantRecord, type LedgerOptions, } from "./ledger.ts";
+export { appendLedgerEvent, appendRecord, buildChildLifecycleEvent, buildRecord, buildWorkspaceLeaseEvent, isEscalationAttempt, LEDGER_VERSION, type CheckReceiptLedgerEvent, type ChildLifecycleEvent, type GrantRecord, type LedgerOptions, type RuntimeLedgerEvent, type WorkspaceLeaseEvent, type WorkspaceLeaseOutcome, } from "./ledger.ts";
 export { planSpawn, type SpawnPlan, type SpawnPlanInput } from "./spawn.ts";
 export { APPROVAL_TTL_DAYS, DELEGATE_SUBJECT, approvalKey, entryVerdict, expiryFor, inheritApprovals, offeredScopes, resolveApprovals, shouldSeekApproval, type ApprovalEntry, type ApprovalPath, type ApprovalScope, type ApprovalSource, type EntryVerdict, type SubjectSnapshot, } from "./approval.ts";
 export { approvalsPath, loadApprovals, revokeAll, revokeApproval, saveApproval, type DroppedApproval, type SubjectLookup, } from "./approval-store.ts";
+export { approvalBindingDigest, approvalBindingsEqual, buildApprovalBinding, digestCapabilities, digestTask, isApprovalBinding, normaliseCorrelation, type ApprovalBinding, type CorrelationMetadata, type JsonValue, } from "./correlation.ts";
+export { GovernanceRefusal, REFUSAL_CODES, refusal, type RefusalCode, type StructuredRefusal, } from "./refusals.ts";
+export { acquireWorkspaceLease, defaultWorkspaceLeaseDir, loadWorkspaceRegistry, resolveWorkspace, validateRegisteredWorkspace, type ValidatedWorkspace, type WorkspaceAccess, type WorkspaceLease, type WorkspaceRegistryFile, } from "./workspace.ts";
+export { buildCheckEnvironment, runNamedCheck, type CheckDefinition, type CheckReceipt, type CheckRegistry, } from "./check-runner.ts";
 export { createApprovalGate, createApprovalGateProvider, timeoutMsFromEnv, type ApprovalGate, type InFlightApprovals, type ApprovalUI, type PromptOutcome, type PromptOutcomeKind, type PromptRequest, } from "./approval-prompt.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,WAAW,EACX,wBAAwB,EACxB,mBAAmB,EACnB,cAAc,EACd,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,OAAO,EACP,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,EAChB,2BAA2B,EAC3B,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,7 +1,11 @@
 export { resolve, assertNarrowing, toPiToolsAllowlist, UNIVERSAL_CAPABILITIES, } from "./resolve.js";
-export { appendRecord, buildRecord, isEscalationAttempt, } from "./ledger.js";
+export { appendLedgerEvent, appendRecord, buildChildLifecycleEvent, buildRecord, buildWorkspaceLeaseEvent, isEscalationAttempt, LEDGER_VERSION, } from "./ledger.js";
 export { planSpawn } from "./spawn.js";
 export { APPROVAL_TTL_DAYS, DELEGATE_SUBJECT, approvalKey, entryVerdict, expiryFor, inheritApprovals, offeredScopes, resolveApprovals, shouldSeekApproval, } from "./approval.js";
 export { approvalsPath, loadApprovals, revokeAll, revokeApproval, saveApproval, } from "./approval-store.js";
+export { approvalBindingDigest, approvalBindingsEqual, buildApprovalBinding, digestCapabilities, digestTask, isApprovalBinding, normaliseCorrelation, } from "./correlation.js";
+export { GovernanceRefusal, REFUSAL_CODES, refusal, } from "./refusals.js";
+export { acquireWorkspaceLease, defaultWorkspaceLeaseDir, loadWorkspaceRegistry, resolveWorkspace, validateRegisteredWorkspace, } from "./workspace.js";
+export { buildCheckEnvironment, runNamedCheck, } from "./check-runner.js";
 export { createApprovalGate, createApprovalGateProvider, timeoutMsFromEnv, } from "./approval-prompt.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,eAAe,EACf,kBAAkB,EAClB,sBAAsB,GAIvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,mBAAmB,GAGpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAuC,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GAOnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,GAGb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,GAOjB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,eAAe,EACf,kBAAkB,EAClB,sBAAsB,GAIvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,WAAW,EACX,wBAAwB,EACxB,mBAAmB,EACnB,cAAc,GAQf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAuC,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GAOnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,GAGb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,UAAU,EACV,iBAAiB,EACjB,oBAAoB,GAIrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,OAAO,GAGR,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,EAChB,2BAA2B,GAK5B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,qBAAqB,EACrB,aAAa,GAId,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,GAOjB,MAAM,sBAAsB,CAAC"}

package/dist/lease-record.d.ts

@@ -0,0 +1,78 @@
+import type { ValidatedWorkspace, WorkspaceAccess } from "./workspace.ts";
+export interface LeaseMetadata {
+    version: 1;
+    state: "active" | "released";
+    token: string;
+    owner_id: string;
+    workspace_id: string;
+    root: string;
+    pid: number;
+    acquired_at: string;
+    released_at?: string;
+    release_reason?: string;
+}
+export interface WorkspaceLease {
+    workspace: ValidatedWorkspace;
+    access: WorkspaceAccess;
+    ownerId: string;
+    /**
+     * `true` only when the kernel lock was free but metadata said the prior owner never released.
+     * `"unknown"` when the prior owner's record could not be read at all — that is not evidence of a
+     * clean handover and must not be recorded as one (R-100).
+     */
+    recovered: boolean | "unknown";
+    /** Attach the governed resource so parent death cleans it before the kernel lock is released. */
+    attachProcess(pid: number): void;
+    attachHerdrTab(tabId: string): void;
+    /** Resolves only when the kernel-lock helper exits before explicit release. */
+    lost: Promise<Error>;
+    /**
+     * NEVER throws. A cleanup function that can throw destroys its caller's return value — a completed
+     * child's entire output was discarded this way (R-99) — so the outcome is a VALUE the caller records:
+     *   `"released"`            the kernel lock was handed back and the handover recorded;
+     *   `"released-unrecorded"` the lock was handed back but the record failed, so the NEXT owner will
+     *                           report a recovery that did not happen unless this is ledgered;
+     *   `"lost"`                the helper was already gone, so this owner never released anything.
+     */
+    release(reason?: string): Promise<LeaseReleaseOutcome>;
+    /**
+     * Record that this lease is being kept deliberately, WITHOUT releasing the kernel lock.
+     *
+     * Needed because a retained lease never calls `release()`, so the metadata stays `state: "active"` and
+     * whoever acquires next reports `recovered: true` — blaming a crash on a known-good path.
+     */
+    markRetained(reason?: string): Promise<void>;
+    /** Reads the give-up marker the helper leaves when it could not close a herdr writer tab. */
+    readCloseFailure(): Promise<{
+        reason: string;
+        herdr_tab?: string;
+    } | null>;
+}
+/**
+ * What a release actually did. Five members rather than three, because the first version conflated facts
+ * that call for different responses — and one of them is an alarm:
+ *   `released`             the lock went back and THIS owner wrote its own handover;
+ *   `released-unrecorded`  the lock went back and the record does not say so, so the next owner will report
+ *                          a recovery that never happened unless the caller ledgers this. **The alarm.**
+ *   `released-superseded`  the lock went back and a successor already owns the metadata, so we correctly
+ *                          declined to overwrite it. Healthy, and previously indistinguishable from the
+ *                          alarm above;
+ *   `not-held`             a read lease, which never took a kernel lock — recording it as `released`
+ *                          overstated how many handovers the kernel performed, which is R-105 on the
+ *                          release side of the same defect;
+ *   `lost`                 the helper was already gone; this owner released nothing.
+ */
+export type LeaseReleaseOutcome = "released" | "released-unrecorded" | "released-superseded" | "not-held" | "lost";
+export declare function leasePaths(leaseDir: string, root: string): {
+    lock: string;
+    metadata: string;
+    marker: string;
+};
+export declare function atomicMetadata(path: string, value: LeaseMetadata): Promise<void>;
+/**
+ * `null` means no prior owner was recorded. `"malformed"` means a record exists and cannot be read,
+ * which is strictly LESS evidence than a readable "active" one and must never read as a clean handover
+ * (R-100). Absent and unreadable are different facts; conflating them silently erases a real recovery.
+ */
+export declare function readMetadata(path: string): Promise<LeaseMetadata | null | "malformed">;
+//# sourceMappingURL=lease-record.d.ts.map

package/dist/lease-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-record.d.ts","sourceRoot":"","sources":["../src/lease-record.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,kBAAkB,CAAC;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,iGAAiG;IACjG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,+EAA+E;IAC/E,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrB;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvD;;;;;OAKG;IACH,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6FAA6F;IAC7F,gBAAgB,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC5E;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,qBAAqB,GACrB,qBAAqB,GACrB,UAAU,GACV,MAAM,CAAC;AAEX,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;;;;EAQxD;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAItF;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,GAAG,WAAW,CAAC,CAgB5F"}

package/dist/lease-record.js

@@ -0,0 +1,52 @@
+/**
+ * The lease's RECORD: what a workspace lease writes down about who holds it and how they let it go.
+ *
+ * Split from `./workspace-lease.ts` to stay under the 400-line module ceiling, along the seam this
+ * review round kept finding defects on — absent vs unreadable metadata, a swallowed handover write, a
+ * successor's token — all of which are about what the record SAYS rather than about the kernel lock.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export function leasePaths(leaseDir, root) {
+    // Canonical root, never caller-chosen workspace ID: aliases for one worktree must contend.
+    const key = createHash("sha256").update(root, "utf8").digest("hex");
+    return {
+        lock: join(leaseDir, `${key}.lock`),
+        metadata: join(leaseDir, `${key}.json`),
+        marker: join(leaseDir, `${key}.close-failed.json`),
+    };
+}
+export async function atomicMetadata(path, value) {
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await rename(temp, path);
+}
+/**
+ * `null` means no prior owner was recorded. `"malformed"` means a record exists and cannot be read,
+ * which is strictly LESS evidence than a readable "active" one and must never read as a clean handover
+ * (R-100). Absent and unreadable are different facts; conflating them silently erases a real recovery.
+ */
+export async function readMetadata(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        return error?.code === "ENOENT" ? null : "malformed";
+    }
+    try {
+        const value = JSON.parse(raw);
+        if (value?.version !== 1)
+            return "malformed";
+        if (value.state !== "active" && value.state !== "released")
+            return "malformed";
+        if (typeof value.token !== "string" || !value.token)
+            return "malformed";
+        return value;
+    }
+    catch {
+        return "malformed";
+    }
+}
+//# sourceMappingURL=lease-record.js.map

package/dist/lease-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-record.js","sourceRoot":"","sources":["../src/lease-record.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAwEjC,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,IAAY;IACvD,2FAA2F;IAC3F,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpE,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QACvC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,oBAAoB,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,KAAoB;IACrE,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC;IAC1D,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5G,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAQ,KAA+B,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;IAClF,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;QACxD,IAAI,KAAK,EAAE,OAAO,KAAK,CAAC;YAAE,OAAO,WAAW,CAAC;QAC7C,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,UAAU;YAAE,OAAO,WAAW,CAAC;QAC/E,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,WAAW,CAAC;QACxE,OAAO,KAAsB,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/ledger-events.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The v2 runtime-event half of the ledger: workspace leases, child lifecycle and check receipts, 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 "./executor.ts";
+import type { CorrelationMetadata } from "./correlation.ts";
+import type { StructuredRefusal } from "./refusals.ts";
+/**
+ * `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 type WorkspaceLeaseOutcome = "acquired" | "uncontended" | "refused" | "released" | "released-unrecorded" | "lost" | "retained" | "timeout" | "recovered";
+export interface WorkspaceLeaseEvent extends LedgerEventBase {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "workspace_lease";
+    childId: string;
+    workspaceId: string;
+    root: string;
+    access: "read" | "write";
+    outcome: WorkspaceLeaseOutcome;
+    /** `"unknown"` when the prior owner's record was unreadable — not evidence of a clean handover. */
+    recovered?: boolean | "unknown";
+    releaseReason?: string;
+    refusal?: StructuredRefusal;
+}
+export interface ChildLifecycleEvent extends LedgerEventBase {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "child_lifecycle";
+    childId: string;
+    state: "starting" | "completed" | "failed";
+    executor: ExecutorKind;
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    truncated?: boolean;
+    reason?: string;
+}
+export interface CheckReceiptLedgerEvent extends LedgerEventBase {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "check_receipt";
+    childId: string;
+    receiptId: string;
+    workspaceId: string;
+    checkId: string;
+    treeSha: string;
+}
+export type RuntimeLedgerEvent = (GrantRecord & {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "capability_decision";
+}) | WorkspaceLeaseEvent | ChildLifecycleEvent | CheckReceiptLedgerEvent;
+export declare function buildWorkspaceLeaseEvent(args: {
+    childId: string;
+    workspaceId: string;
+    root: string;
+    access: "read" | "write";
+    outcome: WorkspaceLeaseOutcome;
+    recovered?: boolean | "unknown";
+    releaseReason?: string;
+    refusal?: StructuredRefusal;
+    correlation?: CorrelationMetadata;
+    now: Date;
+}): WorkspaceLeaseEvent;
+export declare function buildChildLifecycleEvent(args: {
+    childId: string;
+    state: "starting" | "completed" | "failed";
+    executor: ExecutorKind;
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    truncated?: boolean;
+    reason?: string;
+    correlation?: CorrelationMetadata;
+    now: Date;
+}): ChildLifecycleEvent;
+//# sourceMappingURL=ledger-events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-events.d.ts","sourceRoot":"","sources":["../src/ledger-events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,aAAa,GACb,SAAS,GACT,UAAU,GACV,qBAAqB,GACrB,MAAM,GACN,UAAU,GACV,SAAS,GACT,WAAW,CAAC;AAEhB,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,KAAK,EAAE,iBAAiB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,mGAAmG;IACnG,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,KAAK,EAAE,iBAAiB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3C,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAC1B,CAAC,WAAW,GAAG;IAAE,aAAa,EAAE,OAAO,cAAc,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC,GACtF,mBAAmB,GACnB,mBAAmB,GACnB,uBAAuB,CAAC;AAE5B,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,GAAG,EAAE,IAAI,CAAC;CACX,GAAG,mBAAmB,CAmBtB;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3C,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,GAAG,EAAE,IAAI,CAAC;CACX,GAAG,mBAAmB,CAgBtB"}

package/dist/ledger-events.js

@@ -0,0 +1,45 @@
+/**
+ * The v2 runtime-event half of the ledger: workspace leases, child lifecycle and check receipts, 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";
+export function buildWorkspaceLeaseEvent(args) {
+    return {
+        ledgerVersion: LEDGER_VERSION,
+        event: "workspace_lease",
+        ts: args.now.toISOString(),
+        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) {
+    return {
+        ledgerVersion: LEDGER_VERSION,
+        event: "child_lifecycle",
+        ts: args.now.toISOString(),
+        childId: args.childId,
+        state: args.state,
+        executor: args.executor,
+        ...(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) } : {}),
+    };
+}
+//# sourceMappingURL=ledger-events.js.map

package/dist/ledger-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-events.js","sourceRoot":"","sources":["../src/ledger-events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAA0C,MAAM,aAAa,CAAC;AAuErF,MAAM,UAAU,wBAAwB,CAAC,IAWxC;IACC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,KAAK,EAAE,iBAAiB;QACxB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,kGAAkG;QAClG,iGAAiG;QACjG,oGAAoG;QACpG,qDAAqD;QACrD,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,IAYxC;IACC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,KAAK,EAAE,iBAAiB;QACxB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC;AACJ,CAAC"}

package/dist/ledger-report.d.ts

@@ -14,8 +14,26 @@ import type { ApprovalSource } from "./approval.ts";
 export interface LedgerReport {
     /** False when the file is absent — a configuration state, not damage. */
     exists: boolean;
-    /** Lines that parsed as records. */
+    /** Capability-decision records (legacy or v2). */
     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;
+        completed: number;
+        failed: number;
+    };
     /** Lines that did not, with 1-based line numbers so the report is actionable. */
     corrupt: Array<{
         line: number;
@@ -109,16 +127,5 @@ export interface LedgerReport {
     };
     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.
- */
 export declare function verifyLedger(path: string): Promise<LedgerReport>;
 //# sourceMappingURL=ledger-report.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ledger-report.d.ts","sourceRoot":"","sources":["../src/ledger-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,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;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiItE"}
+{"version":3,"file":"ledger-report.d.ts","sourceRoot":"","sources":["../src/ledger-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAKpD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QACzE,kBAAkB,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;KAChG,CAAC;IACF,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,iFAAiF;IACjF,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,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;AAkDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA4KtE"}