pi-daddy 0.18.1 → 0.20.0

package/src/ledger-events.ts

@@ -1,5 +1,5 @@
 /**
- * The v2 runtime-event half of the ledger: workspace leases, child lifecycle and check receipts, with
+ * 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.
@@ -8,6 +8,27 @@ import { LEDGER_VERSION, type LedgerEventBase, type GrantRecord } from "./ledger
 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
@@ -20,27 +41,24 @@ import type { StructuredRefusal } from "./refusals.ts";
  *   `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 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: "read" | "write";
+  access: WorkspaceAccess;
   outcome: WorkspaceLeaseOutcome;
   /** `"unknown"` when the prior owner's record was unreadable — not evidence of a clean handover. */
-  recovered?: boolean | "unknown";
+  recovered?: WorkspaceRecovery;
   releaseReason?: string;
   refusal?: StructuredRefusal;
 }
@@ -48,20 +66,29 @@ export interface WorkspaceLeaseEvent extends LedgerEventBase {
 export interface ChildLifecycleEvent extends LedgerEventBase {
   ledgerVersion: typeof LEDGER_VERSION;
   event: "child_lifecycle";
+  executionId: string;
+  parentExecutionId: string | null;
   childId: string;
-  state: "starting" | "completed" | "failed";
+  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?: NodeJS.Signals | null;
-  timedOut?: boolean;
-  aborted?: boolean;
-  truncated?: boolean;
+  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;
@@ -69,28 +96,42 @@ export interface CheckReceiptLedgerEvent extends LedgerEventBase {
   treeSha: string;
 }
 
+export type CapabilityDecisionEvent = GrantRecord & {
+  ledgerVersion: typeof LEDGER_VERSION;
+  event: "capability_decision";
+  executionId: string;
+  parentExecutionId: string | null;
+  taskDigest: string;
+};
+
 export type RuntimeLedgerEvent =
-  | (GrantRecord & { ledgerVersion: typeof LEDGER_VERSION; event: "capability_decision" })
+  | CapabilityDecisionEvent
   | WorkspaceLeaseEvent
   | ChildLifecycleEvent
-  | CheckReceiptLedgerEvent;
+  | CheckReceiptLedgerEvent
+  | WorkflowFactEvent;
 
 export function buildWorkspaceLeaseEvent(args: {
+  executionId: string;
+  parentExecutionId: string | null;
   childId: string;
   workspaceId: string;
   root: string;
-  access: "read" | "write";
+  access: WorkspaceAccess;
   outcome: WorkspaceLeaseOutcome;
-  recovered?: boolean | "unknown";
+  recovered?: WorkspaceRecovery;
   releaseReason?: string;
   refusal?: StructuredRefusal;
   correlation?: CorrelationMetadata;
   now: Date;
 }): WorkspaceLeaseEvent {
-  return {
+  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,
@@ -104,15 +145,50 @@ export function buildWorkspaceLeaseEvent(args: {
     ...(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: "starting" | "completed" | "failed";
+  state: ChildLifecycleState;
   executor: ExecutorKind;
+  deadlineAt?: string;
+  herdrPaneId?: string;
+  herdrAgentName?: string;
   exitCode?: number | null;
-  signal?: NodeJS.Signals | null;
+  signal?: ChildProcessSignal | null;
   timedOut?: boolean;
   aborted?: boolean;
   truncated?: boolean;
@@ -120,13 +196,19 @@ export function buildChildLifecycleEvent(args: {
   correlation?: CorrelationMetadata;
   now: Date;
 }): ChildLifecycleEvent {
-  return {
+  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 } : {}),
@@ -134,5 +216,11 @@ export function buildChildLifecycleEvent(args: {
     ...(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");
 }

package/src/ledger-identifiers.ts

@@ -0,0 +1,21 @@
+const DISPLAY_IDENTIFIER = /^[A-Za-z0-9@*][A-Za-z0-9@*._:/-]{0,511}$/;
+const CORRELATION_IDENTIFIER = /^[A-Za-z0-9@*][A-Za-z0-9@*._:/-]{0,127}$/;
+const CAPABILITY_TAIL = /^[A-Za-z0-9@*][A-Za-z0-9@*._/-]{0,255}$/;
+const CAPABILITY_PREFIXES = ["tool:", "skill:", "agent:", "workspace:", "ext:"] as const;
+
+/** Identifier text safe to copy onto the operator's terminal; prose belongs in no ledger display field. */
+export function isLedgerDisplayIdentifier(value: unknown): value is string {
+  return typeof value === "string" && DISPLAY_IDENTIFIER.test(value);
+}
+
+/** The tighter bound for model-facing correlation labels that are copied onto every event. */
+export function isLedgerCorrelationIdentifier(value: unknown): value is string {
+  return typeof value === "string" && CORRELATION_IDENTIFIER.test(value);
+}
+
+/** A namespaced capability id with an ASCII, non-prose tail. Namespace wildcards remain representable. */
+export function isLedgerCapabilityIdentifier(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const prefix = CAPABILITY_PREFIXES.find((candidate) => value.startsWith(candidate));
+  return Boolean(prefix && CAPABILITY_TAIL.test(value.slice(prefix.length)));
+}

package/src/ledger-report.ts

@@ -18,11 +18,13 @@ import type { ApprovalSource } from "./approval.ts";
 import type { GrantRecord } from "./ledger.ts";
 import { isEscalationAttempt } from "./ledger.ts";
 import type { WorkspaceLeaseOutcome } from "./ledger-events.ts";
+import { isExecutionId } from "./execution-id.ts";
+import { validateLedgerV3Event } from "./ledger-v3-validation.ts";
 
 export interface LedgerReport {
   /** False when the file is absent — a configuration state, not damage. */
   exists: boolean;
-  /** Capability-decision records (legacy or v2). */
+  /** Capability-decision records (legacy, v2, or v3). */
   records: number;
   /** Every parsed ledger event, including lifecycle and lease events. */
   events: number;
@@ -30,9 +32,11 @@ export interface LedgerReport {
     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 };
+  lifecycle: { starting: number; running: number; completed: number; failed: number };
+  /** Planned/observed/controller-validated facts; never counted as enforced child executions. */
+  workflowFacts: number;
   /** Lines that did not, with 1-based line numbers so the report is actionable. */
-  corrupt: Array<{ line: number; text: string }>;
+  corrupt: Array<{ line: number; reason: string }>;
   /** Records where an agent asked for more than it held — ADR-0008's designated signal. */
   escalationAttempts: number;
   /**
@@ -139,18 +143,20 @@ const LEASE_OUTCOME_COUNTERS: Record<WorkspaceLeaseOutcome, keyof LedgerReport["
   recovered: "recovered",
 };
 
-function validV2Base(event: Record<string, unknown>): boolean {
-  return event.ledgerVersion === 2 && typeof event.ts === "string";
-}
-
-function requireV2(event: Record<string, unknown>, fields: string[]): void {
-  if (!validV2Base(event) || fields.some((field) => typeof event[field] !== "string" || event[field] === "")) {
+function requireVersioned(event: Record<string, unknown>, fields: string[]): void {
+  if ((event.ledgerVersion !== 2 && event.ledgerVersion !== 3) || typeof event.ts !== "string" ||
+      fields.some((field) => typeof event[field] !== "string" || event[field] === "")) {
     throw new Error("invalid versioned ledger event");
   }
+  if (event.ledgerVersion === 3 &&
+      (!isExecutionId(event.executionId) ||
+       (event.parentExecutionId !== null && !isExecutionId(event.parentExecutionId)))) {
+    throw new Error("invalid v3 execution identity");
+  }
 }
 
 function requireCapabilityDecision(event: Record<string, unknown>): void {
-  requireV2(event, ["parentId", "childId", "executor", "taskDigest"]);
+  requireVersioned(event, ["parentId", "childId", "executor", "taskDigest"]);
   for (const field of ["requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked"]) {
     if (!Array.isArray(event[field]) || !(event[field] as unknown[]).every((value) => typeof value === "string")) {
       throw new Error("invalid capability decision arrays");
@@ -172,7 +178,8 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         records: 0,
         events: 0,
         workspaceLeases: { acquired: 0, uncontended: 0, refused: 0, released: 0, releasedUnrecorded: 0, lost: 0, retained: 0, timeout: 0, recovered: 0 },
-        lifecycle: { starting: 0, completed: 0, failed: 0 },
+        lifecycle: { starting: 0, running: 0, completed: 0, failed: 0 },
+        workflowFacts: 0,
         corrupt: [],
         escalationAttempts: 0,
         executors: { herdr: 0, process: 0, unknown: 0 },
@@ -190,13 +197,14 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
     throw error;
   }
 
-  const corrupt: Array<{ line: number; text: string }> = [];
+  const corrupt: Array<{ line: number; reason: string }> = [];
   // Keyed by name+digest: one name with two entries is the signal that the definition changed mid-ledger.
   const digests = new Map<string, { name: string; source: string; sha256: string; spawns: number }>();
   let records = 0;
   let events = 0;
   const workspaceLeases = { acquired: 0, uncontended: 0, refused: 0, released: 0, releasedUnrecorded: 0, lost: 0, retained: 0, timeout: 0, recovered: 0 };
-  const lifecycle = { starting: 0, completed: 0, failed: 0 };
+  const lifecycle = { starting: 0, running: 0, completed: 0, failed: 0 };
+  let workflowFacts = 0;
   let escalationAttempts = 0;
   const executors = { herdr: 0, process: 0, unknown: 0 };
   const bySource: Record<ApprovalSource, number> = { prompt: 0, session: 0, persisted: 0, inherited: 0 };
@@ -217,11 +225,21 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
     if (raw.trim().length === 0) return;
     try {
       const event = JSON.parse(raw) as Record<string, unknown>;
-      if (event.ledgerVersion !== undefined && event.event === undefined) {
-        throw new Error("versioned ledger line has no event discriminator");
+      if (event.ledgerVersion !== undefined) {
+        if (event.event === undefined) throw new Error("versioned ledger line has no event discriminator");
+        if (event.ledgerVersion !== 2 && event.ledgerVersion !== 3) throw new Error("unsupported ledger version");
+        if (event.ledgerVersion === 3 && validateLedgerV3Event(event)) throw new Error("invalid ledger v3 event");
+      }
+      if (event.event === "workflow_fact") {
+        // v2 has no workflow facts; the exact v3 validator above already checked its vocabulary,
+        // correlation and provenance/state relation.
+        if (event.ledgerVersion !== 3) throw new Error("invalid workflow fact event");
+        workflowFacts += 1;
+        events += 1;
+        return;
       }
       if (event.event === "workspace_lease") {
-        requireV2(event, ["childId", "workspaceId", "root", "access"]);
+        requireVersioned(event, ["childId", "workspaceId", "root", "access"]);
         const outcome = typeof event.outcome === "string" ? event.outcome : "";
         // Explicit map, not a name match: the ledger's outcome vocabulary and these counter names are
         // allowed to differ, and a valid event must never be counted as corruption because a counter
@@ -235,7 +253,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         return;
       }
       if (event.event === "child_lifecycle") {
-        requireV2(event, ["childId", "executor"]);
+        requireVersioned(event, ["childId", "executor"]);
         const state = typeof event.state === "string" ? event.state : "";
         if (!Object.hasOwn(lifecycle, state)) throw new Error("invalid child lifecycle event");
         lifecycle[state as keyof typeof lifecycle] += 1;
@@ -243,7 +261,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         return;
       }
       if (event.event === "check_receipt") {
-        requireV2(event, ["childId", "receiptId", "workspaceId", "checkId", "treeSha"]);
+        requireVersioned(event, ["childId", "receiptId", "workspaceId", "checkId", "treeSha"]);
         events += 1;
         return;
       }
@@ -305,7 +323,9 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         else digests.set(key, { name: d.name, source: d.source, sha256: d.sha256, spawns: 1 });
       }
     } catch {
-      corrupt.push({ line: index + 1, text: raw.slice(0, 120) });
+      // Content-free by contract: a torn or foreign line can contain exactly the task/output material the
+      // ledger and dashboard promise never to expose. The line number locates the evidence without copying it.
+      corrupt.push({ line: index + 1, reason: "invalid ledger line" });
     }
   });
 
@@ -315,6 +335,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
     events,
     workspaceLeases,
     lifecycle,
+    workflowFacts,
     corrupt,
     escalationAttempts,
     executors,