pi-daddy 0.19.0 → 0.20.0

package/src/delegate.ts

@@ -19,8 +19,8 @@ import {
 // charged to every caller for a line count they did not cause.
 export { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
 import {
-  ENV_APPROVED, ENV_DEPTH, ENV_FANOUT, ENV_GATED, ENV_GRANT, ENV_LEDGER, ENV_MAX_DEPTH, ENV_PARENT_ID,
-  inheritableGrant,
+  ENV_APPROVED, ENV_DEPTH, ENV_EXECUTION_ID, ENV_FANOUT, ENV_GATED, ENV_GRANT, ENV_LEDGER, ENV_MAX_DEPTH,
+  ENV_PARENT_ID, inheritableGrant,
 } from "./propagation.ts";
 import { inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { suggestForUnknown, unknownCapabilities, type Catalog } from "./catalog.ts";
@@ -309,6 +309,7 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
   // process boundaries with no shared state.
   if (ctx.fanoutBudget !== undefined) env[ENV_FANOUT] = String(ctx.fanoutBudget);
   if (ctx.childSpawnId) env[ENV_PARENT_ID] = ctx.childSpawnId;
+  if (ctx.childExecutionId) env[ENV_EXECUTION_ID] = ctx.childExecutionId;
   if (ctx.gated.length > 0) env[ENV_GATED] = ctx.gated.join(",");
   // Approvals ride down with the grant, but only ever for what this child actually received — so
   // `approved ⊆ grant` holds at every level (ADR-0010). Written even when empty, so this object states
@@ -330,6 +331,7 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     childDepth,
     requested,
     childId: ctx.childSpawnId,
+    executionId: ctx.childExecutionId,
     taskDigest,
     ...(correlation ? { correlation } : {}),
     ...(approvalBinding ? { approvalBinding } : {}),

package/src/execution-id.ts

@@ -0,0 +1,18 @@
+import { randomUUID } from "node:crypto";
+
+/** Unique identity for one governed execution occurrence. Logical child ids remain readable positions. */
+export type ExecutionId = `exec:${string}`;
+
+const EXECUTION_ID_RE = /^exec:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function isExecutionId(value: unknown): value is ExecutionId {
+  return typeof value === "string" && EXECUTION_ID_RE.test(value);
+}
+
+export function newExecutionId(): ExecutionId {
+  return `exec:${randomUUID()}`;
+}
+
+export function assertExecutionId(value: unknown, field = "executionId"): asserts value is ExecutionId {
+  if (!isExecutionId(value)) throw new TypeError(`${field} must be a pi-daddy execution id`);
+}

package/src/index.ts

@@ -15,6 +15,10 @@ export {
   buildChildLifecycleEvent,
   buildRecord,
   buildWorkspaceLeaseEvent,
+  buildWorkflowFactEvent,
+  WORKFLOW_FACT_KINDS,
+  WORKFLOW_FACT_PROVENANCE,
+  WORKFLOW_FACT_STATES,
   isEscalationAttempt,
   LEDGER_VERSION,
   type CheckReceiptLedgerEvent,
@@ -24,6 +28,10 @@ export {
   type RuntimeLedgerEvent,
   type WorkspaceLeaseEvent,
   type WorkspaceLeaseOutcome,
+  type WorkflowFactEvent,
+  type WorkflowFactKind,
+  type WorkflowFactProvenance,
+  type WorkflowFactState,
 } from "./ledger.ts";
 
 export { planSpawn, type SpawnPlan, type SpawnPlanInput } from "./spawn.ts";
@@ -97,6 +105,23 @@ export {
   type CheckRegistry,
 } from "./check-runner.ts";
 
+export {
+  isExecutionId,
+  newExecutionId,
+  type ExecutionId,
+} from "./execution-id.ts";
+
+export {
+  parseDashboardLedger,
+  type DashboardNode,
+  type DashboardProjection,
+  type DashboardState,
+  type DashboardWorkflow,
+  type DashboardWorkflowFact,
+} from "./dashboard-projection.ts";
+
+export { renderDashboard, type DashboardRenderOptions } from "./dashboard-render.ts";
+
 export {
   createApprovalGate,
   createApprovalGateProvider,

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,9 @@ 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];
@@ -15,10 +18,10 @@ 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", "completed", "failed"] as const;
+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 v2 child-lifecycle event. */
+/** 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",
@@ -47,6 +50,8 @@ 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;
@@ -61,9 +66,16 @@ 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: 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;
@@ -75,6 +87,8 @@ export interface ChildLifecycleEvent extends LedgerEventBase {
 export interface CheckReceiptLedgerEvent extends LedgerEventBase {
   ledgerVersion: typeof LEDGER_VERSION;
   event: "check_receipt";
+  executionId: string;
+  parentExecutionId: string | null;
   childId: string;
   receiptId: string;
   workspaceId: string;
@@ -85,6 +99,8 @@ export interface CheckReceiptLedgerEvent extends LedgerEventBase {
 export type CapabilityDecisionEvent = GrantRecord & {
   ledgerVersion: typeof LEDGER_VERSION;
   event: "capability_decision";
+  executionId: string;
+  parentExecutionId: string | null;
   taskDigest: string;
 };
 
@@ -92,9 +108,12 @@ export type RuntimeLedgerEvent =
   | CapabilityDecisionEvent
   | WorkspaceLeaseEvent
   | ChildLifecycleEvent
-  | CheckReceiptLedgerEvent;
+  | CheckReceiptLedgerEvent
+  | WorkflowFactEvent;
 
 export function buildWorkspaceLeaseEvent(args: {
+  executionId: string;
+  parentExecutionId: string | null;
   childId: string;
   workspaceId: string;
   root: string;
@@ -106,10 +125,13 @@ export function buildWorkspaceLeaseEvent(args: {
   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,
@@ -123,10 +145,12 @@ 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;
@@ -135,26 +159,34 @@ export function buildCheckReceiptLedgerEvent(args: {
   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 {
+  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;
@@ -164,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 } : {}),
@@ -178,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,