pi-daddy 0.22.0 → 0.23.0

package/src/retention-contract.ts

@@ -0,0 +1,84 @@
+import { Compile } from "typebox/compile";
+import { parseWorkJson } from "./work-ledger-json.ts";
+import type { ExecutionRetentionManifest } from "./execution-retention.ts";
+
+const string = (maxLength = 512) => ({ type: "string", minLength: 1, maxLength, pattern: "^[^\\u0000-\\u001f\\u007f]+$" });
+const nullable = (schema: object) => ({ anyOf: [schema, { type: "null" }] });
+const literal = (value: unknown) => ({ const: value });
+const closed = (properties: Record<string, object>) => ({ type: "object", properties, required: Object.keys(properties), additionalProperties: false });
+const hash = { type: "string", pattern: "^[a-f0-9]{64}$" };
+const integer = { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER };
+const uuid = { type: "string", pattern: "^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$" };
+export const RETENTION_CONTENT_KINDS = ["stdout", "stderr", "paneSnapshot", "checkReceipt", "result", "session"] as const;
+export const RETENTION_SCHEMA = freeze({
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://pi-daddy.local/contracts/execution-retention/v2/manifest.schema.json",
+  ...closed({
+    version: literal("2.0"), archiveId: uuid,
+    identity: closed({ executionId: string(), parentExecutionId: nullable(string()), childId: string(), toolCallId: nullable(string()),
+      executor: { enum: ["process", "herdr", "check"] }, taskDigest: nullable(hash), definitionDigest: nullable(hash),
+      configurationDigest: hash, workspaceId: nullable(string()) }),
+    native: closed({ pid: nullable({ type: "integer", minimum: 1, maximum: Number.MAX_SAFE_INTEGER }), paneId: nullable(string(4096)),
+      agentName: nullable(string(4096)), tabId: nullable(string(4096)), sessionId: nullable(uuid), sessionPath: nullable(string(4096)), branchLeafId: nullable(string(128)) }),
+    nativeSession: closed({ source: { enum: [null, "herdr-id", "herdr-path", "pi-session-file", "pi-session-manager"] },
+      status: { enum: ["missing", "verified", "invalid", "changed", "truncated", "unsupported"] },
+      sessionId: nullable(uuid), sessionPath: nullable(string(4096)), parentSessionPath: nullable(string(4096)),
+      branchLeafId: nullable(string(128)), branchState: { enum: ["unknown", "observed"] }, lastPersistedEntryId: nullable(string(128)),
+      sha256: nullable(hash), reason: nullable(string()) }),
+    state: { enum: ["running", "terminal"] },
+    outcome: nullable(closed({ code: nullable({ type: "integer", minimum: -2147483648, maximum: 2147483647 }), signal: nullable(string(64)),
+      timedOut: { type: "boolean" }, aborted: { type: "boolean" }, truncated: { type: "boolean" }, failed: { type: "boolean" } })),
+    content: closed(Object.fromEntries(RETENTION_CONTENT_KINDS.map(kind => [kind, { oneOf: [
+      closed({ status: literal("missing"), path: literal(null), sha256: literal(null), bytes: literal(null) }),
+      closed({ status: literal("retained"), path: { type: "string", pattern: `^${kind}-[a-f0-9]{64}\\.bin$` }, sha256: hash,
+        bytes: { ...integer, maximum: 1024 * 1024 } }),
+    ] }]))),
+    coverage: closed({ complete: literal(false), losses: { type: "array", items: string(), maxItems: 64, uniqueItems: true } }),
+    acceptance: literal("not-assessed"),
+  }),
+  allOf: [
+    { if: { properties: { state: literal("running") } }, then: { properties: { outcome: literal(null) } },
+      else: { properties: { outcome: { type: "object" } } } },
+    { if: { properties: { nativeSession: { properties: { branchState: literal("unknown") } } } },
+      then: { properties: { nativeSession: { properties: { branchLeafId: literal(null) } }, native: { properties: { branchLeafId: literal(null) } } } } },
+  ],
+});
+const validator = Compile(RETENTION_SCHEMA);
+function freeze<T>(value: T): T { if (value && typeof value === "object") { for (const child of Object.values(value)) freeze(child); Object.freeze(value); } return value; }
+
+/** Closed, detached versioned wire builder; never authenticates the supplied observation. */
+export function buildExecutionRetentionManifest(value: unknown): ExecutionRetentionManifest {
+  // Reject non-JSON objects/accessors instead of invoking serialization hooks while collecting evidence.
+  let nodes = 0;
+  const inspect = (x: unknown, depth: number): void => {
+    if (++nodes > 4096 || depth > 16) throw new TypeError("retention manifest exceeds bounds");
+    if (x === null || typeof x === "string" || typeof x === "boolean" || (typeof x === "number" && Number.isSafeInteger(x))) return;
+    if (!x || typeof x !== "object" || (!Array.isArray(x) && Object.getPrototypeOf(x) !== Object.prototype && Object.getPrototypeOf(x) !== null)) throw new TypeError("retention manifest must be JSON data");
+    if (Array.isArray(x) && (Object.getPrototypeOf(x) !== Array.prototype || x.length > 256 || Reflect.ownKeys(x).length !== x.length + 1 ||
+      Array.from({ length: x.length }, (_, i) => String(i)).some(key => !Object.hasOwn(x, key)))) throw new TypeError("retention arrays must be dense plain JSON arrays");
+    for (const key of Reflect.ownKeys(x)) {
+      if (Array.isArray(x) && key === "length") continue;
+      const d = Object.getOwnPropertyDescriptor(x, key)!;
+      if (typeof key !== "string" || !d.enumerable || !("value" in d)) throw new TypeError("retention manifest must be plain JSON data");
+      inspect(d.value, depth + 1);
+    }
+  };
+  inspect(value, 0);
+  if (!validator.Check(value)) throw new TypeError("invalid execution-retention 2.0 manifest");
+  const m = JSON.parse(JSON.stringify(value)) as ExecutionRetentionManifest;
+  if (m.native.sessionId !== m.nativeSession.sessionId || m.native.sessionPath !== m.nativeSession.sessionPath || m.native.branchLeafId !== m.nativeSession.branchLeafId) {
+    throw new TypeError("native session projection mismatch");
+  }
+  for (const kind of RETENTION_CONTENT_KINDS) { const ref = m.content[kind];
+    if (ref.status === "retained" && ref.path !== `${kind}-${ref.sha256}.bin`) throw new TypeError("retention content identity mismatch"); }
+  if (m.nativeSession.branchState === "observed" && (m.nativeSession.source !== "pi-session-manager" || m.nativeSession.status !== "verified")) throw new TypeError("unverified active native branch");
+  if (m.nativeSession.status === "verified" && (!m.nativeSession.sessionId || !m.nativeSession.sha256 || m.content.session.sha256 !== m.nativeSession.sha256)) throw new TypeError("verified native session requires retained bytes");
+  return freeze(m);
+}
+export function parseExecutionRetentionManifest(text: string): ExecutionRetentionManifest {
+  if (Buffer.byteLength(text) > 64 * 1024) throw new TypeError("retention manifest exceeds bounds");
+  // Manifest numbers are integers; use the existing exact-token parser before lossy Number conversion.
+  let value: unknown;
+  try { value = parseWorkJson(text); } catch { throw new TypeError("invalid retention JSON"); }
+  return buildExecutionRetentionManifest(value);
+}

package/src/retention-json.ts

@@ -0,0 +1,20 @@
+/** Strict JSON framing for retention metadata/native records. Floats in native usage remain supported. */
+export function parseRetentionJson(text: string, maxBytes = 64 * 1024): unknown {
+  if (Buffer.byteLength(text) > maxBytes) throw new TypeError("retention JSON exceeds bounds");
+  const value: unknown = JSON.parse(text);
+  const stack: Array<{ object: boolean; key: boolean; seen: Set<string> }> = [];
+  for (const match of text.matchAll(/"(?:[^"\\]|\\[\s\S])*"|[{}\[\],:]|[^\s{}\[\],:]+/g)) {
+    const token = match[0], top = stack.at(-1);
+    if (token === "{" || token === "[") {
+      if (stack.length >= 64) throw new TypeError("retention JSON exceeds depth");
+      stack.push({ object: token === "{", key: token === "{", seen: new Set() });
+    } else if (token === "}" || token === "]") stack.pop();
+    else if (token === ",") { if (top?.object) top.key = true; }
+    else if (token.startsWith('"') && top?.object && top.key) {
+      const key = JSON.parse(token) as string;
+      if (top.seen.has(key)) throw new TypeError("duplicate retention JSON member");
+      top.seen.add(key); top.key = false;
+    } else if (/^-?\d/.test(token) && !Number.isFinite(Number(token))) throw new TypeError("non-finite retention JSON number");
+  }
+  return value;
+}

package/src/run-child.ts

@@ -92,6 +92,10 @@ export interface ChildRunRequest {
    * governed child mid-task.
    */
   onOutput?: (chunk: string) => void;
+  /** Optional raw observation; isolated from control, never awaited, separate from display text. */
+  onObservation?: (stream: "stdout" | "stderr", bytes: Uint8Array) => void;
+  /** Passive EOF observation. Never a replacement child/settlement handle. Exceptions are isolated. */
+  onStreamEnd?: (stream: "stdout" | "stderr") => void;
   /** Security hook called immediately after spawn, before output handling (for lease attachment). */
   onSpawn?: (pid: number) => void;
 }
@@ -244,8 +248,15 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
       flush();
     };
 
-    child.stdout?.on("data", capture);
-    child.stderr?.on("data", capture);
+    const observe = (stream: "stdout" | "stderr", chunk: Buffer) => {
+      capture(chunk);
+      try { request.onObservation?.(stream, chunk); } catch { /* observation only */ }
+    };
+    child.stdout?.on("data", (chunk: Buffer) => observe("stdout", chunk));
+    child.stderr?.on("data", (chunk: Buffer) => observe("stderr", chunk));
+    for (const stream of ["stdout", "stderr"] as const) child[stream]?.on("end", () => {
+      try { request.onStreamEnd?.(stream); } catch { /* passive observation only */ }
+    });
 
     timers.push(
       setTimeout(() => controlIfRunning(() => {

package/src/run-herdr.ts

@@ -27,7 +27,7 @@ import type { ChildRunResult } from "./run-child.ts";
 import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS } from "./run-child.ts";
 import { MAX_OPEN_PANES, markPaneSettled, trackPane, trimOpenPanes, untrackPane } from "./pane-reaper.ts";
 import { defaultExec, parseReply, type HerdrExec } from "./herdr-cli.ts";
-import { readPane, waitForSettled } from "./herdr-poll.ts";
+import { readPane, waitForSettled, seqOf, observeHerdrSession, type PollTarget } from "./herdr-poll.ts";
 import { stageSystemPrompt } from "./herdr-stage.ts";
 import { uniqueAgentName } from "./herdr-name.ts";
 
@@ -90,6 +90,8 @@ export interface HerdrRunRequest {
    * Exceptions are swallowed; a renderer must not be able to break a governed run.
    */
   onSnapshot?: (lines: string[]) => void;
+  /** Available pane snapshots only, not a structured session transcript. Never awaited. */
+  onObservation?: (bytes: Uint8Array) => void;
   /** How many pane lines to report per poll. Defaults to `DEFAULT_SNAPSHOT_LINES`. */
   snapshotLines?: number;
   /**
@@ -103,6 +105,9 @@ export interface HerdrRunRequest {
   onRunning?: (paneId: string, agentName: string) => void;
   /** Security hook for attaching a writer lease to the tab. Unlike display callbacks, errors fail the run. */
   onTab?: (tabId: string) => void;
+  /** Optional observation, unlike the required lease hook above. */
+  onNativeTab?: (tabId: string) => void;
+  onSessionReference?: PollTarget["onSessionReference"];
   /** Close even a settled pane before releasing a writer lease; no post-lease prompt may remain live. */
   closeOnSettle?: boolean;
   /** Poll cadence override. Exists so tests do not wait `POLL_INTERVAL_MS` per state transition. */
@@ -179,6 +184,7 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
   const rootPane = (created.result?.root_pane ?? {}) as { pane_id?: string; tab_id?: string };
   const paneId = rootPane.pane_id;
   const tabId = rootPane.tab_id;
+  if (tabId) { try { request.onNativeTab?.(tabId); } catch { /* observation only */ } }
   // **Tracked BEFORE the pane-id check, not after.** A tab can exist from the moment this reply is parsed,
   // so registering later leaves a window — one herdr round-trip wide — in which a killed process orphans a
   // tab nothing would reap. The normal path had no such window and the error path did, which is backwards:
@@ -300,6 +306,7 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
 
     // The state counter BEFORE prompting is what makes the wait correct — see the R-33 note below.
     const before = seqOf(started.result);
+    observeHerdrSession(started.result?.agent, paneId, request.onSessionReference);
 
     const prompted = parseReply(await exec(["agent", "prompt", agentName, request.prompt]));
     if (prompted.error) return { ...empty, spawnError: `herdr agent prompt failed: ${prompted.error}` };
@@ -311,11 +318,12 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
       }
     }
 
-    const settled = await waitForSettled(exec, { ...request, name: agentName }, before, deadline, maxOutputBytes);
+    const settled = await waitForSettled(exec, { ...request, name: agentName, nativePaneId: paneId }, before, deadline, maxOutputBytes);
     if (settled.aborted || settled.timedOut) {
       // Still read: a timed-out child usually produced something, and a partial answer labelled partial is
       // more useful than none. R-03's rule — a missing result must never look like an empty one.
       const partial = await readPane(exec, agentName, maxOutputBytes);
+      if (!partial.readFailed) { try { request.onObservation?.(Buffer.from(partial.text)); } catch { /* observation only */ } }
       return { ...empty, ...settled, text: partial.readFailed ? "" : partial.text, truncated: partial.truncated };
     }
     if (settled.spawnError) return { ...empty, spawnError: settled.spawnError };
@@ -333,6 +341,7 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
           `The work may have been done — check pane ${paneId} if it is still open.`,
       };
     }
+    try { request.onObservation?.(Buffer.from(out.text)); } catch { /* observation only */ }
     settledCleanly = true;
     // The trim may now reclaim this pane if the cap is exceeded. Until this point it must not: closing the tab
     // kills the child, and the child was still working.
@@ -387,8 +396,3 @@ async function startAgent(
     await new Promise((r) => setTimeout(r, PANE_READY_POLL_MS));
   }
 }
-
-function seqOf(result: Record<string, unknown> | undefined): number {
-  const agent = (result?.agent ?? {}) as { state_change_seq?: number };
-  return typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
-}

package/src/vendor/adoption.ts

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

package/src/work-ledger-destination.ts

@@ -0,0 +1,113 @@
+import { lstat, realpath, stat } from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import type { BigIntStats } from "node:fs";
+import { constants } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { WorkLedgerWriteError } from "./work-ledger-types.ts";
+
+/** Only actual errno-class failures cross the content-free filesystem error boundary. */
+export function workFsError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error && typeof error.code === "string" && Object.hasOwn(constants.errno, error.code);
+}
+export const validWorkPath = (path: string) => path.length > 0 && isAbsolute(path) && !path.includes("\0");
+// Node encodes string filesystem paths as UTF-8: lone UTF-16 surrogates become U+FFFD.
+// Compare that exact spelling even for absent leaves/ancestors, before mkdir or lock acquisition.
+// This preserves valid Unicode verbatim; it is not Unicode normalization or case folding.
+const filesystemPath = (path: string) => Buffer.from(resolve(path), "utf8").toString("utf8");
+const invalid = (): never => { throw new WorkLedgerWriteError("WORK_DESTINATION_INVALID"); };
+const alias = (): never => { throw new WorkLedgerWriteError("WORK_DESTINATION_ALIAS"); };
+const same = (a: BigIntStats | null, b: BigIntStats | null) => a !== null && b !== null && a.dev === b.dev && a.ino === b.ino;
+function ancestors(path: string): string[] {
+  const result: string[] = [];
+  for (let p = dirname(path); ; p = dirname(p)) { result.push(p); if (dirname(p) === p) return result; }
+}
+interface PathFact {
+  path: string;
+  canonical: string | null;
+  entry: BigIntStats | null;
+  target: BigIntStats | null;
+  invalid: boolean;
+  io: boolean;
+}
+/** Internal descriptor/topology facts, never a public result, ambient grant lookup or authority input. */
+export interface WorkDestination {
+  readonly requestedPath: string;
+  readonly grantLedgerPath: string | null;
+  readonly path: string;
+  readonly existing: BigIntStats | null;
+  readonly protectedInodes: readonly BigIntStats[];
+}
+
+/** Read-only, complete preflight. A protected filename reserves its entire directory namespace too.
+ * Compare lexical paths, canonical paths and exact dev/ino identities; aliases outrank failed facts,
+ * which outrank unsafe topology. This is cooperative misrouting protection, NOT host containment. */
+export async function workDestination(requestedPath: string, grantLedgerPath: string | null): Promise<WorkDestination> {
+  if (!validWorkPath(requestedPath) || (grantLedgerPath !== null && !validWorkPath(grantLedgerPath))) invalid();
+  const path = filesystemPath(requestedPath), leaves = [path, path + ".lock"];
+  const protectedPaths = grantLedgerPath === null ? [] : [filesystemPath(grantLedgerPath), filesystemPath(grantLedgerPath) + ".lock"];
+  const workPaths = new Set(leaves.flatMap(p => [p, ...ancestors(p)]));
+  if (protectedPaths.some(p => workPaths.has(p))) alias(); // Proven lexical collision needs no I/O.
+  const facts = new Map<string, Promise<PathFact>>();
+  function probe(path: string): Promise<PathFact> {
+    const prior = facts.get(path); if (prior) return prior;
+    const pending = inspect(path); facts.set(path, pending); return pending;
+  }
+  async function inspect(path: string): Promise<PathFact> {
+    const fact: PathFact = { path, canonical: null, entry: null, target: null, invalid: false, io: false };
+    try { fact.entry = await lstat(path, { bigint: true }); }
+    catch (error) {
+      if (!workFsError(error)) throw error;
+      if (error.code !== "ENOENT") { fact.invalid = ["ENOTDIR", "ELOOP"].includes(error.code!); fact.io = !fact.invalid; return fact; }
+    }
+    if (fact.entry) {
+      try {
+        fact.canonical = await realpath(path);
+        fact.target = fact.entry.isSymbolicLink() ? await stat(path, { bigint: true }) : fact.entry;
+      } catch (error) {
+        if (!workFsError(error)) throw error;
+        fact.invalid = ["ENOENT", "ENOTDIR", "ELOOP"].includes(error.code!); fact.io = !fact.invalid;
+      }
+    } else {
+      const parentPath = dirname(path);
+      if (parentPath === path) { fact.invalid = true; return fact; }
+      const parent = await probe(parentPath);
+      fact.invalid = parent.invalid || (parent.target !== null && !parent.target.isDirectory()); fact.io = parent.io;
+      if (parent.canonical) fact.canonical = join(parent.canonical, basename(path));
+    }
+    return fact;
+  }
+  const protectedFacts = await Promise.all(protectedPaths.map(probe));
+  const initial = await Promise.all([...workPaths].map(probe));
+  // A symlink parent can jump INSIDE a reserved directory. Include every canonical ancestor,
+  // not just lexical ancestors whose realpath might skip over the protected directory itself.
+  for (const fact of initial) if (fact.canonical) for (const p of [fact.canonical, ...ancestors(fact.canonical)]) workPaths.add(p);
+  const workFacts = await Promise.all([...workPaths].map(probe));
+  for (const w of workFacts) for (const p of protectedFacts) {
+    if (w.path === p.path || (w.canonical !== null && w.canonical === p.canonical) || same(w.target, p.target)) alias();
+  }
+  const all = [...workFacts, ...protectedFacts];
+  if (all.some(f => f.io)) throw new WorkLedgerWriteError("WORK_LEDGER_WRITE_FAILED");
+  if (all.some(f => f.invalid)) invalid();
+  for (const leaf of leaves) {
+    const f = await probe(leaf);
+    if (f.entry && (!f.entry.isFile() || f.entry.nlink !== 1n)) invalid();
+  }
+  for (const p of [...ancestors(path), ...ancestors((await probe(path)).canonical!)]) {
+    const f = await probe(p);
+    if (f.target && !f.target.isDirectory()) invalid();
+  }
+  const file = await probe(path);
+  return { requestedPath, grantLedgerPath, path: file.canonical!, existing: file.target,
+    protectedInodes: protectedFacts.flatMap(f => f.target ? [f.target] : []) };
+}
+
+/** Repeat classification after mkdir/acquisition/open. Never write through a freshly resolved handle. */
+export async function recheckWorkDestination(original: WorkDestination, handle?: FileHandle): Promise<void> {
+  const current = await workDestination(original.requestedPath, original.grantLedgerPath);
+  if (handle) {
+    const actual = await handle.stat({ bigint: true });
+    if (current.protectedInodes.some(p => same(actual, p))) alias();
+    if (!actual.isFile() || actual.nlink !== 1n || !same(actual, current.existing)) invalid();
+  }
+  if (original.path !== current.path || (original.existing && !same(original.existing, current.existing))) invalid();
+}