pi-daddy 0.22.0 → 0.23.0

package/src/order-schedule.ts

@@ -0,0 +1,42 @@
+import { closed, cloneExperiment, experimentHash } from "./experiment-contract.ts";
+import type { VariantRecord } from "./experiment-state.ts";
+export interface OrderNode { nodeId: string; dependencies: readonly string[]; executions: readonly string[]; expectedDigest: string; decision: { decisionId: string; authorityId: string } | null }
+export interface OrderSchedule { version: "order-schedule-v1"; policyDigest: string; nodes: readonly OrderNode[] }
+export interface FactoryDecision { version: "factory-decision-v1"; requestId: string; bindingDigest: string; nodeId: string; evidenceDigest: string; authorityId: string; choice: "approve" | "reject" }
+export const factoryDecisionDigest = (d: FactoryDecision) => experimentHash(factoryDecision(d));
+export function factoryDecision(value: FactoryDecision): FactoryDecision {
+  const d = cloneExperiment(value); closed(d,["version","requestId","bindingDigest","nodeId","evidenceDigest","authorityId","choice"]);
+  if(d.version!=="factory-decision-v1" || ![d.requestId,d.nodeId,d.authorityId].every(x=>typeof x==="string"&&/^[a-zA-Z0-9:_-]{1,128}$/.test(x)) || ![d.bindingDigest,d.evidenceDigest].every(x=>typeof x==="string"&&/^[a-f0-9]{64}$/.test(x)) || !["approve","reject"].includes(d.choice))throw new Error("invalid reserved decision");return d;
+}
+export function orderSchedule(input: OrderSchedule, executions: readonly string[]): OrderSchedule {
+  const s=cloneExperiment(input);closed(s,["version","policyDigest","nodes"]);
+  if(s.version!=="order-schedule-v1"|| !/^[a-f0-9]{64}$/.test(s.policyDigest)||!Array.isArray(s.nodes)||!s.nodes.length||s.nodes.length>16)throw new Error("bounded order schedule required");
+  const ids=new Set<string>(),all:string[]=[];
+  for(const n of s.nodes as readonly OrderNode[]){closed(n,["nodeId","dependencies","executions","expectedDigest","decision"]);
+    if(!/^[a-zA-Z0-9:_-]{1,128}$/.test(n.nodeId)||ids.has(n.nodeId)||!Array.isArray(n.dependencies)||n.dependencies.length>16||new Set(n.dependencies).size!==n.dependencies.length||!Array.isArray(n.executions)||n.executions.length<1||n.executions.length>3||!/^[a-f0-9]{64}$/.test(n.expectedDigest))throw new Error("invalid node/dependency/recovery policy");
+    if(n.decision!==null){closed(n.decision,["decisionId","authorityId"]);if(![n.decision.decisionId,n.decision.authorityId].every(x=>/^[a-zA-Z0-9:_-]{1,128}$/.test(x)))throw new Error("invalid decision owner");}
+    ids.add(n.nodeId);all.push(...n.executions);
+  }
+  if(new Set(all).size!==all.length||all.length!==executions.length||all.some(x=>!executions.includes(x)))throw new Error("schedule must own every reserved execution exactly once");
+  const visiting=new Set<string>(),done=new Set<string>();
+  const visit=(id:string)=>{if(done.has(id))return;if(visiting.has(id))throw new Error("dependency cycle");const n=s.nodes.find(n=>n.nodeId===id);if(!n)throw new Error("missing dependency");visiting.add(id);n.dependencies.forEach(visit);visiting.delete(id);done.add(id);};s.nodes.forEach(n=>visit(n.nodeId));return s;
+}
+export interface OrderNodeView {nodeId:string;state:"eligible"|"running"|"unknown"|"exhausted"|"decision-required"|"decision-rejected"|"dependency-blocked"|"satisfied";action:"dispatch"|"decide"|"wait"|"stakeholder"|"none";executionId:string|null;evidenceDigest:string|null}
+export function evaluateOrder(s:OrderSchedule,variants:readonly VariantRecord[],digests:ReadonlyMap<string,string|null>,decisions:readonly FactoryDecision[]):OrderNodeView[]{
+  const rows=new Map<string,OrderNodeView>();
+  function evaluate(n:OrderNode):OrderNodeView{
+    if(rows.has(n.nodeId))return rows.get(n.nodeId)!;
+    const row:OrderNodeView={nodeId:n.nodeId,state:"exhausted",action:"stakeholder",executionId:null,evidenceDigest:null};
+    if(n.dependencies.some(id=>evaluate(s.nodes.find(n=>n.nodeId===id)!).state!=="satisfied")){row.state="dependency-blocked";row.action="wait";rows.set(n.nodeId,row);return row;}
+    for(const id of n.executions){const v=variants.find(v=>v.executionId===id)!;row.executionId=id;
+      if(v.state==="unknown"){row.state="unknown";row.action="stakeholder";break;}
+      if(v.state==="completed"&&digests.get(id)===n.expectedDigest){row.evidenceDigest=experimentHash({nodeId:n.nodeId,policyDigest:s.policyDigest,executionId:id,artifactDigest:v.artifactDigest,expectedDigest:n.expectedDigest});
+        const d=decisions.find(d=>d.nodeId===n.nodeId&&d.evidenceDigest===row.evidenceDigest);
+        row.state=n.decision?d?d.choice==="approve"?"satisfied":"decision-rejected":"decision-required":"satisfied";row.action=row.state==="decision-required"?"decide":row.state==="decision-rejected"?"stakeholder":"none";break;}
+      if(["unstarted","queued"].includes(v.state)){row.state="eligible";row.action="dispatch";break;}
+      if(["dispatching","running"].includes(v.state)){row.state="running";row.action="wait";break;}
+    }
+    rows.set(n.nodeId,row);return row;
+  }
+  return s.nodes.map(evaluate);
+}

package/src/ordinary-children.ts

@@ -0,0 +1,59 @@
+import { randomUUID } from "node:crypto";
+import { isExecutionId } from "./execution-id.ts";
+import { dataDigest, detached, freeze, sha } from "./debrief-contract.ts";
+import { controlShape } from "./dispatch-control.ts";
+export interface OrdinaryTarget { executionId:string; parentExecutionId:string|null; toolCallId:string|null }
+export interface OrdinaryCancellation { version:"ordinary-cancel-v1"; requestId:string; bindingDigest:string; expectedRevision:number; target:OrdinaryTarget }
+export interface OrdinaryAuthority { bindingDigest:string; requestDigests:readonly string[] }
+type ControlState="not-assessed"|"failed"|"unknown";
+interface Row { target:OrdinaryTarget; state:"active"|"settled"|"unknown"; abortRequested:boolean; control:ControlState; boundary:ControlState; outcome:unknown }
+interface State { holds:Set<string>; enabled:boolean; coverageGap:boolean; bindingDigest:string; revision:number; rows:Map<string,Row>; handles:Map<string,AbortController>; requests:Map<string,{digest:string;result:unknown}> }
+const sessions=new WeakMap<object,OrdinaryChildren>(),ports=new WeakMap<object,State>();
+const id=(v:unknown)=>typeof v==="string"&&/^[a-zA-Z0-9:_-]{1,128}$/.test(v);
+function target(value:OrdinaryTarget){const t=detached(value);controlShape(t,["executionId","parentExecutionId","toolCallId"]);if(!isExecutionId(t.executionId)||!(t.parentExecutionId===null||isExecutionId(t.parentExecutionId))||!(t.toolCallId===null||typeof t.toolCallId==="string"&&t.toolCallId.length>0&&t.toolCallId.length<=256))throw Error("exact original occurrence identity required");return t;}
+export function ordinaryCancellation(input:OrdinaryCancellation){const r=detached(input);controlShape(r,["version","requestId","bindingDigest","expectedRevision","target"]);if(r.version!=="ordinary-cancel-v1"||!id(r.requestId)||!sha(r.bindingDigest)||!Number.isSafeInteger(r.expectedRevision)||r.expectedRevision<0)throw Error("invalid ordinary cancellation");return freeze({...r,target:target(r.target)});}
+export const ordinaryCancellationDigest=(r:OrdinaryCancellation)=>dataDigest(ordinaryCancellation(r));
+export interface OrdinaryChildren { readonly bindingDigest:string; inspect():unknown; quiescent():boolean; cancel(request:OrdinaryCancellation,authority:OrdinaryAuthority|null):unknown }
+export const isOrdinaryChildren=(p:unknown):p is OrdinaryChildren=>typeof p==="object"&&p!==null&&ports.has(p);
+/** Extension-internal constructor. No disk discovery/recovery and no identity inferred from labels. */
+function initializeOrdinaryChildren(session:object):void {
+  if(sessions.has(session))throw Error("original session already registered");
+  const s:State={holds:new Set(),enabled:false,coverageGap:false,bindingDigest:dataDigest({occurrence:randomUUID()}),revision:0,rows:new Map(),handles:new Map(),requests:new Map()};
+  const port:OrdinaryChildren=Object.freeze({bindingDigest:s.bindingDigest,
+    quiescent:()=>!s.coverageGap&&[...s.rows.values()].every(r=>r.state==="settled"&&r.boundary==="not-assessed"),
+    inspect:()=>freeze(detached({bindingDigest:s.bindingDigest,revision:s.revision,children:[...s.rows.values()],admission:s.holds.size?"held-by-original-owner":"open",coverage:s.coverageGap?"unretained-before-opt-in":"original-registered-lifetimes-only",freshness:"snapshot-unknown",recovery:"unavailable",acceptance:"not-assessed"})),
+    cancel(input:OrdinaryCancellation,authority:OrdinaryAuthority|null){
+      const r=ordinaryCancellation(input),digest=ordinaryCancellationDigest(input),old=s.requests.get(r.requestId);
+      if(old){if(old.digest!==digest)throw Error("immutable ordinary cancellation ID");return freeze(detached(old.result));}
+      if(r.bindingDigest!==s.bindingDigest||r.expectedRevision!==s.revision)throw Error("stale original ordinary controller CAS");
+      if(!authority||authority.bindingDigest!==s.bindingDigest||!authority.requestDigests.includes(digest))throw Error("independent exact ordinary cancellation authority required");
+      const row=s.rows.get(r.target.executionId),handle=s.handles.get(r.target.executionId);
+      if(!row||dataDigest(row.target)!==dataDigest(r.target)||row.state!=="active"||!handle)throw Error("original live child handle unavailable; no recovery");
+      if(s.requests.size>=1024)throw Error("ordinary cancellation capacity exhausted");
+      // Synchronous original-handle operation: CAS cannot yield between checking and requesting abort.
+      const result={state:"abort-requested",target:r.target,revision:++s.revision,completion:"pending-original-caller",durability:"process-local"};
+      s.requests.set(r.requestId,{digest,result});row.abortRequested=true;handle.abort();return freeze(detached(result));
+    }});
+  sessions.set(session,port);ports.set(port,s);
+}
+/** Only the original session object can retrieve its retained port; spreading/copying cannot. */
+export function ordinaryChildrenFor(session:object):OrdinaryChildren {const p=sessions.get(session);if(!p)throw Error("original grants session required");ports.get(p)!.enabled=true;return p;}
+/** Associate the actual extension API object at factory creation, never a label or path. */
+export function associateOrdinaryHost(host:object,session:object){initializeOrdinaryChildren(session);const p=sessions.get(session);if(!p||sessions.has(host))throw Error("original unbound extension host required");sessions.set(host,p);}
+export function retainSessionChild(session:object,input:OrdinaryTarget,caller?:AbortSignal){const p=sessions.get(session);if(!p)return undefined;const s=ports.get(p)!;if(!s.enabled){s.coverageGap=true;return undefined;}return retainOrdinaryChild(p,input,caller);}
+/** Internal host control seam, not a model tool or recovered capability. Reads never call it. */
+export function holdOrdinaryDispatch(port:OrdinaryChildren,key:string){
+ const s=ports.get(port);if(!s||!sha(key))throw Error("original ordinary boundary required");
+ if(s.coverageGap||[...s.rows.values()].some(r=>r.state!=="active"&&r.boundary!=="not-assessed"))throw Error("ordinary boundary unavailable; no recovery");
+ if(!s.holds.has(key)){if(s.holds.size>=32)throw Error("ordinary boundary capacity exhausted");s.holds.add(key);s.revision++;}
+ return Object.freeze({ready:()=>port.quiescent(),release:()=>{if(s.holds.delete(key))s.revision++;}});
+}
+/** Extension executor seam; never exported through the package root or model tools. */
+export function retainOrdinaryChild(port:OrdinaryChildren,input:OrdinaryTarget,caller?:AbortSignal){
+  const s=ports.get(port);if(!s)throw Error("original ordinary controller required");const t=target(input);
+  if(s.holds.size)throw Error("ordinary dispatch held at original control boundary");
+  if(s.rows.has(t.executionId)||s.rows.size>=1024)throw Error("ordinary occurrence reused or capacity exhausted");
+  const abort=new AbortController(),row:Row={target:t,state:"active",abortRequested:false,control:"not-assessed",boundary:"not-assessed",outcome:null};s.rows.set(t.executionId,row);s.handles.set(t.executionId,abort);s.revision++;
+  let done=false;return {signal:caller?AbortSignal.any([caller,abort.signal]):abort.signal,
+    settle(outcome:unknown,control:ControlState,boundary:ControlState=control){if(done)throw Error("original child already settled");done=true;row.outcome=detached(outcome);row.control=control;row.boundary=boundary;row.state=boundary==="unknown"?"unknown":"settled";s.handles.delete(t.executionId);s.revision++;}};
+}

package/src/producer-ipc-contract.ts

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+import { isExecutionId } from "./execution-id.ts";
+import type { AttemptDemand } from "./resource-budget.ts";
+export const PRODUCER_IPC_LIMITS = Object.freeze({ frameBytes:1024, referenceBytes:128, childMs:3000, graceMs:50, maxElapsedMs:30000 });
+export interface ProducerIpcBinding { version:"producer-ipc-v1"; budgetDigest:string; orderId:string; experimentId:string; executionId:string; charterSha256:string; invocationId:string }
+export interface ProducerIpcReferences { claimRef:string; responseRef:string }
+const id = (v:unknown):v is string => typeof v === "string" && /^[a-zA-Z0-9:_-]{1,128}$/.test(v);
+const hash = (v:unknown):v is string => typeof v === "string" && /^[a-f0-9]{64}$/.test(v);
+export function ipcShape(value:unknown, keys:readonly string[]): asserts value is Record<string,unknown> {
+  if (!value || typeof value !== "object" || ![Object.prototype,null].includes(Object.getPrototypeOf(value)) || Reflect.ownKeys(value).length !== keys.length || keys.some(k=>{const d=Object.getOwnPropertyDescriptor(value,k);return !d||!d.enumerable||!Object.hasOwn(d,"value");})) throw new TypeError("closed producer IPC data required");
+}
+export function producerIpcBinding(value:ProducerIpcBinding):Readonly<ProducerIpcBinding> {
+  ipcShape(value,["version","budgetDigest","orderId","experimentId","executionId","charterSha256","invocationId"]);
+  if (value.version!=="producer-ipc-v1" || !hash(value.budgetDigest) || !hash(value.charterSha256) || !isExecutionId(value.executionId) || ![value.orderId,value.experimentId,value.invocationId].every(id)) throw new TypeError("exact producer IPC binding required");
+  return Object.freeze({version:value.version,budgetDigest:value.budgetDigest,orderId:value.orderId,experimentId:value.experimentId,executionId:value.executionId,charterSha256:value.charterSha256,invocationId:value.invocationId});
+}
+export const producerIpcBindingDigest = (value:ProducerIpcBinding) => createHash("sha256").update(JSON.stringify(producerIpcBinding(value))).digest("hex");
+export const producerIpcFrame = (value:ProducerIpcBinding):Buffer => Buffer.from(JSON.stringify({id:producerIpcBinding(value).invocationId,sequence:1})+"\n");
+/** Existing v4 reservation schema, not a new model/effort/skills experiment operation. */
+export function producerIpcDemand(value:ProducerIpcBinding):AttemptDemand {
+  const b=producerIpcBinding(value);return {attemptId:b.executionId,orderId:b.orderId,experimentId:b.experimentId,kind:"primary",parentAttemptId:null,inputBytes:Buffer.byteLength(JSON.stringify(b)),inputDigest:producerIpcBindingDigest(b)};
+}
+export function ipcReferences(value:ProducerIpcReferences):Readonly<ProducerIpcReferences> {
+  ipcShape(value,["claimRef","responseRef"]);if(!id(value.claimRef)||!id(value.responseRef))throw new TypeError("bounded evidence references required");
+  return Object.freeze({claimRef:value.claimRef,responseRef:value.responseRef});
+}

package/src/producer-ipc.ts

@@ -0,0 +1,107 @@
+import { Readable } from "node:stream";
+import { createHash } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { claimResourcePermit, type ResourcePermit, type openResourceBudget } from "./resource-budget.ts";
+import { digestRuntime, digestNamespaceArgs } from "./effect-profile-runtime.ts";
+import { runChild, type ChildRunResult } from "./run-child.ts";
+import { ipcShape, ipcReferences, producerIpcBinding, producerIpcBindingDigest, producerIpcDemand, producerIpcFrame, PRODUCER_IPC_LIMITS as LIMITS, type ProducerIpcBinding, type ProducerIpcReferences } from "./producer-ipc-contract.ts";
+export { producerIpcBinding, producerIpcBindingDigest, producerIpcDemand, PRODUCER_IPC_LIMITS, type ProducerIpcBinding, type ProducerIpcReferences } from "./producer-ipc-contract.ts";
+type Owner = ReturnType<typeof openResourceBudget>;
+export interface ProducerIpcContext { readonly binding:Readonly<ProducerIpcBinding>; readonly signal:AbortSignal }
+export interface ProducerIpcHost { readonly binding:Readonly<ProducerIpcBinding> }
+interface HostState { owner:Owner; exchange:(frames:Readable,context:ProducerIpcContext)=>Promise<ProducerIpcReferences>; used:boolean }
+const hosts = new WeakMap<ProducerIpcHost,HostState>();
+/** Trusted host-only capability constructor, NOT approval/entitlement discovery. */
+export function createProducerIpcHost(input:{owner:Owner;binding:ProducerIpcBinding;exchange:HostState["exchange"]}):ProducerIpcHost {
+  ipcShape(input,["owner","binding","exchange"]);
+  if(typeof input.exchange!=="function")throw new TypeError("original host exchange required");
+  const port=Object.freeze({binding:producerIpcBinding(input.binding)});
+  hosts.set(port,{owner:input.owner,exchange:input.exchange,used:false});return port;
+}
+export interface ProducerIpcSnapshot {
+  readonly binding:Readonly<ProducerIpcBinding>;
+  readonly outcome:"pending"|"completed"|"failed"|"cancelled"|"timed-out";
+  readonly reason:null|"ADMISSION_FAILED"|"RUNTIME_FAILED"|"CHILD_FAILED"|"FRAME_INVALID"|"HOST_FAILED"|"CANCELLED"|"DEADLINE";
+  readonly child:Readonly<ChildRunResult>|null;
+  readonly childState:"pending"|"not-spawned"|"settled"|"unknown";
+  readonly hostState:"not-called"|"pending"|"acknowledged"|"failed";
+  readonly frameSha256:string|null;
+  readonly references:Readonly<ProducerIpcReferences>|null;
+  readonly settlement:"pending"|"acknowledged"|"failed-or-unknown";
+  readonly acceptance:"not-assessed";
+}
+export interface ProducerIpcRun {
+  readonly started:Promise<"spawned"|"not-spawned">;
+  readonly readiness:Promise<"frame-ready"|"not-ready">;
+  readonly child:Promise<ChildRunResult|null>;
+  /** Bounded effect observation, NOT a resource-release/child-settlement receipt. */
+  readonly result:Promise<ProducerIpcSnapshot>;
+  /** May remain pending if original child, host or required accounting does not acknowledge. */
+  readonly completion:Promise<ProducerIpcSnapshot>;
+  inspect():ProducerIpcSnapshot;
+}
+// This is a separate fixed model-free emitter, not a new operation on linux-bwrap-digest-v1.
+const WORKER = "/* producer-ipc-v1 */process.stdout.write(Buffer.from(process.argv[1],'base64'));";
+function deferred<T>() { let resolve!:(value:T)=>void;const promise=new Promise<T>(r=>{resolve=r;});return {promise,resolve}; }
+export async function startProducerIpc(input:{owner:Owner;permit:ResourcePermit;binding:ProducerIpcBinding;host:ProducerIpcHost;signal:AbortSignal;timeoutMs:number}):Promise<ProducerIpcRun> {
+  ipcShape(input,["owner","permit","binding","host","signal","timeoutMs"]);
+  const binding=producerIpcBinding(input.binding), host=hosts.get(input.host);
+  if(!host || host.used || host.owner!==input.owner || producerIpcBindingDigest(input.host.binding)!==producerIpcBindingDigest(binding))throw Error("original unused host with exact owner/charter/invocation required");
+  if(!(input.signal instanceof AbortSignal) || !Number.isSafeInteger(input.timeoutMs) || input.timeoutMs<50 || input.timeoutMs>LIMITS.maxElapsedMs)throw new TypeError("bounded original cancellation/deadline required");
+  const permit=claimResourcePermit(input.owner,input.permit,binding.budgetDigest,producerIpcDemand(binding));host.used=true;
+  const caller=input.signal, deadline=performance.now()+input.timeoutMs, abort=new AbortController(), signal=AbortSignal.any([caller,abort.signal]);
+  const started=deferred<"spawned"|"not-spawned">(), readiness=deferred<"frame-ready"|"not-ready">(), result=deferred<ProducerIpcSnapshot>();
+  let outcome:ProducerIpcSnapshot["outcome"]="pending", reason:ProducerIpcSnapshot["reason"]=null, child:ChildRunResult|null=null;
+  let childState:ProducerIpcSnapshot["childState"]="pending",hostState:ProducerIpcSnapshot["hostState"]="not-called",settlement:ProducerIpcSnapshot["settlement"]="pending";
+  let references:Readonly<ProducerIpcReferences>|null=null,frameSha256:string|null=null,frames:Readable|undefined,timer:NodeJS.Timeout|undefined;
+  const inspect=():ProducerIpcSnapshot=>Object.freeze({binding,outcome,reason,child:child?Object.freeze({...child}):null,childState,hostState,frameSha256,references,settlement,acceptance:"not-assessed"});
+  const latch=(next:Exclude<ProducerIpcSnapshot["outcome"],"pending">,why:ProducerIpcSnapshot["reason"])=>{
+    if(outcome!=="pending")return;outcome=next;reason=why;clearTimeout(timer);caller.removeEventListener("abort",cancel);result.resolve(inspect());
+  };
+  const cancel=()=>{latch("cancelled","CANCELLED");abort.abort();frames?.destroy();};
+  const expire=()=>{latch("timed-out","DEADLINE");abort.abort();frames?.destroy();};
+  const current=()=>{if(outcome!=="pending")return false;if(caller.aborted)cancel();else if(performance.now()>=deadline)expire();return outcome==="pending";};
+  timer=setTimeout(expire,input.timeoutMs);caller.addEventListener("abort",cancel,{once:true});if(caller.aborted)cancel();
+  let stdout=Buffer.alloc(0),overflow=false,eof=false,spawned=false;
+  const childPromise=(async()=>{
+    try {await permit.admission;} catch {latch("failed","ADMISSION_FAILED");return null;}
+    if(!current())return null;
+    try {
+      const runtime=await digestRuntime();
+      if(!current())return null;
+      return Object.freeze(await runChild({command:"/usr/bin/bwrap",args:digestNamespaceArgs(runtime,WORKER,[producerIpcFrame(binding).toString("base64")]),env:{},cwd:"/",signal,
+        timeoutMs:LIMITS.childMs,killGraceMs:LIMITS.graceMs,hardDeadlineAt:Date.now()+LIMITS.childMs+500,maxOutputBytes:LIMITS.frameBytes,
+        onSpawn:()=>{spawned=true;started.resolve("spawned");},onStreamEnd:s=>{if(s==="stdout")eof=true;},
+        onObservation:(s,b)=>{if(s!=="stdout"||overflow)return;if(stdout.length+b.length>LIMITS.frameBytes){overflow=true;return;}stdout=Buffer.concat([stdout,Buffer.from(b)]);}}));
+    } catch {latch("failed","RUNTIME_FAILED");return null;}
+  })();
+  const completion=(async()=>{
+    child=await childPromise;childState=spawned?(child?"settled":"unknown"):"not-spawned";started.resolve("not-spawned");
+    if(childState==="unknown"){readiness.resolve("not-ready");settlement="failed-or-unknown";return inspect();}
+    if(current()) {
+      if(!child || child.code!==0 || child.aborted || child.timedOut || child.truncated || child.spawnError || child.signal)latch("failed","CHILD_FAILED");
+      else if(!eof || overflow || !stdout.equals(producerIpcFrame(binding)))latch("failed","FRAME_INVALID");
+      else {
+        frameSha256=createHash("sha256").update(stdout).digest("hex");readiness.resolve("frame-ready");
+        // Replay ONLY exact bytes from the original completed pipe; never reconstruct a host-authored frame.
+        frames=Readable.from([Buffer.from(stdout)]);
+        try {
+          if(current()) {
+            hostState="pending";references=ipcReferences(await host.exchange(frames,Object.freeze({binding,signal})));
+            if(!frames.readableEnded)throw Error("original host frame not consumed");
+            hostState="acknowledged";if(current())latch("completed",null);
+          }
+        }
+        catch {hostState="failed";if(current())latch("failed","HOST_FAILED");}
+        finally {frames.destroy();}
+      }
+    }
+    readiness.resolve("not-ready");
+    // Observation timeout never reaches here until the ORIGINAL child and invoked host have acknowledged.
+    const terminal=inspect().outcome;
+    try {await permit.settle(terminal==="completed"?"completed":terminal==="cancelled"?"cancelled":"failed");settlement="acknowledged";}
+    catch {settlement="failed-or-unknown";}
+    clearTimeout(timer);caller.removeEventListener("abort",cancel);return inspect();
+  })();
+  return Object.freeze({started:started.promise,readiness:readiness.promise,child:childPromise,result:result.promise,completion,inspect});
+}

package/src/resource-budget.ts

@@ -0,0 +1,349 @@
+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))); }