wip v28

geraldarthurdavis · geraldarthurdavis · commit d2b843eddfc8 · 2026-05-15T21:02:25.000-03:00
diff --git a/BITCODE_V28_QA.md b/BITCODE_V28_QA.md
@@ -929,9 +929,9 @@ Positive-control expectation:
   Terminal Deposit/Read components, repository/branch/commit source selection,
   execution-history persistence, wallet/GitHub readiness, saved QA SQL, BTD
   ledger readback, and proof/finality/admission primitives.
-- The Fit result must name why the selected ENGI evidence is decisive or why it
-  is insufficient. A decorative Fit summary with no source/proof linkage is a
-  failure.
+- The Fit result must name why the selected deposited source evidence is
+  decisive or why it is insufficient. A decorative Fit summary with no
+  source/proof linkage is a failure.
 - The result must produce one of two honest outcomes:
   - `worthy_fit`: a minimal AssetPack candidate with source revision, evidence
     roots, proof/dedupe/materialization posture, and settlement/finality state;
@@ -941,28 +941,31 @@ Positive-control expectation:
 
 Negative controls:
 
-1. Run or simulate a Read unrelated to the deposited ENGI source, such as
+1. Run or simulate a Read unrelated to the deposited source, such as
    "Find a Solana wallet settlement AssetPack." Expected: no-worthy-fit or
-   clarification, not an ENGI AssetPack.
+   clarification, not a confident AssetPack.
 2. Run or simulate an overly broad Read, such as "Make Bitcode better."
    Expected: clarification or blocked measurement, not a confident Fit.
 3. Run or simulate a Read that would require unavailable source material outside
-   the deposited ENGI revision. Expected: no-worthy-fit or source-scope blocker.
+   the deposited revision. Expected: no-worthy-fit or source-scope blocker.
 
 Manual steps:
 
 1. Hard refresh `/terminal`.
-2. Confirm the Activity area shows the successful ENGI Deposit row and no
+2. Confirm the Activity area shows the successful latest Deposit row and no
    execution-history error.
 3. Confirm the repository selector still shows the deposited repository, the
    selected branch, and the selected commit from the successful Deposit.
-4. In the Read area, select or express the commercial Read scenario above.
-5. Record the Read posture. Capture the `/api/executions/history` request and
-   response; expected status is `201`.
-6. Accept the Read for fit search. Capture `/api/read-review`; expected response
-   has `fitSearchAdmission.admitted=true`. If it remains blocked, the blocker
-   must name the Read-review requirement or measurement deficiency.
-7. Record Fit posture. Capture the `/api/executions/history` request and
+4. In the Deposit + read chain, confirm the Read state panel starts at
+   `draft` and explains that recording a Read does not mean Bitcode found a
+   fit.
+5. Record the measured Read. Capture the `/api/executions/history` request and
+   response; expected status is `201`, and the page must remain in the Read
+   chain with a `measured` next-state message.
+6. Admit the measured Read for fit search. Capture the `/api/executions/history`
+   request and response; expected status is `201` with
+   `fitSearchAdmission.admitted=true`.
+7. Record Fit result posture. Capture the `/api/executions/history` request and
    response; expected status is `201`.
 8. If a branch, AssetPack, BTC fee, ledger anchor, or settlement control becomes
    enabled, inspect the preview first. Only click it if the preview names source
@@ -1000,7 +1003,7 @@ Commercial blockers:
 - Terminal claims delivery, settlement, mint, anchor, or finality that SQL
   readback cannot verify.
 - Any staging-testnet Read/Fit row contains `frontier/*`, mock provider, or
-  protocol-demo source as if it were live deposited ENGI source.
+  protocol-demo source as if it were live deposited source.
 
 ## 2026-05-13 Staging Deployment Readiness Gate
 
diff --git a/uapi/app/api/executions/stream/route.ts b/uapi/app/api/executions/stream/route.ts
@@ -0,0 +1,27 @@
+export const runtime = 'nodejs';
+
+function encodeSse(payload: Record<string, unknown>) {
+  return `data: ${JSON.stringify(payload)}\n\n`;
+}
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const runId = searchParams.get('runId') || null;
+
+  const body = encodeSse({
+    type: 'status',
+    runId,
+    step: 'history-snapshot',
+    progress: 1,
+    message: 'No live execution stream is attached to this persisted Bitcode activity.',
+    detail: 'Terminal is reading the saved activity, output, proof, and posture payloads from execution history.',
+  });
+
+  return new Response(body, {
+    headers: {
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'Content-Type': 'text/event-stream; charset=utf-8',
+    },
+  });
+}
diff --git a/uapi/app/terminal/TerminalDepositReadWorkbench.tsx b/uapi/app/terminal/TerminalDepositReadWorkbench.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 
 import BitcodeMetricGrid from '@/components/base/bitcode/execution/BitcodeMetricGrid';
 
@@ -9,6 +9,7 @@ import TerminalWorkspaceCard from './TerminalWorkspaceCard';
 import {
   buildTerminalFitWorkbenchDraft,
   buildTerminalDepositWorkbenchDraft,
+  buildTerminalReadAdmissionDraft,
   buildTerminalReadMeasurementDraft,
   type TerminalActivityRecordDraft,
 } from './terminal-activity-history';
@@ -30,6 +31,8 @@ function readRowValue(rows: Array<{ label: string; value: string }>, label: stri
   return rows.find((row) => row.label === label)?.value || '—';
 }
 
+type ReadFitProgressState = 'draft' | 'measured' | 'admitted' | 'fit-recorded';
+
 interface TerminalDepositReadWorkbenchProps {
   repositoryContext?: TerminalRepositoryContextState | null;
   onRecordActivity?: (draft: TerminalActivityRecordDraft) => Promise<unknown>;
@@ -42,8 +45,9 @@ export default function TerminalDepositReadWorkbench({
   showDemonstrationWorkbench = true,
 }: TerminalDepositReadWorkbenchProps) {
   const { snapshot } = useTerminalShellBridge();
-  const [recordingKey, setRecordingKey] = useState<'deposit' | 'read' | 'fit' | null>(null);
+  const [recordingKey, setRecordingKey] = useState<'deposit' | 'read' | 'read-admission' | 'fit' | null>(null);
   const [recordMessage, setRecordMessage] = useState<string | null>(null);
+  const [readFitProgress, setReadFitProgress] = useState<ReadFitProgressState>('draft');
   const workbenchSnapshot = useMemo(() => {
     if (showDemonstrationWorkbench) return snapshot;
     return buildLiveTerminalDepositReadWorkbenchSnapshot(repositoryContext);
@@ -52,6 +56,11 @@ export default function TerminalDepositReadWorkbench({
     () => normalizeTerminalDepositReadWorkbench(workbenchSnapshot, repositoryContext),
     [repositoryContext, workbenchSnapshot],
   );
+  const scenarioKey = workbench?.scenarioLabel || '';
+
+  useEffect(() => {
+    setReadFitProgress('draft');
+  }, [scenarioKey]);
 
   const selectedEntryChips = useMemo(() => {
     if (!workbench?.deposit.selectedEntries.length) return [];
@@ -86,10 +95,16 @@ export default function TerminalDepositReadWorkbench({
             ],
           }),
         );
-        setRecordMessage('Read-measurement posture recorded into the Bitcode activity ledger.');
+        setReadFitProgress('measured');
+        setRecordMessage(
+          'Measured Read recorded. Next admit it for source-bound fit search, or stop if the Read is too broad or unrelated to the deposited source.',
+        );
       } else {
         await onRecordActivity(buildTerminalFitWorkbenchDraft(workbench));
-        setRecordMessage('Asset-pack fit and settlement posture recorded into the Bitcode activity ledger.');
+        setReadFitProgress('fit-recorded');
+        setRecordMessage(
+          'Fit posture recorded. This records current fit evidence/readiness; settlement and finality remain blocked unless a worthy fit is evidenced.',
+        );
       }
     } catch (error) {
       setRecordMessage(error instanceof Error ? error.message : 'Unable to record Bitcode workbench posture.');
@@ -98,6 +113,25 @@ export default function TerminalDepositReadWorkbench({
     }
   };
 
+  const handleRecordReadAdmission = async () => {
+    if (!workbench || !onRecordActivity) return;
+
+    setRecordingKey('read-admission');
+    setRecordMessage(null);
+
+    try {
+      await onRecordActivity(buildTerminalReadAdmissionDraft(workbench));
+      setReadFitProgress('admitted');
+      setRecordMessage(
+        'Measured Read admitted for fit search. Next run or record the fit result posture as worthy_fit, no_worthy_fit, or blocked_readiness evidence.',
+      );
+    } catch (error) {
+      setRecordMessage(error instanceof Error ? error.message : 'Unable to admit the measured Read for fit search.');
+    } finally {
+      setRecordingKey(null);
+    }
+  };
+
   if (!workbench) {
     return (
       <TerminalWorkspaceCard
@@ -165,8 +199,8 @@ export default function TerminalDepositReadWorkbench({
           metrics={workbench.read.metrics}
           rows={workbench.read.rows}
           chips={workbench.read.closureCriteria.length ? workbench.read.closureCriteria : workbench.read.targetKinds}
-          actionLabel="Focus read scenarios"
-          actionTarget="terminalReadScenarios"
+          actionLabel={showDemonstrationWorkbench ? 'Focus read scenarios' : 'Review measured Read'}
+          actionTarget={showDemonstrationWorkbench ? 'terminalReadScenarios' : 'terminalReadWorkbench'}
           secondaryActionLabel={recordingKey === 'read' ? 'Recording…' : 'Record read posture'}
           secondaryActionDisabled={recordingKey !== null}
           onSecondaryAction={() => {
@@ -175,6 +209,65 @@ export default function TerminalDepositReadWorkbench({
         />
       </div>
 
+      <section className="mt-5 rounded-[1.45rem] border border-emerald-400/16 bg-emerald-400/[0.06] px-5 py-5">
+        <div className="flex flex-col gap-4 xl:flex-row xl:items-start xl:justify-between">
+          <div>
+            <p className="text-[0.66rem] uppercase tracking-[0.2em] text-emerald-200/80">read state</p>
+            <h3 className="mt-2 text-lg font-semibold text-white">Measured Read before fit result</h3>
+            <p className="mt-2 max-w-3xl text-sm leading-6 text-neutral-300">
+              Recording a Read stores the measured demand frame. It does not mean Bitcode found a fit. Fit search must then return
+              worthy_fit, no_worthy_fit, or blocked_readiness before settlement or finality can proceed.
+            </p>
+          </div>
+          <span className="rounded-full border border-white/10 bg-black/20 px-3 py-2 text-[0.66rem] uppercase tracking-[0.18em] text-neutral-200">
+            {readFitProgress.replace('-', ' ')}
+          </span>
+        </div>
+
+        <div className="mt-5 grid gap-3 md:grid-cols-4">
+          {[
+            { id: 'draft', label: '1. Read framed', detail: 'Repository, branch, commit, and demand frame are visible.' },
+            { id: 'measured', label: '2. Read measured', detail: 'Read posture is persisted as ledger evidence.' },
+            { id: 'admitted', label: '3. Fit admitted', detail: 'Measured Read may enter source-bound fit search.' },
+            { id: 'fit-recorded', label: '4. Result recorded', detail: 'Fit result posture is reviewable before proof or settlement.' },
+          ].map((step) => {
+            const active = step.id === readFitProgress;
+            return (
+              <div
+                key={step.id}
+                className={`rounded-[1.1rem] border px-4 py-4 text-sm ${
+                  active ? 'border-emerald-300/35 bg-emerald-300/10' : 'border-white/8 bg-black/20'
+                }`}
+              >
+                <p className="font-semibold text-neutral-100">{step.label}</p>
+                <p className="mt-2 leading-6 text-neutral-400">{step.detail}</p>
+              </div>
+            );
+          })}
+        </div>
+
+        <div className="mt-5 flex flex-wrap gap-3">
+          <button
+            type="button"
+            disabled={recordingKey !== null || readFitProgress === 'draft'}
+            onClick={() => {
+              void handleRecordReadAdmission();
+            }}
+            className="rounded-[1.25rem] border border-emerald-400/30 bg-emerald-400/10 px-4 py-3 text-sm font-medium text-emerald-100 transition hover:border-emerald-300/50 hover:bg-emerald-400/15 disabled:cursor-not-allowed disabled:opacity-55"
+          >
+            {recordingKey === 'read-admission' ? 'Admitting Read…' : 'Admit measured Read for fit search'}
+          </button>
+          <button
+            type="button"
+            disabled={recordingKey !== null}
+            onClick={() => jumpToShellSection('terminalFitWorkbench')}
+            className="rounded-[1.25rem] border border-white/10 bg-white/5 px-4 py-3 text-sm font-medium text-neutral-100 transition hover:border-white/18 hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-55"
+          >
+            Review fit result posture
+          </button>
+        </div>
+      </section>
+
       <article
         id="terminalFitWorkbench"
         className="mt-5 rounded-[1.6rem] border border-amber-400/18 bg-amber-400/5 px-5 py-5"
@@ -199,7 +292,7 @@ export default function TerminalDepositReadWorkbench({
             }}
             className="rounded-full border border-white/10 bg-white/5 px-3 py-2 text-[0.66rem] uppercase tracking-[0.18em] text-neutral-100 transition hover:border-white/18 hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-60"
           >
-            {recordingKey === 'fit' ? 'Recording…' : 'Record fit posture'}
+            {recordingKey === 'fit' ? 'Recording…' : 'Record fit result posture'}
           </button>
         </div>
         <p className="mt-3 text-sm leading-6 text-neutral-300">{workbench.fit.summary}</p>
diff --git a/uapi/app/terminal/TerminalPageClient.tsx b/uapi/app/terminal/TerminalPageClient.tsx
@@ -325,7 +325,9 @@ export default function TerminalPageClient() {
 
       const nextRun = mapExecutionHistoryRunToWorkspaceRun(payload.execution);
       setLiveRuns((currentRuns) => upsertWorkspaceRun(currentRuns, nextRun));
-      replaceTerminalRoute(nextRun.id, draft.detailSection || 'activity');
+      if (draft.selectAfterRecord !== false) {
+        replaceTerminalRoute(nextRun.id, draft.detailSection || 'activity');
+      }
       void refreshLiveRuns();
       return nextRun;
     },
diff --git a/uapi/app/terminal/TerminalReadScenarioPanel.tsx b/uapi/app/terminal/TerminalReadScenarioPanel.tsx
@@ -174,7 +174,9 @@ export default function TerminalReadScenarioPanel({
         explainer={TERMINAL_WORKSPACE_EXPLAINERS.readScenarios}
       >
         <p className="mt-4 text-sm leading-6 text-neutral-300">
-          {showDemonstrationScenarios ? 'Loading read scenarios…' : 'Waiting for live Read scenarios after Depositing is recorded.'}
+          {showDemonstrationScenarios
+            ? 'Loading read scenarios…'
+            : 'Live Read measurement, admission, and fit-result controls are in the Deposit + read chain.'}
         </p>
       </TerminalWorkspaceCard>
     );
diff --git a/uapi/app/terminal/page.tsx b/uapi/app/terminal/page.tsx
@@ -1,5 +1,5 @@
 import type { Metadata } from 'next';
-import React from 'react';
+import React, { Suspense } from 'react';
 
 import TerminalPageClient from '@/app/terminal/TerminalPageClient';
 
@@ -13,5 +13,17 @@ export const metadata: Metadata = {
 };
 
 export default function TerminalPage() {
-  return <TerminalPageClient />;
+  return (
+    <Suspense
+      fallback={
+        <main className="min-h-screen bg-[#02050d] px-6 pt-32 text-neutral-100">
+          <div className="rounded-2xl border border-emerald-400/15 bg-white/5 px-5 py-5 text-sm text-neutral-300">
+            Reading Terminal route state…
+          </div>
+        </main>
+      }
+    >
+      <TerminalPageClient />
+    </Suspense>
+  );
 }
diff --git a/uapi/app/terminal/terminal-activity-history.ts b/uapi/app/terminal/terminal-activity-history.ts
@@ -16,6 +16,7 @@ export interface TerminalActivityRecordDraft {
   type: string;
   summary: string;
   detailSection?: TerminalTransactionDetailSection;
+  selectAfterRecord?: boolean;
   status?: string;
   input?: Record<string, unknown> | null;
   output?: Record<string, unknown> | null;
@@ -317,6 +318,7 @@ export function buildTerminalReadMeasurementDraft(
   return {
     type: 'agentic-execution:read-measurement',
     detailSection: 'activity',
+    selectAfterRecord: false,
     summary: `Recorded read measurement for ${scenario.label}.`,
     output: {
       readMeasurement: {
@@ -341,6 +343,62 @@ export function buildTerminalReadMeasurementDraft(
   };
 }
 
+export function buildTerminalReadAdmissionDraft(
+  workbench: TerminalDepositReadWorkbench,
+): TerminalActivityRecordDraft {
+  const readMeasurement = {
+    scenario: {
+      id: workbench.scenarioLabel,
+      label: workbench.scenarioLabel,
+      repo: readRowValue(workbench.read.rows, 'Repository'),
+      profile: readRowValue(workbench.read.rows, 'Profile'),
+      selected: true,
+    },
+    parserKind: readRowValue(workbench.read.rows, 'Parser'),
+    closureCriteriaCount: workbench.read.closureCriteria.length,
+    targetKindCount: workbench.read.targetKinds.length,
+  };
+  const readReview = {
+    action: 'accept',
+    status: 'accepted',
+    reviewStage: 'post-measurement-pre-fit',
+    requiredBefore: 'find-fitting-asset-pack',
+    fitSearchAdmission: {
+      admitted: true,
+      admissionReason:
+        'Measured Read is admitted for generic source-bound fit search against the selected deposited repository revision.',
+      admittedStages: ['candidate-recall', 'fit-quality-evaluation', 'asset-pack-result-review'],
+      blockedStages: ['settlement', 'finality', 'minting'],
+    },
+    nextProtocolAction: 'Run fit search and return worthy_fit, no_worthy_fit, or blocked_readiness evidence.',
+  };
+
+  return {
+    type: 'agentic-execution:read-measurement',
+    detailSection: 'activity',
+    selectAfterRecord: false,
+    summary: `Accepted measured Read for fit search for ${workbench.scenarioLabel}.`,
+    output: {
+      readMeasurement,
+      readReview,
+      assetPackCompletion: {
+        bitcodeActivityState: {
+          readMeasurement,
+          readReview,
+          fitSearchAdmission: readReview.fitSearchAdmission,
+        },
+      },
+    },
+    context: {
+      source: 'terminal-deposit-read-workbench',
+      workbench: 'read-admission',
+      scenarioLabel: workbench.scenarioLabel,
+      fitSearchAdmitted: true,
+      readResultState: 'admitted_for_fit_search',
+    },
+  };
+}
+
 export function buildTerminalSupplySelectionDraft(
   selection: TerminalSupplySelectionState,
 ): TerminalActivityRecordDraft {
diff --git a/uapi/hooks/usePipelineExecution.ts b/uapi/hooks/usePipelineExecution.ts
diff --git a/uapi/tests/terminalActivityHistory.test.ts b/uapi/tests/terminalActivityHistory.test.ts
diff --git a/uapi/tests/usePipelineExecution.test.tsx b/uapi/tests/usePipelineExecution.test.tsx
