pi-daddy 0.27.4 → 0.32.0

package/src/intent-scheduling.ts

@@ -1,14 +0,0 @@
-import { intentKey, intentSelection, intentPriorities, type IntentState, type IntentAdmission } from "./intent-control.ts";
-import { controlShape } from "./dispatch-control.ts";
-interface Charged { intent?: IntentAdmission }
-export function nextIntent(state: IntentState, records: readonly Charged[]) {
-  return intentPriorities(state.priorities).find(p => !records.some(r => r.intent &&
-    intentKey(r.intent.selection) === intentKey(state.selection) && intentKey(r.intent.obligation) === intentKey(p.obligation)))?.obligation ?? null;
-}
-/** Explicit once-per-selection primary dispatch policy. This is not completion/acceptance accounting. */
-export function intentAdmission(state: IntentState, records: readonly Charged[], input: IntentAdmission): IntentAdmission {
-  controlShape(input, ["selection", "revision", "obligation"]);
-  const selection = intentSelection(input.selection), obligation = intentPriorities([{ obligation: input.obligation, rank: 0 }])[0].obligation;
-  if (input.revision !== state.revision || intentKey(selection) !== intentKey(state.selection) || intentKey(obligation) !== intentKey(nextIntent(state, records))) throw new Error("stale selection/revision or out-of-priority dispatch");
-  return { selection, revision: input.revision, obligation };
-}

package/src/learning-connection.ts

@@ -1,70 +0,0 @@
-import { join, resolve } from "node:path";
-import { intentKey } from "./intent-control.ts";
-import { loadDeclaredWork, type DeclaredWorkState } from "./work-command.ts";
-import { readProductJson, writeProductJson } from "./product-files.ts";
-import { loadedDashboardHarnessDigest } from "./dashboard-harness.ts";
-import type { DashboardHarness } from "./dashboard-host-contract.ts";
-import { buildAdoptionBinding, type AdoptionAuthority, type AdoptionBinding, type AdoptionFacts, type AdoptionReceipt, type RollbackRequest, type ProductionObservation } from "./vendor/adoption.ts";
-
-export interface LearningConfiguration { archiveRoot: string; scopeDigest: string; population: string; author: string }
-export interface LearningUI { select(title: string, choices: string[]): Promise<string | undefined>; input(title: string, initial?: string): Promise<string | undefined>; editor(title: string, text: string): Promise<string | undefined>; confirm(title: string, detail: string): Promise<boolean>; notify(text: string, level?: "info" | "warning" | "error"): void }
-export interface LearningComparisonContext { caseReference: unknown | null; hypothesisManifestId: string | null; adoptionBinding: AdoptionBinding | null }
-export interface LearningWorkspace {
-  configuration(): LearningConfiguration;
-  inspect(now: number): { version: string; configuration: LearningConfiguration; cases: { name: string; title: string; state?: string; reason?: string }[]; comparisons: { name: string; title: string; state?: string; reason?: string }[]; trust: Record<string, unknown>; [key: string]: unknown };
-  dashboardBinding(): { trustDirectory: string | null; trustPolicyId: string | null };
-  bindCases(input: { name: string; title: string; version: 2 | 3; batchId: string }): unknown;
-  comparisonContext(name: string): LearningComparisonContext;
-  linkComparisonContext(name:string, context:LearningComparisonContext):unknown;
-  hypotheses(): {name:string;manifestId:string;hypothesis:{id:string}}[];
-  decisionStatus(name:string):{current:{disposition:string}|null};
-  reveal(name:string):{manifestId:string;choice:{kind:string;labels:readonly string[]};arms:readonly {label:string;configuration:{configuration:string}}[]};
-  preparedAdoption(name: string): AdoptionReceipt | null;
-  previewObservation(name: string, input: ProductionObservation): { observation: ProductionObservation; classification: unknown; digest: string };
-  observe(name: string, input: ProductionObservation, authorized: readonly string[]): { manifestId: string };
-  prepareAdoption(name: string, authority: AdoptionAuthority | null, facts: AdoptionFacts, now: number): AdoptionReceipt;
-  linkActivation(name: string, manifest: string, independentlyAuthorized: readonly string[]): unknown;
-  previewRollback(name: string, reason: "operator-request" | "confirmed-escape", evidence: string[], expiresAt?: number): RollbackRequest;
-  prepareRollback(name: string, request: RollbackRequest, authority: AdoptionAuthority | null, now: number, current: { adoptionId: string; candidateDigest: string; scopeDigest: string }): unknown;
-  linkRollback(name: string, manifest: string, independentlyAuthorized: readonly string[]): unknown;
-}
-export interface LearningHarness extends DashboardHarness {
-  createLearningWorkspace(directory: string, input: LearningConfiguration): LearningWorkspace;
-  openLearningWorkspace(directory: string): LearningWorkspace;
-  runLearningWizard(input: { directory: string; cwd: string; ui: LearningUI }): Promise<unknown>;
-}
-export function learningHarness(harness: DashboardHarness): LearningHarness {
-  if (!loadedDashboardHarnessDigest(harness) || ["createLearningWorkspace", "openLearningWorkspace", "runLearningWizard"].some(key => typeof (harness as unknown as Record<string, unknown>)[key] !== "function")) throw Error("Learning services are unavailable in the loaded skill-harness. Load the compatible learning-workspace-v1 release and start a fresh Pi session (the existing immutable bridge survives /reload); no private adapter is needed.");
-  return harness as LearningHarness;
-}
-/** Author only the missing binding from validated public readback after a durable choice. No authority is generated. */
-export function bindLearningAdoption(workspace:LearningWorkspace,name:string,input:{candidateDigest:string;rollbackCandidateDigest:string;assessmentPolicyDigest:string;expiresAt:number}):AdoptionBinding {
-  const context=workspace.comparisonContext(name);
-  if(context.adoptionBinding)throw Error("Adoption proposal is already bound; it cannot be replaced");
-  if(!context.caseReference||!context.hypothesisManifestId)throw Error("Link the comparison's original confirmed case and hypothesis in Learning first");
-  const original=workspace.hypotheses().find(h=>h.manifestId===context.hypothesisManifestId);
-  if(!original||workspace.decisionStatus(name).current?.disposition!=="adopt")throw Error("Retained original hypothesis and explicit adopt intent required");
-  const reveal=workspace.reveal(name);
-  if(!["one","tie"].includes(reveal.choice.kind)||!reveal.arms.some(a=>reveal.choice.labels.includes(a.label)&&a.configuration.configuration===input.candidateDigest))throw Error("Candidate is not the exact configuration selected by the full-artifact quality choice");
-  const binding=buildAdoptionBinding({...input,hypothesisDigest:original.hypothesis.id,experimentDigest:reveal.manifestId,scopeDigest:workspace.configuration().scopeDigest,activationBoundary:"next-orders"});
-  workspace.linkComparisonContext(name,{...context,adoptionBinding:binding});return binding;
-}
-export interface LearningConnection { version: "producer-learning-connection-v1"; directory: string; configuration: LearningConfiguration; selection: DeclaredWorkState["selectedSnapshot"] }
-export const learningScopeDigest = (state: DeclaredWorkState) => state.selectedSnapshot.snapshot.digest;
-export async function bindLearningConnection(cwd: string, state: DeclaredWorkState, directory: string, harness: LearningHarness, author: string): Promise<LearningConnection> {
-  if (resolve(directory) !== directory) throw Error("absolute learning workspace directory required");
-  const current=await loadDeclaredWork(state.statePath);
-  if(intentKey(current?.selectedSnapshot??null)!==intentKey(state.selectedSnapshot))throw Error("selected work changed before learning connection; reopen Learning");
-  const configuration = harness.openLearningWorkspace(directory).configuration();
-  if (configuration.scopeDigest !== learningScopeDigest(state) || configuration.author !== author) throw Error("learning workspace belongs to another work scope or author; not rebound");
-  const connection: LearningConnection = { version: "producer-learning-connection-v1", directory, configuration, selection: state.selectedSnapshot };
-  await writeProductJson(join(resolve(cwd), ".pi", "learning-workspace.json"), connection, true); return connection;
-}
-export async function loadLearningConnection(cwd: string, state: DeclaredWorkState, harness: LearningHarness, author: string): Promise<{ connection: LearningConnection; workspace: LearningWorkspace } | null> {
-  const c = await readProductJson(join(resolve(cwd), ".pi", "learning-workspace.json")) as LearningConnection | null;
-  if (!c) return null;
-  if (Object.keys(c).sort().join() !== "configuration,directory,selection,version" || c.version !== "producer-learning-connection-v1" || typeof c.directory !== "string" || resolve(c.directory) !== c.directory || intentKey(c.selection) !== intentKey(state.selectedSnapshot)) throw Error("Learning connection is stale for selected work. Reconnect deliberately with /grants learning; no evidence was carried forward.");
-  const workspace = harness.openLearningWorkspace(c.directory), actual = workspace.configuration();
-  if (intentKey(actual) !== intentKey(c.configuration) || actual.scopeDigest !== learningScopeDigest(state) || actual.author !== author) throw Error("learning archive/population/scope/author mismatch");
-  return { connection: c, workspace };
-}

package/src/lease-helper.ts

@@ -1,97 +0,0 @@
-/**
- * **The lock helper: a separate program, and the parent's side of its pipes.**
- *
- * Split out of `workspace-lease.ts` because `test/file-size.test.ts` refused that file — at 405 lines on the
- * ADR-0035 branch when PR #14 merged into it, and at 435 here once R-152's guards landed. Both branches take
- * the same seam so they converge rather than diverge, and the cap has never been raised: `delegate.ts` was
- * split at 413 the same way (rule: when a guard fails, obey it).
- *
- * The seam is not arbitrary. Everything here concerns the process that HOLDS the kernel lock — the source it
- * runs, the readiness token it prints, and the parent-side handles that keep it referenced.
- * `workspace-lease.ts` keeps the lease lifecycle that talks to it.
- */
-
-export const LEASE_READY = "PI_DADDY_LEASE_READY";
-// The lock holder also owns crash cleanup for the governed child. If the parent dies, stdin closes;
-// the helper signals the attached process, or closes the herdr tab, before releasing flock. A raw
-// descendant deliberately detached by bash remains ADR-0012's OS-containment boundary, not a lease
-// guarantee. The process branch SIGTERMs, escalates to SIGKILL at +500ms, and releases at +750ms
-// WITHOUT confirming death (R-101). The herdr branch retries `tab close` a BOUNDED number of times
-// and then releases anyway, leaving a marker file: an unreleasable lock strands a worktree forever
-// with no in-product recovery, which is strictly worse than a recorded failure to close (R-102).
-//
-// **Each attempt is bounded in WALL CLOCK, not just in count (R-146).** `execFile` with no `timeout`
-// never calls back if `herdr` accepts the close and does not answer, so the retry counter never
-// decrements, `giveUp` never runs and no marker is written — the lock is held forever. That was masked
-// while the parent could not exit, because the operator saw a hung `pi` instead; measured with a `herdr`
-// that sleeps, the parent then exited in 82ms and left a silent strand, which is R-102's rejected outcome
-// reached quietly. A bound on retries is not a bound on time.
-export const HELPER_SOURCE = `
-import { execFile } from "node:child_process";
-import { writeFileSync } from "node:fs";
-let clean=false, target=null, buffered="";
-process.stdout.write(${JSON.stringify(`${LEASE_READY}:`)}+process.pid+"\\n");
-process.stdin.setEncoding("utf8");
-process.stdin.on("data",chunk=>{buffered+=chunk;for(;;){const i=buffered.indexOf("\\n");if(i<0)break;const line=buffered.slice(0,i);buffered=buffered.slice(i+1);try{const value=JSON.parse(line);if(value.release)clean=true;else if(value.process_pid)target={process_pid:value.process_pid};else if(value.herdr_tab)target={herdr_tab:value.herdr_tab};}catch{}}});
-process.stdin.on("end",()=>{if(clean||!target)return process.exit(0);if(target.process_pid){try{process.kill(target.process_pid,"SIGTERM")}catch{return process.exit(0)}setTimeout(()=>{try{process.kill(target.process_pid,"SIGKILL")}catch{}},500);return setTimeout(()=>process.exit(0),750);}let left=Number(process.env.PI_DADDY_LEASE_CLOSE_ATTEMPTS||10);const giveUp=last=>{try{if(process.env.PI_DADDY_LEASE_MARKER)writeFileSync(process.env.PI_DADDY_LEASE_MARKER,JSON.stringify({reason:last&&(last.killed||last.signal==="SIGKILL")?"herdr-close-timeout":"herdr-close-failed",herdr_tab:target.herdr_tab})+"\\n")}catch{}process.exit(0)};const close=()=>execFile("herdr",["tab","close",target.herdr_tab],{timeout:Number(process.env.PI_DADDY_LEASE_CLOSE_TIMEOUT_MS||15000),killSignal:"SIGKILL"},error=>{if(!error)return process.exit(0);if(--left<=0)return giveUp(error);setTimeout(close,1000)});close();});
-process.stdin.resume();`;
-
-/**
- * `unref` the parent's end of one of the helper's pipes.
- *
- * A spawned pipe is a `net.Socket`, which has `unref`; `ChildProcess.stdin` is typed `Writable`, which does
- * not. Hence the narrow cast. The optional call is **defensive, not load-bearing** — the holder is spawned at
- * exactly one site with three pipes, so none of these is ever `null`, and an earlier version of this comment
- * claimed otherwise by citing a `stdio: "ignore"` caller that does not exist.
- *
- * Only `stdout` and `stderr` are unref'ed. `stdin` was too, until a line-by-line reversion showed the suite
- * stayed green without it — an unforced line inside the fix that exists to be forced, which is exactly the
- * shape R-122 was about.
- */
-export const unrefStream = (stream: unknown): void => {
-  (stream as { unref?: () => void } | null)?.unref?.();
-};
-
-/**
- * The bounds on the helper's `herdr tab close` attempts live here, with the attempts they bound — moved out of
- * `workspace-lease.ts` when the line ceiling refused it at 402 lines, once both this branch's ADR-0035 work and
- * `main`'s R-152 guards had landed in it. Third time that guard has fired on this file and third time the
- * answer was a seam rather than a bigger cap.
- */
-/**
- * **A bound that is not a bound throws, and it throws a `RangeError` (R-146, R-152).**
- *
- * Both ends fail, in opposite directions and both silently:
- *
- *  - `0` reads as "no limit" and Node agrees — `execFile` treats `timeout: 0` as *no* timeout (measured: the
- *    callback for a 3s sleep arrives at 3004ms with no error), reinstating the unbounded hang the bound exists
- *    to prevent. Negatives behave identically.
- *  - anything above `2^31 - 1` truncates: `setTimeout` warns `TimeoutOverflowWarning … set to 1`, so
- *    `Number.MAX_SAFE_INTEGER` — the plausible "effectively no limit" sentinel, given the argument about `0`
- *    — SIGKILLs every `herdr tab close` after 1ms, before herdr can act. Measured: callback at 3ms.
- *
- * **Not a `GovernanceRefusal`.** It was one, carrying `WORKSPACE_LEASE_STALE`, which everywhere else in this
- * package means *the lease went stale or was lost* — so an ADR-0034 controller switching on codes (the reason
- * codes exist, R-103) would classify a permanent caller bug as transient and retry a call that can never
- * succeed. A refusal is a governance outcome that gets ledgered; a bad argument is neither.
- *
- * Checked for read leases too, which the first version did not: it sat below the read-lease early return, so a
- * controller smoke-testing its configuration against a read lease got a false all-clear.
- */
-export const assertCloseBounds = (input: { herdrCloseTimeoutMs?: number; herdrCloseAttempts?: number }): void => {
-  const MAX_TIMER = 2_147_483_647;
-  for (const [name, value, ceiling] of [
-    ["herdrCloseTimeoutMs", input.herdrCloseTimeoutMs, MAX_TIMER],
-    ["herdrCloseAttempts", input.herdrCloseAttempts, Number.MAX_SAFE_INTEGER],
-  ] as const) {
-    if (value === undefined) continue;
-    if (!Number.isInteger(value) || value < 1 || value > ceiling) {
-      throw new RangeError(
-        `${name} must be a whole number between 1 and ${ceiling}, not ${String(value)}. Zero and negatives ` +
-          `are not "no limit" but no bound at all, a value past ${MAX_TIMER} truncates to 1ms, and a ` +
-          `fractional count is not a count — this bound exists so a hung herdr cannot hold the writer lock ` +
-          `forever (R-146).`,
-      );
-    }
-  }
-};

package/src/lease-record.ts

@@ -1,131 +0,0 @@
-/**
- * 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";
-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.
-   */
-  /**
-   * Record that the lease is being KEPT rather than handed back, and answer what actually happened — the
-   * caller ledgers this word (R-152). It is not always `retained`: a helper that has already died makes the
-   * fact `lost`, and a lease already settled by `release()` keeps the outcome it had.
-   */
-  markRetained(reason?: string): Promise<LeaseReleaseOutcome>;
-  /** 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. Six 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"
-  /**
-   * The lease was RETAINED and is therefore already settled — `release()` after `markRetained()` answers
-   * this instead of running the clean handshake (R-146). It was previously expressible only as the
-   * `| "retained"` bolted onto two signatures, which is why `release()` could not say it and claimed
-   * `released` instead: a clean handover for a lease kept precisely because a pane would not close.
-   */
-  | "retained";
-
-export function leasePaths(leaseDir: string, root: string) {
-  // 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: string, value: LeaseMetadata): Promise<void> {
-  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: string): Promise<LeaseMetadata | null | "malformed"> {
-  let raw: string;
-  try {
-    raw = await readFile(path, "utf8");
-  } catch (error) {
-    return (error as NodeJS.ErrnoException)?.code === "ENOENT" ? null : "malformed";
-  }
-  try {
-    const value = JSON.parse(raw) as Partial<LeaseMetadata>;
-    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 as LeaseMetadata;
-  } catch {
-    return "malformed";
-  }
-}

package/src/ledger-append.ts

@@ -1,72 +0,0 @@
-import { appendFile, mkdir, open, type FileHandle } from "node:fs/promises";
-import { constants } from "node:fs";
-import { dirname } from "node:path";
-import { withFileLock } from "./file-lock.ts";
-import { recheckWorkDestination, workFsError, type WorkDestination } from "./work-ledger-destination.ts";
-import { WORK_TEXT_BYTES, WORK_RECORDS } from "./work-ledger-json.ts";
-import { WorkInputError } from "./work-ledger-types.ts";
-import { parseWorkLedgerText } from "./work-ledger.ts";
-
-/** Bounded descriptor read, including one detection byte; never trust a pre-read size alone. */
-export async function readWorkBytes(handle: FileHandle): Promise<Buffer> {
-  const chunks: Buffer[] = []; let total = 0;
-  for (;;) {
-    const chunk = Buffer.alloc(Math.min(64 * 1024, WORK_TEXT_BYTES + 1 - total));
-    const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
-    if (bytesRead === 0) return Buffer.concat(chunks, total);
-    total += bytesRead;
-    if (total > WORK_TEXT_BYTES) throw new WorkInputError("WORK_LIMIT_EXCEEDED");
-    chunks.push(chunk.subarray(0, bytesRead));
-  }
-}
-/** A secondary filesystem close failure must not replace a primary content/capacity refusal. */
-export async function closeWorkHandle(handle: FileHandle, failed: boolean): Promise<void> {
-  try { await handle.close(); }
-  catch (error) { if (!failed || !workFsError(error)) throw error; }
-}
-
-/** Shared existing-producer persistence. Serialization and each caller's exception policy remain
- * outside this function. The private destination facts select v4 protection, never ambient defaults. */
-export async function appendLedgerLine(options: { readonly path: string }, line: string, destination?: WorkDestination, once?: { eventId: string; digest: string }): Promise<void> {
-  await mkdir(dirname(options.path), { recursive: true });
-  if (!destination) {
-    // Retain even legacy path-property evaluation timing across waits; only v4 owns detached inputs.
-    await withFileLock(options.path, "grant ledger", () => appendFile(options.path, line, { encoding: "utf8", flag: "a" }));
-    return;
-  }
-  const path = destination.path;
-  await recheckWorkDestination(destination);
-  await withFileLock(path, "work ledger", async () => {
-    await recheckWorkDestination(destination);
-    let handle: FileHandle;
-    try {
-      handle = await open(path, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
-    } catch (error) {
-      // A newly proven alias/unsafe kind retains its classification rather than becoming generic I/O.
-      if (workFsError(error)) await recheckWorkDestination(destination);
-      throw error;
-    }
-    let failed = false;
-    try {
-      await recheckWorkDestination(destination, handle);
-      const bytes = await readWorkBytes(handle);
-      const ingestion = parseWorkLedgerText(bytes.toString("utf8"));
-      if (!ingestion.complete) throw new WorkInputError(ingestion.errors[0].code);
-      if (bytes.length && bytes[bytes.length - 1] !== 10) throw new WorkInputError("WORK_JSON_INVALID");
-      if (once) {
-        const sameId = ingestion.events.filter(e => e.eventId === once.eventId);
-        if (sameId.some(e => e.digest !== once.digest)) throw new WorkInputError("WORK_DIGEST_MISMATCH");
-        if (sameId.length) { await handle.sync(); return; } // Reconcile an earlier complete but unacknowledged append.
-      }
-      if (bytes.length + Buffer.byteLength(line, "utf8") > WORK_TEXT_BYTES || ingestion.events.length + 1 > WORK_RECORDS) {
-        throw new WorkInputError("WORK_LIMIT_EXCEEDED");
-      }
-      await recheckWorkDestination(destination, handle);
-      // Same descriptor, same non-expiring lock, O_APPEND. A failed write may leave partial bytes;
-      // preserve them and fail closed. Never truncate, repair or reserialize existing deliveries.
-      await handle.writeFile(line, "utf8");
-      if (once) await handle.sync(); // New application seam requires durable append before controller receipt.
-    } catch (error) { failed = true; throw error; }
-    finally { await closeWorkHandle(handle, failed); }
-  }, { staleRecovery: "disabled" });
-}

package/src/ledger-events.ts

@@ -1,226 +0,0 @@
-/**
- * The v3 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";
-import { assertExecutionId } from "./execution-id.ts";
-import type { WorkflowFactEvent } from "./workflow-facts.ts";
-import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
-
-export const WORKSPACE_ACCESSES = ["read", "write"] as const;
-export type WorkspaceAccess = typeof WORKSPACE_ACCESSES[number];
-
-export const WORKSPACE_RECOVERY_VALUES = [false, true, "unknown"] as const;
-export type WorkspaceRecovery = typeof WORKSPACE_RECOVERY_VALUES[number];
-
-export const CHILD_LIFECYCLE_STATES = ["starting", "running", "completed", "failed"] as const;
-export type ChildLifecycleState = typeof CHILD_LIFECYCLE_STATES[number];
-
-/** 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",
-] as const satisfies readonly NodeJS.Signals[];
-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 const WORKSPACE_LEASE_OUTCOMES = [
-  "acquired", "uncontended", "refused", "released", "released-unrecorded", "lost", "retained", "timeout",
-  "recovered",
-] as const;
-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;
-}
-
-export interface CheckReceiptLedgerEvent extends LedgerEventBase {
-  ledgerVersion: typeof LEDGER_VERSION;
-  event: "check_receipt";
-  executionId: string;
-  parentExecutionId: string | null;
-  childId: string;
-  receiptId: string;
-  workspaceId: string;
-  checkId: string;
-  treeSha: string;
-}
-
-export type CapabilityDecisionEvent = GrantRecord & {
-  ledgerVersion: typeof LEDGER_VERSION;
-  event: "capability_decision";
-  executionId: string;
-  parentExecutionId: string | null;
-  taskDigest: string;
-};
-
-export type RuntimeLedgerEvent =
-  | CapabilityDecisionEvent
-  | WorkspaceLeaseEvent
-  | ChildLifecycleEvent
-  | CheckReceiptLedgerEvent
-  | WorkflowFactEvent;
-
-export 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 {
-  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 buildCheckReceiptLedgerEvent(args: {
-  executionId: string;
-  parentExecutionId: string | null;
-  childId: string;
-  receiptId: string;
-  workspaceId: string;
-  checkId: string;
-  treeSha: string;
-  correlation?: CorrelationMetadata;
-  now: Date;
-}): CheckReceiptLedgerEvent {
-  assertEventIdentity(args);
-  if (!/^[a-f0-9]{64}$/i.test(args.receiptId)) {
-    throw new TypeError("receiptId must be a SHA-256 hex digest");
-  }
-  return assertLedgerV3Wire({
-    ledgerVersion: LEDGER_VERSION,
-    event: "check_receipt",
-    ts: args.now.toISOString(),
-    executionId: args.executionId,
-    parentExecutionId: args.parentExecutionId,
-    childId: args.childId,
-    receiptId: args.receiptId,
-    workspaceId: args.workspaceId,
-    checkId: args.checkId,
-    treeSha: args.treeSha,
-    ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
-  });
-}
-
-export function buildChildLifecycleEvent(args: {
-  executionId: string;
-  parentExecutionId: string | null;
-  childId: string;
-  state: ChildLifecycleState;
-  executor: ExecutorKind;
-  deadlineAt?: string;
-  herdrPaneId?: string;
-  herdrAgentName?: string;
-  exitCode?: number | null;
-  signal?: ChildProcessSignal | null;
-  timedOut?: boolean;
-  aborted?: boolean;
-  truncated?: boolean;
-  reason?: string;
-  correlation?: CorrelationMetadata;
-  now: Date;
-}): ChildLifecycleEvent {
-  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.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: { executionId: string; parentExecutionId: string | null }): void {
-  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");
-}