@hypercarrier/rarebit 0.2.0 → 0.3.0

package/scripts/experiment-recap-fullscreen.mjs

@@ -0,0 +1,56 @@
+// Empirical Pi 0.84.2 renderer probe. Uses the native fullscreen renderer and
+// a synthetic terminal adapter; no provider, credentials, or private sessions.
+import assert from "node:assert/strict";
+import { TuiAltScreen, ScrollView, Container, Text } from "@earendil-works/pi-tui";
+import { createRarebitRecapController } from "../src/rarebit-recap.mjs";
+import { selectRarebits } from "../src/rarebit-core.mjs";
+
+const { renderLayoutFrame } = await import(new URL("layout.js", import.meta.resolve("@earendil-works/pi-tui")));
+
+let input;
+const terminal = {
+  columns: 80, rows: 12, kittyProtocolActive: false,
+  start(fn) { input = fn; }, stop() {}, write() {}, moveBy() {},
+  hideCursor() {}, showCursor() {}, clearLine() {}, clearFromCursor() {},
+  clearScreen() {}, setTitle() {}, setProgress() {},
+};
+const branch = [{ type: "message", id: "synthetic-owner", message: { role: "user", content: "Synthetic renderer probe" } }];
+const selection = selectRarebits(branch);
+const receipt = { status: "ok", sessionId: "synthetic-session", jobId: "synthetic-recap",
+  observedAt: new Date(0).toISOString(), sessionStatus: "finished", summary: "SCROLLABLE_RECAP_SENTINEL",
+  selection: { manifestHash: selection.manifestHash, selectorVersion: selection.manifest.selectorVersion } };
+const ctx = { mode: "tui", ui: { setWidget() {} }, sessionManager: {
+  getHeader: () => ({ id: receipt.sessionId }), getSessionFile: () => "/tmp/synthetic-probe.jsonl", getBranch: () => branch,
+} };
+const controller = createRarebitRecapController({
+  appendEntry: (customType, data) => branch.push({ type: "custom", id: "synthetic-recap-entry", customType, data }),
+  readCurrent: async () => ({ receipt, artifactState: { syncState: "assessment_current", applicability: "exact_selection",
+    receiptRef: { jobId: receipt.jobId }, projection: { status: receipt.sessionStatus } } }),
+});
+assert.equal((await controller.showExisting(ctx)).shown, true);
+const document = new Container();
+document.addChild(controller.renderEntry(branch.at(-1), {}, { fg: (_color, text) => text }));
+document.addChild(new Text(Array.from({ length: 30 }, (_, i) => `Synthetic update ${i}`).join("\n"), 0, 0));
+const scroll = new ScrollView(document, { primary: true, follow: "none" });
+const tui = new TuiAltScreen(terminal);
+tui.setLayoutRoot(scroll);
+const received = [];
+tui.addInputListener((data) => { received.push(data); });
+try {
+  tui.start(); tui.renderNow();
+  scroll.scrollToStart(); tui.renderNow();
+  const atTop = renderLayoutFrame(scroll, 80, 12, () => {}).lines;
+  assert.ok(atTop.some((line) => line.includes("SCROLLABLE_RECAP_SENTINEL")));
+  input("\x1b[<65;3;4M"); tui.renderNow();
+  const afterWheel = scroll.scrollTop;
+  assert.ok(afterWheel > 0, "native wheel events scroll the transcript");
+  input("\x1b[<0;3;2M"); input("\x1b[<0;3;2m"); input("g");
+  scroll.scrollToEnd(); tui.renderNow();
+  const atBottom = renderLayoutFrame(scroll, 80, 12, () => {}).lines;
+  assert.ok(!atBottom.some((line) => line.includes("SCROLLABLE_RECAP_SENTINEL")), "recap is not pinned");
+  console.log(JSON.stringify({ pi: "0.84.2", nativeRenderer: true, syntheticTerminal: true,
+    recapVisibleAtTop: true, recapVisibleAtBottom: false, wheelScrollTop: afterWheel,
+    keyboardReachedExtension: received.includes("g"),
+    mouseReachedExtension: received.some((data) => data.startsWith("\x1b[<")),
+  }, null, 2));
+} finally { tui.stop(); controller.dispose(); }

package/src/extension.mjs

@@ -42,6 +42,8 @@ import {
   registerRarebitLifecycle,
 } from "./lifecycle.mjs";
 import { createRarebitRecapController } from "./rarebit-recap.mjs";
+import { createRarebitViewController } from "./rarebit-view.mjs";
+import { readRarebitCurrent } from "./rarebit-store.mjs";
 import {
   openRarebitPalette,
   openRarebitSettings,
@@ -134,9 +136,29 @@ export default function registerPiRarebit(pi, config = {}) {
   const activityReporter =
     explicit.activityReporter ?? createHerdrActivityReporter();
   const recapController = createRarebitRecapController({
+    appendEntry: typeof pi.registerEntryRenderer === "function" && typeof pi.appendEntry === "function"
+      ? (type, data) => pi.appendEntry(type, data) : undefined,
     delayMs: explicit.recap?.delayMs,
     timezone: explicit.recap?.timezone,
   });
+  const viewController = createRarebitViewController();
+  for (const key of ["ctrl+alt+r", "ctrl+super+r"])
+    pi.registerShortcut?.(key, { description: "Toggle Rarebit view", handler: (ctx) => viewController.toggle(ctx) });
+  for (const key of ["ctrl+alt+n", "ctrl+super+n"])
+    pi.registerShortcut?.(key, { description: "Next Rarebit view", handler: (ctx) => viewController.cycle(ctx) });
+  pi.on("session_compact", () => viewController.refresh());
+  pi.on("message_end", () => viewController.refresh());
+  pi.registerEntryRenderer?.("rarebit-recap", recapController.renderEntry);
+  const acknowledgeRecap = (ctx) => {
+    const result = recapController.acknowledge(ctx);
+    notify(ctx, result.acknowledged ? "Recap marked as read" :
+      result.reason === "already_read" ? "Recap already marked as read" : "No Recap to mark as read in this branch", "info");
+  };
+  if (typeof pi.registerEntryRenderer === "function")
+    pi.registerShortcut?.("ctrl+alt+g", {
+      description: "Mark the latest Recap as read",
+      handler: async (ctx) => acknowledgeRecap(ctx),
+    });
   const projectActivity = (ctx) => {
     const entries = ctx?.sessionManager?.getBranch?.() ?? [];
     return projectRarebitSessionActivity({
@@ -287,7 +309,7 @@ export default function registerPiRarebit(pi, config = {}) {
           );
       },
     });
-    notifyOutcome(ctx, result, synthesisTriggered, effective.diagnostics);
+    if (!force) notifyOutcome(ctx, result, synthesisTriggered, effective.diagnostics);
     recapController.offer({
       ctx,
       result,
@@ -299,7 +321,7 @@ export default function registerPiRarebit(pi, config = {}) {
       rarebitRoot: effective.rarebitRoot,
       allowExternalSession: effective.allowExternalSession === true,
     });
-    return result;
+    return { ...result, rarebitEffective: effective };
   };
   const schedule = createDetachedMaterializer(materialize, (_error, ctx) => {
     notify(
@@ -308,15 +330,49 @@ export default function registerPiRarebit(pi, config = {}) {
       "error",
     );
   });
-  const scheduleManualSummary = createDetachedMaterializer(
-    (ctx) => materialize(ctx, { force: true }),
-    (_error, ctx) =>
-      notify(
-        ctx,
-        "Rarebit Summary failed; inspect its private materialization",
-        "error",
-      ),
-  );
+  const manualAssessmentIsCurrent = async (result, ctx) => {
+    const session = identityFrom(ctx);
+    const generation = activeSession?.generation;
+    const selectionHash = selectRarebits(ctx?.sessionManager?.getBranch?.() ?? []).manifestHash;
+    if (!sameActiveSession(session)) return false;
+    const current = await readRarebitCurrent({
+      sessionFile: session.sessionFile,
+      sessionRoot: result.rarebitEffective?.sessionRoot,
+      rarebitRoot: result.rarebitEffective?.rarebitRoot,
+      allowExternalSession: result.rarebitEffective?.allowExternalSession === true,
+    }).catch(() => null);
+    if (!sameActiveSession(session) || activeSession?.generation !== generation ||
+        !sameActiveSession(identityFrom(ctx)) ||
+        selectRarebits(ctx?.sessionManager?.getBranch?.() ?? []).manifestHash !== selectionHash)
+      return false;
+    return current?.artifactState?.receiptRef?.jobId === result.record?.jobId &&
+      current?.artifactState?.nativeRef?.sessionId === session.sessionId &&
+      current?.artifactState?.nativeRef?.selectionManifestHash === selectionHash &&
+      current?.artifactState?.syncState === "assessment_current";
+  };
+  const scheduleManualSummary = (ctx) => {
+    void materialize(ctx, { force: true }).then(async (result) => {
+      if (result?.inFlight) {
+        notify(ctx, "Rarebit Summary is already in flight", "info");
+        return;
+      }
+      if (result?.record?.status === "ok") {
+        const isCurrent = await manualAssessmentIsCurrent(result, ctx);
+        const duplicate = result?.duplicate === true;
+        notify(ctx,
+          duplicate
+            ? isCurrent ? "Rarebit Summary is already current" : "Rarebit Summary already exists but is not current"
+            : isCurrent ? "Rarebit Summary updated and current" : "Rarebit Summary generated but is not current",
+          isCurrent ? "info" : "warning",
+        );
+        return;
+      }
+      if (result?.record?.status === "skipped_ephemeral_session")
+        notify(ctx, "Rarebit Summary unavailable: Session is not persisted", "warning");
+      else
+        notifyOutcome(ctx, { record: result?.record }, false, result?.rarebitEffective?.diagnostics ?? {});
+    }).catch(() => notify(ctx, "Rarebit Summary failed; inspect its private materialization", "error"));
+  };
 
   const identityFrom = (ctx) => ({
     sessionId: String(
@@ -407,8 +463,9 @@ export default function registerPiRarebit(pi, config = {}) {
 
   registerRarebitLifecycle(pi, schedule, {
     onSessionStart: (ctx, generation) => {
+      viewController.dispose();
       recapController.invalidate(ctx, generation);
-      activeSession = identityFrom(ctx);
+      activeSession = { ...identityFrom(ctx), generation };
       activityReporter.start(projectActivity(ctx));
     },
     onAgentStart: (ctx, generation) => {
@@ -421,6 +478,7 @@ export default function registerPiRarebit(pi, config = {}) {
       recapController.invalidate(ctx, generation);
     },
     onSessionTree: (ctx, _event, generation) => {
+      viewController.refresh();
       recapController.invalidate(ctx, generation);
       activityReporter.update(projectActivity(ctx));
     },
@@ -428,11 +486,13 @@ export default function registerPiRarebit(pi, config = {}) {
       activityReporter.update(projectActivity(ctx));
     },
     onAgentSettled: (ctx) => {
+      viewController.refresh();
       recapController.updateContext(ctx);
       activityReporter.update(projectActivity(ctx));
     },
-    onSessionShutdown: (ctx, generation) => {
-      recapController.invalidate(ctx, generation);
+    onSessionShutdown: () => {
+      viewController.dispose();
+      recapController.dispose();
       activeSession = undefined;
       activityReporter.stop();
     },
@@ -513,6 +573,7 @@ ${fence(requestText)}`;
       let commandInput = String(args ?? "");
       const trimmedCommandInput = commandInput.trim();
       if (!trimmedCommandInput || trimmedCommandInput === "menu") {
+        viewController.dispose();
         const currentUiState = () => ({
           ...identityFrom(ctx),
           branchLeafId: ctx?.sessionManager?.getBranch?.()?.at(-1)?.id ?? null,
@@ -563,7 +624,12 @@ ${fence(requestText)}`;
         );
         return;
       }
+      if (subcommand === "view") {
+        await viewController.command(ctx, rest[0]);
+        return;
+      }
       if (subcommand === "settings") {
+        viewController.dispose();
         const currentUiState = () => ({
           ...identityFrom(ctx),
           branchLeafId: ctx?.sessionManager?.getBranch?.()?.at(-1)?.id ?? null,
@@ -728,7 +794,7 @@ ${fence(requestText)}`;
           : "settings_or_default";
         notify(
           ctx,
-          `Rarebit ${subcommand}: auto-title=${autoTitleOverride ?? effective.autoTitle ?? true}; recap=${effective.recap?.enabled !== false ? "on" : "off"} after ${effective.recap?.delayMs ?? 60000}ms (${effective.recap?.timezone ?? "host"}); diagnostics=triggered:${effective.diagnostics?.summaryTriggered === true ? "on" : "off"},updated:${effective.diagnostics?.summaryUpdated === true ? "on" : "off"}; max_input_tokens=${effective.maxInputTokens ?? 64000}; max_rarebit_ratio=${policy.maxRarebitRatio} (${ratioSource}); min_total_length=${policy.minTotalLength} estimated tokens via ceil(chars/4) (${lengthSource}); measurement=${policy.measurementVersion}; model=${modelLabel(effective.model)} from ${effective.modelProvenance?.settingsKey ?? "explicit config"}${policyStatus}`,
+          `Rarebit ${subcommand}: view=${viewController.activeMode}; auto-title=${autoTitleOverride ?? effective.autoTitle ?? true}; recap=${effective.recap?.enabled !== false ? "on" : "off"} after ${effective.recap?.delayMs ?? 60000}ms (${effective.recap?.timezone ?? "host"}); diagnostics=triggered:${effective.diagnostics?.summaryTriggered === true ? "on" : "off"},updated:${effective.diagnostics?.summaryUpdated === true ? "on" : "off"}; max_input_tokens=${effective.maxInputTokens ?? 64000}; max_rarebit_ratio=${policy.maxRarebitRatio} (${ratioSource}); min_total_length=${policy.minTotalLength} estimated tokens via ceil(chars/4) (${lengthSource}); measurement=${policy.measurementVersion}; model=${modelLabel(effective.model)} from ${effective.modelProvenance?.settingsKey ?? "explicit config"}${policyStatus}`,
           "info",
         );
         return;
@@ -758,6 +824,10 @@ ${fence(requestText)}`;
         );
         return;
       }
+      if (subcommand === "got-it") {
+        acknowledgeRecap(ctx);
+        return;
+      }
       if (subcommand === "recap") {
         if (effective.recap?.enabled === false) {
           recapController.invalidate(ctx);

package/src/rarebit-artifact-state.mjs

@@ -383,6 +383,7 @@ export function validateRarebitArtifactReceipt(record) {
       "hc-rarebit-summary-v4",
       "hc-rarebit-summary-v5",
       "hc-rarebit-summary-v6",
+      "hc-rarebit-summary-v7",
     ].includes(
       record.implementationVersion,
     ) ||
@@ -407,7 +408,7 @@ export function validateRarebitArtifactReceipt(record) {
   if (
     (hasInputCoverage && !validInputCoverage(record.inputCoverage)) ||
     (record.status === "ok" &&
-      ["hc-rarebit-summary-v5", "hc-rarebit-summary-v6"].includes(
+      ["hc-rarebit-summary-v5", "hc-rarebit-summary-v6", "hc-rarebit-summary-v7"].includes(
         record.implementationVersion,
       ) &&
       !hasInputCoverage)
@@ -776,16 +777,7 @@ export function projectRarebitArtifactState({
   const settled = newest(
     exact.filter(({ record }) => record.lifecycleBoundary === "agent_settled"),
   );
-  if (settled && (!activeRequest || newerThan(settled, activeRequest)))
-    return result({
-      syncState: "assessment_current",
-      projection: projection(settled.record),
-      applicability: "exact_selection",
-      nativeRef: nativeReference(native),
-      receiptRef: ref(settled.record),
-      retry: null,
-    });
-  if (activeRequest) {
+  if (activeRequest && !(settled && newerThan(settled, activeRequest))) {
     const cutLength = activeRequest.record.selection.occurrenceCount;
     const settlementPending = native.selection.occurrences
       .slice(cutLength)
@@ -805,7 +797,11 @@ export function projectRarebitArtifactState({
     });
   }
   const assessment = newest(
-    exact.filter(({ record }) => record.lifecycleBoundary !== "owner_request"),
+    exact.filter(({ record }) =>
+      record.lifecycleBoundary === "agent_settled" ||
+      record.lifecycleBoundary === "manual" ||
+      record.lifecycleBoundary === "session_start",
+    ),
   );
   if (assessment)
     return result({

package/src/rarebit-command.mjs

@@ -29,6 +29,11 @@ export const RAREBIT_COMMAND_GRAMMAR = Object.freeze({
       description: "Open interactive Rarebit settings",
       forms: [[], [literal("global", "Edit global Pi settings")], [literal("project", "Edit trusted project settings")]],
     },
+    {
+      name: "view",
+      description: "Read Rarebits in the TUI",
+      forms: [[], [literal("context", "Current context only (experimental)")], [literal("all", "All Rarebits across compactions")], [literal("peek", "All Rarebits with the editor live")], [literal("off", "Normal transcript")]],
+    },
     {
       name: "help",
       description: "Show Rarebit command help",
@@ -93,6 +98,11 @@ export const RAREBIT_COMMAND_GRAMMAR = Object.freeze({
       description: "Show the current Recap in the TUI",
       forms: [[]],
     },
+    {
+      name: "got-it",
+      description: "Mark the latest displayed Recap as read",
+      forms: [[]],
+    },
     {
       name: "summarize",
       description: "Force a Rarebit Summary materialization",

package/src/rarebit-core.mjs

@@ -6,7 +6,7 @@ import { createHash } from "node:crypto";
 // authority.
 export const RAREBIT_SELECTOR_VERSION = "rarebit-selector-v1";
 export const RAREBIT_MEASUREMENT_VERSION = "rarebit-prose-chars-div4-v1";
-export const RAREBIT_SUMMARY_PROMPT_VERSION = "rarebit-summary-v6";
+export const RAREBIT_SUMMARY_PROMPT_VERSION = "rarebit-summary-v8";
 export const RAREBIT_SUMMARY_PROMPT_IDENTITY_VERSION =
   "rarebit-summary-prompt-v1";
 // User guidance is a UTF-16 string in JavaScript. Bound it before any Summary
@@ -16,7 +16,7 @@ export const MAX_RAREBIT_SUMMARY_PROMPT_CHARS = 64_000;
 // well below that limit even when the model returns multi-byte text.
 export const MAX_RAREBIT_SUMMARY_CHARS = 8_000;
 export const DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE =
-  "The summary is free-form prose. State when evidence is uncertain, confusing, contradictory, or importantly missing instead of inventing a coherent account.";
+  "Use 1–2 sentences, at most 300 characters including spaces. Lead with newest changes and needed user action. Flag material uncertainty or conflicting evidence.";
 export const RAREBIT_TITLE_PROMPT_VERSION = "rarebit-title-v1";
 export const RAREBIT_JOB_IDENTITY_VERSION = "rarebit-job-identity-v2";
 
@@ -324,6 +324,7 @@ function summaryPromptParts(messages, {
   omittedMessageCount = 0,
   omittedTextChars = 0,
   summaryPrompt,
+  readCheckpoint,
 } = {}) {
   const ownerRequest = lifecycleBoundary === "owner_request";
   const resolvedPrompt = normalizeRarebitSummaryPrompt(summaryPrompt);
@@ -343,6 +344,7 @@ function summaryPromptParts(messages, {
     "Summarize only what is explicitly stated in the ordered Rarebit evidence stream below.",
     "If an omission record appears, it is authoritative: earlier evidence is unavailable to you. Do not infer what was trimmed, and state when important missing evidence makes the account uncertain or confusing.",
     styleLine,
+    ...(readCheckpoint ? ["A recap_read record marks the evidence covered by the last Recap the user acknowledged. Focus the summary prose on updates AFTER that record, retaining earlier context only when needed to understand them. Acknowledgement does not resolve requests, grant approval, or prove task completion. Assess status against ALL supplied evidence, including unresolved requests before the record. If there are no later updates, say so briefly."] : []),
     "Identify every active, non-superseded request visible in the supplied evidence, not only the last turn. Explicit cancellation, replacement, supersession, and later resolution make an earlier request inactive.",
     "Selected evidence contains only user and assistant message prose at Rarebit continuation or stop boundaries. Tool-call inputs, tool results, hidden reasoning, and transport records are deliberately absent.",
     "Absence of a tool transcript is unobservable and must never by itself imply that work was not performed.",
@@ -377,6 +379,7 @@ export function composeRarebitSummaryDerivationInput(
     lifecycleBoundary = "manual",
     maxPromptChars = Number.MAX_SAFE_INTEGER,
     summaryPrompt,
+    readCheckpoint,
   } = {},
 ) {
   if (
@@ -388,45 +391,63 @@ export function composeRarebitSummaryDerivationInput(
   const resolvedPrompt = normalizeRarebitSummaryPrompt(summaryPrompt);
 
   const allMessages = semanticMessages(selection);
+  const checkpointIndex = readCheckpoint
+    ? selection.occurrences.findIndex((item) => item.sourceEntryId === readCheckpoint.coveredEntryId)
+    : -1;
+  const checkpointMessage = checkpointIndex < 0 ? null : {
+    type: "recap_read", coveredEntryId: readCheckpoint.coveredEntryId,
+    text: "The user acknowledged the Recap covering evidence through this point.",
+  };
+  let start = 0;
   let messages = allMessages.slice();
   let omittedMessageCount = 0;
   let omittedTextChars = 0;
-  let prompt = renderSummaryPrompt(messages, {
-    lifecycleBoundary,
-    summaryPrompt,
-  });
+  const render = () => {
+    const positioned = messages.slice();
+    if (checkpointMessage) {
+      // Keep read metadata beside the retained suffix. If the covered evidence
+      // was trimmed, place the boundary before the first retained occurrence.
+      const insertion = Math.max(0, Math.min(messages.length, checkpointIndex + 1 - start));
+      positioned.splice(insertion, 0, checkpointMessage);
+    }
+    return renderSummaryPrompt(positioned, {
+      lifecycleBoundary, readCheckpoint, omittedMessageCount, omittedTextChars,
+      summaryPrompt,
+    });
+  };
+  let prompt = render();
   while (prompt.length > maxPromptChars && messages.length > 1) {
     messages.shift();
+    start += 1;
     omittedMessageCount += 1;
-    prompt = renderSummaryPrompt(messages, {
-      lifecycleBoundary,
-      omittedMessageCount,
-      summaryPrompt,
-    });
+    prompt = render();
   }
   if (prompt.length > maxPromptChars && messages.length === 1) {
-    const original = messages[0].text;
+    const originalMessage = messages[0];
+    const original = originalMessage.text;
     let low = 0;
     let high = original.length;
     let best = null;
     while (low <= high) {
       const removed = Math.floor((low + high) / 2);
-      const candidate = [{ ...messages[0], text: original.slice(removed) }];
-      const candidatePrompt = renderSummaryPrompt(candidate, {
-        lifecycleBoundary,
-        omittedMessageCount,
-        omittedTextChars: removed,
-        summaryPrompt,
-      });
+      messages[0] = { ...messages[0], text: original.slice(removed) };
+      omittedTextChars = removed;
+      const candidatePrompt = render();
       if (candidatePrompt.length <= maxPromptChars) {
-        best = { messages: candidate, prompt: candidatePrompt, removed };
+        best = { prompt: candidatePrompt, removed };
         high = removed - 1;
       } else low = removed + 1;
     }
     if (best) {
-      messages = best.messages;
+      messages[0] = { ...originalMessage, text: original.slice(best.removed) };
       prompt = best.prompt;
       omittedTextChars = best.removed;
+    } else {
+      // Keep the original evidence and explicit overflow when the fixed
+      // omission contract cannot fit within the caller's budget.
+      messages[0] = originalMessage;
+      omittedTextChars = 0;
+      prompt = render();
     }
   }
   return {

package/src/rarebit-read-checkpoint.mjs

@@ -0,0 +1,59 @@
+import { selectRarebits } from "./rarebit-core.mjs";
+// Native custom entries are UI/read state, never provider conversation messages.
+export const RECAP_ENTRY_TYPE = "rarebit-recap";
+export const RECAP_READ_TYPE = "rarebit-recap-read";
+
+export function latestRecap(branch) {
+  const entries = Array.isArray(branch) ? branch : [];
+  const selection = selectRarebits(entries);
+  return entries.findLast((entry, recapIndex) => {
+    if (entry.type !== "custom" || entry.customType !== RECAP_ENTRY_TYPE || entry.data?.version !== 1 ||
+        typeof entry.data?.jobId !== "string" || typeof entry.data?.coveredEntryId !== "string" ||
+        typeof entry.data?.selectionHash !== "string") return false;
+    const covered = selection.occurrences.find((item) => item.sourceEntryId === entry.data.coveredEntryId);
+    const coveredIndex = covered ? entries.findIndex((item) => item.id === covered.sourceEntryId) : -1;
+    return coveredIndex >= 0 && coveredIndex < recapIndex &&
+      selectRarebits(entries.slice(0, coveredIndex + 1)).manifestHash === entry.data.selectionHash;
+  });
+}
+
+function validatedMarker(entries, marker, selection) {
+  if (marker.type !== "custom" || marker.customType !== RECAP_READ_TYPE || marker.data?.version !== 1)
+    return null;
+  const markerIndex = entries.indexOf(marker);
+  const recapIndex = entries.findIndex((entry) => entry.id === marker.data.recapEntryId);
+  const recap = entries[recapIndex];
+  if (recapIndex < 0 || recapIndex >= markerIndex || recap.customType !== RECAP_ENTRY_TYPE || recap.data?.version !== 1 ||
+      recap.data.jobId !== marker.data.jobId || recap.data.coveredEntryId !== marker.data.coveredEntryId ||
+      recap.data.selectionHash !== marker.data.selectionHash) return null;
+  const covered = selection.occurrences.find((item) => item.sourceEntryId === marker.data.coveredEntryId);
+  const coveredIndex = covered ? entries.findIndex((entry) => entry.id === covered.sourceEntryId) : -1;
+  if (!covered || coveredIndex < 0 || coveredIndex >= recapIndex ||
+      selectRarebits(entries.slice(0, coveredIndex + 1)).manifestHash !== recap.data.selectionHash)
+    return null;
+  return { recap, covered };
+}
+
+export function recapIsRead(branch, recap, selection = selectRarebits(branch)) {
+  const entries = Array.isArray(branch) ? branch : [];
+  return entries.some((marker) => {
+    const valid = validatedMarker(entries, marker, selection);
+    return valid && valid.recap.data.jobId === recap?.data?.jobId &&
+      valid.recap.data.coveredEntryId === recap?.data?.coveredEntryId &&
+      valid.recap.data.selectionHash === recap?.data?.selectionHash;
+  });
+}
+
+export function recapReadCheckpoint(branch, selection) {
+  const entries = Array.isArray(branch) ? branch : [];
+  // Resolve coverage against the referenced earlier Recap. A click acknowledges
+  // that evidence cut, not later conversation or an unvalidated custom entry.
+  for (const marker of entries.slice().reverse()) {
+    const valid = validatedMarker(entries, marker, selection);
+    if (!valid) continue;
+    return { type: "recap_read", markerEntryId: marker.id,
+      recapEntryId: valid.recap.id, coveredEntryId: valid.covered.sourceEntryId,
+      coveredOrder: valid.covered.order };
+  }
+  return null;
+}