pi-daddy 0.28.0 → 0.32.0

package/src/resolve.ts

@@ -1,267 +0,0 @@
-/**
- * Grant resolution — the entire security surface of capability governance, as a pure function.
- *
- * The invariant (ADR-0008): a capability set may only ever SHRINK as it passes down a delegation
- * tree. Escalation is impossible by construction rather than by policy, because a parent can never
- * confer what it does not itself hold.
- *
- *   effective = ( requested ∩ parentGrant ∩ ceiling ) \ (gated \ approved)
- *
- * Being pure — no I/O, no model, no network — this is exhaustively testable, which matters because it
- * is the only place an escalation could be introduced.
- */
-
-/** `tool:read` · `ext:pi-web-access/web_search` · `skill:review` · `agent:researcher` */
-export type Capability = string;
-
-/**
- * Capabilities that transitively confer everything else. Granting one is equivalent to granting the
- * whole catalog, so they can never be a *narrowing* grant.
- *
- * `ext:pi-fabric/fabric_exec` is here on measured evidence, not suspicion: a child granted
- * `tools: []` (nothing at all) plus `recursive: true` still reached `pi.write` and `pi.bash` and
- * spawned a grandchild that wrote to disk. See docs/probes/pi-fabric-eval (probes 2, 4, 7, 8).
- */
-export const UNIVERSAL_CAPABILITIES: readonly Capability[] = [
-  "ext:pi-fabric/fabric_exec",
-  "tool:fabric_exec",
-];
-
-/**
- * Capabilities that functionally contain others.
- *
- * `bash` can run `grep`, `find`, `ls`, `cat`, and `sed` — so a session holding it can already do
- * everything the file and search tools do, whatever the tool list says. Modelling this explicitly serves
- * two purposes:
- *
- *  1. It removes false escalation reports. pi's *default* surface is only `read`, `bash`, `edit`, `write`
- *     (measured, not assumed), so an agent type declaring `tools: read, grep, find, ls` would otherwise
- *     look like an escalation from any normal parent — despite being strictly weaker.
- *  2. It makes the uncomfortable truth visible rather than implied: **a grant containing `bash` is not a
- *     narrow grant.** `subsumedBy` in the result says so, so a reviewer can see what the grant really means.
- */
-export const SUBSUMPTION: Readonly<Record<Capability, readonly Capability[]>> = {
-  "tool:bash": [
-    "tool:grep",
-    "tool:find",
-    "tool:ls",
-    "tool:read",
-    "tool:write",
-    "tool:edit",
-    "tool:edit-diff",
-  ],
-};
-
-/** Expand a grant to everything it functionally confers. */
-export function expandSubsumed(grant: Capability[]): Capability[] {
-  const expanded = new Set(grant);
-  for (const held of grant) {
-    for (const implied of SUBSUMPTION[held] ?? []) expanded.add(implied);
-  }
-  return [...expanded].sort();
-}
-
-import { WILDCARD } from "./pi-tools.ts";
-import { isWellFormedCapability } from "./capabilities.ts";
-
-/**
- * "Any definition" — ADR-0023, and one of two wildcards this module understands.
- *
- * Declared here rather than beside `WILDCARD` because `pi-tools.ts` imports `Capability` from this module.
- * That import is `import type`, so it is erased and the runtime dependency runs one way only — which is
- * what makes importing `WILDCARD` back safe.
- *
- * Deliberately weaker than `tool:*`: it confers **no tool authority**, so `agent:*,tool:read` may spawn
- * every definition on disk and hand each of them nothing but `read`. It exists because the alternative was
- * `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. */
-  requested: Capability[];
-  /** What the delegating agent itself holds. The root's grant is configured, never defaulted to all. */
-  parentGrant: Capability[];
-  /** Declarative maximum for the child's agent type (its frontmatter). Omit for no ceiling. */
-  ceiling?: Capability[];
-  /** Destructive capabilities that may never enter a grant without explicit human approval. */
-  gated?: Capability[];
-  /** Gated capabilities a human has approved for this specific spawn. */
-  approved?: Capability[];
-  /**
-   * Honour functional subsumption when deciding what the parent covers (default true).
-   * Set false for a strict name-equality check.
-   */
-  subsumption?: boolean;
-}
-
-export interface ResolveResult {
-  /** The capability set the child may hold. */
-  effective: Capability[];
-  /** Requested but NOT held by the parent — the escalation-attempt signal. Log every one. */
-  denied: Capability[];
-  /** Held by the parent but outside the child type's declared ceiling. */
-  clipped: Capability[];
-  /** Allowed by the tree but gated and unapproved. */
-  gatedBlocked: Capability[];
-  /** Universal capabilities that survived resolution — see `assertNarrowing`. */
-  universal: Capability[];
-  /**
-   * Capabilities the parent covers only through subsumption, not by holding them directly — e.g. `grep`
-   * covered because the parent holds `bash`. Non-empty means the grant is broader than its list suggests.
-   */
-  subsumedBy: Capability[];
-}
-
-const unique = (xs: Capability[]): Capability[] => [...new Set(xs)].sort();
-
-/**
- * Resolve a child's grant. Total and side-effect free; every rejected capability is reported rather
- * than silently dropped, because a grant nobody can audit proves nothing.
- */
-export function resolve(input: ResolveInput): ResolveResult {
-  const requested = unique(input.requested);
-  const held = new Set(input.parentGrant);
-  const parent =
-    input.subsumption === false ? held : new Set(expandSubsumed(input.parentGrant));
-  /**
-   * `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
-   * it. Definitions are not tools, so nothing enumerates them — which is why `maySpawnDefinition` had to
-   * special-case the wildcard, and why this needs stating rather than falling out.
-   *
-   * Scoped to one namespace on purpose. There is no generalised `<ns>:*` rule, so a namespace added later
-   * does not silently acquire a wildcard; adding one is a deliberate edit and another decision.
-   */
-  const anyDefinition = held.has(AGENT_WILDCARD);
-  /**
-   * `tool:*` satisfies **any** capability, including `skill:` and `agent:` ids.
-   *
-   * Missing until 0.11.2, and the omission broke the one rule this package must never break by accident:
-   * *governance is opt-in*. An ungoverned session holds `[tool:*, …observed tools]` and nothing else, so
-   * spawning a definition whose `allowed-tools` names `agent:worker` or `skill:review` — the composition
-   * ADR-0017 created and ADR-0023's own example uses — was refused with **"capability escalation
-   * blocked"**, and recorded as an escalation attempt, in a session that had opted out.
-   *
-   * `maySpawnDefinition` had always honoured `tool:*` for definition ids and `docs/SPEC.md` had always
-   * claimed it "satisfies any capability". This function disagreed with both, which is R-28's shape: two
-   * 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:"))
-      || (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 ?? []);
-
-  // Order is irrelevant to the outcome (set intersection is commutative), so each rejection reason is
-  // reported independently rather than being masked by whichever filter happened to run first.
-  const denied = requested.filter((c) => !covered(c));
-  const clipped = requested.filter((c) => covered(c) && ceiling !== null && !ceiling.has(c));
-  /**
-   * Is this capability gated, directly or by subsuming something gated?
-   *
-   * ADR-0012. Exact-name gating was defeatable by handing down a broader capability: the package's own
-   * `SUBSUMPTION` table says `bash` confers `write`, so gating `write` produced **no prompt** when `bash`
-   * was granted instead. The gate read as satisfied because the string never appeared.
-   *
-   * The direction is load-bearing and easy to invert. A capability is gated when it **subsumes**
-   * something gated — never when it **is subsumed by** something gated. Gating `bash` must not quietly
-   * gate a plain `write` grant, which would make gating a broad capability restrict the narrow ones and
-   * invert least privilege.
-   */
-  const isGated = (c: Capability): boolean => {
-    if (gated.has(c)) return true;
-    if (input.subsumption === false) return false;
-    return (SUBSUMPTION[c] ?? []).some((implied) => gated.has(implied));
-  };
-
-  const gatedBlocked = requested.filter(
-    (c) => covered(c) && (ceiling === null || ceiling.has(c)) && isGated(c) && !approved.has(c),
-  );
-
-  const rejected = new Set([...denied, ...clipped, ...gatedBlocked]);
-  const effective = requested.filter((c) => !rejected.has(c));
-
-  return {
-    effective,
-    denied,
-    clipped,
-    gatedBlocked,
-    universal: effective.filter((c) => UNIVERSAL_CAPABILITIES.includes(c)),
-    // 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.
-    //
-    // 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:"))),
-  };
-}
-
-/**
- * Fail closed on a grant that cannot actually narrow anything.
- *
- * A universal capability in an "attenuated" grant is not a narrow grant with one extra item — it is
- * full authority wearing a narrow grant's clothing. Callers must opt in explicitly rather than
- * discover this at runtime.
- */
-export function assertNarrowing(result: ResolveResult, allowUniversal = false): void {
-  if (!allowUniversal && result.universal.length > 0) {
-    throw new Error(
-      `refusing to issue a grant containing universal capabilities: ${result.universal.join(", ")}. ` +
-        `These transitively confer the whole catalog, so the grant would not narrow anything. ` +
-        `Pass allowUniversal to override deliberately.`,
-    );
-  }
-}
-
-/**
- * Project an effective grant onto pi's `--tools` allowlist.
- *
- * pi core is the enforcement point — verified: `--tools` and `--no-tools` both hard-block extension
- * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them
- * (docs/probes/pi-fabric-eval probes 9–11). That is why enforcement needs no in-descendant runtime.
- *
- * Returns `null` when the grant contains no callable tools, meaning the caller should pass
- * `--no-tools` rather than an empty `--tools` (an empty list is not a valid allowlist).
- */
-export function toPiToolsAllowlist(effective: Capability[]): string[] | null {
-  const names = effective
-    .filter((c) => c.startsWith("tool:") || c.startsWith("ext:"))
-    // `tool:read` -> `read`; `ext:pkg/web_search` -> `web_search` (pi matches on bare tool name)
-    .map((c) => (c.startsWith("tool:") ? c.slice(5) : c.slice(c.lastIndexOf("/") + 1)))
-    .filter((n) => n.length > 0);
-  const deduped = [...new Set(names)].sort();
-  return deduped.length > 0 ? deduped : null;
-}

package/src/resource-budget.ts

@@ -1,349 +0,0 @@
-import { constants } from "node:fs";
-import { lstat, mkdir, open, realpath } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { createHash, randomUUID } from "node:crypto";
-import { withFileLock } from "./file-lock.ts";
-import { parseWorkJson, freezeWork } from "./work-ledger-json.ts";
-import { runWithFinalizers } from "./finalization.ts";
-import { workIntentBinding, readIntentWork, resolveIntent, validateIntentApplication, applyIntentApplication } from "./intent-application.ts";
-import { intentKey, intentRequest, intentRequestDigest, intentReceipt, matchesIntentReceipt, intentDecision, replayIntent, intentSnapshot,
-  type WorkIntentBinding, type IntentState, type IntentRequest, type IntentAdmission } from "./intent-control.ts";
-import { intentAdmission, nextIntent } from "./intent-scheduling.ts";
-import { dispatchAuthority, dispatchRequest, dispatchRequestDigest, dispatchDecision, replayDispatch, freezeDispatch,
-  type DispatchAuthority, type DispatchRequest, type DispatchState } from "./dispatch-control.ts";
-
-export interface ResourceLimits { maxAttempts: number; maxInputBytes: number; maxConcurrent: number }
-export interface BudgetBinding<V extends "1.0" | "2.0" | "3.0" | "4.0" = "1.0"> {
-  version: V; directory: string; device: string; inode: string;
-  journalDevice: string; journalInode: string; authorityDigest: string; limits: ResourceLimits; intent?: V extends "3.0" ? WorkIntentBinding : never;
-}
-export type DispatchBudgetBinding = BudgetBinding<"2.0">;
-export type ExperimentBudgetBinding = BudgetBinding<"4.0">;
-export type GovernedBudgetBinding = BudgetBinding<"1.0" | "2.0" | "3.0" | "4.0">;
-export type IntentBudgetBinding = BudgetBinding<"3.0"> & { intent: WorkIntentBinding };
-export interface AttemptDemand {
-  attemptId: string; orderId: string; experimentId: string;
-  kind: "primary" | "retry" | "shadow" | "descendant";
-  parentAttemptId: string | null; inputBytes: number; inputDigest: string;
-}
-interface Reservation extends AttemptDemand { intent?: IntentAdmission; owner: string; state: "reserved" | "settled"; outcome: string | null }
-export interface BudgetSnapshot { attempts: number; inputBytes: number; active: number; reservations: readonly Readonly<Reservation>[] }
-export interface ResourcePermit { readonly attemptId: string; settle(outcome: "completed" | "failed" | "cancelled"): Promise<void> }
-interface PermitControl { owner:object; bindingDigest:string; version:string; demand:AttemptDemand; claimed:boolean; settling:number; settled:boolean; verify():Promise<void>; finish:ResourcePermit["settle"] }
-const originalPermits = new WeakMap<ResourcePermit,PermitControl>();
-/** Exclusive original-permit handoff for the separate opt-in IPC route. No mint/recovery API. */
-export function claimResourcePermit(owner:object, permit:ResourcePermit, bindingDigest:string, expected:AttemptDemand) {
-  const d=demand(expected), c=originalPermits.get(permit);
-  if(!c || c.owner!==owner || c.version!=="4.0" || c.bindingDigest!==bindingDigest || JSON.stringify(c.demand)!==JSON.stringify(d) || c.claimed || c.settling || c.settled) fail("OWNERSHIP_LOST","original unclaimed experiment permit required");
-  c.claimed=true;
-  // Admission failure is consumed by the original recipient, which must still settle the charged attempt.
-  return Object.freeze({admission:c.verify(),settle:c.finish});
-}
-export class ResourceAdmissionError extends Error {
-  readonly code: "INVALID" | "AUTHORITY_CHANGED" | "DUPLICATE" | "EXHAUSTED" | "OWNERSHIP_LOST" | "DISPATCH_BLOCKED";
-  constructor(code: ResourceAdmissionError["code"], message: string) {
-    super(message); this.name = "ResourceAdmissionError"; this.code = code;
-  }
-}
-function fail(code: ResourceAdmissionError["code"], text: string): never { throw new ResourceAdmissionError(code, text); }
-const hash = (text: string) => createHash("sha256").update(text).digest("hex");
-const digest = (x: unknown): x is string => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
-const id = (x: unknown): x is string => typeof x === "string" && /^[a-zA-Z0-9:_-]{1,128}$/.test(x);
-const integer = (x: unknown, max: number): x is number => Number.isSafeInteger(x) && Number(x) >= 0 && Number(x) <= max;
-function shape(x: unknown, keys: string[]): asserts x is Record<string, unknown> {
-  if (!x || typeof x !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(x)) ||
-    Reflect.ownKeys(x).length !== keys.length || keys.some(k => { const d = Object.getOwnPropertyDescriptor(x, k); return !d || !d.enumerable || !Object.hasOwn(d, "value"); })) fail("INVALID", "closed data object required");
-}
-function limits(x: ResourceLimits): ResourceLimits {
-  shape(x, ["maxAttempts", "maxInputBytes", "maxConcurrent"]);
-  if (!integer(x.maxAttempts, 1024) || x.maxAttempts < 1 || !integer(x.maxInputBytes, 16 * 1024 * 1024) ||
-    !integer(x.maxConcurrent, 32) || x.maxConcurrent < 1 || x.maxConcurrent > x.maxAttempts) fail("INVALID", "unsupported resource limits");
-  return Object.freeze({ maxAttempts: x.maxAttempts, maxInputBytes: x.maxInputBytes, maxConcurrent: x.maxConcurrent });
-}
-function binding<T extends GovernedBudgetBinding>(x: T): Readonly<T> {
-  shape(x, ["version", "directory", "device", "inode", "journalDevice", "journalInode", "authorityDigest", "limits", ...(Object.getOwnPropertyDescriptor(x ?? {}, "version")?.value === "3.0" ? ["intent"] : [])]);
-  if (!["1.0", "2.0", "3.0", "4.0"].includes(x.version) || typeof x.directory !== "string" || !isAbsolute(x.directory) || resolve(x.directory) !== x.directory ||
-    x.directory.length > 1024 || x.directory.split("/").includes(".pi") || ![x.device, x.inode, x.journalDevice, x.journalInode].every(v => typeof v === "string" && /^\d+$/.test(v)) || !digest(x.authorityDigest)) fail("INVALID", "invalid independent budget binding");
-  return Object.freeze({ version: x.version, directory: x.directory, device: x.device, inode: x.inode, journalDevice: x.journalDevice, journalInode: x.journalInode, authorityDigest: x.authorityDigest, limits: limits(x.limits), ...(x.version === "3.0" ? { intent: freezeWork(workIntentBinding(x.intent!)) } : {}) }) as Readonly<T>;
-}
-function demand(x: AttemptDemand): AttemptDemand {
-  shape(x, ["attemptId", "orderId", "experimentId", "kind", "parentAttemptId", "inputBytes", "inputDigest"]);
-  if (![x.attemptId, x.orderId, x.experimentId].every(id) || !["primary", "retry", "shadow", "descendant"].includes(x.kind) ||
-    !(x.parentAttemptId === null || id(x.parentAttemptId)) || (x.kind !== "primary" && x.parentAttemptId === null) ||
-    !integer(x.inputBytes, 16384) || !digest(x.inputDigest)) fail("INVALID", "invalid attempt demand");
-  return { attemptId: x.attemptId, orderId: x.orderId, experimentId: x.experimentId, kind: x.kind,
-    parentAttemptId: x.parentAttemptId, inputBytes: x.inputBytes, inputDigest: x.inputDigest };
-}
-async function privateDirectory(path: string) {
-  const st = await lstat(path, { bigint: true });
-  if (!st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o077n) !== 0n || st.uid !== BigInt(process.getuid!()) || await realpath(path) !== path) fail("INVALID", "a canonical owner-private directory is required");
-  return st;
-}
-
-/** Explicit one-time creation, never implicit reset/recovery. Keep this binding outside the mutable journal. */
-type BudgetCreation = { directory: string; authorityDigest: string; limits: ResourceLimits };
-export function createResourceBudget(input: BudgetCreation): Promise<Readonly<BudgetBinding>> { return createBudget(input, "1.0"); }
-/** Explicit opt-in v2 journal; old readers refuse rather than ignore control events. */
-export function createDispatchBudget(input: BudgetCreation): Promise<Readonly<DispatchBudgetBinding>> { return createBudget(input, "2.0"); }
-export async function createIntentBudget(input: BudgetCreation, intent: Parameters<typeof readIntentWork>[0]): Promise<Readonly<IntentBudgetBinding>> {
-  return createBudget(input, "3.0", JSON.parse(intentKey(intent)));
-}
-/** Explicit batch semantics. All queued slots remain conservatively active until original settlement. */
-export function createExperimentBudget(input: BudgetCreation): Promise<Readonly<ExperimentBudgetBinding>> { return createBudget(input, "4.0"); }
-function createBudget(input: BudgetCreation, version: "4.0"): Promise<Readonly<ExperimentBudgetBinding>>;
-function createBudget(input: BudgetCreation, version: "1.0"): Promise<Readonly<BudgetBinding>>;
-function createBudget(input: BudgetCreation, version: "2.0"): Promise<Readonly<DispatchBudgetBinding>>;
-function createBudget(input: BudgetCreation, version: "3.0", intent: WorkIntentBinding): Promise<Readonly<IntentBudgetBinding>>;
-async function createBudget(input: BudgetCreation, version: GovernedBudgetBinding["version"], intent?: WorkIntentBinding): Promise<Readonly<GovernedBudgetBinding>> {
-  const initialIntent = version === "3.0" ? workIntentBinding(intent!) : undefined;
-  shape(input, ["directory", "authorityDigest", "limits"]);
-  const policy = limits(input.limits), directoryPath = input.directory, authorityDigest = input.authorityDigest;
-  if (typeof directoryPath !== "string" || !isAbsolute(directoryPath) || resolve(directoryPath) !== directoryPath ||
-    directoryPath.split("/").includes(".pi") || !digest(authorityDigest)) fail("INVALID", "invalid budget creation");
-  if (initialIntent) resolveIntent(await readIntentWork(initialIntent), initialIntent.selection, initialIntent.priorities);
-  await privateDirectory(dirname(directoryPath));
-  await mkdir(directoryPath, { mode: 0o700 }); // EEXIST refuses even if its journal was deleted.
-  const st = await privateDirectory(directoryPath);
-  const file = await open(join(directoryPath, "budget.jsonl"), "wx", 0o600);
-  const b = await runWithFinalizers(async () => {
-    const journal = await file.stat({ bigint: true });
-    const result = binding({ version, directory: directoryPath, device: String(st.dev), inode: String(st.ino),
-      journalDevice: String(journal.dev), journalInode: String(journal.ino), authorityDigest, limits: policy, ...(initialIntent ? { intent: initialIntent } : {}) });
-    await file.writeFile(JSON.stringify(result) + "\n"); await file.sync(); return result;
-  }, [{ label: "budget creation close failed", run: () => file.close() }]);
-  const directory = await open(b.directory, constants.O_RDONLY | constants.O_DIRECTORY);
-  await runWithFinalizers(() => directory.sync(), [{ label: "budget directory close failed", run: () => directory.close() }]);
-  return b;
-}
-
-/** Host-side arithmetic for this exact independently retained binding. Not a money/CPU/memory cap. */
-export function openResourceBudget<T extends GovernedBudgetBinding>(input: T) {
-  const b = binding(input), path = join(b.directory, "budget.jsonl"), owner = randomUUID();
-  let pinnedFile: string | undefined;
-  async function transaction<T>(work: (records: Reservation[], append: (event: unknown) => Promise<void>, control: DispatchState, intent: IntentState | null) => Promise<T>, readOnly = false): Promise<T> {
-    const checkRoot = async () => {
-      const st = await privateDirectory(b.directory);
-      if (String(st.dev) !== b.device || String(st.ino) !== b.inode) fail("AUTHORITY_CHANGED", "budget root identity changed");
-    };
-    await checkRoot();
-    const execute = async () => {
-      await checkRoot();
-      const file = await open(path, (readOnly ? constants.O_RDONLY : constants.O_RDWR | constants.O_APPEND) | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-      return runWithFinalizers(async () => {
-        const st = await file.stat({ bigint: true }), key = `${st.dev}:${st.ino}`;
-        if (!st.isFile() || st.nlink !== 1n || st.uid !== BigInt(process.getuid!()) || (st.mode & 0o077n) !== 0n || st.size > 2n * 1024n * 1024n) fail("INVALID", "unsafe or oversized budget journal");
-        if (key !== `${b.journalDevice}:${b.journalInode}` || (pinnedFile && pinnedFile !== key)) fail("AUTHORITY_CHANGED", "budget journal replaced");
-        pinnedFile = key;
-        const buffer = Buffer.alloc(Number(st.size));
-        let offset = 0;
-        while (offset < buffer.length) { const n = (await file.read(buffer, offset, buffer.length - offset, offset)).bytesRead; if (!n) fail("INVALID", "short budget read"); offset += n; }
-        const text = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
-        if (!text.endsWith("\n")) fail("INVALID", "incomplete budget journal; no automatic recovery");
-        const lines = text.slice(0, -1).split("\n");
-        if (lines.length > (b.version === "3.0" ? 2369 : b.version !== "1.0" ? 2305 : 2049) || JSON.stringify(binding(parseWorkJson(lines[0]) as unknown as GovernedBudgetBinding)) !== JSON.stringify(b)) fail("AUTHORITY_CHANGED", "budget header does not match independent authority");
-        const records: Reservation[] = [], control: DispatchState = { revision: 0, paused: false, records: [] };
-        const intent: IntentState | null = b.intent ? { revision: 0, selection: b.intent.selection, priorities: b.intent.priorities, records: [] } : null;
-        for (const line of lines.slice(1)) {
-          const event = parseWorkJson(line) as Record<string, unknown>;
-          if (event.type === "intent-request" || event.type === "intent-apply") {
-            if (!intent) fail("INVALID", "intent controls require explicit v3 binding");
-            replayIntent(intent, event, records.filter(r => r.state === "reserved").length, control.records.some(r => r.application === "pending"));
-          } else if (event.type === "control-request" || event.type === "control-apply") {
-            if (b.version === "1.0") fail("INVALID", "controls require explicit v2/v3 binding");
-            replayDispatch(control, event, resourceBindingDigest(b), records.filter(r => r.state === "reserved").length, Boolean(intent?.records.some(r => r.application === "pending-or-unknown")));
-          } else if (event.type === "reserve-batch") {
-            if (b.version !== "4.0") fail("INVALID", "batch requires explicit v4 budget");
-            shape(event, ["type", "owner", "demands"]);
-            if (!id(event.owner) || !Array.isArray(event.demands) || !event.demands.length || event.demands.length > 32 || control.paused || control.records.some(r => r.application === "pending")) fail("INVALID", "invalid batch");
-            for (const value of event.demands) {
-              const d = demand(value as AttemptDemand);
-              if (records.some(r => r.attemptId === d.attemptId) || d.parentAttemptId !== null && !records.some(r => r.attemptId === d.parentAttemptId)) fail("INVALID", "invalid batch sequence");
-              records.push({ ...d, owner: event.owner, state: "reserved", outcome: null });
-            }
-          } else if (event.type === "reserve") {
-            if (control.paused || control.records.some(r => r.application === "pending") || intent?.records.some(r => r.application === "pending-or-unknown")) fail("INVALID", "reservation crossed dispatch barrier");
-            shape(event, ["type", "owner", "demand", ...(intent ? ["intent"] : [])]);
-            const d = demand(event.demand as AttemptDemand);
-            if (!id(event.owner) || records.some(r => r.attemptId === d.attemptId) || (d.parentAttemptId !== null && !records.some(r => r.attemptId === d.parentAttemptId))) fail("INVALID", "invalid reservation sequence");
-            if (intent && (d.kind !== "primary" || d.parentAttemptId !== null)) fail("INVALID", "v3 schedules primary dispatch only");
-            const assigned = intent ? intentAdmission(intent, records, event.intent as IntentAdmission) : undefined;
-            records.push({ ...d, ...(assigned ? { intent: assigned } : {}), owner: event.owner, state: "reserved", outcome: null });
-          } else {
-            shape(event, ["type", "owner", "attemptId", "outcome"]);
-            const r = records.find(r => r.attemptId === event.attemptId);
-            if (event.type !== "settle" || !r || r.state !== "reserved" || event.owner !== r.owner || !["completed", "failed", "cancelled"].includes(String(event.outcome))) fail("INVALID", "invalid settlement sequence");
-            r.state = "settled"; r.outcome = String(event.outcome);
-          }
-          if (records.length > b.limits.maxAttempts || records.reduce((n, r) => n + r.inputBytes, 0) > b.limits.maxInputBytes || records.filter(r => r.state === "reserved").length > b.limits.maxConcurrent) fail("INVALID", "journal exceeds independently fixed limits");
-        }
-        let expectedSize = st.size;
-        const unchanged = async () => {
-          await checkRoot(); const current = await lstat(path, { bigint: true });
-          if (`${current.dev}:${current.ino}` !== key || current.size !== expectedSize || (await file.stat({ bigint: true })).size !== expectedSize ||
-            current.nlink !== 1n || (current.mode & 0o077n) !== 0n) fail("AUTHORITY_CHANGED", "budget journal changed under lock");
-        };
-        await unchanged();
-        return await work(records, async event => {
-          if (readOnly) fail("INVALID", "inspection cannot write");
-          const line = JSON.stringify(event) + "\n";
-          if (expectedSize + BigInt(Buffer.byteLength(line)) > 2n * 1024n * 1024n) fail("EXHAUSTED", "journal capacity reached");
-          await unchanged(); await file.writeFile(line); expectedSize += BigInt(Buffer.byteLength(line)); await file.sync(); await unchanged();
-        }, control, intent);
-      }, [{ label: "budget journal close failed", run: () => file.close() }]);
-    };
-    return readOnly ? execute() : withFileLock(path, "resource budget", execute, { staleRecovery: "disabled" });
-  }
-  const permit = (d:AttemptDemand): Readonly<ResourcePermit> => {
-    const attemptId=d.attemptId;
-    const c:PermitControl={owner:api,bindingDigest:resourceBindingDigest(b),version:b.version,demand:d,claimed:false,settling:0,settled:false,
-      verify:()=>transaction(async(records,_append,control,intent)=>{
-        const r=records.find(r=>r.attemptId===attemptId);
-        if(!r || r.owner!==owner || r.state!=="reserved" || Object.keys(d).some(k=>r[k as keyof AttemptDemand]!==d[k as keyof AttemptDemand])) fail("OWNERSHIP_LOST","original reservation is not held");
-        if(control.paused || control.records.some(r=>r.application==="pending") || intent?.records.some(r=>r.application==="pending-or-unknown")) fail("DISPATCH_BLOCKED","dispatch barrier");
-      }),
-      async finish(outcome) {
-        if(!["completed","failed","cancelled"].includes(outcome)) fail("INVALID","invalid outcome");
-        c.settling++;
-        try {
-          await transaction(async(records,append)=>{
-            const r=records.find(r=>r.attemptId===attemptId);
-            if(!r || r.owner!==owner) fail("OWNERSHIP_LOST","only original live host may settle");
-            if(r.state==="settled"){if(r.outcome!==outcome)fail("INVALID","contradictory settlement");return;}
-            await append({type:"settle",owner,attemptId,outcome});
-          }); c.settled=true;
-        } finally {c.settling--;}
-      }};
-    const result=Object.freeze({attemptId,async settle(outcome:Parameters<ResourcePermit["settle"]>[0]) {
-      if(c.claimed) fail("OWNERSHIP_LOST","original permit handed to IPC lifetime");
-      return c.finish(outcome);
-    }}); originalPermits.set(result,c); return result;
-  };
-  const api = Object.freeze({
-    binding: b,
-    async reserveBatch(inputs: readonly AttemptDemand[]): Promise<readonly Readonly<ResourcePermit>[]> {
-      if (b.version !== "4.0" || !Array.isArray(inputs) || !inputs.length || inputs.length > 32 || Reflect.ownKeys(inputs).length !== inputs.length + 1 || Array.from({ length: inputs.length }, (_, i) => Object.getOwnPropertyDescriptor(inputs, String(i))).some(d => !d?.enumerable || !Object.hasOwn(d, "value"))) fail("INVALID", "explicit v4 dense bounded batch required");
-      const demands = Array.from(inputs, demand);
-      await transaction(async (records, append, control) => {
-        if (control.paused || control.records.some(r => r.application === "pending")) fail("DISPATCH_BLOCKED", "dispatch barrier");
-        const ids = new Set(records.map(r => r.attemptId));
-        for (const d of demands) {
-          if (ids.has(d.attemptId)) fail("DUPLICATE", "batch identity already charged");
-          if (d.parentAttemptId !== null && !ids.has(d.parentAttemptId)) fail("INVALID", "batch parent missing");
-          ids.add(d.attemptId);
-        }
-        if (records.length + demands.length > b.limits.maxAttempts || records.reduce((n,r) => n+r.inputBytes,0) + demands.reduce((n,d) => n+d.inputBytes,0) > b.limits.maxInputBytes || records.filter(r => r.state === "reserved").length + demands.length > b.limits.maxConcurrent) fail("EXHAUSTED", "whole experiment exceeds aggregate allowance");
-        await append({ type: "reserve-batch", owner, demands });
-      });
-      return Object.freeze(demands.map(d => permit(d)));
-    },
-    intentControls(input: DispatchAuthority | null) {
-      if (!b.intent) fail("INVALID", "intent controls require explicit v3 budget creation");
-      const work = b.intent, authority = dispatchAuthority(input), scope = resourceBindingDigest(b);
-      const authorized = (digest: string) => authority?.authorityDigest === b.authorityDigest && authority.requestDigests.includes(digest);
-      const apply = async (request: ReturnType<typeof intentRequest>, records: Reservation[], append: (event: unknown) => Promise<void>, control: DispatchState, state: IntentState) => {
-        const pending = state.records.find(r => r.requestId === request.requestId);
-        if (!pending || pending.digest !== intentRequestDigest(request)) fail("DUPLICATE", "exact original intent request required");
-        if (!matchesIntentReceipt(pending, request)) fail("INVALID", "intent receipt projection does not match original request");
-        if (pending.application !== "pending-or-unknown" || !authorized(pending.digest) || records.some(r => r.state === "reserved") || control.records.some(r => r.application === "pending")) return;
-        await applyIntentApplication(work, state, request);
-        const event = { type: "intent-apply", requestId: request.requestId };
-        await append(event); replayIntent(state, event, 0, false);
-      };
-      return Object.freeze({
-        inspect: () => transaction(async (records, _append, control, state) => {
-          resolveIntent(await readIntentWork(work), state!.selection, state!.priorities);
-          const blocked = control.paused || control.records.some(r => r.application === "pending") || state!.records.some(r => r.application === "pending-or-unknown");
-          return freezeWork({ ...intentSnapshot(state!, scope), dispatchPaused: control.paused, nextObligation: blocked ? null : nextIntent(state!, records) });
-        }, true),
-        async request(input: IntentRequest) {
-          const request = intentRequest(input), digest = intentRequestDigest(request);
-          if (request.bindingDigest !== scope) fail("AUTHORITY_CHANGED", "intent request is for another binding");
-          return transaction(async (records, append, control, state) => {
-            const prior = state!.records.find(r => r.requestId === request.requestId);
-            if (prior) {
-              if (prior.digest !== digest) fail("DUPLICATE", "immutable intent request identity");
-              if (!matchesIntentReceipt(prior, request)) fail("INVALID", "intent receipt projection does not match original request");
-              return intentSnapshot(state!, scope);
-            }
-            if (state!.records.length >= 32) fail("EXHAUSTED", "intent request capacity reached");
-            const decision = intentDecision(state!, request, Boolean(authorized(digest)), control.records.some(r => r.application === "pending"));
-            if (decision === "approved") await validateIntentApplication(work, state!, request);
-            const event = { type: "intent-request", receipt: intentReceipt(request, decision) };
-            await append(event); replayIntent(state!, event, records.filter(r => r.state === "reserved").length, control.records.some(r => r.application === "pending"));
-            if (decision === "approved") await apply(request, records, append, control, state!);
-            return intentSnapshot(state!, scope);
-          });
-        },
-        async reconcile(input: IntentRequest) {
-          const request = intentRequest(input);
-          if (request.bindingDigest !== scope) fail("AUTHORITY_CHANGED", "intent request is for another binding");
-          return transaction(async (records, append, control, state) => { await apply(request, records, append, control, state!); return intentSnapshot(state!, scope); });
-        },
-      });
-    },
-    controls(input: DispatchAuthority | null) {
-      if (b.version === "1.0") fail("INVALID", "controls require explicit v2/v3 budget creation");
-      const authority = dispatchAuthority(input), scope = resourceBindingDigest(b);
-      const authorized = (digest: string) => authority?.authorityDigest === b.authorityDigest && authority.requestDigests.includes(digest);
-      const apply = async (requestId: string, records: Reservation[], append: (event: unknown) => Promise<void>, control: DispatchState) => {
-        const pending = control.records.find(r => r.request.requestId === requestId && r.application === "pending");
-        if (!pending || !authorized(pending.digest) || records.some(r => r.state === "reserved")) return;
-        const event = { type: "control-apply", requestId: pending.request.requestId };
-        await append(event); replayDispatch(control, event, scope, 0);
-      };
-      return Object.freeze({
-        inspect: () => transaction(async (_records, _append, control, intent) => freezeDispatch(control, scope, Boolean(intent?.records.some(r => r.application === "pending-or-unknown"))), true),
-        async reconcile(requestId: string) {
-          if (typeof requestId !== "string" || !/^[a-zA-Z0-9:_-]{1,128}$/.test(requestId)) fail("INVALID", "exact request ID required for reconciliation");
-          return transaction(async (records, append, control, intent) => { await apply(requestId, records, append, control); return freezeDispatch(control, scope, Boolean(intent?.records.some(r => r.application === "pending-or-unknown"))); });
-        },
-        async request(input: DispatchRequest) {
-          const request = dispatchRequest(input), digest = dispatchRequestDigest(request);
-          if (request.bindingDigest !== scope) fail("AUTHORITY_CHANGED", "request is for another binding");
-          return transaction(async (records, append, control, intent) => {
-            const previous = control.records.find(r => r.request.requestId === request.requestId);
-            if (previous) {
-              if (previous.digest !== digest) fail("DUPLICATE", "request ID cannot name another decision");
-              // Redelivery is readback only, never a second effect or implicit reconciliation.
-              return freezeDispatch(control, scope, Boolean(intent?.records.some(r => r.application === "pending-or-unknown")));
-            }
-            if (control.records.length >= 128) fail("EXHAUSTED", "control request capacity reached");
-            const event = { type: "control-request", request, decision: dispatchDecision(control, request, Boolean(authorized(digest)), Boolean(intent?.records.some(r => r.application === "pending-or-unknown"))) };
-            await append(event); replayDispatch(control, event, scope, records.filter(r => r.state === "reserved").length, Boolean(intent?.records.some(r => r.application === "pending-or-unknown")));
-            if (event.decision === "approved") await apply(request.requestId, records, append, control);
-            return freezeDispatch(control, scope, Boolean(intent?.records.some(r => r.application === "pending-or-unknown")));
-          });
-        },
-      });
-    },
-    /** Explicit control-path synchronization; unlike inspect, this takes the existing journal lock. */
-    async controlSnapshot(): Promise<Readonly<BudgetSnapshot>> {
-      return transaction(async records => Object.freeze({ attempts: records.length, inputBytes: records.reduce((n,r)=>n+r.inputBytes,0), active: records.filter(r=>r.state==="reserved").length, reservations:Object.freeze(records.map(r=>freezeWork({...r}))) }));
-    },
-    async inspect(): Promise<Readonly<BudgetSnapshot>> {
-      return transaction(async records => Object.freeze({ attempts: records.length, inputBytes: records.reduce((n, r) => n + r.inputBytes, 0),
-        active: records.filter(r => r.state === "reserved").length, reservations: Object.freeze(records.map(r => freezeWork({ ...r }))) }), true);
-    },
-    async reserve(input: AttemptDemand, selection?: IntentAdmission): Promise<Readonly<ResourcePermit>> {
-      const d = demand(input), selected: IntentAdmission | null = selection === undefined ? null : JSON.parse(intentKey(selection));
-      if (Boolean(b.intent) !== Boolean(selected)) fail("INVALID", "v3 reservations require an exact scheduled intent; older bindings do not accept it");
-      await transaction(async (records, append, control, intent) => {
-        if (control.paused || control.records.some(r => r.application === "pending") || intent?.records.some(r => r.application === "pending-or-unknown")) fail("DISPATCH_BLOCKED", "dispatch paused or awaiting verified boundary");
-        if (records.some(r => r.attemptId === d.attemptId)) fail("DUPLICATE", "attempt identity already charged; never launch a redelivery");
-        if (d.parentAttemptId !== null && !records.some(r => r.attemptId === d.parentAttemptId)) fail("INVALID", "parent attempt is not in this budget");
-        if (records.length >= b.limits.maxAttempts || records.reduce((n, r) => n + r.inputBytes, 0) + d.inputBytes > b.limits.maxInputBytes ||
-          records.filter(r => r.state === "reserved").length >= b.limits.maxConcurrent) fail("EXHAUSTED", "aggregate allowance exhausted");
-        if (intent) {
-          if (d.kind !== "primary" || d.parentAttemptId !== null) fail("INVALID", "v3 schedules primary dispatch only");
-          resolveIntent(await readIntentWork(b.intent!), intent.selection, intent.priorities);
-          const assigned = intentAdmission(intent, records, selected!);
-          await append({ type: "reserve", owner, demand: d, intent: assigned });
-        } else await append({ type: "reserve", owner, demand: d });
-      });
-      return permit(d);
-    },
-  });
-  return api;
-}
-
-export function resourceBindingDigest(b: GovernedBudgetBinding): string { return hash(JSON.stringify(binding(b))); }