pi-daddy 0.22.0 → 0.24.0

package/src/dashboard-host.ts

@@ -0,0 +1,191 @@
+import { isOrdinaryChildren, holdOrdinaryDispatch, type OrdinaryChildren, type OrdinaryCancellation } from "./ordinary-children.ts";
+import { loadedDashboardHarnessDigest } from "./dashboard-harness.ts";
+import { join, isAbsolute } from "node:path";
+import { dataDigest, detached, freeze, sha, reviewPage } from "./debrief-contract.ts";
+import { createRetainedDebrief } from "./debrief-host.ts";
+import type { DebriefCheckpoint, DebriefPresenter, DebriefPersistence } from "./debrief.ts";
+import { debriefAction } from "./debrief-render.ts";
+import { openResourceBudget, resourceBindingDigest, type GovernedBudgetBinding } from "./resource-budget.ts";
+import { dispatchRequest, dispatchRequestDigest, controlShape, type DispatchRequest } from "./dispatch-control.ts";
+import { intentRequest, intentRequestDigest, type IntentRequest } from "./intent-control.ts";
+import { experimentBindingDigest, isExperimentController, type ExperimentCancellation, type openExperiment } from "./experiment.ts";
+import { dashboardObservations } from "./dashboard-observation.ts";
+import { dashboardHostDigest, dashboardHostRequest, dashboardHostRequestDigest, dashboardSelectionDigest,
+  type DashboardHarness, type DashboardHostConfig, type DashboardHostRequest, type DashboardHostAuthority } from "./dashboard-host-contract.ts";
+export * from "./dashboard-host-contract.ts";
+const hosts=new WeakSet<object>();
+export const isDashboardHost=(value:unknown):value is DashboardHost=>typeof value==="object"&&value!==null&&hosts.has(value);
+export type DashboardHost=ReturnType<typeof openDashboardHost>;
+export interface DashboardHostOptions { ordinary?:OrdinaryChildren; harness:DashboardHarness; config:DashboardHostConfig; budget:GovernedBudgetBinding; experiment?:ReturnType<typeof openExperiment>; authority:()=>DashboardHostAuthority|null;
+  /** Exact actions constructed and authorized by the owner; the dashboard exposes only human labels/keys. */
+  humanActions?:(context:{hostDigest:string;selectionDigest:string;tip:string;observations:readonly {sourceId:string;checkpointId:string}[]})=>readonly {key:string;label:string;request:DashboardHostRequest}[]|Promise<readonly {key:string;label:string;request:DashboardHostRequest}[]>;
+  /** Explicit approved observation effect only; refresh/frame never invokes it. */
+  beforeObservation?:(sourceId:string)=>Promise<void>;
+  /** Independently sourced current declaration. Never inferred from idle, a PID, title or request fields. */
+  presence?:()=>{present:boolean;closing:boolean;evidenceDigest:string;expiresAt:number}|null;
+}
+function configuration(input:DashboardHostConfig){
+  const c=detached(input);controlShape(c,["version","trustDirectory","trustPolicyId","archiveRoot","scope","author","policyPath","policySha256","sources","selection","cases","blind","budgetDigest","experimentDigest","harnessArtifactDigest",...(Object.hasOwn(c,"ordinaryDigest")?["ordinaryDigest"]:[])]);
+  if(Object.hasOwn(c,"ordinaryDigest")&&!sha(c.ordinaryDigest))throw Error("invalid ordinary binding digest");
+  if(c.version!=="producer-dashboard-host-v1"||![c.trustDirectory,c.archiveRoot,c.policyPath].every(p=>typeof p==="string"&&isAbsolute(p))||![c.trustPolicyId,c.policySha256,c.budgetDigest,c.harnessArtifactDigest].every(sha)||!(c.experimentDigest===null||sha(c.experimentDigest))||typeof c.scope!=="string"||!c.scope||c.scope.length>128||typeof c.author!=="string"||!c.author||c.author.length>256||!Array.isArray(c.sources)||c.sources.length<1||c.sources.length>32||new Set(c.sources.map(s=>s.id)).size!==c.sources.length||c.sources.filter(s=>s.kind==="work").length>1||c.sources.some(s=>!/^[a-zA-Z0-9:_-]{1,128}$/.test(s.id)||!["work","retention","facts"].includes(s.kind)))throw Error("invalid explicit dashboard host binding");
+  return freeze(c);
+}
+/** Explicit creation, NEVER called by refresh/reconnect. One fixed host child per registered trust store. */
+export function createDashboardHost(options:DashboardHostOptions){
+  const c=configuration(options.config),h=options.harness,a=options.authority();
+  if(loadedDashboardHarnessDigest(h)!==c.harnessArtifactDigest)throw Error("verified loaded harness artifact required");
+  if(!a?.hostDigests.includes(dashboardHostDigest(c)))throw Error("independent exact host authority required");
+  const trust=h.openTrustLifecycle(c.trustDirectory),view=trust.inspect(Date.now());
+  if(view.policyId!==c.trustPolicyId)throw Error("trust policy changed");
+  h.learningJournal(join(c.trustDirectory,"producer-host"),{type:"producer-host-initial",config:c});
+  return openDashboardHost(options);
+}
+/** Existing native writers + original controllers; no model, launch, authority-file loader or PID recovery. */
+export function openDashboardHost(options:DashboardHostOptions){
+  const c=configuration(options.config),h=options.harness,hostDigest=dashboardHostDigest(c),selectionDigest=dashboardSelectionDigest(c.selection);
+  if(loadedDashboardHarnessDigest(h)!==c.harnessArtifactDigest)throw Error("verified loaded harness artifact required");
+  const budget=openResourceBudget(options.budget),experiment=options.experiment,ordinary=options.ordinary;
+  if(ordinary&&(!isOrdinaryChildren(ordinary)||ordinary.bindingDigest!==c.ordinaryDigest))throw Error("original ordinary controller binding required");
+  if(resourceBindingDigest(budget.binding)!==c.budgetDigest||experiment&&(!isExperimentController(experiment)||experimentBindingDigest(experiment.binding)!==c.experimentDigest))throw Error("original controller binding required");
+  const trust=h.openTrustLifecycle(c.trustDirectory),journal=h.learningJournal(join(c.trustDirectory,"producer-host"));
+  const initial=journal.read()[0].value;
+  if(initial.type!=="producer-host-initial"||dataDigest(initial.config)!==hostDigest)throw Error("host store binding changed; no new budget");
+  const trustInput=trust.history()[0].value.input as {archiveRoot:string;component:unknown;exposure:{attentionRemaining:number}|null};
+  if(trustInput.archiveRoot!==c.archiveRoot||trust.inspect(Date.now()).policyId!==c.trustPolicyId||trustInput.exposure&&trustInput.exposure.attentionRemaining>5)throw Error("one scoped five-total attention policy required");
+  const authority=()=>{const a=options.authority();if(!a)return null;const safe=detached(a);if(!safe.hostDigests.includes(hostDigest))return null;return safe;};
+  const observation=dashboardObservations(h,c,journal.read),history=()=>journal.read();
+  const append=(value:Record<string,unknown>)=>journal.append(history().at(-1)!.id,value);
+  const saved=():DebriefCheckpoint|null=>{const rows=history().filter(e=>e.value.type==="checkpoint");return rows.length?detached(rows.at(-1)!.value.checkpoint) as DebriefCheckpoint:null;};
+  let presenter:DebriefPresenter|undefined,busy=false,poisoned=false,presentationRevision:number|null=null,presenceDigest:string|null=null,attentionDeferred:string|null=null;
+  const ordinaryDispatchHoldKey=dataDigest({hostDigest,control:"pause-new-ordinary-dispatch"});
+  let displayedActions:null|{tip:string;actions:{key:string;label:string;operation:DashboardHostRequest["operation"];request:DashboardHostRequest}[];digest:string}=null;
+  const presence=()=>{const p=options.presence?.();return p&&p.present===true&&p.closing===true&&sha(p.evidenceDigest)&&Number.isFinite(p.expiresAt)&&p.expiresAt>Date.now()?p:null;};
+  const persistence:DebriefPersistence={durability:"host-owned",load:saved,compareAndSwap(expected,next){
+    const rows=history(),previous=saved();if((previous?dataDigest(previous):null)!==expected)throw Error("stale attention CAS");
+    if(previous&&(dataDigest(previous.caseIds)!==dataDigest(next.caseIds)||previous.blindDigest!==next.blindDigest))throw Error("no replacement cards or budget refill");
+    const cards=[...next.caseIds,...(next.blindDigest?[next.blindDigest]:[])];if(cards.length>5)throw Error("five total cards");
+    if(!previous)for(const card of cards){const result=trust.expose("producer:"+dataDigest({hostDigest,card}),Date.now());if(result.mode!=="ask"){attentionDeferred=result.reason;throw Error("predeclared policy defers this question: "+result.reason);}}
+    journal.append(rows.at(-1)!.id,{type:"checkpoint",checkpoint:next});
+  }};
+  const boundary=async()=>{const dispatch=await budget.controls(null).inspect(),accounting=await budget.inspect();return {dispatch,active:accounting.active};};
+  const paused=async(revision:number)=>{const b=await boundary();if(ordinary&&!ordinary.quiescent())throw Error("original ordinary children not quiescent");if(experiment){const view=await experiment.inspect();if(view.budget?.active!==0||view.control!=="not-assessed")throw Error("original experiment not quiescent");}if(!b.dispatch.paused||b.dispatch.admission!=="paused"||b.dispatch.revision!==revision||b.active!==0)throw Error("safe paused selection unavailable");};
+  const currentSelection=async()=>budget.binding.intent?(await budget.intentControls(null).inspect()).selection:c.selection;
+  const nativeRead=async()=>({dispatch:await budget.controls(null).inspect(),intent:budget.binding.intent?await budget.intentControls(null).inspect():null,experiment:experiment?await experiment.inspect():null,ordinary:ordinary?ordinary.inspect():null});
+  const availableHumanActions=async()=>{
+    const rows=history(),tip=rows.at(-1)!.id,selection=await currentSelection(),seen=new Set<string>();
+    const declared=await options.humanActions?.({hostDigest,selectionDigest:dashboardSelectionDigest(selection),tip,observations:observation.latest().map(x=>({sourceId:x.sourceId,checkpointId:x.checkpointId}))})??[],a=authority();
+    return declared.map(value=>{const x=detached(value);controlShape(x,["key","label","request"]);const request=dashboardHostRequest(x.request);
+      if(!/^[a-zA-Z0-9:_-]{1,64}$/.test(x.key)||typeof x.label!=="string"||!x.label.trim()||Buffer.byteLength(x.label)>120||seen.has(x.key))throw Error("invalid human dashboard action");seen.add(x.key);
+      if(request.hostDigest!==hostDigest||request.expectedTip!==tip||request.selectionDigest!==dashboardSelectionDigest(selection)||!a?.requestDigests.includes(dashboardHostRequestDigest(request)))throw Error("human dashboard action is stale or not exactly authorized");
+      return {key:x.key,label:x.label,operation:request.operation,request};});
+  };
+  const api={hostDigest,selectionDigest,
+    async frame(){
+      const rows=history(),tip=rows.at(-1)!.id,a=authority();let source:unknown=null,error:string|null=null;
+      let selection=c.selection,selectionState="current-control-snapshot";
+      try{selection=await currentSelection();}catch(e){error=String(e);selectionState="unavailable-host-declaration-only";}
+      try{source=await observation.view(selectionState==="current-control-snapshot"?a:null,selection);}catch(e){error=String(e);}
+      let debrief:unknown=null;
+      if(a&&presenter&&presentationRevision!==null&&presence()?.evidenceDigest===presenceDigest){try{await paused(presentationRevision);debrief=presenter.view();}catch{debrief=null;}}
+      let controls:unknown=null;try{controls=await nativeRead();}catch(e){error=String(e);}
+      const attention=trust.inspect(Date.now());let actions:{key:string;label:string;operation:string}[]=[];
+      try{const available=await availableHumanActions(),digest=dataDigest(available.map(({key,label,operation,request})=>({key,label,operation,requestDigest:dashboardHostRequestDigest(request)})));
+        if(displayedActions?.tip===tip&&displayedActions.digest!==digest)throw Error("displayed dashboard actions changed before journal advance");
+        displayedActions={tip,actions:available,digest};actions=available.map(({key,label,operation})=>({key,label,operation}));}catch(e){error=String(e);}
+      return freeze(detached({version:"producer-dashboard-frame-v1",hostDigest,selectionDigest:dashboardSelectionDigest(selection),selectionState,tip,source,controls,debrief,attention,error,actions,
+        requests:rows.filter(e=>["claim","result","presentation","defer","ordinary-intent-pending"].includes(String(e.value.type))).map(e=>e.value),
+        control:rows.some(e=>e.value.type==="host-failure")?"failed":rows.some(e=>e.value.type==="claim"&&!rows.some(r=>r.value.type==="result"&&r.value.requestId===e.value.requestId))?"unknown":"not-assessed",
+        acknowledgement:poisoned?"unknown":"readback-only",identity:"independently-declared-host; not human/module authentication",activeBranch:null,acceptance:"not-assessed",freshness:"snapshot-unknown",workerInteractions:0}));
+    },
+    /** Explicit reconciliation is read-only. A retained claim is never replayed as an effect. */
+    reconcile:()=>api.frame(),
+    async humanAction(key:string){const tip=history().at(-1)!.id;if(!displayedActions||displayedActions.tip!==tip)throw Error("dashboard actions must be displayed at the current tip");
+      const found=displayedActions.actions.find(action=>action.key===key);if(!found)throw Error(`unknown dashboard action ${JSON.stringify(key)}`);
+      const current=(await availableHumanActions()).find(action=>action.key===key);if(!current||current.label!==found.label||dashboardHostRequestDigest(current.request)!==dashboardHostRequestDigest(found.request))throw Error("displayed dashboard action changed; no effect attempted");return api.action(found.request);},
+    async action(input:DashboardHostRequest){
+      const request=dashboardHostRequest(input),digest=dashboardHostRequestDigest(request);
+      if(busy||poisoned)throw Error("dashboard operation busy or acknowledgement unknown");busy=true;let attempted=false;
+      try{
+        const rows=history(),old=rows.find(e=>e.value.type==="claim"&&e.value.requestId===request.requestId);
+        if(old){if(old.value.digest!==digest)throw Error("immutable dashboard request ID");return {state:rows.some(e=>e.value.type==="host-failure")?"failed-or-unknown":"readback-only",result:rows.find(e=>e.value.type==="result"&&e.value.requestId===request.requestId)?.value??null};}
+        const selection=request.operation==="observe"?await currentSelection().catch(()=>c.selection):await currentSelection();
+        if(request.hostDigest!==hostDigest||request.selectionDigest!==dashboardSelectionDigest(selection)||request.expectedTip!==rows.at(-1)!.id)throw Error("stale dashboard selection/CAS");
+        if(rows.some(e=>e.value.type==="host-failure")||rows.some(e=>e.value.type==="claim"&&!rows.some(r=>r.value.type==="result"&&r.value.requestId===e.value.requestId)))throw Error("prior acknowledgement unknown; inspect without repeating effects");
+        const a=authority(),approved=Boolean(a?.requestDigests.includes(digest));
+        attempted=true;journal.append(request.expectedTip,{type:"claim",requestId:request.requestId,digest,request,decision:approved?"approved":"denied"});
+        if(!approved){append({type:"result",requestId:request.requestId,state:"denied"});return {state:"denied"};}
+        let result:unknown,releaseOrdinary:(()=>void)|undefined;
+        try{
+          if(request.operation==="observe"){
+            const sourceId=(request.payload as {sourceId?:unknown})?.sourceId;if(typeof sourceId!=="string")throw Error("exact observation source required");await options.beforeObservation?.(sourceId);
+            const captured=observation.observe(request.payload,a!,selection);append({type:"observation",observation:captured});result=captured;
+          }else if(request.operation==="present"){
+            const p=detached(request.payload) as {userPresent:boolean;closing:boolean;evidenceDigest:string;dispatchRevision:number};
+            if(Object.keys(p).sort().join()!=="closing,dispatchRevision,evidenceDigest,userPresent"||!sha(p.evidenceDigest)||typeof p.userPresent!=="boolean"||typeof p.closing!=="boolean"||!Number.isSafeInteger(p.dispatchRevision))throw Error("explicit presence/boundary evidence required");
+            if(!p.userPresent||!p.closing||presence()?.evidenceDigest!==p.evidenceDigest){append({type:"defer",requestId:request.requestId,evidence:p,reason:"absent or uncertain closing boundary",weekly:true});presenter?.close();presentationRevision=null;result={state:"deferred"};}
+            else{
+              await paused(p.dispatchRevision);const cases=observation.latest().find(r=>r.kind==="work")?.cases??c.cases;if(!cases)throw Error("retained selected case batch unavailable");
+              const reviewer=cases.version==="work-signals-v1"?h.createWorkSignalReviewer(c.archiveRoot,cases.batchId,c.author):h.createWorkCaseReviewer(c.archiveRoot,cases.batchId,c.author);
+              const page=reviewPage(await reviewer.list(0,c.blind?4:5),c.blind?4:5,0,cases.version==="work-signals-v1"?{batchId:cases.batchId,observationId:cases.observationId}:undefined);
+              if(page.items.some(i=>dataDigest({kind:"detector",...i.candidate.detector as object})!==dataDigest(trustInput.component)))throw Error("case population/version differs from predeclared trust policy");
+              presenter=createRetainedDebrief(h,{archiveRoot:c.archiveRoot,scope:c.scope,author:c.author,cases,blind:c.blind??undefined,persistence});
+              attentionDeferred=null;const view=await presenter.open({mode:"manual",userPresent:true});await paused(p.dispatchRevision);
+              if(attentionDeferred){presenter.close();presentationRevision=null;append({type:"defer",requestId:request.requestId,reason:attentionDeferred,weekly:true});result={state:"deferred",reason:attentionDeferred};}
+              else {if(view.state!=="open")throw Error("presentation data/attention acknowledgement unavailable");
+                presentationRevision=p.dispatchRevision;presenceDigest=p.evidenceDigest;const frameDigest=dataDigest(view);append({type:"presentation",requestId:request.requestId,evidence:p,frameDigest,state:"prepared-not-delivery",automatic:"unqualified"});result={state:"prepared",frameDigest};}
+            }
+          }else if(request.operation==="presented"){
+            const p=detached(request.payload) as {frameDigest:string};if(Object.keys(p).join()!=="frameDigest"||!presenter||presentationRevision===null)throw Error("original prepared presentation required");
+            await paused(presentationRevision);if(presence()?.evidenceDigest!==presenceDigest)throw Error("user absent/presence changed");if(p.frameDigest!==dataDigest(presenter.view()))throw Error("stale presentation acknowledgement");result={state:"host-acknowledged-presentation",frameDigest:p.frameDigest,humanAuthentication:"unqualified"};
+          }else if(request.operation==="defer"){
+            presenter?.close();presentationRevision=null;append({type:"defer",requestId:request.requestId,weekly:true,evidence:request.payload});result={state:"deferred"};
+          }else if(request.operation==="debrief"){
+            if(!presenter||presentationRevision===null||typeof request.payload!=="string")throw Error("original paused presenter required");await paused(presentationRevision);if(presence()?.evidenceDigest!==presenceDigest)throw Error("user absent/presence changed");result=await debriefAction(presenter,request.payload);await paused(presentationRevision);if(result==="unknown"||result==="stale-or-unknown")throw Error("debrief writer acknowledgement unknown");
+          }else{
+            presenter?.close();presentationRevision=null;
+            if(request.operation==="dispatch"||request.operation==="dispatch-reconcile"){
+              const native=dispatchRequest(request.payload as DispatchRequest);if(native.action==="cancel-execution")throw Error("cancellation needs exact separately approved native bridge");
+              const port=budget.controls(a!.dispatch),ordinaryHold=ordinary&&["pause-dispatch","resume-dispatch"].includes(native.action)?holdOrdinaryDispatch(ordinary,ordinaryDispatchHoldKey):undefined;
+              if(request.operation==="dispatch-reconcile"&&(await port.inspect()).records.find(r=>r.request.requestId===native.requestId)?.digest!==dispatchRequestDigest(native))throw Error("exact original dispatch reconciliation required");
+              result=request.operation==="dispatch"?await port.request(native):await port.reconcile(native.requestId);
+              const record=(result as {records:{request:{requestId:string};decision:string;application:string}[]}).records.find(r=>r.request.requestId===native.requestId);
+              if(ordinaryHold&&(record?.decision!=="approved"||native.action==="resume-dispatch"&&record.application==="applied"))ordinaryHold.release();
+            }else if(request.operation==="intent"||request.operation==="intent-reconcile"){
+              const native=detached(intentRequest(request.payload as IntentRequest)) as IntentRequest,port=budget.intentControls(a!.dispatch),digest=intentRequestDigest(native);
+              if(c.ordinaryDigest&&!ordinary)throw Error("original ordinary boundary unavailable; no recovery");
+              if(!ordinary)result=request.operation==="intent"?await port.request(native):await port.reconcile(native);
+              else {
+              const pending=history().filter(e=>e.value.type==="ordinary-intent-pending"&&e.value.nativeRequestId===native.requestId);
+              if(pending.some(e=>e.value.digest!==digest))throw Error("immutable pending ordinary intent ID");
+              if(pending.some(e=>!history().some(row=>{const original=row.value.request as DashboardHostRequest|undefined;return row.value.type==="claim"&&row.value.requestId===e.value.hostRequestId&&row.value.decision==="approved"&&original&&["intent","intent-reconcile"].includes(original.operation)&&intentRequestDigest(original.payload as IntentRequest)===digest;})))throw Error("unbound ordinary pending transport");
+              const exists=(await port.inspect()).records.some(r=>r.requestId===native.requestId);
+              if(request.operation==="intent-reconcile"&&!exists&&!pending.length)throw Error("original pending intent required for reconciliation");
+              if(ordinary&&(a!.dispatch?.authorityDigest!==budget.binding.authorityDigest||!a!.dispatch.requestDigests.includes(digest)))throw Error("independent native intent authority required before ordinary hold");
+              const held=ordinary?holdOrdinaryDispatch(ordinary,dataDigest({hostDigest,digest})):undefined;
+              if(held&&!held.ready()){
+                if(!pending.length)append({type:"ordinary-intent-pending",nativeRequestId:native.requestId,digest,hostRequestId:request.requestId});
+                result={state:"pending-ordinary-boundary",nativeRequestId:native.requestId,application:"not-acknowledged"};
+              }else{
+                result=(request.operation==="intent"||pending.length>0&&!exists)?await port.request(native):await port.reconcile(native);
+                const outcome=(result as {records:{requestId:string;application:string}[]}).records.find(r=>r.requestId===native.requestId);
+                if(held&&!outcome)throw Error("native intent application acknowledgement unavailable");
+                if(held&&["applied","not-applied"].includes(outcome!.application))releaseOrdinary=held.release;
+              }
+              }
+            }else if(request.operation==="ordinary-cancel"){
+              if(!ordinary||!isOrdinaryChildren(ordinary))throw Error("original ordinary child handles unavailable; no recovery");
+              result=ordinary.cancel(request.payload as OrdinaryCancellation,a!.ordinary??null);
+            }else if(request.operation==="cancel"){
+              const p=detached(request.payload) as {dispatch:DispatchRequest;cancellation:ExperimentCancellation};controlShape(p,["dispatch","cancellation"]);const legacy=dispatchRequest(p.dispatch);
+              const current=await budget.controls(null).inspect();
+              if(!experiment||!isExperimentController(experiment)||legacy.action!=="cancel-execution"||legacy.bindingDigest!==c.budgetDigest||legacy.expectedRevision!==current.revision||legacy.targetExecutionId!==p.cancellation.executionId||legacy.requestId!==p.cancellation.requestId)throw Error("exact original cancellation target/revision required");
+              if(a!.dispatch?.authorityDigest!==budget.binding.authorityDigest||!a!.dispatch.requestDigests.includes(dispatchRequestDigest(legacy)))throw Error("independent legacy cancellation authority required");
+              result=await experiment.cancel(p.cancellation,a!.experiment);
+            }else throw Error("unsupported dashboard operation");
+          }
+        }catch(error){presenter?.close();presentationRevision=null;append({type:"result",requestId:request.requestId,state:"failed-or-unknown",reason:String(error)});throw error;}
+        append({type:"result",requestId:request.requestId,state:"acknowledged",resultDigest:dataDigest(result??null)});releaseOrdinary?.();return {state:"acknowledged",result};
+      }catch(error){if(attempted){poisoned=true;try{if(history().some(e=>e.value.type==="claim"&&e.value.requestId===request.requestId))append({type:"host-failure",requestId:request.requestId,reason:String(error)});}catch{/* Failure recording also unacknowledged; no claim of no effects. */}}throw error;}finally{busy=false;}
+    }
+  };hosts.add(api);return Object.freeze(api);
+}

package/src/dashboard-observation.ts

@@ -0,0 +1,45 @@
+import { parseRetentionJson } from "./retention-json.ts";
+import { createHash } from "node:crypto";
+import { createDailyViewReader } from "./daily-view.ts";
+import { dataDigest, detached } from "./debrief-contract.ts";
+import type { DashboardHarness, DashboardHostConfig, DashboardHostAuthority, HostEvent } from "./dashboard-host-contract.ts";
+export interface DashboardObservation { sourceId: string; kind: "work" | "retention" | "facts"; checkpointId: string; sourceManifestId: string | null; metadata: unknown; cases: { version: "work-signals-v1"; batchId: string; observationId: string } | null; linkageManifestId: string | null }
+export function dashboardObservations(h: DashboardHarness, c: DashboardHostConfig, history: () => HostEvent[]) {
+  const reader=createDailyViewReader(), root=c.archiveRoot;
+  const latest=()=>{const rows=new Map<string,DashboardObservation>();for(const e of history())if(e.value.type==="observation") {const row=e.value.observation as unknown as DashboardObservation;rows.set(row.sourceId,row);}return [...rows.values()];};
+  const policy=(id:string)=>{const binding=h.archivePolicyBinding(c.policyPath,id);if(binding.archiveRoot!==root||binding.policySha256!==c.policySha256)throw Error("source policy binding changed");};
+  const bytes=(id:string)=>{const source=h.readArchiveSource(root,id);if(source.status!=="available"||source.reference?.retention!=="exact"||!source.bytes||createHash("sha256").update(source.bytes).digest("hex")!==source.reference.sha256)throw Error("exact retained source unavailable");return Uint8Array.from(source.bytes);};
+  return { latest,
+    observe(payload: unknown, authority: DashboardHostAuthority, selection: DashboardHostConfig["selection"]): DashboardObservation {
+      const input=detached(payload) as {sourceId:string;previousCheckpointId:string|null;facts:unknown};
+      if(Object.keys(input).sort().join()!=="facts,previousCheckpointId,sourceId")throw Error("exact observation request required");
+      const source=c.sources.find(s=>s.id===input.sourceId);if(!source)throw Error("source outside host binding");policy(source.id);
+      const previous=latest().find(r=>r.sourceId===source.id)?.checkpointId??null;if(input.previousCheckpointId!==previous)throw Error("stale observation checkpoint");
+      const captured=h.ingestPolicySource(c.policyPath,source.id,previous??undefined,c.policySha256);policy(source.id);
+      let sourceManifestId:string|null=null,cases:DashboardObservation["cases"]=null,linkageManifestId:string|null=null;
+      if(source.kind==="work"||source.kind==="facts"){
+        const checkpoint=h.readArchiveCheckpoint(root,captured.checkpointId).checkpoint;sourceManifestId=checkpoint.sourceManifestId;bytes(sourceManifestId);
+        if(source.kind==="facts") {if(input.facts!==null)throw Error("facts sources are declarations, not replacement authority");return {sourceId:source.id,kind:source.kind,checkpointId:captured.checkpointId,sourceManifestId,metadata:captured,cases:null,linkageManifestId:null};}
+        const factSource=input.facts===null?null:latest().find(r=>r.kind==="facts"&&r.sourceManifestId===input.facts);if(input.facts!==null&&!factSource)throw Error("exact observed fact source required, not caller replacement facts");
+        const facts=factSource?parseRetentionJson(new TextDecoder("utf-8",{fatal:true}).decode(bytes(factSource.sourceManifestId!)),256*1024):null;
+        captured.factSourceManifestId=factSource?.sourceManifestId??null;captured.factBasis=factSource?"explicit-host-declarations-not-authenticated-truth":"derived-retained-work-only";
+        if(dataDigest(authority.workContext.selectedSnapshot)!==dataDigest(selection))throw Error("independent source selection changed");
+        try { const signals=h.captureArchivedWorkSignals(root,sourceManifestId,authority.workContext,facts);
+          cases={version:"work-signals-v1",batchId:signals.caseBatchId,observationId:signals.observationId};linkageManifestId=signals.linkageManifestId;
+        } catch(error) { captured.semanticFailure=String(error); } // Retain checkpoint/gap even when nomination is unavailable.
+      } else {if(input.facts!==null||captured.kind!=="execution-retention-v2")throw Error("retention source requires exact referenced-blobs policy");h.readRetainedExecution(root,captured.checkpointId);}
+      return {sourceId:source.id,kind:source.kind,checkpointId:captured.checkpointId,sourceManifestId,metadata:captured,cases,linkageManifestId};
+    },
+    async view(authority: DashboardHostAuthority | null, selection: DashboardHostConfig["selection"]) {
+      const rows=latest(), projections:unknown[]=[], manifests:Record<string,Uint8Array>={};let workBytes:Uint8Array|undefined;
+      for(const row of rows){policy(row.sourceId);if(row.kind==="work")workBytes=bytes(row.sourceManifestId!);else if(row.kind==="retention"){
+        const read=h.readRetainedExecution(root,row.checkpointId);projections.push(read.projection);
+        const raw=JSON.parse(new TextDecoder().decode(bytes(row.checkpointId))),manifest=bytes(raw.manifestId);manifests[createHash("sha256").update(manifest).digest("hex")]=manifest;
+      }}
+      const context=authority?.workContext??{selectedSnapshot:selection,authority:null};
+      if(dataDigest(context.selectedSnapshot)!==dataDigest(selection))throw Error("dashboard selection drift");
+      const daily=await reader({workBytes,archiveBytes:Buffer.from(JSON.stringify(h.projectRetainedExecutions(projections))),sourceManifestBytes:manifests,workContext:context});
+      return {daily,observations:rows,coverage:"partial",unobservedSources:c.sources.filter(s=>!rows.some(r=>r.sourceId===s.id)).map(s=>s.id),sourceJobGaps:history().filter(e=>e.value.type==="claim"&&!history().some(r=>r.value.type==="result"&&r.value.requestId===e.value.requestId)).map(e=>String(e.value.requestId)),workerInteractions:0,continuity:"retained-checkpoints-not-live-continuity"};
+    }
+  };
+}

package/src/debrief-contract.ts

@@ -0,0 +1,127 @@
+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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,53 @@
+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

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