pi-daddy 0.27.4 → 0.32.0

package/src/skill-packages.ts

@@ -1,314 +0,0 @@
-/**
- * Setup discovers enabled Pi resources in place through its package resolver. Configured packages
- * are never copied into another autoload root. For legacy npm installs unregistered with Pi only,
- * the explicit package.json pi.skills declaration remains a scaffold source (ADR-0074).
- * Names, ceilings and bytes are checked before they can enter the generated shell grant.
- */
-
-import { readdir, readFile, realpath } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, resolve, sep } from "node:path";
-import { ceilingForDefinition, parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
-import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
-import { WILDCARD } from "./pi-tools.ts";
-import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
-import { isSafeCapability } from "./capabilities.ts";
-
-export interface DiscoveredSkill {
-  definition: SkillDefinition;
-  /** The file verbatim. `init` copies it rather than regenerating it, so nothing is lost in a round trip. */
-  text: string;
-  path: string;
-  /** Already enabled by Pi; setup must reference it rather than making a competing copy. */
-  referenced?: boolean;
-}
-
-/** Why a declared skill was refused before it could be planned. Each has a different fix. */
-export type RefusalReason =
-  /** The name cannot be a capability id, a line in a sourced file, or a path segment. */
-  | "unsafe-name"
-  /** A declared `allowed-tools` entry cannot be one either — R-78, the sibling of R-77. */
-  | "unsafe-capability"
-  /** The declaration claims `tool:*` or `agent:*`: root authority, which a package may not hand itself. */
-  | "wildcard"
-  /** The bytes are not valid UTF-8, so "copied verbatim" could not be honoured. */
-  | "not-utf8";
-
-export interface RefusedSkill {
-  /** The `pi.skills` entry or the definition name, whichever the operator can act on. */
-  subject: string;
-  reason: RefusalReason;
-  /** The offending id(s), when the reason names any. */
-  detail: string[];
-}
-
-export interface SkillPackage {
-  name: string;
-  version: string;
-  /** Paths `pi.skills` named that could not be read as a `SKILL.md`, so the report can say so out loud. */
-  unreadable: string[];
-  /** Skills refused for a reason that would otherwise reach a generated file. Never silently dropped. */
-  refused: RefusedSkill[];
-  skills: DiscoveredSkill[];
-}
-
-/**
- * May this definition's name be written into a capability id, a shell file and a path?
- *
- * **Measured before it was written, and it was a defect in this module's first version (R-77).** A
- * definition's identity is its directory name, and `init` interpolates that name into three places at once:
- * `agent:<name>` inside a **comma-separated** `PI_GRANTS_GRANT`, a `.pi/grants.env` an operator **sources**,
- * and the path it writes the copy to. An installed package with a directory called `a,tool:bash` produced
- *
- * ```
- * export PI_GRANTS_GRANT="agent:a,tool:bash,tool:delegate,tool:read"
- * ```
- *
- * — `tool:bash` in an operator's grant, declared by nobody. A quote character reaches a file that gets
- * `source`d, and a name of `..` writes outside `.pi/skills/`. One rule closes all three, and it is
- * deliberately a **whitelist**: the safe set here is small and the unsafe set is the rest of Unicode.
- *
- * The first character must be alphanumeric, so `..` and dotfiles are refused along with everything else.
- */
-export function isSafeName(name: string): boolean {
-  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
-}
-
-/**
- * May this DECLARED capability id be written into the generated grant? — R-78.
- *
- * **R-77's other half, and the reason a whitelist beats a blocklist twice.** R-77 was closed on the name
- * channel; the `allowed-tools` *value* travels to the identical interpolation site and was unchecked, so a
- * package declaring
- *
- * ```yaml
- * allowed-tools: Read,ext:x";touch /tmp/pwned;PI_GRANTS_GRANT="
- * ```
- *
- * produced a `.pi/grants.env` that executed arbitrary code the moment the operator ran the `source` line
- * `init` itself prints. Reproduced end to end before this existed. `ceilingForDefinition` passes `ext:`,
- * `skill:` and `agent:` entries through **as written** by design (a translation table would invent or drop
- * grants), which is right for the enforcement path — the catalog refuses what it does not know — and is
- * exactly why the check has to be here, at the boundary that *generates* rather than the one that enforces.
- *
- * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`,
- * `workspace:<id>`, and `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused
- * separately and loudly, because "you tried to grant yourself everything" is a different fact from "that is
- * not a name".
- *
- * `workspace:` was absent until 2026-08-21, so the boundary that GENERATES grants could not emit the one
- * capability ADR-0035's breaking change made mandatory: a package needing to route was reported as declaring
- * something that "is not a name". A namespace has to be added here as well as to the enforcing path, and
- * that is the whole lesson of the review this came out of.
- */
-// Imported as well as re-exported: a bare `export … from` does not bind the name in this module's scope, and
-// `refusalFor` below calls it. Re-exported because this has been the import site since 0.13.0.
-export { isSafeCapability };
-
-/**
- * The ids that confer authority over a whole namespace. A package declaring one is claiming it, not
- * describing a need — so it is reported as a *wildcard claim* rather than as a malformed name, which is a
- * different sentence to show an operator. `workspace:*` belongs here for the same reason `agent:*` does.
- */
-function wildcardsIn(capabilities: Capability[]): Capability[] {
-  return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD || c === WORKSPACE_WILDCARD);
-}
-
-/**
- * Everything about one declared skill that would make it unsafe to scaffold. `null` when it is fine.
- *
- * Ordered so the operator is told the most actionable thing: a wildcard is a deliberate claim, an unsafe id
- * is probably a typo or an attack, and a bad name is neither.
- */
-function refusalFor(skill: DiscoveredSkill): RefusedSkill | null {
-  const name = skill.definition.name;
-  if (!isSafeName(name)) return { subject: name, reason: "unsafe-name", detail: [name] };
-
-  const ceiling = ceilingForDefinition(skill.definition);
-  const wildcards = wildcardsIn(ceiling.capabilities);
-  if (wildcards.length > 0) return { subject: name, reason: "wildcard", detail: wildcards };
-
-  const unsafe = ceiling.capabilities.filter((c) => !isSafeCapability(c));
-  if (unsafe.length > 0) return { subject: name, reason: "unsafe-capability", detail: unsafe };
-
-  return null;
-}
-
-/** One `pi.skills` entry: a directory holding `SKILL.md`, or a `.md` file — the same two shapes pi allows. */
-async function readSkill(packageDir: string, entry: string): Promise<DiscoveredSkill | "not-utf8" | null> {
-  const target = resolve(packageDir, entry);
-  // A manifest is data from another package, so an entry escaping its own directory is refused rather than
-  // followed. **`realpath`, not a lexical prefix test** (R-80): `resolve()` normalises `..` and knows
-  // nothing about symlinks, so a packaged symlink walked straight past the first version of this check and
-  // a definition from outside the package was copied in, with its `allowed-tools` landing in the operator's
-  // grant. Measured. This is the same lesson as the `realpathSync` fix in `cli.ts`, which was found by the
-  // smoke test one day earlier and not applied here.
-  const realPackageDir = await realpath(packageDir).catch(() => packageDir);
-  for (const path of [join(target, "SKILL.md"), ...(target.endsWith(".md") ? [target] : [])]) {
-    let bytes: Buffer;
-    try {
-      bytes = await readFile(path);
-    } catch {
-      continue;
-    }
-    const realPath = await realpath(path).catch(() => path);
-    if (!realPath.startsWith(realPackageDir + sep)) return null;
-
-    // "The file verbatim … nothing is lost in a round trip" is a claim this module makes, so bytes that
-    // cannot survive the round trip are refused rather than silently replaced. A latin-1 `0xE9` used to come
-    // back as U+FFFD, changing the file's length and its digest, with no warning.
-    const text = bytes.toString("utf8");
-    if (!Buffer.from(text, "utf8").equals(bytes)) return "not-utf8";
-
-    const definition = parseSkillDefinition(path, text);
-    return definition ? { definition, text, path } : null;
-  }
-  return null;
-}
-
-/** Read one installed package, if it declares skills. `null` means "not a skill package", not an error. */
-export async function readSkillPackage(packageDir: string): Promise<SkillPackage | null> {
-  let manifest: { name?: string; version?: string; pi?: { skills?: unknown } };
-  try {
-    manifest = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
-  } catch {
-    return null;
-  }
-  const declared = manifest.pi?.skills;
-  if (!Array.isArray(declared) || declared.length === 0) return null;
-
-  const skills: DiscoveredSkill[] = [];
-  const unreadable: string[] = [];
-  const refused: RefusedSkill[] = [];
-  for (const entry of declared) {
-    if (typeof entry !== "string") continue;
-    const skill = await readSkill(packageDir, entry);
-    if (skill === null) {
-      unreadable.push(entry);
-    } else if (skill === "not-utf8") {
-      refused.push({ subject: entry, reason: "not-utf8", detail: [] });
-    } else {
-      const refusal = refusalFor(skill);
-      if (refusal) refused.push(refusal);
-      else skills.push(skill);
-    }
-  }
-
-  return {
-    name: manifest.name ?? packageDir.split(sep).pop() ?? "(unnamed)",
-    version: manifest.version ?? "(no version)",
-    unreadable,
-    refused,
-    skills,
-  };
-}
-
-/**
- * Every installed package under `<cwd>/node_modules` that declares `pi.skills`, sorted by name.
- *
- * Top level and one scope deep, which is what npm's layout has. Nothing recurses into a dependency's own
- * `node_modules`: a transitive skill package is not something an operator asked to install definitions
- * from, and scaffolding one into their project would be a surprise wearing a helpful face.
- */
-/**
- * Every place a pi package can be installed, most specific first (R-75).
- *
- * **Two roots, because pi has two install paths and only one of them is `npm install`.** `pi install
- * npm:principal-pi-skills` — the documented, pi-native way, and the only one that registers the package so
- * pi will auto-load its extension — puts it in `$PI_CODING_AGENT_DIR/npm/node_modules`, and leaves the
- * project without a `node_modules` at all. Searching only `<cwd>/node_modules` therefore found **nothing**
- * for an operator who followed pi's own instructions, and said "install principal-pi-skills" to somebody
- * who just had.
- *
- * Measured, in a fresh `PI_CODING_AGENT_DIR` with an empty project: `pi install` populates the agent root
- * and creates no project root.
- *
- * Project first when both exist, because a package pinned in the repository is the one the team agreed on.
- */
-export function skillPackageRoots(cwd: string): string[] {
-  const agentDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-  return [join(cwd, "node_modules"), join(agentDir, "npm", "node_modules")];
-}
-
-export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]> {
-  const resolved = await resolveSkillResources(cwd);
-  const packages: SkillPackage[] = [];
-  const seenSkills = new Set<string>();
-  const runtimeNames = new Set(resolved.skills.map(s => skillResourceName(s.path)));
-  const configuredRoots = new Set(resolved.configured.flatMap(p => p.installedPath ? [resolve(p.installedPath)] : []));
-  const configuredNames = new Set<string>(resolved.configured.flatMap(p => {
-    if (!p.source.startsWith("npm:")) return [];
-    const spec = p.source.slice(4);
-    const versionAt = spec.indexOf("@", 1);
-    return [versionAt < 0 ? spec : spec.slice(0, versionAt)];
-  }));
-  for (const root of configuredRoots) {
-    try { configuredNames.add(JSON.parse(await readFile(join(root, "package.json"), "utf8")).name); } catch { /* absent */ }
-  }
-  for (const resource of resolved.skills) {
-    const bytes = await readFile(resource.path).catch(() => null);
-    if (bytes === null) continue;
-    const text = bytes.toString("utf8");
-    const resourceName = skillResourceName(resource.path);
-    if (seenSkills.has(resourceName)) continue;
-    seenSkills.add(resourceName);
-    let name = resource.metadata.source;
-    let version = "local";
-    if (resource.metadata.origin === "package" && resource.metadata.baseDir) {
-      try {
-        const manifest = JSON.parse(await readFile(join(resource.metadata.baseDir, "package.json"), "utf8"));
-        name = manifest.name ?? name; version = manifest.version ?? version;
-      } catch { /* the resource can be used without optional display metadata */ }
-    } else name = `${resource.metadata.scope} skills`;
-    let pkg = packages.find(p => p.name === name && p.version === version);
-    if (!pkg) { pkg = { name, version, skills: [], refused: [], unreadable: [] }; packages.push(pkg); }
-    if (!Buffer.from(text, "utf8").equals(bytes)) {
-      pkg.refused.push({ subject: resourceName, reason: "not-utf8", detail: [] });
-      continue;
-    }
-    const definition = parseSkillDefinition(resource.path, text);
-    if (!definition) continue;
-    const skill = { definition, text, path: resource.path, referenced: true };
-    const refusal = refusalFor(skill);
-    if (refusal) pkg.refused.push(refusal); else pkg.skills.push(skill);
-  }
-
-  // Compatibility for npm installs that were never registered with Pi. Runtime discovery never scans
-  // node_modules. A configured package (including one disabled by a filter) must not re-enter here.
-  const dirs: string[] = [];
-  for (const root of skillPackageRoots(cwd)) await collectFrom(root, dirs);
-  const seenNames = new Set(packages.map(p => p.name));
-  for (const dir of dirs) {
-    if (configuredRoots.has(resolve(dir))) continue;
-    const found = await readSkillPackage(dir);
-    if (!found || configuredNames.has(found.name) || seenNames.has(found.name)) continue;
-    seenNames.add(found.name);
-    found.skills = found.skills.filter(skill => !runtimeNames.has(skill.definition.name));
-    packages.push(found);
-  }
-  return packages;
-
-}
-
-/** Append every package directory under one `node_modules`, scoped packages included. */
-async function collectFrom(root: string, dirs: string[]): Promise<void> {
-  let entries: string[];
-  try {
-    entries = await readdir(root);
-  } catch {
-    return; // a root that does not exist is a normal state, not a failure
-  }
-
-  for (const entry of entries.sort()) {
-    if (entry.startsWith(".")) continue; // .bin, .package-lock.json
-    if (entry.startsWith("@")) {
-      try {
-        for (const scoped of (await readdir(join(root, entry))).sort()) dirs.push(join(root, entry, scoped));
-      } catch {
-        continue;
-      }
-    } else {
-      dirs.push(join(root, entry));
-    }
-  }
-}

package/src/skill-resources.ts

@@ -1,48 +0,0 @@
-/** Read Pi's configured resource surface without locks, installs, extension execution or model calls. */
-import { readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { DefaultPackageManager, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
-
-interface SkillResources {
-  skills: { path: string; enabled: boolean; metadata: { source: string; scope: string; origin: string; baseDir?: string } }[];
-  configured: { source: string; scope: string; installedPath?: string }[];
-}
-
-export function skillResourceName(path: string): string {
-  const parts = path.split(/[\\/]/);
-  const file = parts.at(-1) ?? "";
-  return file.toLowerCase() === "skill.md" ? parts.at(-2) ?? "" : file.replace(/\.md$/i, "");
-}
-
-export async function resolveSkillResources(cwd: string): Promise<SkillResources> {
-  const agentDir = getAgentDir();
-  const settingsManager = SettingsManager.fromStorage({
-    withLock(scope, read) {
-      const path = scope === "global" ? join(agentDir, "settings.json") : join(cwd, ".pi", "settings.json");
-      let text: string | undefined;
-      try { text = readFileSync(path, "utf8"); }
-      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
-      // This storage is intentionally read-only: no lock files or migrated settings are persisted.
-      read(text);
-    },
-  });
-  const errors = settingsManager.drainErrors();
-  if (errors.length) throw new Error(`Cannot discover skills: ${errors.map(e => `${e.scope} settings: ${e.error.message}`).join("; ")}`);
-  const manager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
-  const resolved = await manager.resolve(async () => "skip");
-  // Pi has already applied package identity, scope, manifest and settings filters and precedence.
-  const seen = new Set<string>();
-  const skills = resolved.skills.filter(resource => resource.enabled).flatMap(resource => {
-    try {
-      const path = statSync(resource.path).isDirectory() ? join(resource.path, "SKILL.md") : resource.path;
-      return statSync(path).isFile() ? [{ ...resource, path }] : [];
-    } catch { return []; }
-  }).filter(resource => {
-    // Reserve identity before parsing: a malformed local override cannot reveal a wider package ceiling.
-    const name = skillResourceName(resource.path);
-    if (seen.has(name)) return false;
-    seen.add(name);
-    return true;
-  });
-  return { skills, configured: manager.listConfiguredPackages() };
-}

package/src/vendor/adoption.ts

@@ -1,109 +0,0 @@
-import { createHash } from "node:crypto";
-const SHA = /^[a-f0-9]{64}$/;
-const text = (x: unknown): x is string => typeof x === "string" && x.length > 0 && x.length <= 512 && !/[\u0000-\u001f\u007f]/.test(x);
-const closed = (value: object, names: string[]) => {
-  if (!value || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return false;
-  const fields = Object.getOwnPropertyDescriptors(value);
-  return Reflect.ownKeys(fields).length === names.length && Reflect.ownKeys(fields).every(key => typeof key === "string" && names.includes(key) && fields[key].enumerable && Object.hasOwn(fields[key], "value"));
-};
-const hash = (value: Record<string, unknown>) => createHash("sha256").update(JSON.stringify(Object.keys(value).sort().map(k => [k, value[k]]))).digest("hex");
-export interface AdoptionInput {
-  hypothesisDigest: string; experimentDigest: string; candidateDigest: string; scopeDigest: string; assessmentPolicyDigest: string;
-  rollbackCandidateDigest: string; activationBoundary: "next-orders"; expiresAt: number;
-}
-export interface AdoptionBinding extends AdoptionInput { version: "adoption-binding-v1"; id: string }
-export interface AdoptionAuthority { id: string; adoptions: readonly string[]; rollbacks: readonly string[] }
-export interface AdoptionFacts { experimentDigest: string; candidateDigest: string; scopeDigest: string; assessmentPolicyDigest: string; eligible: boolean }
-export function buildAdoptionBinding(input: AdoptionInput): AdoptionBinding {
-  if (!input || !closed(input, ["hypothesisDigest", "experimentDigest", "candidateDigest", "scopeDigest", "assessmentPolicyDigest", "rollbackCandidateDigest", "activationBoundary", "expiresAt"])
-    || ![input.hypothesisDigest,input.experimentDigest,input.candidateDigest,input.scopeDigest,input.assessmentPolicyDigest,input.rollbackCandidateDigest].every(s => typeof s === "string" && SHA.test(s))
-    || input.activationBoundary !== "next-orders" || !Number.isSafeInteger(input.expiresAt) || input.expiresAt < 0) throw new Error("invalid scoped adoption binding");
-  const body = { version: "adoption-binding-v1" as const, ...input };
-  return Object.freeze({ ...body, id: hash(body) });
-}
-function bindingValid(binding: AdoptionBinding) {
-  const { version, id, ...input } = binding;
-  if (version !== "adoption-binding-v1" || buildAdoptionBinding(input).id !== id) throw new Error("adoption binding changed");
-}
-function authorityValid(authority: AdoptionAuthority | null): authority is AdoptionAuthority {
-  return !!authority && text(authority.id) && Array.isArray(authority.adoptions) && Array.isArray(authority.rollbacks)
-    && authority.adoptions.length <= 256 && authority.rollbacks.length <= 256 && [...authority.adoptions, ...authority.rollbacks].every(id => typeof id === "string" && SHA.test(id));
-}
-/** Independent host declarations and independently verified eligible facts are required again at use. */
-export function authorizeAdoption(binding: AdoptionBinding, authority: AdoptionAuthority | null, facts: AdoptionFacts, now: number) {
-  bindingValid(binding);
-  if (!authorityValid(authority) || !authority.adoptions.includes(binding.id)) throw new Error("independent adoption authority required");
-  if (!Number.isSafeInteger(now) || now < 0 || now >= binding.expiresAt || !facts || !closed(facts, ["experimentDigest", "candidateDigest", "scopeDigest", "assessmentPolicyDigest", "eligible"]) || facts.eligible !== true
-    || facts.experimentDigest !== binding.experimentDigest || facts.candidateDigest !== binding.candidateDigest
-    || facts.scopeDigest !== binding.scopeDigest || facts.assessmentPolicyDigest !== binding.assessmentPolicyDigest) throw new Error("adoption expired, ineligible or outside verified scope");
-  const body = { version: "adoption-receipt-v1" as const, bindingId: binding.id, authorityId: authority.id, hypothesisDigest: binding.hypothesisDigest,
-    experimentDigest: binding.experimentDigest, candidateDigest: binding.candidateDigest, scopeDigest: binding.scopeDigest,
-    assessmentPolicyDigest: binding.assessmentPolicyDigest, rollbackCandidateDigest: binding.rollbackCandidateDigest,
-    activationBoundary: "next-orders" as const, grantExpansion: false as const, expiresAt: binding.expiresAt };
-  return Object.freeze({ ...body, id: hash(body) });
-}
-export type AdoptionReceipt = ReturnType<typeof authorizeAdoption>;
-export function validateAdoptionReceipt(receipt: AdoptionReceipt, binding: AdoptionBinding, authority: AdoptionAuthority | null, facts: AdoptionFacts, now: number): void {
-  if (authorizeAdoption(binding, authority, facts, now).id !== receipt.id) throw new Error("adoption receipt does not match current independent authority/facts");
-  receiptValid(receipt);
-}
-function receiptValid(receipt: AdoptionReceipt) {
-  const { id, ...body } = receipt;
-  if (!closed(receipt, ["version", "bindingId", "authorityId", "hypothesisDigest", "experimentDigest", "candidateDigest", "scopeDigest", "assessmentPolicyDigest", "rollbackCandidateDigest", "activationBoundary", "grantExpansion", "expiresAt", "id"])
-    || body.version !== "adoption-receipt-v1" || !text(body.authorityId) || body.activationBoundary !== "next-orders" || body.grantExpansion !== false || hash(body) !== id) throw new Error("adoption receipt changed");
-  const binding = buildAdoptionBinding({ hypothesisDigest: body.hypothesisDigest, experimentDigest: body.experimentDigest, candidateDigest: body.candidateDigest,
-    scopeDigest: body.scopeDigest, assessmentPolicyDigest: body.assessmentPolicyDigest, rollbackCandidateDigest: body.rollbackCandidateDigest, activationBoundary: body.activationBoundary, expiresAt: body.expiresAt });
-  if (binding.id !== body.bindingId) throw new Error("adoption receipt binding mismatch");
-}
-export interface ProductionObservation {
-  id: string; adoptionId: string; candidateDigest: string; scopeDigest: string;
-  originalRequirementDigest: string; currentRequirementDigest: string;
-  /** Only an independent host may supply confirmed outcomes; observer/model claims are not confirmation. */
-  outcome: "confirmed-defect" | "success" | "unknown";
-  acceptanceDigest: string | null; acceptedArtifactDigest: string | null; observedArtifactDigest: string;
-  evidence: string[];
-}
-export function classifyProductionObservation(adoption: AdoptionReceipt, input: ProductionObservation) {
-  receiptValid(adoption);
-  if (!input || !text(input.id) || input.evidence.length > 256 || input.evidence.some(h => !SHA.test(h))
-    || ![input.originalRequirementDigest,input.currentRequirementDigest,input.candidateDigest,input.scopeDigest,input.observedArtifactDigest].every(h => typeof h === "string" && SHA.test(h))
-    || ![input.acceptanceDigest,input.acceptedArtifactDigest].every(h => h === null || (typeof h === "string" && SHA.test(h)))
-    || (input.acceptanceDigest === null) !== (input.acceptedArtifactDigest === null)
-    || !["confirmed-defect", "success", "unknown"].includes(input.outcome)) throw new Error("invalid production observation");
-  const state = input.adoptionId !== adoption.id || input.candidateDigest !== adoption.candidateDigest || input.scopeDigest !== adoption.scopeDigest ? "out-of-scope"
-    : input.originalRequirementDigest !== input.currentRequirementDigest ? "changed-requirements"
-      : input.acceptedArtifactDigest !== null && input.acceptedArtifactDigest !== input.observedArtifactDigest ? "changed-artifact"
-        : input.outcome === "confirmed-defect" && input.evidence.length ? input.acceptanceDigest === null ? "caught-defect" : "escape" : input.outcome === "success" ? "success" : "unknown";
-  return Object.freeze({ state, adoptionId: adoption.id, hypothesisDigest: adoption.hypothesisDigest, experimentDigest: adoption.experimentDigest, observationId: input.id, acceptanceDigest: input.acceptanceDigest, acceptedArtifactDigest: input.acceptedArtifactDigest, observedArtifactDigest: input.observedArtifactDigest, automaticRollback: false });
-}
-export interface RollbackRequest { version: "rollback-request-v1"; id: string; adoptionId: string; scopeDigest: string; restoreCandidateDigest: string; reason: "operator-request" | "confirmed-escape"; evidence: readonly string[]; expiresAt: number }
-export function buildRollbackRequest(adoption: AdoptionReceipt, reason: RollbackRequest["reason"], evidence: string[], expiresAt = adoption.expiresAt): RollbackRequest {
-  receiptValid(adoption);
-  if (!Number.isSafeInteger(expiresAt) || expiresAt < 0 || !["operator-request", "confirmed-escape"].includes(reason) || !evidence.length || evidence.length > 256 || evidence.some(h => !SHA.test(h))) throw new Error("invalid rollback request");
-  const body = { version: "rollback-request-v1" as const, adoptionId: adoption.id, scopeDigest: adoption.scopeDigest, restoreCandidateDigest: adoption.rollbackCandidateDigest, reason, expiresAt, evidence: Object.freeze([...new Set(evidence)].sort()) };
-  return Object.freeze({ ...body, id: hash(body) });
-}
-/** This validates a recorded choice, not an automatic rollback action or a caller-created authority flag. */
-export function authorizeRollback(adoption: AdoptionReceipt, request: RollbackRequest, authority: AdoptionAuthority | null, now: number,
-  current: { adoptionId: string; candidateDigest: string; scopeDigest: string }) {
-  receiptValid(adoption); const { id, ...body } = request;
-  if (!authorityValid(authority) || authority.id !== adoption.authorityId || !authority.rollbacks.includes(id)) throw new Error("independent rollback authority required");
-  if (hash(body) !== id || request.version !== "rollback-request-v1" || request.adoptionId !== adoption.id || request.scopeDigest !== adoption.scopeDigest
-    || request.restoreCandidateDigest !== adoption.rollbackCandidateDigest || !Number.isSafeInteger(now) || now < 0 || !Number.isSafeInteger(request.expiresAt) || now >= request.expiresAt
-    || !current || current.adoptionId !== adoption.id || current.candidateDigest !== adoption.candidateDigest || current.scopeDigest !== adoption.scopeDigest) throw new Error("rollback binding changed or expired");
-  return Object.freeze({ requestId: id, adoptionId: adoption.id, restoreCandidateDigest: request.restoreCandidateDigest, scopeDigest: adoption.scopeDigest, grantExpansion: false, application: "not-performed" });
-}
-export interface LeanOutcome {
-  population: string; complete: boolean; accepted: boolean | null; repairAttempts: number | null;
-  escape: "confirmed" | "none-observed" | "unknown"; requirementsChanged: boolean; decisionWaitMs: number | null; questions: number | null;
-}
-export function summarizeLeanOutcomes(population: string, rows: readonly LeanOutcome[]) {
-  if (!text(population) || rows.length > 10000 || rows.some(r => r.population !== population || typeof r.complete !== "boolean" || typeof r.requirementsChanged !== "boolean"
-    || ![true,false,null].includes(r.accepted) || !["confirmed","none-observed","unknown"].includes(r.escape)
-    || [r.repairAttempts,r.decisionWaitMs,r.questions].some(n => n !== null && (!Number.isSafeInteger(n) || n < 0)))) throw new Error("invalid or incomparable lean population");
-  const complete = rows.filter(r => r.complete && r.accepted !== null && r.repairAttempts !== null);
-  const observed = (field: "decisionWaitMs" | "questions" | "repairAttempts") => ({ known: rows.reduce((n, r) => n + (r[field] ?? 0), 0), observed: rows.filter(r => r[field] !== null).length, total: rows.length });
-  return { population, firstPassAccepted: complete.filter(r => r.accepted && r.repairAttempts === 0).length, firstPassDenominator: complete.length,
-    incomplete: rows.length - complete.length, confirmedEscapes: rows.filter(r => r.escape === "confirmed" && !r.requirementsChanged).length,
-    changedRequirements: rows.filter(r => r.requirementsChanged).length, recovery: observed("repairAttempts"), decisionWait: observed("decisionWaitMs"), questions: observed("questions"), universalScore: null };
-}