@hypercarrier/rarebit 0.1.0-alpha.6 → 0.2.1

package/src/rarebit-core.mjs

@@ -6,7 +6,17 @@ 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
+// provider work so a malformed settings value cannot create an unbounded job.
+export const MAX_RAREBIT_SUMMARY_PROMPT_CHARS = 64_000;
+// Receipts have a 48 KiB protocol limit. Keep the configurable Summary field
+// 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 =
+  "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";
 
@@ -274,12 +284,51 @@ function semanticMessages(selection) {
   }));
 }
 
+/**
+ * Resolve the bounded Summary style contract. The setting is a scalar prompt
+ * fragment. The fixed evidence and status contract remains in this module.
+ * The normalized identity is used by the service to prevent a changed prompt
+ * from reusing an older receipt.
+ */
+export function normalizeRarebitSummaryPrompt(value) {
+  if (value === undefined) {
+    return {
+      guidance: DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE,
+      promptIdentity: null,
+    };
+  }
+  if (typeof value !== "string")
+    throw new TypeError("summary_prompt must be a string");
+  const guidance = value.replace(/\r\n?/g, "\n").trim();
+  if (!guidance) throw new TypeError("summary_prompt must not be blank");
+  if (guidance.length > MAX_RAREBIT_SUMMARY_PROMPT_CHARS)
+    throw new RangeError(
+      `summary_prompt must not exceed ${MAX_RAREBIT_SUMMARY_PROMPT_CHARS} UTF-16 characters`,
+    );
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/.test(guidance))
+    throw new TypeError("summary_prompt contains unsafe control characters");
+  return {
+    guidance,
+    promptIdentity:
+      guidance === DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE
+        ? null
+        : sha256({
+            version: RAREBIT_SUMMARY_PROMPT_IDENTITY_VERSION,
+            guidance,
+          }),
+  };
+}
+
 function summaryPromptParts(messages, {
   lifecycleBoundary,
   omittedMessageCount = 0,
   omittedTextChars = 0,
+  summaryPrompt,
+  readCheckpoint,
 } = {}) {
   const ownerRequest = lifecycleBoundary === "owner_request";
+  const resolvedPrompt = normalizeRarebitSummaryPrompt(summaryPrompt);
+  const styleLine = resolvedPrompt.guidance;
   const omission =
     omittedMessageCount > 0 || omittedTextChars > 0
       ? {
@@ -294,7 +343,8 @@ function summaryPromptParts(messages, {
     "You are the HyperCarrier Rarebit summarizer.",
     "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.",
-    "The summary is free-form prose. State when evidence is uncertain, confusing, contradictory, or importantly missing instead of inventing a coherent account.",
+    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.",
@@ -328,55 +378,82 @@ export function composeRarebitSummaryDerivationInput(
     promptVersion = RAREBIT_SUMMARY_PROMPT_VERSION,
     lifecycleBoundary = "manual",
     maxPromptChars = Number.MAX_SAFE_INTEGER,
+    summaryPrompt,
+    readCheckpoint,
   } = {},
 ) {
-  void promptVersion;
   if (
     !RAREBIT_SUMMARY_WRITABLE_LIFECYCLE_BOUNDARIES.includes(lifecycleBoundary)
   )
     throw new TypeError("Unsupported Summary lifecycle boundary");
   if (!Number.isInteger(maxPromptChars) || maxPromptChars < 1)
     throw new RangeError("maxPromptChars must be a positive integer");
+  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 });
+  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,
-    });
+    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,
-      });
+      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 {
     prompt,
+    promptIdentity: resolvedPrompt.promptIdentity,
+    promptVersion,
     coverage: {
       totalMessageCount: allMessages.length,
       includedMessageCount: messages.length,
@@ -425,17 +502,35 @@ function compactLine(value) {
     .trim();
 }
 
-export function normalizeRarebitSummary(value, { maxChars = 2_000 } = {}) {
+function preserveProseLayout(value) {
+  return String(value ?? "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "")
+    .replace(/[\u2028\u2029]/g, "\n")
+    .trim();
+}
+
+export function normalizeRarebitSummary(
+  value,
+  { maxChars = MAX_RAREBIT_SUMMARY_CHARS } = {},
+) {
   if (!Number.isInteger(maxChars) || maxChars < 1)
     throw new RangeError("maxChars must be a positive integer");
-  const compact = compactLine(value);
-  if (!compact) throw new Error("Summary model returned no usable summary");
-  return compact.slice(0, maxChars).trimEnd();
+  if (maxChars > MAX_RAREBIT_SUMMARY_CHARS)
+    throw new RangeError(
+      `maxChars must not exceed ${MAX_RAREBIT_SUMMARY_CHARS}`,
+    );
+  const normalized = preserveProseLayout(value);
+  if (!normalized) throw new Error("Summary model returned no usable summary");
+  if (normalized.length <= maxChars) return normalized;
+  throw new RangeError(
+    `Summary model returned ${normalized.length} characters; configured limit is ${maxChars}`,
+  );
 }
 
 export function normalizeRarebitSummarySynthesis(
   value,
-  { maxChars = 2_000 } = {},
+  { maxChars = MAX_RAREBIT_SUMMARY_CHARS } = {},
 ) {
   let synthesis;
   try {
@@ -456,7 +551,9 @@ export function normalizeRarebitSummarySynthesis(
   if (!RAREBIT_SESSION_STATUS_REASONS[status].includes(reason))
     throw new TypeError("Summary model response has an illegal statusReason");
   return {
-    summary: normalizeRarebitSummary(synthesis.summary, { maxChars }),
+    summary: normalizeRarebitSummary(synthesis.summary, {
+      maxChars,
+    }),
     sessionStatus: status,
     statusReason: reason,
   };
@@ -501,6 +598,7 @@ export function rarebitJobIdentity({
   selection,
   policy = null,
   promptVersion,
+  promptIdentity = null,
   model = null,
 } = {}) {
   if (!new Set(["summary", "title"]).has(operation))
@@ -520,6 +618,7 @@ export function rarebitJobIdentity({
     selectionManifestHash: selection.manifestHash,
     policy: policy === null ? null : normalizeRarebitSummaryPolicy(policy),
     promptVersion: promptVersion ?? null,
+    promptIdentity: promptIdentity ?? null,
     model,
   });
 }

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;
+}