pi-daddy 0.22.0 → 0.23.0

package/src/experiment.ts

@@ -0,0 +1,231 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { MAX_CHILDREN_PER_CALL } from "./fanout.ts";
+import { openResourceBudget, resourceBindingDigest, type ExperimentBudgetBinding, type BudgetSnapshot } from "./resource-budget.ts";
+import { isDigestProfile, reserveDigestProfileBatch, type DigestProfile, type ReservedDigestRun } from "./effect-profile.ts";
+import { readIntentWork, resolveIntent } from "./intent-application.ts";
+import { freezeWork } from "./work-ledger-json.ts";
+import { byteHash, cloneExperiment, experimentAuthority, experimentCancellation, experimentCancellationDigest, experimentCharter, experimentCharterDigest,
+  type ExperimentAuthority, type ExperimentCancellation, type ExperimentCharter } from "./experiment-contract.ts";
+import { createExperimentStore, experimentBindingDigest, experimentStore, ownedDirectory, readExperimentFile, writeExperimentFile, type ExperimentBinding } from "./experiment-store.ts";
+import { evaluateOrder, factoryDecision, factoryDecisionDigest, type FactoryDecision } from "./order-schedule.ts";
+import { replayExperiment, type VariantRecord } from "./experiment-state.ts";
+export { experimentCharterDigest, experimentCancellationDigest, parseExperimentCharter, type ExperimentCharter, type ExperimentAuthority, type ExperimentCancellation } from "./experiment-contract.ts";
+export { experimentBindingDigest, type ExperimentBinding } from "./experiment-store.ts";
+export interface ExperimentView {
+  version: "experiment-view-v1"; experimentId: string; mode: ExperimentCharter["mode"]; variants: readonly VariantRecord[];
+  budget: Readonly<BudgetSnapshot> | null; cancellations: readonly { request: ExperimentCancellation; outcome: "requested-or-unknown" | "observed-cancelled" | "finished-without-cancel" }[];
+  control: "not-assessed" | "failed" | "unknown"; diagnostics: readonly string[]; acceptance: "not-assessed"; configuration: { model: null; effort: null; skills: null }; freshness: "snapshot-unknown";
+}
+function approved(a: ExperimentAuthority | null, b: ExperimentBudgetBinding, c: ExperimentCharter) {
+  if (!a || a.authorityDigest !== b.authorityDigest || !a.charterDigests.includes(experimentCharterDigest(c))) throw new Error("independent exact experiment authority unavailable");
+}
+async function common(c: ExperimentCharter, bytes: Uint8Array) {
+  if (bytes.length !== c.common.bytes || byteHash(bytes) !== c.common.sha256) throw new Error("common input drift");
+  if (c.common.work) {
+    const text = await readIntentWork(c.common.work);
+    if (byteHash(text) !== c.common.workTextDigest) throw new Error("common P01 work drift");
+    resolveIntent(text, c.common.work.selection, c.common.work.priorities);
+  }
+}
+export async function createExperiment(input: { directory: string; budget: ExperimentBudgetBinding; charter: ExperimentCharter; bytes: Uint8Array; authority: ExperimentAuthority | null }): Promise<ExperimentBinding> {
+  if (!(input.bytes instanceof Uint8Array) || input.bytes.length > 16384) throw new TypeError("bounded common bytes required");
+  const c = experimentCharter(input.charter), budget = openResourceBudget(input.budget).binding, a = experimentAuthority(input.authority), bytes = Buffer.from(input.bytes), directory = input.directory;
+  if (budget.version !== "4.0" || resourceBindingDigest(budget) !== c.budgetDigest) throw new Error("explicit experiment budget required");
+  approved(a, budget, c); await common(c, bytes); await openResourceBudget(budget).inspect();
+  return createExperimentStore(directory, budget, c, bytes);
+}
+export interface ExperimentRun { readonly primary: Promise<VariantRecord>; readonly completion: Promise<ExperimentView>; readonly boundary: Promise<ExperimentView>; readonly started: readonly Promise<"spawned" | "settled-without-spawn">[] }
+const controllers = new WeakSet<object>();
+export const isExperimentController = (value: unknown): value is ReturnType<typeof openExperiment> => typeof value === "object" && value !== null && controllers.has(value);
+/** A separate owned controller, not delegate_all and not a model-facing launch/callback loader. */
+export function openExperiment(input: ExperimentBinding, hostAuthority: ExperimentAuthority | null) {
+  const store = experimentStore(input), b = store.binding, c = b.charter, a = experimentAuthority(hostAuthority), owner = randomUUID(), digest = experimentBindingDigest(b);
+  const budget = openResourceBudget(b.budget), handles = new Map<string, AbortController>();
+  let live: ExperimentRun | null = null, starting = false, wake: (() => void) | null = null, epoch = 0;
+  let fault = false, failureAcknowledged: boolean | null = null;
+  const notify = () => { epoch++; wake?.(); wake = null; };
+  const artifact = (id: string) => join(b.directory, "variant-" + byteHash(id), "result.json");
+  const load = async () => {
+    const data = await store.read(), state = replayExperiment(c, data.events);
+    if (state.cancellations.some(r => r.bindingDigest !== digest)) throw new Error("cancellation binding mismatch");
+    return state;
+  };
+  const append = (event: unknown) => store.transaction(async (events, write) => { replayExperiment(c, [...events, cloneExperiment(event) as Record<string, unknown>]); await write(event); });
+  const unknown = (): ExperimentView => ({ version: "experiment-view-v1", experimentId: c.experimentId, mode: c.mode,
+    variants: c.variants.map(v => ({ variantId: v.variantId, kind: v.kind, operation: v.operation, executionId: v.executionId, state: "unknown", artifactDigest: null, spawned: false })), budget: null, cancellations: [], control: "unknown", diagnostics: ["controller-or-storage-unknown", ...(fault ? ["controller-failure-observed"] : [])], acceptance: "not-assessed", configuration: { model: null, effort: null, skills: null }, freshness: "snapshot-unknown" });
+  const inspect = async (control = false): Promise<ExperimentView> => {
+    const state = await load(), diagnostics: string[] = [], accounting = await (control ? budget.controlSnapshot() : budget.inspect());
+    if (state.controllerFailed) diagnostics.push("controller-failure-record-observed");
+    if (fault) diagnostics.push("controller-failure-observed");
+    if (failureAcknowledged === false) diagnostics.push("controller-failure-recording-unacknowledged");
+    for (const v of state.variants) {
+      if (v.artifactDigest) {
+        try { await ownedDirectory(join(b.directory, "variant-" + byteHash(v.executionId))); if (byteHash(await readExperimentFile(artifact(v.executionId), 16384)) !== v.artifactDigest) throw new Error("artifact mismatch"); }
+        catch { diagnostics.push("artifact-unavailable:" + v.executionId); v.state = "unknown"; v.artifactDigest = null; }
+      } else if (state.claim && (!handles.has(v.executionId) || state.claim.owner !== owner)) v.state = "unknown";
+    }
+    return freezeWork({ version: "experiment-view-v1", experimentId: c.experimentId, mode: c.mode, variants: state.variants, budget: accounting,
+      cancellations: state.cancellations.map(request => { const v = state.variants.find(v => v.executionId === request.executionId)!; return { request,
+        outcome: v.state === "cancelled" ? "observed-cancelled" : v.artifactDigest ? "finished-without-cancel" : "requested-or-unknown" }; }),
+      control: state.controllerFailed || fault ? "failed" : "not-assessed", diagnostics, acceptance: "not-assessed", configuration: { model: null, effort: null, skills: null }, freshness: "snapshot-unknown" }) as ExperimentView;
+  };
+  const computeOrder = async (control = false) => {
+    if (!c.order) throw new Error("not an order controller");
+    const view = await inspect(control), state = await load(), digests = new Map<string,string|null>();
+    for (const v of view.variants) if (v.artifactDigest) {
+      try { const bytes=await readExperimentFile(artifact(v.executionId),16384); if(byteHash(bytes)!==v.artifactDigest)throw new Error("changed artifact");const result=JSON.parse(bytes.toString());
+        if(result.attemptId!==v.executionId)throw new Error("wrong execution artifact"); digests.set(v.executionId, typeof result.digest==="string"&&result.output?.code===0&&!result.output.aborted&&!result.output.timedOut&&!result.output.spawnError?result.digest:null);
+      } catch { /* frozen view: use a detached unknown row below */ digests.set(v.executionId,"unavailable"); }
+    }
+    const variants=view.variants.map(v=>digests.get(v.executionId)==="unavailable"?{...v,state:"unknown" as const}:v);
+    return { view, nodes:evaluateOrder(c.order,variants,digests,state.decisions).map(n => view.control === "not-assessed" ? n : {...n, action:"stakeholder" as const}), superseded:state.superseded };
+  };
+  const orderView = () => computeOrder(false);
+  const api = Object.freeze({ binding: b, inspect: () => inspect(false), reconcile: () => inspect(false), orderView,
+    async decideOrder(input: FactoryDecision, authority: { id: string; digests: readonly string[] } | null) {
+      const request=factoryDecision(input); approved(a,b.budget,c);
+      if(!authority||authority.id!==request.authorityId||!authority.digests.includes(factoryDecisionDigest(request))||request.bindingDigest!==digest)throw new Error("independent decision authority required");
+      const fresh=await store.transaction(async(events,write)=>{
+        const state=replayExperiment(c,events),old=state.decisions.find(d=>d.requestId===request.requestId);
+        if(old){if(factoryDecisionDigest(old)!==factoryDecisionDigest(request))throw new Error("conflicting decision ID");return false;}
+        await common(c,await readExperimentFile(join(b.directory,"common.bin"),16384));
+        const row=(await computeOrder(true)).nodes.find(n=>n.nodeId===request.nodeId);
+        if(!row||row.state!=="decision-required"||row.evidenceDigest!==request.evidenceDigest)throw new Error("stale decision or unavailable evidence");
+        replayExperiment(c,[...events,{type:"order-decision",request}]);await write({type:"order-decision",request});return true;
+      });if(fresh)notify();return orderView();
+    },
+    async readArtifact(executionId: string): Promise<Uint8Array> {
+      const row = (await load()).variants.find(v => v.executionId === executionId);
+      if (!row?.artifactDigest) throw new Error("exact byte-backed artifact unavailable");
+      await ownedDirectory(join(b.directory, "variant-" + byteHash(executionId)));
+      const bytes = await readExperimentFile(artifact(executionId), 16384);
+      if (byteHash(bytes) !== row.artifactDigest) throw new Error("artifact digest mismatch");
+      return Uint8Array.from(bytes);
+    },
+    async cancel(input: ExperimentCancellation, hostAuthority?: ExperimentAuthority | null): Promise<ExperimentView> {
+      const request = experimentCancellation(input), cancellationAuthority = hostAuthority === undefined ? a : experimentAuthority(hostAuthority);
+      approved(cancellationAuthority, b.budget, c);
+      if (request.bindingDigest !== digest || !c.variants.some(v => v.executionId === request.executionId) || !cancellationAuthority!.cancellationDigests.includes(experimentCancellationDigest(request))) throw new Error("independent exact cancellation authority unavailable");
+      const fresh = await store.transaction(async (events, write) => {
+        const state = replayExperiment(c, events), old = state.cancellations.find(r => r.requestId === request.requestId);
+        if (old) { if (experimentCancellationDigest(old) !== experimentCancellationDigest(request)) throw new Error("conflicting cancellation ID"); return false; }
+        replayExperiment(c, [...events, { type: "cancel", request }]); await write({ type: "cancel", request }); return true;
+      });
+      if (fresh) handles.get(request.executionId)?.abort("operator-cancellation"); // Only an original live handle; no PID/idle/pane lookup.
+      // Cancellation is a control operation: serialize its readback with controller appends
+      // and original budget settlement. Public inspect/reconcile remain unlocked, fallible reads.
+      return store.transaction(async () => inspect(true));
+    },
+    async start(profile: DigestProfile): Promise<ExperimentRun> {
+      approved(a, b.budget, c);
+      if (!isDigestProfile(profile) || profile.bindingDigest !== c.budgetDigest) throw new Error("profile budget mismatch");
+      if (live) return live;
+      if (starting) throw new Error("controller start pending; inspect, do not retry effects"); starting = true;
+      let reserved: readonly ReservedDigestRun[] = [];
+      try {
+        const bytes = await readExperimentFile(join(b.directory, "common.bin"), 16384); await common(c, bytes);
+        const claimed = await store.transaction(async (events, write) => {
+          const state = replayExperiment(c, events); if (state.superseded) throw new Error("order migrated; no old dispatch"); if (state.claim) return false;
+          await write({ type: "claim", owner, deadlineAt: Date.now() + c.deadlineMs }); return true;
+        });
+        if (!claimed) {
+          const view = await inspect(); return Object.freeze({ primary: Promise.resolve(view.variants[0]), completion: Promise.resolve(view), boundary: Promise.resolve(view), started: [] });
+        }
+        reserved = await reserveDigestProfileBatch(profile, c.variants.map(v => ({ attempt: { attemptId: v.executionId, orderId: c.orderId, experimentId: c.experimentId, kind: v.kind, parentAttemptId: v.parentExecutionId }, bytes: Buffer.concat([bytes, Buffer.from(v.suffixBase64, "base64")]), operation: v.operation })));
+        await append({ type: "admitted" });
+        const state = await load(), used = new Set<number>();
+        let resolvePrimary!: (value: VariantRecord) => void;
+        const primary = { promise: new Promise<VariantRecord>(resolve => { resolvePrimary = resolve; }), resolve: (value: VariantRecord) => resolvePrimary(value) };
+        for (const v of c.variants) { const handle = new AbortController(); handles.set(v.executionId, handle); if (state.cancellations.some(r => r.executionId === v.executionId)) handle.abort("operator-cancellation"); }
+        // Close the read-to-handle-install race without adding a control/observation transport.
+        for (const request of (await load()).cancellations) handles.get(request.executionId)?.abort("operator-cancellation");
+        const abort = (reason = "controller-failure") => { handles.forEach(h => h.abort(reason)); notify(); };
+        const timer = setTimeout(() => abort("deadline"), Math.max(1, state.claim!.deadlineAt - Date.now()));
+        const settled = c.variants.map(() => {
+          let resolve!: (success: boolean) => void;
+          return { promise: new Promise<boolean>(done => { resolve = done; }), done: (success: boolean) => resolve(success) };
+        });
+        const one = async (i: number) => {
+          const v = c.variants[i]; let success = false, launched = false, primaryResult: VariantRecord | null = null;
+          try {
+            if (!c.order && v.kind === "retry" && await settled[c.variants.findIndex(p => p.executionId === v.parentExecutionId)].promise) handles.get(v.executionId)!.abort("retry-not-needed");
+            await append({ type: "dispatch", executionId: v.executionId });
+            used.add(i);
+            launched = true;
+            const running = reserved[i].run(handles.get(v.executionId)!.signal);
+            // Consume both promises even on bookkeeping failure. No untracked rejection or worker.
+            const observed = reserved[i].started.then(async value => { if (value === "spawned") await append({ type: "spawn", executionId: v.executionId }); });
+            const [result, observation] = await Promise.allSettled([running, observed]);
+            if (result.status === "rejected" || observation.status === "rejected") throw new Error("runtime/accounting/observation unknown");
+            const data = Buffer.from(JSON.stringify(result.value) + "\n"), out = result.value.output;
+            const cancelled = out.aborted && (Boolean(out.signal) || await reserved[i].started === "settled-without-spawn");
+            await ownedDirectory(join(b.directory, "variant-" + byteHash(v.executionId))); await writeExperimentFile(artifact(v.executionId), data);
+            const state = out.timedOut || cancelled && handles.get(v.executionId)?.signal.reason === "deadline" ? "timed-out" : cancelled ? "cancelled" : result.value.digest ? "completed" : "failed";
+            // Original worker/artifact outcome, NOT a successful controller acknowledgement.
+            primaryResult = {variantId:v.variantId,kind:v.kind,operation:v.operation,executionId:v.executionId,state,artifactDigest:byteHash(data),spawned:await reserved[i].started === "spawned"};
+            await append({ type: "result", executionId: v.executionId, artifactDigest: byteHash(data), state });
+            success = Boolean(result.value.digest);
+          } catch {
+            fault = true; abort();
+            // Failed dispatch acknowledgement still consumes the ORIGINAL unused permit without
+            // spawning and resolves started, including when the control journal stays locked.
+            if (!launched) { used.add(i); await reserved[i].run(AbortSignal.abort()).catch(() => {}); }
+          }
+          finally {
+            settled[i].done(success); handles.delete(v.executionId);
+            if (i === 0) primary.resolve(primaryResult ? freezeWork(primaryResult) : unknown().variants[0]);
+          }
+        };
+        let resolveBoundary!: (view: ExperimentView) => void;
+        const boundary = new Promise<ExperimentView>(resolve => { resolveBoundary = resolve; });
+        const orderRunning = new Set<Promise<void>>();
+        const completion = (async () => {
+          try {
+            if(c.order) {
+              const running=orderRunning;
+              while(true) {
+                const before=epoch; await common(c,await readExperimentFile(join(b.directory,"common.bin"),16384));
+                const status=await store.transaction(async()=>computeOrder(true));
+                if(fault || Date.now()>=state.claim!.deadlineAt) { abort("deadline"); await Promise.all(running); break; }
+                const eligible=status.nodes.filter(n=>n.action==="dispatch").map(n=>c.variants.findIndex(v=>v.executionId===n.executionId)).filter(i=>!used.has(i));
+                for(const i of eligible.slice(0,MAX_CHILDREN_PER_CALL-running.size)) {
+                  used.add(i); const task=one(i); running.add(task); void task.then(()=>{running.delete(task);notify();},()=>{running.delete(task);notify();});
+                }
+                if(running.size){await Promise.race(running);continue;}
+                if(!status.nodes.some(n=>n.state==="decision-required"))break;
+                resolveBoundary(status.view);
+                if(epoch!==before)continue;
+                await new Promise<void>(resolve=>{wake=resolve;});
+              }
+            } else for (let i = 0; i < c.variants.length; i += MAX_CHILDREN_PER_CALL) {
+              await common(c, await readExperimentFile(join(b.directory, "common.bin"), 16384));
+              await Promise.all(c.variants.slice(i, i + MAX_CHILDREN_PER_CALL).map((_, n) => one(i + n)));
+              if (fault) break;
+            }
+          } catch { fault = true; abort(); }
+          finally {
+            clearTimeout(timer); abort(); await Promise.allSettled(orderRunning);
+            for (let i = 0; i < reserved.length; i++) if (!used.has(i)) {
+              if(c.order) { handles.get(c.variants[i].executionId)?.abort("unused-order-reservation"); await one(i); }
+              else { used.add(i); await reserved[i].run(AbortSignal.abort()).catch(() => { fault = true; }); }
+            }
+            handles.clear();
+            if (fault) {
+              try { await append({ type: "controller-unknown" }); failureAcknowledged = true; }
+              catch { failureAcknowledged = false; } // No fabricated durable acknowledgement.
+            }
+          }
+          const view = await inspect().catch(unknown); primary.resolve(view.variants[0]); resolveBoundary(view); return view;
+        })();
+        live = Object.freeze({ primary: primary.promise, completion, boundary: c.order ? boundary : completion, started: Object.freeze(reserved.map(r => r.started)) }); return live;
+      } catch (error) {
+        fault = true;
+        for (const run of reserved) await run.run(AbortSignal.abort()).catch(() => {});
+        const state = await load().catch(() => null); if (state?.claim?.owner === owner) await append({ type: "controller-unknown" }).catch(() => {});
+        throw error;
+      } finally { starting = false; }
+    },
+  });
+  controllers.add(api); return api;
+}

package/src/factory-contract.ts

@@ -0,0 +1,47 @@
+import { cloneExperiment, closed, experimentHash, experimentCharter, byteHash, type ExperimentCharter } from "./experiment-contract.ts";
+import { resourceBindingDigest, type ExperimentBudgetBinding } from "./resource-budget.ts";
+import { workIntentBinding, readIntentWork, resolveIntent } from "./intent-application.ts";
+import type { WorkIntentBinding } from "./intent-control.ts";
+import type { WorkFrozen, RevisionRef } from "./work-ledger-types.ts";
+import type { AdoptionAuthority, AdoptionFacts, AdoptionBinding, AdoptionReceipt } from "./vendor/adoption.ts";
+import { parseWorkJson } from "./work-ledger-json.ts";
+import { orderSchedule } from "./order-schedule.ts";
+export { factoryDecisionDigest, type FactoryDecision } from "./order-schedule.ts";
+export interface FixedPolicy {version:"fixed-policy-v1";suffixBase64:string;acceptancePolicyDigest:string;grants:readonly string[];effects:readonly "fixed-digest"[];model:null;effort:null;skills:readonly string[]}
+export const fixedPolicyDigest=(p:FixedPolicy)=>experimentHash(fixedPolicy(p));
+const hex=(x:unknown)=>typeof x==="string"&&/^[a-f0-9]{64}$/.test(x);
+export function fixedPolicy(value:FixedPolicy):FixedPolicy{const p=cloneExperiment(value);closed(p,["version","suffixBase64","acceptancePolicyDigest","grants","effects","model","effort","skills"]);
+  if(p.version!=="fixed-policy-v1"||!hex(p.acceptancePolicyDigest)||typeof p.suffixBase64!=="string"||p.suffixBase64.length>2048||Buffer.from(p.suffixBase64,"base64").toString("base64")!==p.suffixBase64||JSON.stringify(p.grants)!=="[]"||JSON.stringify(p.effects)!=='["fixed-digest"]'||p.model!==null||p.effort!==null||JSON.stringify(p.skills)!=="[]")throw new Error("unsupported policy or grant expansion");return p;}
+export interface FactoryOrderCharter {version:"factory-order-v1";orderId:string;directory:string;budget:ExperimentBudgetBinding;work:WorkFrozen<WorkIntentBinding>;workTextDigest:string;scopeDigest:string;commonBase64:string;deadlineMs:number;pin:{revision:number;candidateDigest:string};nodes:readonly {nodeId:string;obligation:RevisionRef;dependencies:readonly string[];attempts:readonly {executionId:string;suffixBase64:string;operation:"digest"|"hold"}[];expectedDigest:string;decision:{decisionId:string;authorityId:string}|null}[]}
+/** Digest of the entire bounded proposal; validation at application is separate. */
+export const factoryOrderDigest=(c:FactoryOrderCharter)=>experimentHash(c);
+export interface FactoryAuthority {id:string;orderDigests:readonly string[];decisionDigests:readonly string[];cancellationDigests?:readonly string[];activationDigests:readonly string[];migrationDigests:readonly string[];adoption:AdoptionAuthority|null;facts:readonly {bindingId:string;facts:AdoptionFacts}[]}
+export function factoryAuthority(value:FactoryAuthority|null):FactoryAuthority|null{if(value===null)return null;const a=cloneExperiment(value);closed(a,["id","orderDigests","decisionDigests","activationDigests","migrationDigests","adoption","facts",...(Object.hasOwn(a,"cancellationDigests")?["cancellationDigests"]:[])]);
+  if(typeof a.id!=="string"||!/^[a-zA-Z0-9:_-]{1,128}$/.test(a.id)||[a.orderDigests,a.decisionDigests,a.activationDigests,a.migrationDigests,...(Object.hasOwn(a,"cancellationDigests")?[a.cancellationDigests!]:[])].some(xs=>!Array.isArray(xs)||xs.length>128||xs.some(x=>!hex(x)))||!Array.isArray(a.facts)||a.facts.length>128)throw new Error("invalid independent factory authority");
+  const ids=new Set<string>();for(const f of a.facts as FactoryAuthority["facts"]){closed(f,["bindingId","facts"]);if(!hex(f.bindingId)||ids.has(f.bindingId))throw new Error("ambiguous independent facts");ids.add(f.bindingId);}
+  if(a.adoption!==null){closed(a.adoption,["id","adoptions","rollbacks"]);if(a.adoption.id!==a.id)throw new Error("independent authority identity mismatch");}
+  return a;}
+export function requireFactoryAuthority(a:FactoryAuthority|null,id:string){if(!a||a.id!==id)throw new Error("independent factory authority required");return a;}
+export interface ActivationRequest {version:"factory-activation-v1";requestId:string;expectedRevision:number;expectedCandidateDigest:string;candidate:FixedPolicy;binding:AdoptionBinding;receipt:AdoptionReceipt}
+export const activationRequestDigest=(r:ActivationRequest)=>experimentHash(r);
+export function factoryCharter(value:FactoryOrderCharter):FactoryOrderCharter{
+  const c=cloneExperiment(value);closed(c,["version","orderId","directory","budget","work","workTextDigest","scopeDigest","commonBase64","deadlineMs","pin","nodes"]);closed(c.pin,["revision","candidateDigest"]);
+  if(c.version!=="factory-order-v1"||!/^[a-zA-Z0-9:_-]{1,128}$/.test(c.orderId)||typeof c.directory!=="string"||!hex(c.workTextDigest)||!hex(c.scopeDigest)||!hex(c.pin.candidateDigest)||!Number.isSafeInteger(c.pin.revision)||c.pin.revision<0||typeof c.commonBase64!=="string"||c.commonBase64.length>22000||Buffer.from(c.commonBase64,"base64").toString("base64")!==c.commonBase64||Buffer.byteLength(JSON.stringify(c))>48000||c.budget.version!=="4.0")throw new Error("invalid bounded factory charter");
+  c.work=workIntentBinding(JSON.parse(JSON.stringify(c.work)));if(c.scopeDigest!==experimentHash(c.work.selection.snapshot))throw new Error("changed scope");
+  if(!Array.isArray(c.nodes)||!c.nodes.length||c.nodes.length>16)throw new Error("bounded nodes required");
+  for(const n of c.nodes as FactoryOrderCharter["nodes"]){closed(n,["nodeId","obligation","dependencies","attempts","expectedDigest","decision"]);if(!Array.isArray(n.attempts)||!n.attempts.length||n.attempts.length>3)throw new Error("bounded recovery required");for(const a of n.attempts){closed(a,["executionId","suffixBase64","operation"]);if(typeof a.suffixBase64!=="string"||a.suffixBase64.length>22000||Buffer.from(a.suffixBase64,"base64").toString("base64")!==a.suffixBase64)throw new Error("invalid attempt byte suffix");}}
+  orderSchedule({version:"order-schedule-v1",policyDigest:c.pin.candidateDigest,nodes:(c.nodes as FactoryOrderCharter["nodes"]).map(n=>({nodeId:n.nodeId,dependencies:n.dependencies,executions:n.attempts.map(a=>a.executionId),expectedDigest:n.expectedDigest,decision:n.decision}))},(c.nodes as FactoryOrderCharter["nodes"]).flatMap(n=>n.attempts.map(a=>a.executionId)));
+  return c;
+}
+export const parseFactoryOrder = (text:string) => factoryCharter(parseWorkJson(text) as unknown as FactoryOrderCharter);
+export async function compileFactoryOrder(value:FactoryOrderCharter,candidate:FixedPolicy):Promise<ExperimentCharter>{
+  const c=factoryCharter(value),p=fixedPolicy(candidate),text=await readIntentWork(c.work);
+  if(byteHash(text)!==c.workTextDigest||fixedPolicyDigest(p)!==c.pin.candidateDigest)throw new Error("work or candidate drift");
+  const intent=resolveIntent(text,c.work.selection,c.work.priorities),refs=intent.snapshot!.bindings.map(b=>experimentHash(b.obligation)).sort();
+  if(JSON.stringify(refs)!==JSON.stringify(c.nodes.map(n=>experimentHash(n.obligation)).sort()))throw new Error("order must cover exact selected obligations");
+  for(const n of c.nodes){const rev=intent.revisions.find(r=>experimentHash({kind:r.kind,id:r.id,revision:r.revision,digest:r.digest})===experimentHash(n.obligation));if(!rev||!rev.permittedEffects.includes("read"))throw new Error("unsupported obligation effects");for(const dep of rev.dependencies.filter(d=>d.kind==="obligation")){const parent=c.nodes.find(m=>experimentHash(m.obligation)===experimentHash(dep));if(!parent||!n.dependencies.includes(parent.nodeId))throw new Error("required intent dependency omitted");}}
+  const bytes=Buffer.from(c.commonBase64,"base64");
+  return experimentCharter({version:"fixed-experiment-v2",experimentId:c.orderId,orderId:c.orderId,budgetDigest:resourceBindingDigest(c.budget),profile:"linux-bwrap-digest-v1",common:{bytes:bytes.length,sha256:byteHash(bytes),work:c.work,workTextDigest:c.workTextDigest},mode:"bounded-waves",deadlineMs:c.deadlineMs,
+    variants:c.nodes.flatMap(n=>n.attempts.map((a,i)=>({variantId:a.executionId,executionId:a.executionId,kind:i?"retry" as const:"primary" as const,parentExecutionId:i?n.attempts[i-1].executionId:null,suffixBase64:Buffer.concat([Buffer.from(p.suffixBase64,"base64"),Buffer.from(a.suffixBase64,"base64")]).toString("base64"),operation:a.operation,configuration:{model:null,effort:null,skills:null}}))),
+    order:{version:"order-schedule-v1",policyDigest:p.acceptancePolicyDigest,nodes:c.nodes.map(n=>({nodeId:n.nodeId,dependencies:n.dependencies,executions:n.attempts.map(a=>a.executionId),expectedDigest:n.expectedDigest,decision:n.decision}))}});
+}

package/src/factory-migration.ts

@@ -0,0 +1,29 @@
+import { cloneExperiment, closed, experimentHash } from "./experiment-contract.ts";
+import { experimentStore } from "./experiment-store.ts";
+import { replayExperiment } from "./experiment-state.ts";
+import { factoryAuthority, factoryCharter, factoryOrderDigest, requireFactoryAuthority, type FactoryAuthority, type FactoryOrderCharter } from "./factory-contract.ts";
+import { factoryRegistryStore, replayRegistry, type FactoryRegistryBinding } from "./factory-registry.ts";
+import { createFactoryOrder } from "./factory-order.ts";
+export interface FactoryMigration {version:"factory-migration-v1";requestId:string;sourceOrderId:string;successor:FactoryOrderCharter}
+export const factoryMigrationDigest=(request:FactoryMigration)=>experimentHash(request);
+/** Only unstarted controllers can be superseded. An original claim is a refusal, never an idle/PID guess. */
+export async function migrateFactoryOrder(inputRegistry:FactoryRegistryBinding,input:FactoryMigration,host:FactoryAuthority|null){
+  const b=factoryRegistryStore(inputRegistry).binding;
+  const r=cloneExperiment(input),a=requireFactoryAuthority(factoryAuthority(host),b.initial.authorityId);closed(r,["version","requestId","sourceOrderId","successor"]);
+  if(r.version!=="factory-migration-v1"||!/^[a-zA-Z0-9:_-]{1,128}$/.test(r.requestId)||r.sourceOrderId===r.successor.orderId||!a.migrationDigests.includes(factoryMigrationDigest(r)))throw new Error("independent migration authority required");
+  r.successor=factoryCharter(r.successor);if(!a.orderDigests.includes(factoryOrderDigest(r.successor)))throw new Error("successor order authority required");
+  const store=factoryRegistryStore(b);let fresh=false;
+  await store.transaction(async(events,append)=>{const s=replayRegistry(b,events),old=s.changes.get(r.requestId);if(old){if(old!==factoryMigrationDigest(r))throw new Error("conflicting migration ID");return;}
+    const source=s.orders.get(r.sourceOrderId);if(!source?.binding||!a.orderDigests.includes(factoryOrderDigest(source.charter)))throw new Error("source order authority unavailable");
+    if(r.successor.scopeDigest!==b.initial.scopeDigest||r.successor.pin.revision!==s.revision||r.successor.pin.candidateDigest!==s.candidateDigest||s.orders.has(r.successor.orderId))throw new Error("stale migration target");
+    const e={type:"migration-request",requestId:r.requestId,sourceOrderId:r.sourceOrderId,targetOrderId:r.successor.orderId,requestDigest:factoryMigrationDigest(r)};replayRegistry(b,[...events,e]);await append(e);fresh=true;
+  });
+  if(fresh){const s=replayRegistry(b,(await store.read()).events),source=s.orders.get(r.sourceOrderId)!,binding=source.binding!,old=experimentStore(binding);
+    const applied=await old.transaction(async(events,append)=>{const state=replayExperiment(binding.charter,events);if(state.claim||state.superseded)return false;
+      const e={type:"order-migrated",requestId:r.requestId,successorDigest:factoryOrderDigest(r.successor)};replayExperiment(binding.charter,[...events,e]);await append(e);return true;});
+    if(applied)await createFactoryOrder(b,r.successor,a);
+    await store.transaction(async(events,append)=>{const e={type:"migration-receipt",requestId:r.requestId,application:applied?"applied":"refused-active",renewedObligations:applied?source.charter.nodes.map(n=>n.obligation):[]};replayRegistry(b,[...events,e]);await append(e);});
+  }
+  const m=replayRegistry(b,(await store.read()).events).migrations.get(r.requestId)!;
+  return {...m,requestId:r.requestId,grantExpansion:false,acceptanceTransfer:"none" as const};
+}

package/src/factory-order.ts

@@ -0,0 +1,56 @@
+import { byteHash, cloneExperiment, experimentCharterDigest, experimentHash } from "./experiment-contract.ts";
+import { createExperiment, openExperiment, type ExperimentView } from "./experiment.ts";
+import { experimentBindingDigest, experimentStore } from "./experiment-store.ts";
+import { readIntentWork } from "./intent-application.ts";
+import { freezeWork } from "./work-ledger-json.ts";
+import { compileFactoryOrder, factoryAuthority, factoryCharter, factoryOrderDigest, fixedPolicyDigest, requireFactoryAuthority, type FactoryOrderCharter, type FactoryAuthority } from "./factory-contract.ts";
+import { factoryRegistryStore, replayRegistry, validateActivePolicy, type FactoryRegistryBinding, type PinnedOrder } from "./factory-registry.ts";
+import type { ExperimentCancellation } from "./experiment-contract.ts";
+import type { FactoryDecision } from "./order-schedule.ts";
+import type { DigestProfile } from "./effect-profile.ts";
+export { migrateFactoryOrder, factoryMigrationDigest, type FactoryMigration } from "./factory-migration.ts";
+export { createFactoryRegistry, openFactoryRegistry, type FactoryRegistryBinding } from "./factory-registry.ts";
+export { parseFactoryOrder, factoryOrderDigest, fixedPolicyDigest, factoryDecisionDigest, activationRequestDigest, type FactoryOrderCharter, type FactoryAuthority, type FixedPolicy, type ActivationRequest } from "./factory-contract.ts";
+function lowerAuthority(p:PinnedOrder,a:FactoryAuthority|null){return a?.orderDigests.includes(factoryOrderDigest(p.charter))?{authorityDigest:p.charter.budget.authorityDigest,charterDigests:[p.compiledDigest],cancellationDigests:a.cancellationDigests??[]}:null;}
+export async function createFactoryOrder(inputRegistry:FactoryRegistryBinding,input:FactoryOrderCharter,host:FactoryAuthority|null){
+  const registry=factoryRegistryStore(inputRegistry).binding;
+  const c=factoryCharter(input),a=requireFactoryAuthority(factoryAuthority(host),registry.initial.authorityId),store=factoryRegistryStore(registry);
+  if(!a.orderDigests.includes(factoryOrderDigest(c)))throw new Error("independent order authority required");
+  let pinned!:PinnedOrder,existing=false;
+  await store.transaction(async(events,append)=>{
+    const state=replayRegistry(registry,events),old=state.orders.get(c.orderId);
+    if(old){if(factoryOrderDigest(old.charter)!==factoryOrderDigest(c))throw new Error("conflicting order identity");pinned=old;existing=true;return;}
+    if(c.scopeDigest!==registry.initial.scopeDigest)throw new Error("changed registry scope");
+    if(c.pin.revision!==state.revision||c.pin.candidateDigest!==state.candidateDigest)throw new Error("stale order policy pin");validateActivePolicy(state,a);
+    const compiled=await compileFactoryOrder(c,state.candidate),event={type:"order-pin",charter:c,candidate:state.candidate,compiledDigest:experimentCharterDigest(compiled),adoptionId:state.activation?.receipt.id??null};
+    replayRegistry(registry,[...events,event]);await append(event);pinned={charter:c,candidate:state.candidate,compiledDigest:event.compiledDigest,adoptionId:event.adoptionId,binding:null};
+  });
+  if(existing){if(!pinned.binding)throw new Error("order materialization pending-or-unknown; no retry effects");await experimentStore(pinned.binding).read();return pinned.binding;}
+  const charter=await compileFactoryOrder(c,pinned.candidate);
+  const binding=await createExperiment({directory:c.directory,budget:c.budget,charter,bytes:Buffer.from(c.commonBase64,"base64"),authority:lowerAuthority(pinned,a)});
+  await store.transaction(async(events,append)=>{const event={type:"order-materialized",orderId:c.orderId,binding};replayRegistry(registry,[...events,event]);await append(event);});return binding;
+}
+export async function openFactoryOrder(inputRegistry:FactoryRegistryBinding,orderId:string,host:FactoryAuthority|null){
+  const registry=factoryRegistryStore(inputRegistry).binding;
+  const a=factoryAuthority(host),store=factoryRegistryStore(registry),state=replayRegistry(registry,(await store.read()).events),p=state.orders.get(orderId);
+  if(!p?.binding)throw new Error("order materialization missing or unknown");
+  const binding=p.binding;await experimentStore(binding).read();
+  if(experimentCharterDigest(binding.charter)!==p.compiledDigest)throw new Error("compiled order identity mismatch");
+  const admitted=a?.id===registry.initial.authorityId?lowerAuthority(p,a):null,controller=openExperiment(binding,admitted);
+  const inspect=async()=>{
+    const result=await controller.orderView();let scope:"pinned"|"changed-or-unavailable"="pinned";
+    try{if(byteHash(await readIntentWork(p.charter.work))!==p.charter.workTextDigest)scope="changed-or-unavailable";}catch{scope="changed-or-unavailable";}
+    const nodes=result.superseded?result.nodes.map(n=>({...n,state:"superseded" as const,action:"none" as const})):scope==="pinned"?result.nodes:result.nodes.map(n=>({...n,state:"unknown" as const,action:"stakeholder" as const}));
+    return freezeWork({version:"factory-order-view-v1",orderId,scope,policyPin:{revision:p.charter.pin.revision,candidateDigest:fixedPolicyDigest(p.candidate),adoptionId:p.adoptionId},orderDigest:factoryOrderDigest(p.charter),nodes:nodes.map(n=>({...n,obligation:p.charter.nodes.find(o=>o.nodeId===n.nodeId)!.obligation})),resources:result.view.budget,control:result.view.control,diagnostics:result.view.diagnostics,superseded:result.superseded,dispatchAuthorized:Boolean(admitted)&&result.view.control==="not-assessed",modelTransport:"not-used-fixed-profile",acceptance:"not-assessed",freshness:"snapshot-unknown"});
+  };
+  const settledView = async (completed: ExperimentView) => { const view = await inspect().catch(() => freezeWork({version:"factory-order-view-v1",orderId,scope:"changed-or-unavailable",policyPin:{revision:p.charter.pin.revision,candidateDigest:fixedPolicyDigest(p.candidate),adoptionId:p.adoptionId},orderDigest:factoryOrderDigest(p.charter),nodes:p.charter.nodes.map(n=>({nodeId:n.nodeId,obligation:n.obligation,state:"unknown",action:"stakeholder",executionId:null,evidenceDigest:null})),resources:null,superseded:null,dispatchAuthorized:false,modelTransport:"not-used-fixed-profile",acceptance:"not-assessed",freshness:"snapshot-unknown",control:"unknown"}));
+    return completed.control === "not-assessed" ? view : freezeWork({...view,control:completed.control,diagnostics:completed.diagnostics,dispatchAuthorized:false,nodes:view.nodes.map(n=>({...n,action:"stakeholder" as const}))});
+  };
+  return Object.freeze({bindingDigest:experimentBindingDigest(binding),binding,pin:freezeWork({revision:p.charter.pin.revision,candidateDigest:fixedPolicyDigest(p.candidate),adoptionId:p.adoptionId}),inspect,reconcile:inspect,
+    async advance(profile:DigestProfile){if(!admitted)throw new Error("independent order authority required");const run=await controller.start(profile);return Object.freeze({boundary:run.boundary.then(settledView),completion:run.completion.then(settledView),started:run.started});},
+    async decide(request:FactoryDecision,host:FactoryAuthority|null){const current=requireFactoryAuthority(factoryAuthority(host),registry.initial.authorityId);if(!current.orderDigests.includes(factoryOrderDigest(p.charter)))throw new Error("order authority required");await controller.decideOrder(request,{id:current.id,digests:current.decisionDigests});return inspect();},
+    async cancel(request:ExperimentCancellation,host:FactoryAuthority|null){const current=requireFactoryAuthority(factoryAuthority(host),registry.initial.authorityId);await controller.cancel(request,lowerAuthority(p,current));return inspect();},
+    readArtifact:controller.readArtifact,
+  });
+}
+export type FactoryOrderView=Awaited<ReturnType<Awaited<ReturnType<typeof openFactoryOrder>>["inspect"]>>;

package/src/factory-registry.ts

@@ -0,0 +1,60 @@
+import { createControlJournal, controlJournal, type ControlBinding } from "./control-journal.ts";
+import { cloneExperiment, closed, experimentHash, experimentCharterDigest } from "./experiment-contract.ts";
+import { validateExperimentBinding, type ExperimentBinding } from "./experiment-store.ts";
+import { fixedPolicy, fixedPolicyDigest, factoryCharter, factoryOrderDigest, factoryAuthority, requireFactoryAuthority, activationRequestDigest, type FixedPolicy, type FactoryAuthority, type FactoryOrderCharter, type ActivationRequest } from "./factory-contract.ts";
+import { validateAdoptionReceipt, authorizeRollback, buildRollbackRequest, buildAdoptionBinding, type RollbackRequest } from "./vendor/adoption.ts";
+export interface RegistryInitial {version:"factory-registry-v1";authorityId:string;scopeDigest:string;baseline:FixedPolicy}
+export type FactoryRegistryBinding=ControlBinding<RegistryInitial>;
+export interface PinnedOrder {charter:FactoryOrderCharter;candidate:FixedPolicy;compiledDigest:string;adoptionId:string|null;binding:ExperimentBinding|null}
+export function registryInitial(value:RegistryInitial){const v=cloneExperiment(value);closed(v,["version","authorityId","scopeDigest","baseline"]);if(v.version!=="factory-registry-v1"||!/^[a-zA-Z0-9:_-]{1,128}$/.test(v.authorityId)||!/^[a-f0-9]{64}$/.test(v.scopeDigest))throw new Error("invalid registry initial binding");v.baseline=fixedPolicy(v.baseline);return v;}
+export function replayRegistry(b:FactoryRegistryBinding,events:Record<string,unknown>[]){
+  const initial=registryInitial(b.initial);let revision=0,candidate=initial.baseline,activation:ActivationRequest|null=null;
+  const changes=new Map<string,string>(),orders=new Map<string,PinnedOrder>(),migrations=new Map<string,{digest:string;sourceOrderId:string;targetOrderId:string;application:string}>();
+  const candidates=new Map([[fixedPolicyDigest(candidate),candidate]]), lineage:(ActivationRequest|null)[]=[];
+  for(const e of events){
+    if(e.type==="activate"){
+      closed(e,["type","request"]);const r=cloneExperiment(e.request) as ActivationRequest;closed(r,["version","requestId","expectedRevision","expectedCandidateDigest","candidate","binding","receipt"]);
+      const {id,version,...input}=r.binding;
+      if(r.version!=="factory-activation-v1"||typeof r.requestId!=="string"||!/^[a-zA-Z0-9:_-]{1,128}$/.test(r.requestId)||version!=="adoption-binding-v1"||buildAdoptionBinding(input).id!==id||r.expectedRevision!==revision||r.expectedCandidateDigest!==fixedPolicyDigest(candidate)||r.binding.scopeDigest!==initial.scopeDigest||r.binding.rollbackCandidateDigest!==fixedPolicyDigest(candidate)||r.binding.candidateDigest!==fixedPolicyDigest(r.candidate)||r.binding.assessmentPolicyDigest!==r.candidate.acceptancePolicyDigest||changes.has(r.requestId))throw new Error("invalid activation sequence");
+      changes.set(r.requestId,activationRequestDigest(r));lineage.push(activation);candidate=fixedPolicy(r.candidate);candidates.set(fixedPolicyDigest(candidate),candidate);activation=r;revision++;
+    }else if(e.type==="rollback"){
+      closed(e,["type","request","fromRevision"]);const r=e.request as RollbackRequest;
+      if(!activation||e.fromRevision!==revision||changes.has(r.id)||buildRollbackRequest(activation.receipt,r.reason,[...r.evidence],r.expiresAt).id!==r.id||r.restoreCandidateDigest!==activation.binding.rollbackCandidateDigest)throw new Error("invalid rollback sequence");
+      const restored=candidates.get(r.restoreCandidateDigest);if(!restored)throw new Error("rollback bytes not registered");changes.set(r.id,experimentHash(r));candidate=restored;if(!lineage.length)throw new Error("missing rollback lineage");activation=lineage.pop()!;
+      if((activation?.binding.candidateDigest??fixedPolicyDigest(initial.baseline))!==r.restoreCandidateDigest)throw new Error("rollback lineage mismatch");revision++;
+    }else if(e.type==="order-pin"){
+      closed(e,["type","charter","candidate","compiledDigest","adoptionId"]);const charter=factoryCharter(e.charter as FactoryOrderCharter),policy=fixedPolicy(e.candidate as FixedPolicy);
+      if(orders.size>=32||orders.has(charter.orderId)||charter.scopeDigest!==initial.scopeDigest||charter.pin.revision!==revision||charter.pin.candidateDigest!==fixedPolicyDigest(candidate)||fixedPolicyDigest(policy)!==fixedPolicyDigest(candidate)||e.adoptionId!==(activation?.receipt.id??null)||typeof e.compiledDigest!=="string"||!/^[a-f0-9]{64}$/.test(e.compiledDigest))throw new Error("invalid order pin sequence");
+      orders.set(charter.orderId,{charter,candidate:policy,compiledDigest:e.compiledDigest,adoptionId:e.adoptionId as string|null,binding:null});
+    }else if(e.type==="order-materialized"){
+      closed(e,["type","orderId","binding"]);const p=orders.get(String(e.orderId)),binding=validateExperimentBinding(e.binding as ExperimentBinding);
+      if(!p||p.binding||binding.directory!==p.charter.directory||experimentCharterDigest(binding.charter)!==p.compiledDigest)throw new Error("invalid order materialization");p.binding=binding;
+    }else if(e.type==="migration-request"){
+      closed(e,["type","requestId","sourceOrderId","targetOrderId","requestDigest"]);
+      if(typeof e.requestId!=="string"||changes.has(e.requestId)||!orders.has(String(e.sourceOrderId))||e.sourceOrderId===e.targetOrderId||typeof e.requestDigest!=="string"||!/^[a-f0-9]{64}$/.test(e.requestDigest))throw new Error("invalid migration request");
+      changes.set(e.requestId,e.requestDigest);migrations.set(e.requestId,{digest:e.requestDigest,sourceOrderId:String(e.sourceOrderId),targetOrderId:String(e.targetOrderId),application:"pending-or-unknown"});
+    }else if(e.type==="migration-receipt"){
+      closed(e,["type","requestId","application","renewedObligations"]);const m=migrations.get(String(e.requestId));
+      if(!m||m.application!=="pending-or-unknown"||!["applied","refused-active"].includes(String(e.application))||!Array.isArray(e.renewedObligations)||e.renewedObligations.length>16||e.application==="applied"&&!orders.get(m.targetOrderId)?.binding)throw new Error("invalid migration receipt");m.application=String(e.application);
+    }else throw new Error("unknown factory control event");
+  }
+  return{revision,candidate,candidateDigest:fixedPolicyDigest(candidate),activation,changes,orders,migrations};
+}
+export const factoryRegistryStore=(b:FactoryRegistryBinding)=>{registryInitial(b.initial);return controlJournal(b);};
+export async function createFactoryRegistry(input:{directory:string;authorityId:string;scopeDigest:string;baseline:FixedPolicy}):Promise<FactoryRegistryBinding>{const {directory,...rest}=cloneExperiment(input);return createControlJournal(directory,registryInitial({version:"factory-registry-v1",...rest}));}
+export function validateActivePolicy(state:ReturnType<typeof replayRegistry>,a:FactoryAuthority){if(state.activation){const r=state.activation,facts=a.facts.find(f=>f.bindingId===r.binding.id)?.facts;if(!facts)throw new Error("current independent eligibility facts required");validateAdoptionReceipt(r.receipt,r.binding,a.adoption,facts,Date.now());}}
+export function openFactoryRegistry(input:FactoryRegistryBinding){const store=factoryRegistryStore(input),b=store.binding;
+  const inspect=async()=>{const s=replayRegistry(b,(await store.read()).events);return{version:"factory-registry-view-v1" as const,revision:s.revision,candidateDigest:s.candidateDigest,candidate:cloneExperiment(s.candidate),scopeDigest:b.initial.scopeDigest,migrations:[...s.migrations].map(([requestId,m])=>({requestId,...m})),orders:[...s.orders].map(([orderId,p])=>({orderId,orderDigest:factoryOrderDigest(p.charter),candidateDigest:fixedPolicyDigest(p.candidate),revision:p.charter.pin.revision,materialization:p.binding?"recorded":"pending-or-unknown"})),acceptance:"not-assessed" as const};};
+  return{inspect,async activate(input:ActivationRequest,host:FactoryAuthority|null){const r=cloneExperiment(input),a=requireFactoryAuthority(factoryAuthority(host),b.initial.authorityId);closed(r,["version","requestId","expectedRevision","expectedCandidateDigest","candidate","binding","receipt"]);
+    if(!a.activationDigests.includes(activationRequestDigest(r)))throw new Error("independent activation authority required");
+    await store.transaction(async(events,append)=>{const s=replayRegistry(b,events),old=s.changes.get(r.requestId);if(old){if(old!==activationRequestDigest(r))throw new Error("conflicting activation ID");return;}
+      if(r.expectedRevision!==s.revision||r.expectedCandidateDigest!==s.candidateDigest)throw new Error("stale activation");
+      if(r.binding.scopeDigest!==b.initial.scopeDigest||r.binding.candidateDigest!==fixedPolicyDigest(r.candidate)||r.binding.assessmentPolicyDigest!==r.candidate.acceptancePolicyDigest||r.binding.rollbackCandidateDigest!==s.candidateDigest)throw new Error("activation scope/candidate/policy mismatch");
+      const facts=a.facts.find(f=>f.bindingId===r.binding.id)?.facts;if(!facts)throw new Error("independent eligibility facts required");validateAdoptionReceipt(r.receipt,r.binding,a.adoption,facts,Date.now());
+      replayRegistry(b,[...events,{type:"activate",request:r}]);await append({type:"activate",request:r});});return inspect();
+  },async rollback(input:RollbackRequest,host:FactoryAuthority|null){const r=cloneExperiment(input),a=requireFactoryAuthority(factoryAuthority(host),b.initial.authorityId);closed(r,["version","id","adoptionId","scopeDigest","restoreCandidateDigest","reason","evidence","expiresAt"]);
+    await store.transaction(async(events,append)=>{const s=replayRegistry(b,events),old=s.changes.get(r.id);if(old){if(old!==experimentHash(r)||!a.adoption?.rollbacks.includes(r.id))throw new Error("rollback authority/identity mismatch");return;}
+      if(!s.activation)throw new Error("stale rollback");authorizeRollback(s.activation.receipt,r,a.adoption,Date.now(),{adoptionId:s.activation.receipt.id,candidateDigest:s.candidateDigest,scopeDigest:b.initial.scopeDigest});
+      const event={type:"rollback",request:r,fromRevision:s.revision};replayRegistry(b,[...events,event]);await append(event);});return{...await inspect(),application:"applied" as const,requestId:r.id,grantExpansion:false};
+  }};
+}

package/src/file-lock.ts

@@ -1,5 +1,5 @@
 /**
- * One cross-process file lock, used by both files this package writes.
+ * One cross-process file lock, shared by producer ledgers and the approvals store.
  *
  * **Extracted rather than copied (R-49).** The ledger has had this lock since fan-out made a second writer
  * possible; the approvals store had an unlocked read-modify-write, so session 1 could load, session 2 could
@@ -36,8 +36,25 @@ export class LockTimeoutError extends Error {
   }
 }
 
+export interface FileLockOptions { readonly staleRecovery?: "age" | "disabled" }
+function lockPolicy(options: FileLockOptions | undefined): "age" | "disabled" {
+  if (options === undefined) return "age";
+  const invalid = (): never => { throw new TypeError("invalid file lock options"); };
+  if (options === null || typeof options !== "object" || Array.isArray(options) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(options))) return invalid();
+  const keys = Reflect.ownKeys(options);
+  if (keys.some(key => key !== "staleRecovery")) return invalid();
+  if (!keys.length) return "age";
+  const field = Object.getOwnPropertyDescriptor(options, "staleRecovery")!;
+  if (!Object.hasOwn(field, "value") || !field.enumerable || !["age", "disabled"].includes(field.value)) return invalid();
+  return field.value;
+}
+
 /**
  * Run `work` while holding an exclusive lock beside `path`.
+ * Explicit disabled recovery never reclaims by age/liveness. V4 selects it internally; an orphan
+ * requires separately authorized quiescent recovery, not a timer or automatic operator action.
+ * The age-based behavior described below remains the default for legacy callers.
  *
  * **Why a lock at all.** `O_APPEND` is atomic for one write to a regular file on a POSIX filesystem, and the
  * guarantee does **not** hold on drvfs (`/mnt/c` under WSL2) or NFS — which is exactly where this project
@@ -59,7 +76,8 @@ export class LockTimeoutError extends Error {
  * The timeout is short *on purpose*: work refused because a file was busy is recoverable and loud, while
  * work that hangs waiting for a lock is neither.
  */
-export async function withFileLock<T>(path: string, label: string, work: () => Promise<T>): Promise<T> {
+export async function withFileLock<T>(path: string, label: string, work: () => Promise<T>, options?: FileLockOptions): Promise<T> {
+  const staleRecovery = lockPolicy(options); // Detached once, before I/O or any wait.
   const lockPath = `${path}.lock`;
   const deadline = Date.now() + LOCK_TIMEOUT_MS;
 
@@ -98,7 +116,7 @@ export async function withFileLock<T>(path: string, label: string, work: () => P
 
       // Someone else holds it. Break it only if it is old enough to be abandoned — and only the exact file
       // we judged, so a lock created in the gap survives.
-      try {
+      if (staleRecovery === "age") try {
         const held = await stat(lockPath);
         if (Date.now() - held.mtimeMs > STALE_LOCK_MS) {
           const abandoned = await readFile(lockPath, "utf8").catch(() => undefined);
@@ -113,17 +131,34 @@ export async function withFileLock<T>(path: string, label: string, work: () => P
       continue;
     }
 
+    let bodyFailed = false;
     try {
       return await work();
-    } finally {
-      await handle.close().catch(() => undefined);
-      // Only if it is still OURS. A lock broken out from under us belongs to somebody else now, and
-      // deleting it is what turned one lost race into a cascade.
-      await removeIfOurs(lockPath, token);
+    } catch (error) { bodyFailed = true; throw error; }
+    finally {
+      if (staleRecovery === "disabled") {
+        try { await releaseDisabledLock(handle, lockPath, token); }
+        catch (error) { if (!bodyFailed) throw error; } // Preserve even a falsy primary rejection.
+      } else {
+        await handle.close().catch(() => undefined);
+        // Legacy age policy remains best effort; never remove a demonstrably different token.
+        await removeIfOurs(lockPath, token);
+      }
     }
   }
 }
 
+/** Disabled ownership cannot silently manufacture an indefinite orphan after a successful body.
+ * Try token-checked removal even if close failed; report the first failure after both attempts.
+ * Appended bytes are not rolled back, and a primary body error takes precedence at the caller. */
+async function releaseDisabledLock(handle: Awaited<ReturnType<typeof open>>, lockPath: string, token: string): Promise<void> {
+  let failure: { error: unknown } | null = null;
+  try { await handle.close(); } catch (error) { failure = { error }; }
+  try { await removeIfOurs(lockPath, token, true); }
+  catch (error) { failure ??= { error }; }
+  if (failure) throw failure.error;
+}
+
 /**
  * Delete the lock only if it still holds `token`.
  *
@@ -131,12 +166,13 @@ export async function withFileLock<T>(path: string, label: string, work: () => P
  * "the whole of `work()`" to "between a read and an unlink", and it removes the *systematic* break entirely:
  * a process can no longer delete a lock it demonstrably never owned.
  */
-async function removeIfOurs(lockPath: string, token: string): Promise<void> {
+async function removeIfOurs(lockPath: string, token: string, strict = false): Promise<void> {
   try {
     const held = await readFile(lockPath, "utf8");
     if (held.trim() !== token) return;
     await rm(lockPath, { force: true });
-  } catch {
-    /* already gone, or unreadable — either way this process is not the one that should force it */
+  } catch (error) {
+    if (strict) throw error; // No ownership inference or force-delete after a failed read.
+    /* Legacy: already gone, or unreadable — this process must not force removal. */
   }
 }