pi-daddy 0.18.1 → 0.20.0

package/src/ledger-v3-validation.ts

@@ -0,0 +1,266 @@
+import { normaliseCorrelation, type CorrelationMetadata } from "./correlation.ts";
+import { isExecutionId } from "./execution-id.ts";
+import { REFUSAL_CODES } from "./refusals.ts";
+import { isWorkflowFactId, isWorkflowIdentifier, workflowFactStateMatches } from "./workflow-fact-id.ts";
+import { isLedgerCapabilityIdentifier, isLedgerDisplayIdentifier } from "./ledger-identifiers.ts";
+
+export type LedgerV3Object = Record<string, unknown>;
+
+const SHA256_RE = /^[a-f0-9]{64}$/i;
+const EXECUTORS = new Set(["process", "herdr"]);
+const APPROVAL_SOURCES = new Set(["prompt", "session", "persisted", "inherited"]);
+const APPROVAL_SCOPES = new Set(["once", "session", "always"]);
+const GATE_OUTCOMES = new Set(["declined", "dismissed", "no-ui", "error"]);
+const LEASE_OUTCOMES = new Set([
+  "acquired", "uncontended", "refused", "released", "released-unrecorded", "lost", "retained", "timeout", "recovered",
+]);
+const PROCESS_SIGNALS = new Set([
+  "SIGABRT", "SIGALRM", "SIGBUS", "SIGCHLD", "SIGCONT", "SIGFPE", "SIGHUP", "SIGILL", "SIGINT", "SIGIO",
+  "SIGIOT", "SIGKILL", "SIGPIPE", "SIGPOLL", "SIGPROF", "SIGPWR", "SIGQUIT", "SIGSEGV", "SIGSTKFLT",
+  "SIGSTOP", "SIGSYS", "SIGTERM", "SIGTRAP", "SIGTSTP", "SIGTTIN", "SIGTTOU", "SIGUNUSED", "SIGURG",
+  "SIGUSR1", "SIGUSR2", "SIGVTALRM", "SIGWINCH", "SIGXCPU", "SIGXFSZ", "SIGBREAK", "SIGLOST", "SIGINFO",
+]);
+
+const FIELDS = {
+  capability_decision: new Set([
+    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "parentId", "childId", "depth",
+    "agentType", "requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked", "blocked",
+    "reason", "approved", "approvalSource", "approvalSources", "approvalScopes", "approvalExpiresAt",
+    "approvalUses", "approvalScope", "humanDenied", "gateOutcome", "definitionDigest", "executor", "taskFrom",
+    "taskFromExecutionId", "taskDigest", "correlation", "refusal",
+  ]),
+  workspace_lease: new Set([
+    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "workspaceId", "root",
+    "access", "outcome", "recovered", "releaseReason", "refusal", "correlation",
+  ]),
+  child_lifecycle: new Set([
+    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "state", "executor",
+    "exitCode", "signal", "timedOut", "aborted", "truncated", "reason", "deadlineAt", "herdrPaneId",
+    "herdrAgentName", "correlation",
+  ]),
+  check_receipt: new Set([
+    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "receiptId", "workspaceId",
+    "checkId", "treeSha", "correlation",
+  ]),
+  workflow_fact: new Set([
+    "ledgerVersion", "event", "ts", "factId", "source", "provenance", "kind", "subject", "state", "correlation",
+  ]),
+} as const;
+type EventKind = keyof typeof FIELDS;
+
+export function isLedgerObject(value: unknown): value is LedgerV3Object {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+/** Ledger timestamp profile: JSON Schema `date-time`, narrowed to seconds 00-59 for JS date arithmetic. */
+export function isTimestamp(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|([+-])(\d{2}):(\d{2}))$/.exec(value);
+  if (!match) return false;
+  const [, yearText, monthText, dayText, hourText, minuteText, secondText, , offsetHourText, offsetMinuteText] = match;
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  const hour = Number(hourText);
+  const minute = Number(minuteText);
+  const second = Number(secondText);
+  if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59) return false;
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (day < 1 || day > days[month - 1]) return false;
+  return offsetHourText === undefined || (Number(offsetHourText) <= 23 && Number(offsetMinuteText) <= 59);
+}
+
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function optional(event: LedgerV3Object, field: string, valid: (value: unknown) => boolean): boolean {
+  return !Object.hasOwn(event, field) || valid(event[field]);
+}
+
+function stringMap(value: unknown, valid: (entry: unknown) => boolean): boolean {
+  return isLedgerObject(value) && Object.values(value).every(valid);
+}
+
+function capabilityMap(value: unknown, valid: (entry: unknown) => boolean): boolean {
+  return isLedgerObject(value) && Object.keys(value).every(isLedgerCapabilityIdentifier) && Object.values(value).every(valid);
+}
+
+function validCorrelation(value: unknown): boolean {
+  if (!isLedgerObject(value)) return false;
+  try {
+    const normalised = normaliseCorrelation(value as CorrelationMetadata);
+    // `normaliseCorrelation` drops nulls. The closed schema does not, so equality is part of validation.
+    return JSON.stringify(normalised) === JSON.stringify(value);
+  } catch {
+    return false;
+  }
+}
+
+function validRefusal(value: unknown): boolean {
+  if (!isLedgerObject(value) || Object.keys(value).some((key) => !["code", "message", "details"].includes(key))) return false;
+  if (!REFUSAL_CODES.includes(value.code as never) || typeof value.message !== "string") return false;
+  return optional(value, "details", (details) => isLedgerObject(details) && Object.values(details).every(
+    (entry) => entry === null || ["string", "number", "boolean"].includes(typeof entry),
+  ));
+}
+
+function validDefinitionDigest(value: unknown): boolean {
+  return isLedgerObject(value) &&
+    Object.keys(value).every((key) => ["name", "source", "sha256"].includes(key)) &&
+    typeof value.name === "string" && typeof value.source === "string" && SHA256_RE.test(String(value.sha256));
+}
+
+function validApprovalUse(value: unknown): boolean {
+  return isLedgerObject(value) && Object.keys(value).every((key) => ["max", "remaining"].includes(key)) &&
+    Number.isInteger(value.max) && (value.max as number) >= 0 &&
+    Number.isInteger(value.remaining) && (value.remaining as number) >= 0;
+}
+
+function validateBase(event: LedgerV3Object): string | null {
+  if (!isTimestamp(event.ts)) return "ts must be an RFC 3339 timestamp";
+  if (!isExecutionId(event.executionId)) return "executionId is missing or invalid";
+  if (event.parentExecutionId !== null && !isExecutionId(event.parentExecutionId)) {
+    return "parentExecutionId must be an execution id or null";
+  }
+  if (event.parentExecutionId === event.executionId) return "an execution cannot be its own parent";
+  if (!isLedgerDisplayIdentifier(event.childId)) return "childId is missing or invalid";
+  return null;
+}
+
+function validateCapabilityDecision(event: LedgerV3Object): string | null {
+  if (!isLedgerDisplayIdentifier(event.parentId) || !Number.isInteger(event.depth) || (event.depth as number) < 0) {
+    return "capability decision identity is invalid";
+  }
+  for (const field of ["requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked"]) {
+    if (!isStringArray(event[field]) || !event[field].every(isLedgerCapabilityIdentifier)) {
+      return `capability decision ${field} must contain capability identifiers`;
+    }
+  }
+  if (typeof event.blocked !== "boolean" || !EXECUTORS.has(String(event.executor)) || !SHA256_RE.test(String(event.taskDigest))) {
+    return "capability decision required fields are invalid";
+  }
+  if (!optional(event, "agentType", isLedgerDisplayIdentifier) ||
+      !optional(event, "reason", (value) => typeof value === "string") ||
+      !optional(event, "approved", (value) => isStringArray(value) && value.every(isLedgerCapabilityIdentifier)) ||
+      !optional(event, "approvalSource", (value) => APPROVAL_SOURCES.has(String(value))) ||
+      !optional(event, "approvalSources", (value) => capabilityMap(value, (entry) => APPROVAL_SOURCES.has(String(entry)))) ||
+      !optional(event, "approvalScopes", (value) => capabilityMap(value, (entry) => APPROVAL_SCOPES.has(String(entry)))) ||
+      !optional(event, "approvalExpiresAt", (value) => capabilityMap(value, isTimestamp)) ||
+      !optional(event, "approvalUses", (value) => capabilityMap(value, validApprovalUse)) ||
+      !optional(event, "approvalScope", (value) => APPROVAL_SCOPES.has(String(value))) ||
+      !optional(event, "humanDenied", (value) => value === true) ||
+      !optional(event, "gateOutcome", (value) => GATE_OUTCOMES.has(String(value))) ||
+      !optional(event, "definitionDigest", validDefinitionDigest) ||
+      !optional(event, "taskFrom", isLedgerDisplayIdentifier) ||
+      !optional(event, "taskFromExecutionId", isExecutionId) ||
+      !optional(event, "correlation", validCorrelation) ||
+      !optional(event, "refusal", validRefusal)) {
+    return "capability decision optional fields are invalid";
+  }
+  return null;
+}
+
+function validateWorkspaceLease(event: LedgerV3Object): string | null {
+  if (!isLedgerDisplayIdentifier(event.workspaceId) || !isNonEmptyString(event.root) ||
+      !["read", "write"].includes(String(event.access)) || !LEASE_OUTCOMES.has(String(event.outcome))) {
+    return "workspace lease required fields are invalid";
+  }
+  if (!optional(event, "recovered", (value) => value === true || value === false || value === "unknown") ||
+      !optional(event, "releaseReason", (value) => typeof value === "string") ||
+      !optional(event, "refusal", validRefusal) || !optional(event, "correlation", validCorrelation)) {
+    return "workspace lease optional fields are invalid";
+  }
+  return null;
+}
+
+function validateChildLifecycle(event: LedgerV3Object): string | null {
+  if (!["starting", "running", "completed", "failed"].includes(String(event.state)) || !EXECUTORS.has(String(event.executor))) {
+    return "child lifecycle required fields are invalid";
+  }
+  if (["starting", "running"].includes(String(event.state)) && !isTimestamp(event.deadlineAt)) {
+    return "deadlineAt is required and must be an RFC 3339 timestamp for a non-terminal lifecycle";
+  }
+  if (!optional(event, "deadlineAt", isTimestamp) ||
+      !optional(event, "exitCode", (value) => value === null || Number.isInteger(value)) ||
+      !optional(event, "signal", (value) => value === null || PROCESS_SIGNALS.has(String(value))) ||
+      !optional(event, "timedOut", (value) => value === true) ||
+      !optional(event, "aborted", (value) => value === true) ||
+      !optional(event, "truncated", (value) => value === true) ||
+      !optional(event, "reason", (value) => typeof value === "string") ||
+      !optional(event, "correlation", validCorrelation)) {
+    return "child lifecycle optional fields are invalid";
+  }
+  if (!optional(event, "herdrPaneId", isLedgerDisplayIdentifier) ||
+      !optional(event, "herdrAgentName", isLedgerDisplayIdentifier)) {
+    return "Herdr runtime identity is invalid";
+  }
+  if (Object.hasOwn(event, "herdrPaneId") !== Object.hasOwn(event, "herdrAgentName")) {
+    return "Herdr runtime identity must be paired";
+  }
+  if (Object.hasOwn(event, "herdrPaneId") && event.executor !== "herdr") {
+    return "Herdr runtime identity requires the Herdr executor";
+  }
+  return null;
+}
+
+function validateCheckReceipt(event: LedgerV3Object): string | null {
+  if (!SHA256_RE.test(String(event.receiptId)) || !isLedgerDisplayIdentifier(event.workspaceId) ||
+      !isLedgerDisplayIdentifier(event.checkId) || !isNonEmptyString(event.treeSha) ||
+      !optional(event, "correlation", validCorrelation)) {
+    return "check receipt required fields are invalid";
+  }
+  return null;
+}
+
+function validateWorkflowFact(event: LedgerV3Object): string | null {
+  if (!isTimestamp(event.ts) || !isWorkflowFactId(event.factId) ||
+      !isWorkflowIdentifier(event.source) || !isWorkflowIdentifier(event.subject) ||
+      !["planned", "observed", "controller_validated"].includes(String(event.provenance)) ||
+      !["workflow_phase", "inline_skill", "transition"].includes(String(event.kind)) ||
+      !["pending", "observed", "started", "completed", "blocked"].includes(String(event.state)) ||
+      !validCorrelation(event.correlation) ||
+      !isNonEmptyString((event.correlation as LedgerV3Object).run_id)) {
+    return "workflow fact required fields are invalid";
+  }
+  return workflowFactStateMatches(event.provenance, event.state)
+    ? null
+    : "workflow fact provenance contradicts its state";
+}
+
+/** Exact, content-free runtime validation for one closed ledger v3 event. */
+export function validateLedgerV3Event(event: LedgerV3Object): string | null {
+  if (event.ledgerVersion !== 3) return "unsupported ledger version";
+  const kind = event.event;
+  if (typeof kind !== "string" || !Object.hasOwn(FIELDS, kind)) return "unknown ledger event discriminator";
+  const allowed = FIELDS[kind as EventKind];
+  if (Object.keys(event).some((field) => !allowed.has(field))) return "ledger v3 contains an unsupported field";
+  if (kind === "workflow_fact") return validateWorkflowFact(event);
+  const base = validateBase(event);
+  if (base) return base;
+  if (kind === "capability_decision") return validateCapabilityDecision(event);
+  if (kind === "workspace_lease") return validateWorkspaceLease(event);
+  if (kind === "child_lifecycle") return validateChildLifecycle(event);
+  return validateCheckReceipt(event);
+}
+
+/** Ensure a public builder cannot emit bytes the closed v3 reader would reject. */
+export function assertLedgerV3Wire<T extends object>(event: T): T {
+  let wire: unknown;
+  try {
+    wire = JSON.parse(JSON.stringify(event));
+  } catch (error) {
+    throw new TypeError(`invalid ledger v3 event: ${String(error)}`);
+  }
+  if (!isLedgerObject(wire)) throw new TypeError("invalid ledger v3 event: event is not a JSON object");
+  const invalid = validateLedgerV3Event(wire);
+  if (invalid) throw new TypeError(`invalid ledger v3 event: ${invalid}`);
+  return event;
+}

package/src/ledger.ts

@@ -32,21 +32,33 @@ import type { CorrelationMetadata } from "./correlation.ts";
 import type { StructuredRefusal } from "./refusals.ts";
 // Type-only, so the cycle with ./ledger-events.ts is erased at runtime.
 import type { RuntimeLedgerEvent } from "./ledger-events.ts";
+import { assertExecutionId } from "./execution-id.ts";
+import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
 
-export const LEDGER_VERSION = 2 as const;
+export const LEDGER_VERSION = 3 as const;
+export const LEDGER_EVENT_KINDS = [
+  "capability_decision", "workspace_lease", "child_lifecycle", "check_receipt", "workflow_fact",
+] as const;
+export type LedgerEventKind = typeof LEDGER_EVENT_KINDS[number];
+export const LEDGER_GATE_OUTCOMES = ["declined", "dismissed", "no-ui", "error"] as const;
+export type LedgerGateOutcome = typeof LEDGER_GATE_OUTCOMES[number];
 
 export interface LedgerEventBase {
-  /** Optional only on the legacy-compatible `GrantRecord` public type; every v2 event builder writes it. */
+  /** Optional only on the legacy-compatible `GrantRecord` public type; every v3 event builder writes it. */
   ledgerVersion?: typeof LEDGER_VERSION;
-  event?: "capability_decision" | "workspace_lease" | "child_lifecycle" | "check_receipt";
+  event?: LedgerEventKind;
   ts: string;
+  /** Unique execution occurrence. Optional only for legacy, unversioned GrantRecord values. */
+  executionId?: string;
+  /** Explicit execution parent; null means the delegating session is not itself a governed child. */
+  parentExecutionId?: string | null;
   childId?: string;
   correlation?: CorrelationMetadata;
 }
 
 export interface GrantRecord extends LedgerEventBase {
   /**
-   * Present only when a trusted `taskDigest` was supplied — that is what makes a line v2. `buildRecord`
+   * Present only when a trusted `taskDigest` was supplied — that is what makes a line v3. `buildRecord`
    * does NOT always emit it, and the comment here used to say it did while the emission site 200 lines
    * down said the opposite. Two comments asserting contradictory facts about one field is R-28's shape.
    */
@@ -104,7 +116,7 @@ export interface GrantRecord extends LedgerEventBase {
   /** Present only when the source was a live prompt, and only when one scope covers the whole set. */
   approvalScope?: ApprovalScope;
   /** A human was asked and declined. Distinct from `denied`, which is an escalation attempt. */
-  humanDenied?: boolean;
+  humanDenied?: true;
   /**
    * WHY a gate went unsatisfied, when the answer was not a yes.
    *
@@ -120,9 +132,10 @@ export interface GrantRecord extends LedgerEventBase {
    * say *"nobody was there to ask"* and be believed, so it is recorded rather than inferred.
    *
    * **Privacy is unchanged**: this is a fixed five-member enum, not text — nothing model-authored, nothing
-   * a task could carry.
+   * a task could carry. The prompt has five outcomes, but `granted` is deliberately omitted from the
+   * four-member ledger enum because the approval source/scope fields already record a yes.
    */
-  gateOutcome?: PromptOutcomeKind;
+  gateOutcome?: LedgerGateOutcome;
   /**
    * WHICH operator-authored instructions this child was given (ADR-0018).
    *
@@ -158,6 +171,8 @@ export interface GrantRecord extends LedgerEventBase {
    * `definitionDigest` names its instructions, and neither says where the TASK came from.
    */
   taskFrom?: string;
+  /** Unique occurrence whose output composed this task; taskFrom remains the readable logical position. */
+  taskFromExecutionId?: string;
   /** Trusted SHA-256 of the exact task; task text remains forbidden (ADR-0034). */
   taskDigest?: string;
   /** Stable machine-readable refusal accompanying `reason`. */
@@ -182,6 +197,10 @@ export interface LedgerOptions {
 }
 
 export function buildRecord(args: {
+  /** Required whenever taskDigest makes this an explicit v3 event. */
+  executionId?: string;
+  /** Required (including explicit null) whenever taskDigest makes this an explicit v3 event. */
+  parentExecutionId?: string | null;
   parentId: string;
   childId: string;
   depth: number;
@@ -201,23 +220,42 @@ export function buildRecord(args: {
   definitionDigest?: DefinitionDigest;
   /** Where the child ran (ADR-0031). Required: the probe's answer survives nowhere else. */
   executor: ExecutorKind;
-  /** The child whose output composed this task (ADR-0033). Absent for anything but a chain step. */
+  /** The logical child whose output composed this task (ADR-0033). */
   taskFrom?: string;
+  /** The unique occurrence whose output composed this task. */
+  taskFromExecutionId?: string;
   taskDigest?: string;
   correlation?: CorrelationMetadata;
   refusal?: StructuredRefusal;
   now: Date;
 }): GrantRecord {
+  if (args.taskDigest !== undefined) {
+    if (!/^[a-f0-9]{64}$/i.test(args.taskDigest)) throw new TypeError("taskDigest must be a SHA-256 hex digest");
+    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");
+    if (args.taskFromExecutionId !== undefined) assertExecutionId(args.taskFromExecutionId, "taskFromExecutionId");
+  }
+  if (args.definitionDigest && !/^[a-f0-9]{64}$/i.test(args.definitionDigest.sha256)) {
+    throw new TypeError("definitionDigest.sha256 must be a SHA-256 hex digest");
+  }
   // R-46: the scalar is a SUMMARY, emitted only when it cannot mislead. `buildRecord` derives it rather
   // than accepting it, so a call site cannot supply one that disagrees with the map beside it.
   const sources = args.approvalSources ?? {};
   const distinct = [...new Set(Object.values(sources))];
   const scopes = args.approvalScopes ?? {};
   const distinctScopes = [...new Set(Object.values(scopes))];
-  return {
-    // A trusted task digest is what distinguishes a v2 capability event from the legacy construction API.
+  const record: GrantRecord = {
+    // A trusted task digest is what distinguishes a v3 capability event from the legacy construction API.
     // Production delegation always supplies it; old TypeScript callers remain able to append legacy lines.
-    ...(args.taskDigest ? { ledgerVersion: LEDGER_VERSION, event: "capability_decision" as const } : {}),
+    ...(args.taskDigest !== undefined
+      ? {
+          ledgerVersion: LEDGER_VERSION,
+          event: "capability_decision" as const,
+          executionId: args.executionId,
+          parentExecutionId: args.parentExecutionId,
+        }
+      : {}),
     ts: args.now.toISOString(),
     parentId: args.parentId,
     childId: args.childId,
@@ -225,7 +263,8 @@ export function buildRecord(args: {
     agentType: args.agentType,
     executor: args.executor,
     ...(args.taskFrom ? { taskFrom: args.taskFrom } : {}),
-    ...(args.taskDigest ? { taskDigest: args.taskDigest } : {}),
+    ...(args.taskFromExecutionId ? { taskFromExecutionId: args.taskFromExecutionId } : {}),
+    ...(args.taskDigest !== undefined ? { taskDigest: args.taskDigest } : {}),
     ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
     ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
     requested: args.requested,
@@ -252,6 +291,8 @@ export function buildRecord(args: {
     ...(args.gateOutcome && args.gateOutcome !== "granted" ? { gateOutcome: args.gateOutcome } : {}),
     ...(args.definitionDigest ? { definitionDigest: args.definitionDigest } : {}),
   };
+  if (args.taskDigest !== undefined) assertLedgerV3Wire(record);
+  return record;
 }
 
 // R-49: the lock moved to `src/file-lock.ts` so the approvals store could use the SAME one rather than
@@ -302,11 +343,33 @@ export function isEscalationAttempt(record: GrantRecord): boolean {
 }
 
 export {
+  CHILD_LIFECYCLE_STATES,
+  CHILD_PROCESS_SIGNALS,
+  WORKSPACE_ACCESSES,
+  WORKSPACE_LEASE_OUTCOMES,
+  WORKSPACE_RECOVERY_VALUES,
+  buildCheckReceiptLedgerEvent,
   buildChildLifecycleEvent,
   buildWorkspaceLeaseEvent,
+  type CapabilityDecisionEvent,
   type ChildLifecycleEvent,
+  type ChildLifecycleState,
+  type ChildProcessSignal,
   type CheckReceiptLedgerEvent,
   type RuntimeLedgerEvent,
+  type WorkspaceAccess,
   type WorkspaceLeaseEvent,
   type WorkspaceLeaseOutcome,
+  type WorkspaceRecovery,
 } from "./ledger-events.ts";
+
+export {
+  WORKFLOW_FACT_KINDS,
+  WORKFLOW_FACT_PROVENANCE,
+  WORKFLOW_FACT_STATES,
+  buildWorkflowFactEvent,
+  type WorkflowFactEvent,
+  type WorkflowFactKind,
+  type WorkflowFactProvenance,
+  type WorkflowFactState,
+} from "./workflow-facts.ts";

package/src/propagation.ts

@@ -27,6 +27,7 @@
 
 import type { Capability } from "./resolve.ts";
 import { WILDCARD } from "./pi-tools.ts";
+import { WORKSPACE_WILDCARD } from "./resolve.ts";
 import { inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { assertCapabilitiesArePropagatable } from "./capabilities.ts";
 
@@ -45,6 +46,8 @@ export const ENV_FANOUT = "PI_GRANTS_FANOUT";
  * Without it every level restarts at `d0` and the ledger cannot be joined into a tree across processes.
  */
 export const ENV_PARENT_ID = "PI_GRANTS_PARENT_ID";
+/** Unique identity of this governed execution occurrence; unlike ENV_PARENT_ID it is never reused. */
+export const ENV_EXECUTION_ID = "PI_GRANTS_EXECUTION_ID";
 export const ENV_DEPTH = "PI_GRANTS_DEPTH";
 export const ENV_MAX_DEPTH = "PI_GRANTS_MAX_DEPTH";
 export const ENV_GATED = "PI_GRANTS_GATED";
@@ -67,6 +70,7 @@ export const GRANT_ENV_KEYS = [
   ENV_APPROVED,
   ENV_FANOUT,
   ENV_PARENT_ID,
+  ENV_EXECUTION_ID,
 ] as const;
 
 export const parseList = (raw: string | undefined): Capability[] =>
@@ -247,9 +251,28 @@ export interface ChildEnvInput {
  * empty grant, so they can spawn nothing. That fails closed. It is also unreachable in normal flow,
  * because a session's first provider request always precedes its first tool call.
  */
+/**
+ * The part of a grant a child may inherit: everything but the wildcards that are HELD, never handed down.
+ *
+ * `tool:*` for R-26's reason — a root that handed it down let every descendant reacquire the full catalog.
+ * `workspace:*` for the same reason one namespace over (R-131): a descendant holding it could route anywhere
+ * the registry lists, which is the attenuation failure ADR-0035 exists to close. `agent:*` is deliberately
+ * NOT stripped — ADR-0023 decided that a session authorised for any definition passes that on, because
+ * definitions are ceilings rather than roots.
+ *
+ * **Exported, and there is exactly one spelling of this rule on purpose.** It shipped as a filter inline in
+ * `childEnv` and nowhere else, so a grant travelling the OTHER path — `delegate.ts` building a child's
+ * `PI_GRANTS_GRANT` from `result.effective` — carried `workspace:*` straight down. The test written beside
+ * that fix exercised `childEnv`, which is not the path a delegated child's grant travels, so it could not
+ * catch it. R-28's shape: two routes for one rule, with the guard on the quieter one. Both call this now.
+ */
+export function inheritableGrant(grant: readonly Capability[]): Capability[] {
+  return grant.filter((c) => c !== WILDCARD && c !== WORKSPACE_WILDCARD);
+}
+
 export function childEnv(input: ChildEnvInput): Record<string, string> {
   if (input.governed === false) return {};
-  const inheritable = input.ownGrant.filter((c) => c !== WILDCARD);
+  const inheritable = inheritableGrant(input.ownGrant);
   const env: Record<string, string> = {
     [ENV_GRANT]: (assertCapabilitiesArePropagatable(inheritable), inheritable.join(",")),
     [ENV_DEPTH]: String(input.depth + 1),

package/src/refusals.ts

@@ -28,6 +28,7 @@ export const REFUSAL_CODES = [
   "LEDGER_WRITE_FAILED",
   "FANOUT_FAILED",
   "WORKSPACE_NOT_REGISTERED",
+  "WORKSPACE_NOT_AUTHORIZED",
   "WORKSPACE_WRITE_CONFLICT",
   "WORKSPACE_LEASE_STALE",
   "CHECK_NOT_CONFIGURED",

package/src/resolve.ts

@@ -76,6 +76,16 @@ import { isWellFormedCapability } from "./capabilities.ts";
  * `tool:*` — authority to grant every tool — which made the safe configuration the laborious one.
  */
 export const AGENT_WILDCARD: Capability = "agent:*";
+/**
+ * `workspace:*` covers any `workspace:<id>` — ADR-0035, and the second namespace wildcard.
+ *
+ * Added as a deliberate edit, which is what the comment in `resolve()` below asks for: there is no
+ * generalised `<ns>:*` rule, so a namespace does not acquire a wildcard by existing. Unlike `agent:*` this
+ * one is **not inheritable** (`childEnv` strips it) — R-26's rule, because a root that handed
+ * `workspace:*` down would make routing attenuation meaningless below the root, which is the exact defect
+ * R-131 records.
+ */
+export const WORKSPACE_WILDCARD: Capability = "workspace:*";
 
 export interface ResolveInput {
   /** What the delegating agent asked to give the child. */
@@ -125,7 +135,10 @@ export function resolve(input: ResolveInput): ResolveResult {
   const parent =
     input.subsumption === false ? held : new Set(expandSubsumed(input.parentGrant));
   /**
-   * `agent:*` covers any `agent:<name>` — ADR-0023, and the ONLY wildcard rule in this function.
+   * `agent:*` covers any `agent:<name>` — ADR-0023. It was the only wildcard rule in this function when
+   * that was written; ADR-0035 added a third, so `covered()` now has `tool:*`, `agent:*` and `workspace:*`.
+   * There is still no GENERALISED `<ns>:*` rule: each is a deliberate edit, which is the property worth
+   * keeping. Corrected because the sentence sat eighty lines above "all THREE wildcards are excluded".
    *
    * `resolve` is otherwise exact-match plus subsumption, deliberately: `tool:*` works not because anything
    * here understands it, but because `deriveOwnGrant` *enumerates* a session's observed tool names beside
@@ -150,13 +163,17 @@ export function resolve(input: ResolveInput): ResolveResult {
    * spellings of one rule, and the enforcing one was wrong.
    */
   const anyCapability = held.has(WILDCARD);
+  const anyWorkspace = held.has(WORKSPACE_WILDCARD);
   // A malformed id is never covered — not by an exact hold, and above all not by a wildcard's PREFIX rule,
   // which is how `agent:x,tool:bash` got admitted and then split into two capabilities in the child.
   // Landing in `denied` is the right outcome rather than a throw: it fails closed AND records an
   // escalation attempt, so the ledger shows the attempt instead of a clean line.
   const covered = (c: Capability): boolean =>
     isWellFormedCapability(c)
-    && (parent.has(c) || anyCapability || (anyDefinition && c.startsWith("agent:")));
+    && (parent.has(c) || anyCapability
+      || (anyDefinition && c.startsWith("agent:"))
+      || (anyWorkspace && c.startsWith("workspace:")));
+
   const ceiling = input.ceiling === undefined ? null : new Set(input.ceiling);
   const gated = new Set(input.gated ?? []);
   const approved = new Set(input.approved ?? []);
@@ -199,7 +216,16 @@ export function resolve(input: ResolveInput): ResolveResult {
     // F9: capabilities covered by a WILDCARD are not "subsumed" — this field means "the grant is broader
     // than its list suggests", which is the `bash`-covers-`grep` warning. A wildcard holder already knows
     // its grant is broad; listing every id under it would bury the signal the field exists to carry.
-    subsumedBy: effective.filter((c) => !held.has(c) && !anyCapability && !(anyDefinition && c.startsWith("agent:"))),
+    //
+    // All THREE wildcards are excluded. `anyWorkspace` was missing, so a caller holding `workspace:*` saw
+    // its own `workspace:prod` reported as subsumed while the `agent:*` holder correctly saw nothing — the
+    // field contradicting its own rule, and a false "broader than it looks" flag in the ledger and in
+    // `/grants`. Every wildcard added to `covered()` above needs a line here; that is now three for three.
+    subsumedBy: effective.filter((c) =>
+      !held.has(c)
+      && !anyCapability
+      && !(anyDefinition && c.startsWith("agent:"))
+      && !(anyWorkspace && c.startsWith("workspace:"))),
   };
 }