pi-daddy 0.28.0 → 0.32.0

package/src/debrief-contract.ts

@@ -1,127 +0,0 @@
-import { createRequire } from "node:module";
-import { createHash } from "node:crypto";
-import { Compile } from "typebox/compile";
-import { parseRetentionJson } from "./retention-json.ts";
-const require = createRequire(import.meta.url);
-const caseCheck = Compile(require("../contracts/debrief/v1/work-capture/work-case.schema.json"));
-const requestCheck = Compile(require("../contracts/debrief/v1/work-capture/review-request.schema.json"));
-export type Disposition = "confirmed_defect" | "expected_behavior" | "exemplar" | "uncertain" | "skip";
-export interface ReviewRequest { caseManifestId: string; priorDecisionId: string | null; disposition: Disposition; note: string }
-export interface ReviewItem { caseManifestId: string; candidate: { id: string; reason: string; [key: string]: unknown }; priorDecisionId: string | null; disposition: Disposition | "unresolved" }
-export interface ReviewPort {
-  list(offset: number, limit: number): unknown | Promise<unknown>;
-  history(caseManifestId: string): unknown | Promise<unknown>;
-  decide?: (request: ReviewRequest) => unknown | Promise<unknown>;
-}
-export interface BlindChoice { kind: "one" | "tie" | "none" | "insufficient"; labels: string[] }
-export interface BlindView { version: "blind-intervention-view-v1"; cards: { label: string; artifactDigests: string[] }[]; limitations: string[] }
-export interface BlindPort {
-  quality?(): unknown | Promise<unknown>;
-  view(): unknown | Promise<unknown>;
-  readArtifact(label: string, digest: string): Uint8Array | Promise<Uint8Array>;
-  choose(choice: BlindChoice): unknown | Promise<unknown>;
-  reveal(): unknown | Promise<unknown>;
-}
-export const dataKey = (v: unknown): string => Array.isArray(v) ? `[${v.map(dataKey).join(",")}]` : v !== null && typeof v === "object"
-  ? `{${Object.keys(v).sort().map(k => JSON.stringify(k) + ":" + dataKey((v as Record<string, unknown>)[k])).join(",")}}` : JSON.stringify(v);
-export const dataDigest = (v: unknown) => createHash("sha256").update(dataKey(v)).digest("hex");
-export const byteDigest = (v: Uint8Array) => createHash("sha256").update(v).digest("hex");
-export const sha = (v: unknown): v is string => typeof v === "string" && /^[a-f0-9]{64}$/.test(v);
-export function detached<T>(input: T): T {
-  const active = new Set<object>(); let count = 0;
-  const inspect = (v: unknown, depth: number): void => {
-    if (++count > 50000 || depth > 32) throw new Error("debrief data bound exceeded");
-    if (v === null || typeof v === "string" || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v)) return;
-    if (!v || typeof v !== "object" || active.has(v)) throw new Error("plain debrief data required");
-    const array = Array.isArray(v), prototype = Object.getPrototypeOf(v), fields = Object.getOwnPropertyDescriptors(v);
-    if (array ? prototype !== Array.prototype || v.length > 4096 || Reflect.ownKeys(fields).length !== v.length + 1 : ![Object.prototype, null].includes(prototype)) throw new Error("plain debrief object/array required");
-    active.add(v);
-    for (const k of Reflect.ownKeys(fields)) {
-      if (array && k === "length") continue;
-      const d = fields[k as string]; if (typeof k !== "string" || !d.enumerable || !Object.hasOwn(d, "value")) throw new Error("hidden/accessor debrief data refused");
-      inspect(d.value, depth + 1);
-    }
-    if (array) for (let i = 0; i < v.length; i++) if (!Object.hasOwn(fields, String(i))) throw new Error("sparse debrief array");
-    active.delete(v);
-  };
-  inspect(input, 0);
-  const text = JSON.stringify(input);
-  if (!text || Buffer.byteLength(text) > 1024 * 1024) throw new Error("bounded debrief data required");
-  return parseRetentionJson(text) as T;
-}
-export function freeze<T>(v: T): T { if (v && typeof v === "object") { Object.values(v).forEach(freeze); Object.freeze(v); } return v; }
-export function closed(v: unknown, names: string[]): asserts v is Record<string, unknown> {
-  if (!v || typeof v !== "object" || Array.isArray(v) || Object.keys(v).sort().join() !== [...names].sort().join()) throw new Error("closed debrief object required");
-}
-export function reviewRequest(input: ReviewRequest): ReviewRequest {
-  const r = detached(input); if (!requestCheck.Check(r)) throw new Error("invalid label request"); return freeze(r);
-}
-export interface SignalSelection { batchId: string; observationId: string }
-function signalCase(c: Record<string, any>): boolean {
-  if (c.capture_schema === 2) return c.reason === "coverage_gap" && c.classification === "coverage_issue" && caseCheck.Check(c) && c.id === dataDigest({ detector: c.detector, target: c.target, reason: c.reason });
-  if (c.capture_schema !== 3 || c.classification !== "candidate_defect" || !["overdue_checkpoint", "reopened_acceptance", "intent_conflict"].includes(c.reason)) return false;
-  // Signal facts may contribute256 references plus the two base scope/obligation references.
-  if (!Array.isArray(c.evidence) || !c.evidence.length || c.evidence.length > 258 || !c.evidence.every(sha)) return false;
-  const common = { ...c, capture_schema: 2, reason: "coverage_gap", classification: "coverage_issue", metrics: {}, evidence: c.evidence.slice(0, 256) };
-  if (!caseCheck.Check(common) || c.detector.id !== c.reason || !c.detector.version.startsWith("work-signals-v1:") || !c.metrics || typeof c.metrics !== "object") return false;
-  const keys = c.reason === "overdue_checkpoint" ? ["deadlineMs", "observedAt"] : c.reason === "intent_conflict" ? ["failedChecks"] : [];
-  closed(c.metrics, keys);
-  if (keys.some(k => !Number.isSafeInteger(c.metrics[k]) || c.metrics[k] < 0)) return false;
-  const m = c.metrics as Record<string, number>;
-  if (c.reason === "overdue_checkpoint" && m.observedAt <= m.deadlineMs || c.reason === "intent_conflict" && m.failedChecks < 1) return false;
-  const detector = { id: c.detector.id, version: c.detector.version, population: c.detector.population };
-  const target = { kind: c.target.kind, snapshotDigest: c.target.snapshotDigest, obligationId: c.target.obligationId, obligationDigest: c.target.obligationDigest };
-  const metrics = Object.fromEntries(keys.map(k => [k, c.metrics[k]])), evidence = [...new Set(c.evidence)].sort();
-  return dataKey(evidence) === dataKey(c.evidence) && c.id === createHash("sha256").update(JSON.stringify({ capture_schema: 3, detector, target, reason: c.reason, metrics, evidence })).digest("hex");
-}
-export function reviewPage(value: unknown, limit: number, offset = 0, signals?: SignalSelection) {
-  const page = detached(value) as { total: number; offset: number; items: ReviewItem[]; observationId?: string; issues?: string[] };
-  closed(page, signals ? ["total", "offset", "items", "observationId", "issues"] : ["total", "offset", "items"]);
-  if (signals && (page.observationId !== signals.observationId || page.total > 1024 || !Array.isArray(page.issues) || page.issues.length > 1 || page.issues.some(i => i !== "scope-unresolved"))) throw new Error("unbound work signal observation");
-  if (!Number.isSafeInteger(page.total) || page.total < 0 || page.total > 4096 || page.offset !== offset || !Array.isArray(page.items) || page.items.length > limit || page.items.length > Math.max(0, page.total - offset)) throw new Error("invalid bounded case page");
-  for (const item of page.items) {
-    closed(item, ["caseManifestId", "candidate", "priorDecisionId", "disposition"]);
-    const c = item.candidate as Record<string, any>;
-    if (!sha(item.caseManifestId) || !(signals ? signalCase(c) : caseCheck.Check(c)) || !(item.priorDecisionId === null || sha(item.priorDecisionId)) ||
-      !["unresolved", "confirmed_defect", "expected_behavior", "exemplar", "uncertain", "skip"].includes(item.disposition) ||
-      (!signals && c.id !== dataDigest({ detector: c.detector, target: c.target, reason: c.reason })) ||
-      (!signals && c.classification !== ({ repeat_without_progress: "candidate_defect", economical_exemplar: "candidate_exemplar", coverage_gap: "coverage_issue" } as Record<string, string>)[c.reason]) ||
-      (c.reason === "repeat_without_progress" && (c.metrics.equivalentAttempts === undefined || c.metrics.equivalentAttempts < 2)) ||
-      (c.reason === "economical_exemplar" && (c.metrics.measuredCost === undefined || c.metrics.costLimit === undefined || c.metrics.costUnit === undefined || c.metrics.measuredCost > c.metrics.costLimit))) throw new Error("invalid case identity/state");
-  }
-  if (new Set(page.items.map(i => i.caseManifestId)).size !== page.items.length) throw new Error("duplicate case card");
-  return freeze(page);
-}
-export function validatedHistory(value: unknown, item: ReviewItem) {
-  const history = detached(value) as Record<string, any>[];
-  if (!Array.isArray(history) || history.length > 4096) throw new Error("invalid review history");
-  let prior: string | null = null;
-  for (const d of history) {
-    closed(d, ["decision_schema", "id", "caseId", "priorDecisionId", "disposition", "author", "evidence", "note"]);
-    const { decision_schema, id, ...body } = d;
-    if (decision_schema !== 1 || !sha(id) || dataDigest(body) !== id || d.caseId !== item.candidate.id || d.priorDecisionId !== prior ||
-      typeof d.author !== "string" || !d.author || d.author.length > 512 || /[\u0000-\u001f\u007f]/.test(d.author) ||
-      !requestCheck.Check({ caseManifestId: item.caseManifestId, priorDecisionId: d.priorDecisionId, disposition: d.disposition, note: d.note }) ||
-      !Array.isArray(d.evidence) || d.evidence.length > 256 || !d.evidence.every(sha) || !d.evidence.includes(item.caseManifestId)) throw new Error("unbound review history");
-    prior = id;
-  }
-  return history.at(-1) ?? null;
-}
-export function matchingHistory(value: unknown, item: ReviewItem, request: ReviewRequest, author: string) {
-  const last = validatedHistory(value, item);
-  const expected = dataDigest({ caseId: item.candidate.id, priorDecisionId: request.priorDecisionId, disposition: request.disposition,
-    author, evidence: [item.caseManifestId], note: request.note });
-  return last?.id === expected ? expected : null;
-}
-export function blindView(value: unknown): BlindView {
-  const view = detached(value) as BlindView; closed(view, ["version", "cards", "limitations"]);
-  if (view.version !== "blind-intervention-view-v1" || !Array.isArray(view.cards) || view.cards.length < 2 || view.cards.length > 4 || !Array.isArray(view.limitations) || view.limitations.some(v => typeof v !== "string")) throw new Error("unsupported blind view");
-  for (const c of view.cards) { closed(c, ["label", "artifactDigests"]); if (!/^variant-[a-f0-9]{16}$/.test(c.label) || !Array.isArray(c.artifactDigests) || c.artifactDigests.length > 4 || !c.artifactDigests.every(sha)) throw new Error("invalid opaque artifact card"); }
-  if (new Set(view.cards.map(c => c.label)).size !== view.cards.length) throw new Error("duplicate blind label"); return freeze(view);
-}
-export function blindChoice(input: BlindChoice, view: BlindView): BlindChoice {
-  const c = detached(input); closed(c, ["kind", "labels"]);
-  if (!Array.isArray(c.labels) || new Set(c.labels).size !== c.labels.length || c.labels.some(l => !view.cards.some(v => v.label === l)) ||
-    !["one", "tie", "none", "insufficient"].includes(c.kind) || (c.kind === "one" ? c.labels.length !== 1 : c.kind === "tie" ? c.labels.length < 2 : c.labels.length !== 0)) throw new Error("invalid quality choice");
-  return freeze({ kind: c.kind, labels: [...c.labels].sort() });
-}

package/src/debrief-fixture.ts

@@ -1,29 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { createDebriefPresenter, type DebriefCheckpoint, type DebriefPersistence } from "./debrief.ts";
-import { blindView, blindChoice, dataKey, dataDigest, detached, freeze, type BlindChoice } from "./debrief-contract.ts";
-import { parseRetentionJson } from "./retention-json.ts";
-const root = new URL("../contracts/debrief/v1/", import.meta.url);
-const json = async (path: string) => parseRetentionJson(await readFile(new URL(path, root), "utf8")) as any;
-/** Explicit frozen demo only. No case writer or durable blind/attention qualification is fabricated. */
-export async function createFixtureDebrief() {
-  const cases = await json("work-capture/fixtures/cases.json"), batch = await json("work-capture/fixtures/batch.json");
-  if (cases.length !== 7 || batch.candidateIds.length !== 7) throw new Error("fixture inventory changed");
-  const items = cases.map((candidate: any, i: number) => ({ candidate, caseManifestId: batch.candidateIds[i], priorDecisionId: null, disposition: "unresolved" })).sort((a: any, b: any) => a.caseManifestId.localeCompare(b.caseManifestId));
-  const view = blindView(await json("intervention/fixtures/blind-view.json"));
-  let choice: BlindChoice | null = null, revealed = false, state: DebriefCheckpoint | null = null;
-  const persistence: DebriefPersistence = { durability: "fixture-memory", load: () => detached(state), compareAndSwap(expected, next) {
-    if (expected !== (state ? dataDigest(state) : null)) throw new Error("stale fixture checkpoint"); state = freeze(detached(next));
-  } };
-  return createDebriefPresenter({ scope: "manual-frozen-fixture-v1", fixture: true, persistence,
-    reviewer: { list: (offset, limit) => ({ total: 7, offset, items: items.slice(offset, offset + limit) }), history: () => [] },
-    blind: { view: () => view, readArtifact: async (label, digest) => {
-      if (!view.cards.some(c => c.label === label && c.artifactDigests.includes(digest))) throw new Error("artifact outside fixture blind view");
-      return readFile(new URL(`intervention/fixtures/artifact-${digest}.txt`, root));
-    }, choose(input) {
-      const next = blindChoice(input, view); if (revealed && dataKey(choice) !== dataKey(next)) throw new Error("fixture choice locked"); choice = next; return next;
-    }, async reveal() {
-      if (!choice) throw new Error("quality first"); const saved = await json("intervention/fixtures/reveal.json");
-      revealed = true; return { ...saved, choice };
-    } },
-  });
-}

package/src/debrief-host.ts

@@ -1,53 +0,0 @@
-import { isAbsolute } from "node:path";
-import { createDebriefPresenter, type DebriefPersistence } from "./debrief.ts";
-import { closed, detached, freeze, sha, type BlindChoice, type BlindPort, type ReviewPort } from "./debrief-contract.ts";
-/** Host supplies its loaded harness module, not worker metadata or a permission-shaped receipt.
- * Ordinary integration consumes exact638494af... source bytes; this structural port is not module authentication. */
-export interface DebriefHarness {
-  createWorkCaseReviewer(root: string, batchId: string, author: string): ReviewPort;
-  createWorkSignalReviewer(root: string, batchId: string, author: string): ReviewPort;
-  retainBlindIntervention(root: string, manifest: unknown, evidence: unknown[], qualification: unknown, author: string): string;
-  openBlindIntervention(root: string, id: string, author: string): BlindPort & { quality(): unknown };
-}
-export interface DurableBlindBinding { comparisonId: string; author: string }
-export type CaseSelection = { version: "work-case-v2"; batchId: string } | { version: "work-signals-v1"; batchId: string; observationId: string };
-function location(root: string, author: string) {
-  if (typeof root !== "string" || !isAbsolute(root) || typeof author !== "string" || !author || author.length > 512 || /[\u0000-\u001f\u007f]/.test(author)) throw new Error("explicit archive and independent operator author required");
-}
-function binding(input: DurableBlindBinding): DurableBlindBinding {
-  const value = detached(input); closed(value, ["comparisonId", "author"]);
-  if (!sha(value.comparisonId) || typeof value.author !== "string") throw new Error("exact retained comparison binding required");
-  return freeze(value);
-}
-/** Explicit host retention action only. Caller must retain returned identity independently before exposure. */
-export function retainDebriefBlind(harness: DebriefHarness, root: string, input: { manifest: unknown; evidence: unknown[]; qualification: unknown }, author: string): DurableBlindBinding {
-  location(root, author);
-  const comparisonId = harness.retainBlindIntervention(root, input.manifest, input.evidence, input.qualification, author);
-  return binding({ comparisonId, author });
-}
-/** No choose/reveal/archive/seed/role/cost capability is given to a pre-reveal consumer. */
-export function openDebriefBlindPreview(harness: DebriefHarness, root: string, input: DurableBlindBinding) {
-  const b = binding(input); location(root, b.author);
-  const port = harness.openBlindIntervention(root, b.comparisonId, b.author);
-  return Object.freeze({ view: port.view.bind(port), readArtifact: port.readArtifact.bind(port), quality: port.quality.bind(port) });
-}
-/** Existing presenter + existing durable writers. No second decision history or automatic retention/reveal. */
-export function createRetainedDebrief(harness: DebriefHarness, input: {
-  archiveRoot: string; scope: string; author: string; cases: CaseSelection; blind?: DurableBlindBinding;
-  persistence: DebriefPersistence; offset?: number;
-}) {
-  const root = input.archiveRoot, author = input.author, selection = freeze(detached(input.cases)); location(root, author);
-  if (selection.version !== "work-case-v2" && selection.version !== "work-signals-v1") throw new Error("explicit case version required");
-  closed(selection, selection.version === "work-signals-v1" ? ["version", "batchId", "observationId"] : ["version", "batchId"]);
-  if (!sha(selection.batchId) || selection.version === "work-signals-v1" && !sha(selection.observationId)) throw new Error("exact selected batch/observation required");
-  const reviewer = selection.version === "work-signals-v1" ? harness.createWorkSignalReviewer(root, selection.batchId, author) : harness.createWorkCaseReviewer(root, selection.batchId, author);
-  const blindBinding = input.blind ? binding(input.blind) : undefined;
-  if (blindBinding && blindBinding.author !== author) throw new Error("blind author differs from independent operator");
-  const open = harness.openBlindIntervention.bind(harness);
-  const blind = blindBinding ? { ...openDebriefBlindPreview(harness, root, blindBinding),
-    choose: (choice: BlindChoice) => open(root, blindBinding.comparisonId, author).choose(choice),
-    reveal: () => open(root, blindBinding.comparisonId, author).reveal() } : undefined;
-  return createDebriefPresenter({ scope: input.scope, offset: input.offset, operatorIdentity: author, reviewer, blind, blindBinding,
-    signals: selection.version === "work-signals-v1" ? { batchId: selection.batchId, observationId: selection.observationId } : undefined,
-    persistence: input.persistence });
-}

package/src/debrief-render.ts

@@ -1,49 +0,0 @@
-import type { DebriefFrame, DebriefPresenter } from "./debrief.ts";
-import { isDebriefPresenter } from "./debrief.ts";
-const safe = (v: unknown) => String(v).replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, " ");
-export function renderDebrief(view: DebriefFrame, width = 100): string {
-  const lines = ["PI-DADDY — MANUAL DEBRIEF / WEEKLY QUEUE", `State: ${view.state}; automatic presentation UNQUALIFIED`,
-    `Attention: ${view.budgetSpent ?? "UNKNOWN"}/5 allocated slots; ${view.unexposed} incidents not exposed; persistence: ${view.persistence}`,
-    view.fixture ? "FROZEN SYNTHETIC FIXTURE — public seed/artifacts, NOT a real blind study" : "Host identity, pause policy and durability are not authenticated by this view."];
-  if (view.observation) lines.push(`Selected signal batch: ${view.total} cases; observation ${view.observation.id}`,
-    `Observation issues: ${view.observation.issues.join(", ") || "none recorded"}; counts are selected-batch only.`);
-  if (view.remainingBudget === null) lines.push("Attention persistence UNKNOWN — no new exposure allowance is inferred.");
-  if (view.remainingBudget === 0) lines.push("New questions DEFERRED — budget exhausted. Reopen retains the same slots; answers/skip do not refill them.");
-  for (const card of view.cards) {
-    if (card.kind === "case") lines.push(`${card.slot}. CASE — ${card.summary}`, `   ${card.disposition} / ${card.resolution}; labels ${card.actionEnabled ? "enabled" : "unavailable or already submitted"}`);
-    else {
-      lines.push(`${card.slot}. BLIND QUALITY — one shared slot; ${card.choice ? card.choice.kind : "UNSELECTED / UNRESOLVED"}`);
-      for (const variant of card.variants) lines.push(`   ${variant.label}: ${variant.text.join(" | ")}`);
-      lines.push("   Filenames/captions/metadata omitted; arbitrary artifact text may disclose identity.");
-      if (card.revealed) {
-        lines.push("   AFTER QUALITY CHOICE — no routing/adoption authorized");
-        for (const arm of (card.revealed as { arms: { label: string; cost: number | null; costUnit: string; configuration: Record<string, unknown> }[] }).arms) {
-          lines.push(`   ${arm.label}: ${arm.cost ?? "unknown"} ${arm.costUnit}`);
-          for (const [key, value] of Object.entries(arm.configuration)) lines.push(`      ${key}: ${String(value)}`);
-        }
-      }
-      else lines.push(`   Configuration/cost hidden; reveal ${card.choiceConfirmed ? "available" : "locked"}. Choices: one / tie / none / insufficient.`);
-    }
-  }
-  lines.push("Skip and unselected remain unresolved. Labels are not work acceptance, causal proof or routing/adoption.",
-    "Own dashboard commands: label SLOT DISPOSITION NOTE | choose KIND LABEL... | reveal | reconcile SLOT | close | open",
-    "No worker messages, control dispatch or automatic recovery. Missing host callbacks disable actions.");
-  const w = Math.max(40, Math.min(240, Math.floor(width) || 100));
-  return lines.slice(0, 80).map(line => { const text = safe(line); return text.length > w ? text.slice(0, w - 1) + "…" : text; }).join("\n");
-}
-/** The actual existing dashboard action seam; no terminal/worker transport or authority metadata. */
-export async function debriefAction(presenter: DebriefPresenter, command: string): Promise<unknown> {
-  if (!isDebriefPresenter(presenter) || typeof command !== "string" || command.length > 4096) throw new Error("invalid debrief action");
-  const [action, ...args] = command.trim().split(/\s+/), view = presenter.view();
-  if (action === "close" && !args.length) { return presenter.close(); }
-  if (action === "open" && !args.length) { return presenter.open({ mode: "manual", userPresent: true }); }
-  if (action === "reveal" && !args.length) { return presenter.reveal(); }
-  if (action === "choose") { return presenter.choose({ kind: args[0] as "one", labels: args.slice(1) }); }
-  const slot = Number(args[0]), card = view.cards.find(c => c.slot === slot);
-  if (card?.kind !== "case") throw new Error("exact exposed case slot required");
-  if (action === "reconcile" && args.length === 1) { return presenter.reconcile(card.caseManifestId); }
-  if (action === "label" && args.length >= 2) {
-    return presenter.label({ caseManifestId: card.caseManifestId, priorDecisionId: card.priorDecisionId, disposition: args[1] as "skip", note: args.slice(2).join(" ") });
-  }
-  throw new Error("unsupported debrief action");
-}

package/src/debrief.ts

@@ -1,198 +0,0 @@
-import { reviewPage, reviewRequest, matchingHistory, validatedHistory, blindView, blindChoice, byteDigest, dataDigest, dataKey, detached, freeze,
-  sha, closed, type SignalSelection, type ReviewPort, type ReviewItem, type ReviewRequest, type BlindPort, type BlindView, type BlindChoice } from "./debrief-contract.ts";
-export interface DebriefCheckpoint {
-  version: "debrief-checkpoint-v1" | "debrief-checkpoint-v2"; bindingDigest?: string; scope: string; offset: number; operatorIdentity: string | null; caseIds: string[]; blindDigest: string | null;
-  requests: ReviewRequest[]; choice: BlindChoice | null; revealRequested: boolean;
-}
-/** Host-owned attention/transport checkpoint, NOT a dashboard decision ledger. CAS must be durable/atomic. */
-export interface DebriefPersistence {
-  durability: "host-owned" | "fixture-memory";
-  load(): unknown | Promise<unknown>;
-  compareAndSwap(expectedDigest: string | null, next: DebriefCheckpoint): void | Promise<void>;
-}
-export interface DebriefHost {
-  scope: string; offset?: number; operatorIdentity?: string; reviewer: ReviewPort; blind?: BlindPort; persistence?: DebriefPersistence;
-  fixture?: boolean;
-  signals?: SignalSelection;
-  blindBinding?: { comparisonId: string; author: string };
-}
-export interface DebriefFrame {
-  version: "debrief-view-v1"; mode: "manual"; state: string; persistence: "host-checkpoint" | "session-only";
-  total: number; unexposed: number; budgetSpent: number | null; remainingBudget: number | null; cards: ({ kind: "case"; slot: number; caseManifestId: string; priorDecisionId: string | null;
-    summary: string; disposition: string; resolution: "unresolved" | "label-recorded"; actionEnabled: boolean } |
-    { kind: "blind"; slot: number; variants: { label: string; text: string[] }[]; choice: BlindChoice | null; choiceConfirmed: boolean;
-      actionEnabled: boolean; revealed: unknown | null })[];
-  observation?: { batchId: string; id: string; issues: string[] };
-  fixture: boolean; acceptance: "not-assessed"; automatic: "unqualified"; freshness: "snapshot-unknown";
-}
-const presenters = new WeakSet<object>();
-export const isDebriefPresenter = (p: unknown): p is DebriefPresenter => typeof p === "object" && p !== null && presenters.has(p);
-export type DebriefPresenter = ReturnType<typeof createDebriefPresenter>;
-const reasons: Record<string, string> = { repeat_without_progress: "Repeated attempts without recorded progress", economical_exemplar: "Candidate economical exemplar", coverage_gap: "Missing evidence coverage", overdue_checkpoint: "Declared checkpoint overdue", reopened_acceptance: "Previously accepted binding reopened", intent_conflict: "Declared objective intent conflict" };
-function checkpoint(value: unknown, scope: string, offset: number, operatorIdentity: string | null, bindingDigest: string | null): DebriefCheckpoint | null {
-  if (value === null) return null;
-  const c = detached(value) as DebriefCheckpoint;
-  if (!c || Object.keys(c).sort().join() !== (bindingDigest ? "bindingDigest," : "") + "blindDigest,caseIds,choice,offset,operatorIdentity,requests,revealRequested,scope,version" || c.version !== (bindingDigest ? "debrief-checkpoint-v2" : "debrief-checkpoint-v1") || (bindingDigest !== null && c.bindingDigest !== bindingDigest) || c.scope !== scope || c.offset !== offset || c.operatorIdentity !== operatorIdentity || !Array.isArray(c.caseIds) ||
-    new Set(c.caseIds).size !== c.caseIds.length || c.caseIds.length + (c.blindDigest ? 1 : 0) > 5 || c.caseIds.some(id => !/^[a-f0-9]{64}$/.test(id)) ||
-    !(c.blindDigest === null || /^[a-f0-9]{64}$/.test(c.blindDigest)) || !Array.isArray(c.requests) || c.requests.length > c.caseIds.length || typeof c.revealRequested !== "boolean" ||
-    new Set(c.requests.map(r => r.caseManifestId)).size !== c.requests.length || c.requests.some(r => !c.caseIds.includes(reviewRequest(r).caseManifestId)) ||
-    (!c.blindDigest && (c.choice !== null || c.revealRequested)) || (c.revealRequested && !c.choice)) throw new Error("invalid host presentation checkpoint");
-  return c;
-}
-/** Manual host path only. Neither events nor caller-shaped idle/pause claims qualify automatic exposure. */
-export function createDebriefPresenter(host: DebriefHost) {
-  if (typeof host.scope !== "string" || !host.scope || host.scope.length > 256) throw new Error("explicit host presentation scope required");
-  const scope = host.scope, fixture = host.fixture === true, offset = host.offset ?? 0, operatorIdentity = host.operatorIdentity ?? null;
-  if (operatorIdentity !== null && (typeof operatorIdentity !== "string" || !operatorIdentity || operatorIdentity.length > 512 || /[\u0000-\u001f\u007f]/.test(operatorIdentity))) throw new Error("invalid independent operator identity");
-  if (!Number.isSafeInteger(offset) || offset < 0 || offset > 4096) throw new Error("invalid independently selected queue offset");
-  const signals = host.signals ? freeze(detached(host.signals)) : undefined, blindBinding = host.blindBinding ? freeze(detached(host.blindBinding)) : undefined;
-  if (signals) { closed(signals, ["batchId", "observationId"]); if (!sha(signals.batchId) || !sha(signals.observationId)) throw new Error("exact signal selection required"); }
-  if (blindBinding) { closed(blindBinding, ["comparisonId", "author"]); if (!sha(blindBinding.comparisonId) || blindBinding.author !== operatorIdentity || !host.blind?.quality) throw new Error("independent durable blind binding/quality reader required"); }
-  const bindingDigest = signals || blindBinding ? dataDigest({ signals: signals ?? null, blind: blindBinding ?? null }) : null;
-  const reviewer: ReviewPort = Object.freeze({ list: host.reviewer.list.bind(host.reviewer), history: host.reviewer.history.bind(host.reviewer),
-    ...(host.reviewer.decide ? { decide: host.reviewer.decide.bind(host.reviewer) } : {}) });
-  const blind: BlindPort | undefined = host.blind ? Object.freeze({ view: host.blind.view.bind(host.blind), readArtifact: host.blind.readArtifact.bind(host.blind),
-    choose: host.blind.choose.bind(host.blind), reveal: host.blind.reveal.bind(host.blind), ...(host.blind.quality ? { quality: host.blind.quality.bind(host.blind) } : {}) }) : undefined;
-  const persistence: DebriefPersistence | undefined = host.persistence ? Object.freeze({ durability: host.persistence.durability,
-    load: host.persistence.load.bind(host.persistence), compareAndSwap: host.persistence.compareAndSwap.bind(host.persistence) }) : undefined;
-  let saved: DebriefCheckpoint | null = null, items: ReviewItem[] = [], publicBlind: BlindView | null = null;
-  let checkpointKnown = !persistence;
-  let issues: string[] = [];
-  let total = 0, state = "closed", busy = false, poisoned = false, choiceConfirmed = false, revealed: unknown | null = null;
-  let variants: { label: string; text: string[] }[] = [];
-  const outcomes = new Map<string, { disposition: string; prior: string | null; resolution: "unresolved" | "label-recorded" }>();
-  const enabled = () => Boolean(operatorIdentity && persistence && (persistence.durability === "host-owned" || fixture) && reviewer.decide && !poisoned);
-  const persist = async (next: DebriefCheckpoint) => {
-    if (persistence) {
-      await persistence.compareAndSwap(saved ? dataDigest(saved) : null, detached(next));
-      const observed = checkpoint(await persistence.load(), scope, offset, operatorIdentity, bindingDigest);
-      if (!observed || dataDigest(observed) !== dataDigest(next)) throw new Error("checkpoint acknowledgement has no exact readback");
-    }
-    saved = freeze(detached(next));
-  };
-  const exclusive = async <T>(run: () => Promise<T>): Promise<T> => {
-    if (busy || poisoned) throw new Error("debrief busy or persistence unknown"); busy = true;
-    try { return await run(); } finally { busy = false; }
-  };
-  const reconcileItem = async (item: ReviewItem, request: ReviewRequest) => {
-    try {
-      const id = matchingHistory(await reviewer.history(item.caseManifestId), item, request, operatorIdentity ?? "");
-      outcomes.set(item.caseManifestId, { disposition: id ? request.disposition : "unresolved", prior: id ?? item.priorDecisionId,
-        resolution: id && !["skip", "uncertain"].includes(request.disposition) ? "label-recorded" : "unresolved" });
-      return id ? "recorded" : "stale-or-unknown";
-    } catch { outcomes.set(item.caseManifestId, { disposition: "unresolved", prior: item.priorDecisionId, resolution: "unresolved" }); return "unknown"; }
-  };
-  const api = {
-    async open(input: { mode: "manual" | "automatic"; userPresent: boolean; boundary?: string }) {
-      return exclusive(async () => {
-        if (input.mode !== "manual" || !input.userPresent || input.boundary === "busy") { state = "deferred: automatic/absent/busy boundary unqualified"; return api.view(); }
-        try {
-          if (persistence) {
-            const loaded = checkpoint(await persistence.load(), scope, offset, operatorIdentity, bindingDigest);
-            if (saved && (!loaded || dataKey(saved.caseIds) !== dataKey(loaded.caseIds) || saved.blindDigest !== loaded.blindDigest ||
-              saved.choice && dataKey(saved.choice) !== dataKey(loaded.choice) || saved.requests.some(r => !loaded.requests.some(n => dataKey(n) === dataKey(r))) || saved.revealRequested && !loaded.revealRequested)) throw new Error("checkpoint rollback/change; no new allowance");
-            saved = loaded; checkpointKnown = true;
-          }
-          publicBlind = blind ? blindView(await blind.view()) : null;
-          const page = reviewPage(await reviewer.list(offset, publicBlind ? 4 : 5), publicBlind ? 4 : 5, offset, signals); total = page.total; issues = page.issues ?? [];
-          if (!saved) await persist({ version: bindingDigest ? "debrief-checkpoint-v2" : "debrief-checkpoint-v1", ...(bindingDigest ? { bindingDigest } : {}), scope, offset, operatorIdentity, caseIds: page.items.map(i => i.caseManifestId), blindDigest: publicBlind ? dataDigest(publicBlind) : null, requests: [], choice: null, revealRequested: false });
-          if (saved!.blindDigest !== (publicBlind ? dataDigest(publicBlind) : null) || saved!.caseIds.some(id => !page.items.some(i => i.caseManifestId === id))) throw new Error("changed batch/blind identity; no fresh allowance");
-          items = saved!.caseIds.map(id => page.items.find(i => i.caseManifestId === id)!);
-          if (saved!.choice && publicBlind) blindChoice(saved!.choice, publicBlind);
-          for (const item of items) {
-            const latest = validatedHistory(await reviewer.history(item.caseManifestId), item);
-            const consistent = (latest?.id ?? null) === item.priorDecisionId && (latest?.disposition ?? "unresolved") === item.disposition;
-            outcomes.set(item.caseManifestId, { disposition: consistent ? item.disposition : "unresolved", prior: item.priorDecisionId, resolution: !consistent || ["unresolved", "skip", "uncertain"].includes(item.disposition) ? "unresolved" : "label-recorded" });
-            const request = saved!.requests.find(r => r.caseManifestId === item.caseManifestId); if (request) await reconcileItem(item, request);
-          }
-          variants = [];
-          for (const c of publicBlind?.cards ?? []) {
-            const text: string[] = [];
-            for (const digest of c.artifactDigests) {
-              const bytes = await blind!.readArtifact(c.label, digest);
-              if (!(bytes instanceof Uint8Array) || bytes.byteLength > 65536 || byteDigest(bytes) !== digest) throw new Error("blind artifact unavailable/mismatched");
-              let preview = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-              if (fixture) preview = preview.replace(/Synthetic Layout [AB]/g, "Synthetic layout (fixture caption removed)");
-              text.push(preview.slice(0, 320) + (preview.length > 320 ? " [preview truncated]" : ""));
-            }
-            variants.push({ label: c.label, text });
-          }
-          if (blindBinding) {
-            choiceConfirmed = false; revealed = null;
-            const value = await blind!.quality!();
-            if (value !== null) {
-              const quality = blindChoice(value as BlindChoice, publicBlind!);
-              if (saved!.choice && dataKey(saved!.choice) !== dataKey(quality)) throw new Error("durable quality changed");
-              if (!saved!.choice) await persist({ ...saved!, choice: quality });
-              choiceConfirmed = true;
-            }
-          }
-          state = "open"; return api.view();
-        } catch { state = "unavailable: host data/persistence unknown"; poisoned = true; return api.view(); }
-      });
-    },
-    close() { state = "closed"; return api.view(); },
-    view(): Readonly<DebriefFrame> {
-      const cards: DebriefFrame["cards"] = state === "open" ? items.map((item, i) => ({ kind: "case", slot: i + 1, caseManifestId: item.caseManifestId,
-        priorDecisionId: outcomes.get(item.caseManifestId)?.prior ?? item.priorDecisionId, summary: reasons[item.candidate.reason] ?? "Unresolved case",
-        disposition: outcomes.get(item.caseManifestId)?.disposition ?? "unresolved", resolution: outcomes.get(item.caseManifestId)?.resolution ?? "unresolved",
-        actionEnabled: enabled() && !saved?.requests.some(r => r.caseManifestId === item.caseManifestId) })) : [];
-      if (state === "open" && publicBlind) cards.push({ kind: "blind", slot: cards.length + 1, variants, choice: saved?.choice ?? null, choiceConfirmed,
-        actionEnabled: Boolean(blind && (fixture || operatorIdentity) && persistence && (persistence.durability === "host-owned" || fixture) && !poisoned), revealed });
-      return freeze(detached({ version: "debrief-view-v1", mode: "manual", state, persistence: persistence?.durability === "host-owned" ? "host-checkpoint" : "session-only", total,
-        unexposed: Math.max(0, total - items.length), budgetSpent: saved ? saved.caseIds.length + (saved.blindDigest ? 1 : 0) : poisoned || !checkpointKnown ? null : 0,
-        ...(signals ? { observation: { batchId: signals.batchId, id: signals.observationId, issues } } : {}),
-        remainingBudget: !checkpointKnown || poisoned && !saved ? null : 5 - (saved ? saved.caseIds.length + (saved.blindDigest ? 1 : 0) : 0), cards, fixture, acceptance: "not-assessed", automatic: "unqualified", freshness: "snapshot-unknown" }));
-    },
-    async label(input: ReviewRequest) {
-      const request = reviewRequest(input);
-      return exclusive(async () => {
-        if (state !== "open" || !enabled()) throw new Error("genuine host writer/persistence unavailable");
-        const item = items.find(i => i.caseManifestId === request.caseManifestId); if (!item) throw new Error("case not exposed in this budget");
-        const prior = saved!.requests.find(r => r.caseManifestId === item.caseManifestId);
-        if (prior) { if (dataKey(prior) !== dataKey(request)) throw new Error("one immutable label request per card/pause"); return reconcileItem(item, request); }
-        if (request.priorDecisionId !== item.priorDecisionId) throw new Error("stale displayed label request");
-        try { await persist({ ...saved!, requests: [...saved!.requests, request] }); }
-        catch { poisoned = true; throw new Error("label request persistence unknown; no writer call"); }
-        outcomes.set(item.caseManifestId, { disposition: "unresolved", prior: item.priorDecisionId, resolution: "unresolved" });
-        try { await reviewer.decide!(request); } catch { return "unknown"; }
-        return reconcileItem(item, request);
-      });
-    },
-    async reconcile(caseManifestId: string) {
-      return exclusive(async () => {
-        const item = items.find(i => i.caseManifestId === caseManifestId), request = saved?.requests.find(r => r.caseManifestId === caseManifestId);
-        if (!item || !request) throw new Error("no exact pending request"); return reconcileItem(item, request);
-      });
-    },
-    async choose(input: BlindChoice) {
-      return exclusive(async () => {
-        if (state !== "open" || !blind || !publicBlind || !persistence || !fixture && !operatorIdentity || persistence.durability !== "host-owned" && !fixture) throw new Error("quality persistence/host unavailable");
-        const choice = blindChoice(input, publicBlind);
-        if (saved!.choice && dataKey(saved!.choice) !== dataKey(choice)) throw new Error("quality choice is locked");
-        try { if (!saved!.choice) await persist({ ...saved!, choice }); }
-        catch { poisoned = true; throw new Error("quality persistence unknown; no reveal"); }
-        const chosen = blindChoice(await blind.choose(choice) as BlindChoice, publicBlind);
-        if (dataKey(chosen) !== dataKey(choice)) throw new Error("quality acknowledgement mismatch");
-        if (blindBinding && dataKey(blindChoice(await blind.quality!() as BlindChoice, publicBlind)) !== dataKey(choice)) throw new Error("durable quality readback mismatch");
-        choiceConfirmed = true; return api.view();
-      });
-    },
-    async reveal() {
-      return exclusive(async () => {
-        if (state !== "open" || !blind || !saved?.choice || !choiceConfirmed || !persistence || !fixture && !operatorIdentity) throw new Error("confirmed quality choice required before reveal");
-        try { if (!saved.revealRequested) await persist({ ...saved, revealRequested: true }); }
-        catch { poisoned = true; throw new Error("reveal persistence unknown; no exposure"); }
-        if (blindBinding && dataKey(blindChoice(await blind.quality!() as BlindChoice, publicBlind!)) !== dataKey(saved.choice)) throw new Error("durable quality unavailable/changed");
-        const result = detached(await blind.reveal()) as Record<string, any>;
-        if (!result || Object.keys(result).sort().join() !== "arms,choice,manifestId,routingDefault" || result.routingDefault !== null || !Array.isArray(result.arms) || result.arms.length !== publicBlind!.cards.length || new Set(result.arms.map(a => a.label)).size !== result.arms.length || dataKey(blindChoice(result.choice, publicBlind!)) !== dataKey(saved.choice)) throw new Error("invalid reveal acknowledgement");
-        revealed = { arms: result.arms.map(a => {
-          if (Object.keys(a).sort().join() !== "armId,configuration,cost,costUnit,label" || !publicBlind!.cards.some(c => c.label === a.label) || !["wall_ms", "tool_calls", "usd"].includes(a.costUnit) || !(a.cost === null || typeof a.cost === "number" && Number.isFinite(a.cost) && a.cost >= 0) || typeof a.configuration !== "object" || a.configuration === null || Object.keys(a.configuration).sort().join() !== "configuration,effort,model,prompt,skill" || Object.values(a.configuration).some(v => typeof v !== "string")) throw new Error("invalid reveal arm");
-          return { label: a.label, configuration: a.configuration, cost: a.cost, costUnit: a.costUnit };
-        }), routingDefault: null, adoptionAuthorized: false };
-        return api.view();
-      });
-    },
-  };
-  presenters.add(api); return Object.freeze(api);
-}