pi-daddy 0.28.0 → 0.32.0

package/src/kernel/catalog.ts

@@ -0,0 +1,313 @@
+/**
+ * Live capability catalog — what *can* be granted, enumerated at runtime.
+ *
+ * Until now grants were checked against agent-type files alone, which covers `tool:` capabilities and
+ * nothing else. That leaves two gaps: extension tools are invisible (so `ext:` grants cannot be
+ * validated), and **skills were ungovernable** despite "skills and tools" being half the requirement.
+ *
+ * Sources, and why each is trusted:
+ *  - **tools** — the `tools` array of a live provider request. Authoritative: it is exactly what pi sent
+ *    the model, so it includes extension-registered tools and reflects any `--tools` allowlist already in
+ *    force. Nothing else can see the real surface.
+ *  - **skills** — `SKILL.md` directories and top-level `.md` files under pi's skill roots.
+ *  - **definitions** — spawnable `SKILL.md` agents (ADR-0016), as `agent:<name>`.
+ *
+ * Provenance note: a provider payload gives tool NAMES, not owning packages, so extension tools cannot be
+ * qualified as `ext:<pkg>/<tool>` from that source alone. They are catalogued as `tool:<name>` — which is
+ * also how pi's `--tools` matches — and marked `kind: "extension"` for display. `ext:` ids remain
+ * supported for hand-authored grants; `deriveOwnGrant` already matches them by bare name.
+ */
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
+import { join } from "node:path";
+import { loadDefinitions, type SkillDefinition } from "./definitions.ts";
+import { PI_BUILTIN_TOOLS, WILDCARD } from "./pi-tools.ts";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
+import { loadWorkspaceRegistry, type WorkspaceRegistryFile } from "./workspace.ts";
+import { isSafeWorkspaceId } from "./capabilities.ts";
+import { piProjectDir } from "./project-paths.ts";
+
+export type CapabilityKind = "builtin" | "extension" | "skill" | "agentType" | "workspace";
+
+export interface CatalogEntry {
+  capability: Capability;
+  kind: CapabilityKind;
+  /** Where it was found, for display and debugging. */
+  source?: string;
+}
+
+export interface Catalog {
+  entries: CatalogEntry[];
+  /** Every capability id in the catalog. */
+  all: Capability[];
+  byKind(kind: CapabilityKind): Capability[];
+  has(capability: Capability): boolean;
+}
+
+/** Split observed tool names into pi built-ins and extension-provided tools. */
+export function classifyToolNames(observed: string[]): CatalogEntry[] {
+  const builtins = new Set<string>(PI_BUILTIN_TOOLS);
+  return [...new Set(observed)].sort().map((name) => ({
+    capability: `tool:${name}`,
+    kind: builtins.has(name) ? ("builtin" as const) : ("extension" as const),
+  }));
+}
+
+/** Skill roots pi discovers, project first. */
+export function skillDirs(cwd: string): string[] {
+  return [join(piProjectDir(cwd), "skills"), join(getAgentDir(), "skills")];
+}
+
+/** Enumerate the same enabled Pi resource paths as definitions, preserving resolver precedence. */
+export async function loadSkills(cwd: string): Promise<CatalogEntry[]> {
+  const found = new Map<string, CatalogEntry>();
+  for (const { path } of (await resolveSkillResources(cwd)).skills) {
+    const name = skillResourceName(path);
+    if (!found.has(name)) found.set(name, { capability: `skill:${name}`, kind: "skill", source: path });
+  }
+  return [...found.values()];
+}
+
+/**
+ * Spawnable definitions, as `agent:<name>` capabilities.
+ *
+ * A definition is BOTH a skill (loadable into a session) and an agent (spawnable as a child) — ADR-0016
+ * collapsed those into one file — so the same `SKILL.md` legitimately appears twice in the catalog under
+ * two capability ids. That is not duplication: `skill:review` means "may load these instructions" and
+ * `agent:review` means "may spawn a child running them", and a grant can hold either without the other.
+ */
+export function definitionEntries(definitions: Map<string, SkillDefinition>): CatalogEntry[] {
+  return [...definitions.values()].map((d) => ({
+    capability: `agent:${d.name}`,
+    kind: "agentType" as const,
+    source: d.source,
+  }));
+}
+
+/**
+ * Registered workspaces, as `workspace:<id>` capabilities (ADR-0035).
+ *
+ * For DISPLAY and SCAFFOLDING only — `/grants` listing what this session may route to, and `init` offering
+ * the ids without choosing among them (ADR-0028). It is deliberately **not** what `unknownCapabilities`
+ * checks against; see the comment there.
+ *
+ * The operator registry is the authority on which ids exist, exactly as it is at `resolveWorkspace`. This
+ * enumerates it; it does not decide anything.
+ */
+export function workspaceEntries(registry: WorkspaceRegistryFile, source?: string): CatalogEntry[] {
+  return Object.keys(registry.workspaces)
+    .sort()
+    .map((id) => ({
+      capability: `workspace:${id}` as Capability,
+      kind: "workspace" as const,
+      ...(source ? { source } : {}),
+    }));
+}
+
+/** Assemble a catalog from parts. Pure, so it is testable without a filesystem. */
+export function makeCatalog(entries: CatalogEntry[]): Catalog {
+  const deduped = new Map<Capability, CatalogEntry>();
+  for (const entry of entries) if (!deduped.has(entry.capability)) deduped.set(entry.capability, entry);
+  const list = [...deduped.values()].sort((a, b) => a.capability.localeCompare(b.capability));
+  const ids = list.map((e) => e.capability);
+  const idSet = new Set(ids);
+  return {
+    entries: list,
+    all: ids,
+    byKind: (kind) => list.filter((e) => e.kind === kind).map((e) => e.capability),
+    has: (capability) => idSet.has(capability),
+  };
+}
+
+/** Build the live catalog. `observedTools` comes from a provider payload; null when not yet seen. */
+export async function buildCatalog(input: {
+  cwd: string;
+  observedTools: string[] | null;
+  /** Operator workspace registry (`PI_DADDY_WORKSPACE_REGISTRY`). Absent or unreadable yields no entries. */
+  registryPath?: string;
+}): Promise<Catalog> {
+  const [skills, definitions, workspaces] = await Promise.all([
+    loadSkills(input.cwd),
+    loadDefinitions(input.cwd),
+    // Fails SOFT, and only because nothing here is an authority. A malformed registry must not stop a
+    // session from starting — `loadWorkspaceRegistry` throws a GovernanceRefusal naming the file, and that
+    // refusal is the operator's signal at the point of USE, where routing actually depends on it. Swallowing
+    // it there would be unsafe; swallowing it here costs a display list.
+    input.registryPath
+      ? loadWorkspaceRegistry(input.registryPath).then(
+          (r) => workspaceEntries(r, input.registryPath),
+          () => [] as CatalogEntry[],
+        )
+      : Promise.resolve([] as CatalogEntry[]),
+  ]);
+  return makeCatalog([
+    // pi's built-ins are seeded unconditionally, because they are known statically and the catalog is
+    // consulted BEFORE any provider request has happened — `/grants` runs at that point. Without this,
+    // every capability looked "unknown" until the first model call, so the preview refused grants that
+    // enforcement would have allowed: R-28's failure shape (a diagnostic disagreeing with the enforcer)
+    // reappearing through a different door.
+    //
+    // The trade-off, stated plainly: in a session started with `--tools read`, this still lists `bash`
+    // as an existing capability, so a delegation naming it passes the *unknown* check and is refused by
+    // the *grant* check instead ("this session does not hold it"). That is the better error anyway, and
+    // the grant check — not this catalog — is the authority. Nothing here grants anything.
+    ...PI_BUILTIN_TOOLS.map((name) => ({ capability: `tool:${name}` as const, kind: "builtin" as const })),
+    ...(input.observedTools ? classifyToolNames(input.observedTools) : []),
+    ...skills,
+    ...definitionEntries(definitions),
+    ...workspaces,
+  ]);
+}
+
+/**
+ * Capabilities requested that the catalog does not contain.
+ *
+ * Reported separately from `denied` because the causes differ and so do the fixes: `denied` means the
+ * delegator lacks authority, `unknown` means the capability does not exist here — usually a typo or a
+ * stale grant referring to an uninstalled package. Silently treating unknown as denied hides that.
+ */
+export function unknownCapabilities(requested: Capability[], catalog: Catalog): Capability[] {
+  // Wildcards are GRAMMAR, not entries. Nothing enumerates them into the catalog — `definitionEntries`
+  // emits `agent:<name>` per discovered definition and `PI_BUILTIN_TOOLS` contains no `*` — so this check
+  // reported `agent:*` as *"not present in this session's catalog (typo, or an uninstalled package?)"* and
+  // refused it BEFORE `resolve` could apply ADR-0023's rule. That made the ADR's "a parent holding
+  // `agent:*` may hand down `agent:*`" false, and made a definition declaring `allowed-tools: agent:*`
+  // unspawnable from any grant. The wildcard is live only at the root without this.
+  //
+  // `workspace:` is exempt as a NAMESPACE, not merely at its wildcard, and that asymmetry is deliberate.
+  // ADR-0035 minted the namespace and taught `normaliseCapability`, `resolve` and `childEnv` about it, but
+  // not this line — so with a catalog present (and `delegationContext` always supplies one) every requested
+  // `workspace:<id>` was refused UNKNOWN_TOOL as *"a typo, or an uninstalled package"*. A child could
+  // therefore never be granted a workspace capability at all, which made routing stop dead below the root
+  // instead of attenuating, and made the ADR's own "two authorities, not one" unreachable in production.
+  //
+  // Exempt rather than catalogued-and-checked because the operator registry is the authority and it is
+  // consulted where it matters: `resolveWorkspace` refuses an unregistered id with WORKSPACE_NOT_REGISTERED,
+  // naming the registry. A second, weaker check here can only turn that precise refusal into a misleading
+  // one — and it would do so for reasons that have nothing to do with the id, like a registry this session
+  // cannot read. `buildCatalog` still ENUMERATES workspaces, for `/grants` and for `init`'s scaffold; that
+  // is display, and display is not authority. Same trade-off the built-ins comment above states and accepts.
+  // The workspace exemption requires a WELL-FORMED id, not merely the prefix. A bare `workspace:` names
+  // nothing, and exempting it let it reach a child's grant and the ledger as authority over no workspace at
+  // all — an exemption for ids the registry is authoritative about should not also cover ids no registry
+  // could contain.
+  // `WORKSPACE_WILDCARD` is listed with the other two because it is GRAMMAR, and `isSafeCapability` refuses
+  // wildcards by design — so folding it into the namespace test below un-exempts it. Caught by the tests for
+  // the previous two fixes, which is the checklist paying for itself.
+  const exempt = (c: Capability) =>
+    c === WILDCARD ||
+    c === AGENT_WILDCARD ||
+    c === WORKSPACE_WILDCARD ||
+    (c.startsWith("workspace:") && isSafeWorkspaceId(c.slice("workspace:".length)));
+  return requested.filter((c) => !exempt(c) && !catalog.has(c)).sort();
+}
+
+/**
+ * Tool names that exist in OTHER harnesses' vocabularies, mapped to the pi tool that does the same job.
+ *
+ * This is a hint for an error message and nothing else. `ceilingForDefinition` deliberately refuses to
+ * translate names — lowercasing and no more — because a translation table there would have to decide what
+ * `Glob` *means* and would either invent a grant or silently drop one. Naming a likely intent in the
+ * refusal costs nothing and keeps that property: the delegation is still refused, and the author still
+ * edits the file.
+ *
+ * Populated from the names an author actually reaches for. `allowed-tools` is an Agent Skills field, so
+ * the frontmatter people copy in is usually written against Claude Code's toolset; `Glob` is the one that
+ * bit a real consumer (principal-pi-skills, seven definitions), because pi's equivalent is `find`.
+ */
+const FOREIGN_TOOL_NAMES: Readonly<Record<string, string>> = {
+  "tool:glob": "tool:find",
+  "tool:searchfiles": "tool:find",
+  "tool:bashtool": "tool:bash",
+  "tool:readfile": "tool:read",
+  "tool:writefile": "tool:write",
+  "tool:str_replace_editor": "tool:edit",
+  "tool:multiedit": "tool:edit",
+};
+
+/**
+ * Optimal string alignment distance — Levenshtein plus adjacent transposition.
+ *
+ * Transposition counts as ONE edit, not two, because it is the typo people actually make: `raed` for
+ * `read` is a single slip of the fingers, and plain Levenshtein scores it 2 — the same as two unrelated
+ * substitutions. With the threshold this small, that difference is the whole feature.
+ */
+function editDistance(a: string, b: string): number {
+  // Three rows, because a transposition needs the row before last.
+  const rows: number[][] = [
+    Array.from({ length: b.length + 1 }, (_, j) => j),
+    new Array<number>(b.length + 1).fill(0),
+    new Array<number>(b.length + 1).fill(0),
+  ];
+  let twoBack = rows[2];
+  let prev = rows[0];
+  let cur = rows[1];
+
+  for (let i = 1; i <= a.length; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let d = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        d = Math.min(d, twoBack[j - 2] + 1);
+      }
+      cur[j] = d;
+    }
+    const spent = twoBack;
+    twoBack = prev;
+    prev = cur;
+    cur = spent;
+  }
+  return prev[b.length];
+}
+
+/**
+ * The capability an unknown one was most likely meant to be, or null when nothing is close enough.
+ *
+ * Two sources, in order. A known foreign name wins outright — `Glob` is not a typo for `find`, so no
+ * distance metric would ever connect them, and that is exactly the case worth naming. Otherwise the
+ * nearest catalog entry within a small edit distance, which catches `raed`/`serach` and stops well short
+ * of guessing: the threshold scales with the name's length and never exceeds two.
+ */
+export function suggestForUnknown(unknown: Capability, catalog: Catalog): Capability | null {
+  const foreign = FOREIGN_TOOL_NAMES[unknown.toLowerCase()];
+  if (foreign && catalog.has(foreign)) return foreign;
+
+  // Only among capabilities of the same namespace: suggesting `skill:review` for a mistyped tool name
+  // would be a worse message than none, because it points the author at the wrong kind of fix.
+  const ns = unknown.slice(0, unknown.indexOf(":") + 1);
+  if (!ns) return null;
+  const bare = unknown.slice(ns.length);
+  const limit = Math.min(2, Math.floor(bare.length / 3));
+  if (limit < 1) return null;
+
+  let best: Capability | null = null;
+  let bestDistance = limit + 1;
+  for (const candidate of catalog.all) {
+    if (!candidate.startsWith(ns)) continue;
+    const d = editDistance(bare, candidate.slice(ns.length));
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = candidate;
+    }
+  }
+  return bestDistance <= limit ? best : null;
+}
+
+/**
+ * Skill name -> absolute path, for `planSpawn`'s `--skill` flags (R-32).
+ *
+ * Derived from the catalog's own `source` field rather than re-scanning, so what a child is handed
+ * cannot drift from what was discovered and offered. A skill entry without a source is omitted, which
+ * makes it *unresolvable* rather than silently absent — `planDelegation` refuses on that, because a
+ * grant naming a skill the child never receives is a ledger line that lies.
+ */
+export function skillPathsFromCatalog(catalog: Catalog): Record<string, string> {
+  const paths: Record<string, string> = {};
+  for (const entry of catalog.entries) {
+    if (entry.kind !== "skill" || !entry.source) continue;
+    paths[entry.capability.slice("skill:".length)] = entry.source;
+  }
+  return paths;
+}

package/src/kernel/correlation.ts

@@ -0,0 +1,351 @@
+import { createHash } from "node:crypto";
+import type { DefinitionDigest } from "./definitions.ts";
+import type { Capability } from "./resolve.ts";
+import { GovernanceRefusal, refusal } from "./refusals.ts";
+import { isLedgerCorrelationIdentifier } from "./ledger-identifiers.ts";
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export interface AssuranceScope {
+  type: "entire-run" | "selectors";
+  selectors: string[];
+}
+
+/**
+ * Non-authoritative workflow metadata copied onto runtime and ledger events.
+ *
+ * pi-daddy interprets only the pinned correlation wire contract: schema version 1.0 and the closed
+ * assurance-scope shape. Labels, selector meanings, timestamps and sequence floors remain non-authoritative.
+ * In particular, a digest-looking value here never substitutes for a digest computed by the planner. The
+ * snake_case names are the wire vocabulary used by external controllers.
+ */
+export interface CorrelationMetadata {
+  schema_version?: string;
+  run_id?: string;
+  task_id?: string;
+  workspace_id?: string;
+  context_id?: string;
+  phase?: string;
+  assurance?: string;
+  assurance_effective?: string;
+  policy_label?: string;
+  assurance_source?: string;
+  assurance_scope?: AssuranceScope;
+  activated_at?: string;
+  plan_digest?: string;
+  definition_digest?: string;
+  task_digest?: string;
+  base_sha?: string;
+  head_sha?: string;
+  tree_sha?: string;
+  event_seq?: number;
+  last_change_seq?: number;
+  last_authority_seq?: number;
+  check_receipt_id?: string;
+}
+
+const MAX_CORRELATION_BYTES = 32 * 1024;
+/**
+ * Per-field bound on the STRING fields — most are an id, a digest, a label or a timestamp. It does not
+ * apply to the three sequence numbers or to `assurance_scope`, which are checked separately; an earlier
+ * version of this comment claimed it covered every declared field.
+ */
+const MAX_CORRELATION_FIELD_CHARS = 512;
+/** `assurance_scope` is the one structured field, so it gets its own, larger bound. */
+const MAX_CORRELATION_SCOPE_BYTES = 4 * 1024;
+
+/**
+ * The exact field set of the pinned schema 1.0 contract. Anything else is refused by name.
+ *
+ * This is a whitelist rather than a size cap because `correlation` is a MODEL-FACING tool parameter that
+ * is copied verbatim onto every append-only ledger event. `src/governance/ledger.ts` states the invariant — capability
+ * ids, counts and identifiers only, never prompts, tool arguments or results — and ADR-0034 repeats that the
+ * ledger must never carry task text. A 32 KB "bounded JSON object" with no key whitelist and no per-field
+ * length bound satisfied neither: `assurance_scope` was declared `Type.Any()`, undeclared keys survived the
+ * round trip, and every string was unbounded, so a model could write 32 KB of arbitrary text into the
+ * ledger through it (R-111). Refusing an unknown key is also the loud option: if upstream adds a field, the
+ * refusal names it, which is an actionable break rather than a silent secrets sink.
+ */
+const CORRELATION_FIELDS = new Set<keyof CorrelationMetadata>([
+  "schema_version",
+  "run_id",
+  "task_id",
+  "workspace_id",
+  "context_id",
+  "phase",
+  "assurance",
+  "assurance_effective",
+  "policy_label",
+  "assurance_source",
+  "assurance_scope",
+  "activated_at",
+  "plan_digest",
+  "definition_digest",
+  "task_digest",
+  "base_sha",
+  "head_sha",
+  "tree_sha",
+  "event_seq",
+  "last_change_seq",
+  "last_authority_seq",
+  "check_receipt_id",
+]);
+
+const CORRELATION_NUMERIC = new Set<keyof CorrelationMetadata>(["event_seq", "last_change_seq", "last_authority_seq"]);
+
+// These fields are rendered as labels/identities. Treating arbitrary prose as an "id" let a model copy
+// task or output text into the ledger and dashboard through correlation while staying schema-valid.
+const CORRELATION_IDENTIFIERS = new Set<keyof CorrelationMetadata>([
+  "schema_version",
+  "run_id",
+  "task_id",
+  "workspace_id",
+  "context_id",
+  "phase",
+  "assurance",
+  "assurance_effective",
+  "policy_label",
+  "assurance_source",
+]);
+
+function correlationRefusal(message: string, details?: Record<string, string | number>): GovernanceRefusal {
+  return new GovernanceRefusal(refusal("CORRELATION_INVALID", `correlation metadata: ${message}`, details));
+}
+
+/**
+ * Size refusals get their own code, because they call for a different response: "you sent too much" is
+ * retryable by truncating, "you sent a field we do not recognise" is not. `CORRELATION_TOO_LARGE` was
+ * declared in the taxonomy and constructed nowhere, so the union advertised a distinction the code did not
+ * make — and the enumeration test kept the dead member green.
+ */
+function correlationTooLarge(message: string, details?: Record<string, string | number>): GovernanceRefusal {
+  return new GovernanceRefusal(refusal("CORRELATION_TOO_LARGE", `correlation metadata: ${message}`, details));
+}
+
+function normaliseAssuranceScope(value: unknown): AssuranceScope {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw correlationRefusal("assurance_scope must be an object with type and selectors");
+  }
+  const scope = value as Record<string, unknown>;
+  const keys = Object.keys(scope).sort();
+  if (keys.length !== 2 || keys[0] !== "selectors" || keys[1] !== "type") {
+    throw correlationRefusal("assurance_scope must contain only type and selectors");
+  }
+  if (
+    !Array.isArray(scope.selectors) ||
+    !scope.selectors.every((selector) => typeof selector === "string" && selector.length > 0)
+  ) {
+    throw correlationRefusal("assurance_scope selectors must be non-empty strings");
+  }
+  if (scope.type === "entire-run") {
+    if (scope.selectors.length !== 0) throw correlationRefusal("entire-run assurance_scope requires empty selectors");
+    return { type: "entire-run", selectors: [] };
+  }
+  if (scope.type === "selectors") {
+    if (scope.selectors.length === 0) throw correlationRefusal("selectors scope requires at least one selector");
+    return { type: "selectors", selectors: [...scope.selectors] };
+  }
+  throw correlationRefusal("assurance_scope type must be entire-run or selectors");
+}
+
+/**
+ * Snapshot bounded JSON metadata so a caller cannot mutate a record after planning, and so nothing
+ * unbounded or undeclared can reach the ledger through it.
+ *
+ * Refuses with a stable code rather than a bare `Error`: this is reachable from a model-facing tool
+ * parameter on all three delegation tools, and it used to throw outside every try, producing a governed
+ * refusal with no code and no ledger line at all (R-112).
+ */
+export function normaliseCorrelation(input: CorrelationMetadata | undefined): CorrelationMetadata | undefined {
+  if (input === undefined) return undefined;
+  let encoded: string;
+  try {
+    encoded = JSON.stringify(input);
+  } catch (error) {
+    throw correlationRefusal(`must be JSON serializable (${String(error)})`);
+  }
+  if (encoded === undefined) throw correlationRefusal("must be a JSON object");
+  if (Buffer.byteLength(encoded) > MAX_CORRELATION_BYTES) {
+    throw correlationTooLarge(`exceeds ${MAX_CORRELATION_BYTES} bytes`, { limit: MAX_CORRELATION_BYTES });
+  }
+  const parsed = JSON.parse(encoded) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw correlationRefusal("must be a JSON object");
+  }
+
+  const source = parsed as Record<string, unknown>;
+  const undeclared = Object.keys(source).filter((key) => !CORRELATION_FIELDS.has(key as keyof CorrelationMetadata));
+  if (undeclared.length > 0) {
+    throw correlationRefusal(`carries fields outside the pinned schema 1.0 contract: ${undeclared.sort().join(", ")}`, {
+      undeclared: undeclared.sort().join(","),
+    });
+  }
+
+  const output: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined || value === null) continue;
+    if (key === "assurance_scope") {
+      const size = Buffer.byteLength(JSON.stringify(value) ?? "");
+      if (size > MAX_CORRELATION_SCOPE_BYTES) {
+        throw correlationTooLarge(`assurance_scope exceeds ${MAX_CORRELATION_SCOPE_BYTES} bytes`, {
+          limit: MAX_CORRELATION_SCOPE_BYTES,
+          actual: size,
+        });
+      }
+      output[key] = normaliseAssuranceScope(value);
+      continue;
+    }
+    if (CORRELATION_NUMERIC.has(key as keyof CorrelationMetadata)) {
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw correlationRefusal(`${key} must be a finite number`, { field: key });
+      }
+      output[key] = value;
+      continue;
+    }
+    if (typeof value !== "string") throw correlationRefusal(`${key} must be a string`, { field: key });
+    if (key === "schema_version" && value !== "1.0") {
+      throw correlationRefusal(`unsupported schema_version ${value}; supported version is 1.0`, {
+        field: key,
+        supported: "1.0",
+      });
+    }
+    if (value.length > MAX_CORRELATION_FIELD_CHARS) {
+      throw correlationTooLarge(`${key} exceeds ${MAX_CORRELATION_FIELD_CHARS} characters`, {
+        field: key,
+        limit: MAX_CORRELATION_FIELD_CHARS,
+        actual: value.length,
+      });
+    }
+    if (CORRELATION_IDENTIFIERS.has(key as keyof CorrelationMetadata) && !isLedgerCorrelationIdentifier(value)) {
+      throw correlationRefusal(`${key} must be an ASCII identifier, not free-form text`, { field: key });
+    }
+    output[key] = value;
+  }
+  return output as CorrelationMetadata;
+}
+
+export function digestTask(task: string): string {
+  return createHash("sha256").update(task, "utf8").digest("hex");
+}
+
+export function digestCapabilities(capabilities: readonly Capability[]): string {
+  const canonical = [...new Set(capabilities)].sort();
+  return createHash("sha256").update(JSON.stringify(canonical), "utf8").digest("hex");
+}
+
+/** Trusted, internally-computed scope of one gated approval. */
+export interface ApprovalBinding {
+  version: "1";
+  task_sha256: string;
+  requested_sha256: string;
+  effective_sha256: string;
+  requested: Capability[];
+  effective: Capability[];
+  definition_sha256?: string;
+  workspace_id?: string;
+  context_id?: string;
+  tree_sha?: string;
+  last_change_seq?: number;
+  parent_id: string;
+}
+
+/**
+ * Builds the binding from TRUSTED values only. It deliberately does not take a `CorrelationMetadata`.
+ *
+ * It used to read `workspace_id` and `context_id` straight out of caller-supplied correlation into what
+ * the comment above calls the trusted scope, and a bound approval could then be spent outside the
+ * workspace it named (R-110): approve a delegation carrying a real, registry-validated `workspace` spec,
+ * then re-issue the identical task with `correlation.workspace_id` set and NO `workspace` field — no
+ * registry lookup, no lease, the parent's own cwd, and every digest still matching. The guard that would
+ * have caught it can only fire when there is a spec to disagree with.
+ *
+ * `workspaceId` must therefore be the id of a workspace that was actually resolved and leased.
+ * `contextId` is a caller-declared label that nothing validates; it is included because it can only
+ * ever NARROW a binding, and a mismatch fails closed.
+ */
+export function buildApprovalBinding(input: {
+  task: string;
+  requested: readonly Capability[];
+  effective: readonly Capability[];
+  definitionSha256?: DefinitionDigest["sha256"] | string;
+  parentId: string;
+  /** Id of a workspace this delegation was actually routed to and holds a lease for. */
+  workspaceId?: string;
+  /** Caller-declared label. Narrows only; never a claim that anything was enforced. */
+  contextId?: string;
+  /** Optional upstream tree identity. When supplied, later approval use must match it exactly. */
+  treeSha?: string;
+  /** Optional upstream change floor. When supplied, later approval use must match it exactly. */
+  lastChangeSeq?: number;
+}): ApprovalBinding {
+  const requested = [...new Set(input.requested)].sort();
+  const effective = [...new Set(input.effective)].sort();
+  return {
+    version: "1",
+    task_sha256: digestTask(input.task),
+    requested_sha256: digestCapabilities(requested),
+    effective_sha256: digestCapabilities(effective),
+    requested,
+    effective,
+    ...(input.definitionSha256 ? { definition_sha256: input.definitionSha256 } : {}),
+    ...(input.workspaceId ? { workspace_id: input.workspaceId } : {}),
+    ...(input.contextId ? { context_id: input.contextId } : {}),
+    ...(input.treeSha !== undefined ? { tree_sha: input.treeSha } : {}),
+    ...(input.lastChangeSeq !== undefined ? { last_change_seq: input.lastChangeSeq } : {}),
+    parent_id: input.parentId,
+  };
+}
+
+export function approvalBindingDigest(binding: ApprovalBinding): string {
+  const ordered = {
+    version: binding.version,
+    task_sha256: binding.task_sha256,
+    requested_sha256: binding.requested_sha256,
+    effective_sha256: binding.effective_sha256,
+    requested: binding.requested,
+    effective: binding.effective,
+    definition_sha256: binding.definition_sha256 ?? null,
+    workspace_id: binding.workspace_id ?? null,
+    context_id: binding.context_id ?? null,
+    // Keep the exact pre-ADR-0039 serialization when both additions are absent: persisted approvals store
+    // this digest, so unconditional null placeholders would invalidate every existing bound approval.
+    ...(binding.tree_sha !== undefined ? { tree_sha: binding.tree_sha } : {}),
+    ...(binding.last_change_seq !== undefined ? { last_change_seq: binding.last_change_seq } : {}),
+    parent_id: binding.parent_id,
+  };
+  return createHash("sha256").update(JSON.stringify(ordered), "utf8").digest("hex");
+}
+
+export function isApprovalBinding(value: unknown): value is ApprovalBinding {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const binding = value as Partial<ApprovalBinding>;
+  return (
+    binding.version === "1" &&
+    [binding.task_sha256, binding.requested_sha256, binding.effective_sha256].every(
+      (digest) => typeof digest === "string" && /^[a-f0-9]{64}$/i.test(digest),
+    ) &&
+    Array.isArray(binding.requested) &&
+    binding.requested.every((item) => typeof item === "string") &&
+    Array.isArray(binding.effective) &&
+    binding.effective.every((item) => typeof item === "string") &&
+    typeof binding.parent_id === "string" &&
+    ["definition_sha256", "workspace_id", "context_id", "tree_sha"].every((key) => {
+      const value = (binding as Record<string, unknown>)[key];
+      return value === undefined || typeof value === "string";
+    }) &&
+    (binding.last_change_seq === undefined ||
+      (typeof binding.last_change_seq === "number" && Number.isFinite(binding.last_change_seq))) &&
+    // Self-consistency. This guard's only trust boundary is a binding parsed off DISK
+    // (`approval-store.ts`), so an internally contradictory record — digests that do not match the
+    // capability arrays sitting beside them — must be unrepresentable rather than merely unlikely.
+    binding.requested_sha256 === digestCapabilities(binding.requested as Capability[]) &&
+    binding.effective_sha256 === digestCapabilities(binding.effective as Capability[])
+  );
+}
+
+export function approvalBindingsEqual(a: ApprovalBinding | undefined, b: ApprovalBinding | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  if (!isApprovalBinding(a) || !isApprovalBinding(b)) return false;
+  return approvalBindingDigest(a) === approvalBindingDigest(b);
+}