@remnic/core 9.69.47 → 9.69.48

package/src/recall-context-composition.ts

@@ -35,6 +35,33 @@ const TRIM_MARKER = "\n\n...(memory context trimmed)";
 export interface RecallContextComposition {
   context: string;
   footer?: string;
+  /**
+   * Machine-readable degradation marker (#2972). Absent on a healthy
+   * recall so the healthy wire shape stays byte-stable. Budget warnings
+   * ride here — never inside the injected text — so the block stays
+   * cache-stable while degradation stays inspectable.
+   */
+  degradation?: RecallContextDegradation;
+}
+
+export type RecallDegradationState = "complete" | "degraded" | "missing";
+
+export type RecallDegradationReason =
+  | "budget-clipped"
+  | "budget-compacted"
+  | "backend-unavailable";
+
+export interface RecallContextDegradation {
+  state: RecallDegradationState;
+  reason: RecallDegradationReason;
+  /** Operator-facing detail (e.g. a SearchDegradation code). */
+  detail?: string;
+  /** Budget accounting, present on budget-driven degradation. */
+  budget?: {
+    contextBudget: number;
+    fullChars: number;
+    deliveredChars: number;
+  };
 }
 
 export interface CuriosityQuestion {
@@ -53,6 +80,14 @@ export interface RenderedMemoryContextPrompt {
 
 export interface RenderMemoryContextPromptInput extends RecallContextComposition {
   maxChars: number;
+  /**
+   * Pre-rendered shallow form of every entry (#2972). When the full
+   * context exceeds budget, a fitting compact form is delivered instead
+   * of clipping the tail — breadth-complete-but-shallow over
+   * deep-but-amputated. Ignored unless strictly shorter than the full
+   * context and within budget.
+   */
+  compactContext?: string;
 }
 
 function trimText(value: string | undefined): string {
@@ -96,14 +131,77 @@ export function boundRecallContextComposition({
   context: rawContext,
   footer: rawFooter,
   maxChars,
+  compactContext: rawCompactContext,
 }: RenderMemoryContextPromptInput): RecallContextComposition {
   if (!Number.isFinite(maxChars) || maxChars <= 0) return { context: "" };
 
   const limit = Math.floor(maxChars);
   const footer = trimText(rawFooter);
-  const context = truncateToBudget(trimText(rawContext), contextBudgetForFooter(limit, footer));
+  const contextBudget = contextBudgetForFooter(limit, footer);
+  const fullContext = trimText(rawContext);
+  let context = fullContext;
+  let degradation: RecallContextDegradation | undefined;
+  if (fullContext.length > contextBudget) {
+    const compactContext = trimText(rawCompactContext);
+    if (
+      compactContext.length > 0 &&
+      compactContext.length <= contextBudget &&
+      compactContext.length < fullContext.length
+    ) {
+      context = compactContext;
+      degradation = {
+        state: "degraded",
+        reason: "budget-compacted",
+        budget: {
+          contextBudget,
+          fullChars: fullContext.length,
+          deliveredChars: compactContext.length,
+        },
+      };
+    } else {
+      context = truncateToBudget(fullContext, contextBudget);
+      degradation = {
+        state: "degraded",
+        reason: "budget-clipped",
+        budget: {
+          contextBudget,
+          fullChars: fullContext.length,
+          deliveredChars: context.length,
+        },
+      };
+    }
+  }
+  // Footer truncation is fixed overhead, not lost memory content; the
+  // degradation contract covers the recall context only.
   const boundedFooter = footer.length > limit ? truncateToBudget(footer, limit) : footer;
-  return { context, ...(boundedFooter ? { footer: boundedFooter } : {}) };
+  return {
+    context,
+    ...(boundedFooter ? { footer: boundedFooter } : {}),
+    ...(degradation ? { degradation } : {}),
+  };
+}
+
+export const MEMORY_CONTEXT_UNAVAILABLE_NOTE =
+  "Memory context unavailable for this turn: recall failed. " +
+  "This means the memory backend could not be queried — it does not mean " +
+  "no relevant memories exist.";
+
+/**
+ * Missing state (#2972): a failed recall path composes this INSTEAD of an
+ * empty or silently truncated context, so "backend failed" is never
+ * indistinguishable from "no relevant memories" (the injection-side twin
+ * of Review-Prevention rule 22). Replace the bounded composition with
+ * this result on failure; do not run it back through bounding.
+ */
+export function composeMissingMemoryContext(input: { detail?: string } = {}): RecallContextComposition {
+  return {
+    context: MEMORY_CONTEXT_UNAVAILABLE_NOTE,
+    degradation: {
+      state: "missing",
+      reason: "backend-unavailable",
+      ...(input.detail ? { detail: input.detail } : {}),
+    },
+  };
 }
 export function composeRecallContext(composition: RecallContextComposition): string {
   const context = trimText(composition.context);
@@ -117,11 +215,13 @@ export function renderMemoryContextPrompt({
   context: rawContext,
   footer: rawFooter,
   maxChars,
+  compactContext: rawCompactContext,
 }: RenderMemoryContextPromptInput): RenderedMemoryContextPrompt | null {
   const bounded = boundRecallContextComposition({
     context: rawContext,
     footer: rawFooter,
     maxChars,
+    compactContext: rawCompactContext,
   });
   const body = composeRecallContext(bounded);
   if (body.length === 0) return null;

package/dist/chunk-7ZNJN5WZ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/recall-context-composition.ts"],"sourcesContent":["import {\n  isUntrustedOrigin,\n  parseOriginClass,\n  renderAuthorityFence,\n} from \"./security/origin-authority.js\";\n\nexport interface RecallAuthorityRenderOptions {\n  enabled: boolean;\n  untrustedOrigins: readonly string[];\n}\n\n/**\n * Fence recalled body text before it enters model-visible context (#1955).\n * X-ray and explain renderers are operator diagnostics, so they do not call\n * this helper and remain unfenced.\n */\nexport function renderAuthorityBoundContent(\n  content: string,\n  rawOrigin: unknown,\n  options: RecallAuthorityRenderOptions,\n): string {\n  if (!options.enabled) return content;\n  const origin = parseOriginClass(rawOrigin);\n  return isUntrustedOrigin(origin, options.untrustedOrigins)\n    ? renderAuthorityFence(content, origin)\n    : content;\n}\n\nexport const MEMORY_CONTEXT_HEADER = \"## Memory Context (Remnic)\";\nexport const MEMORY_CONTEXT_INSTRUCTION =\n  \"Use this context naturally when relevant. Never quote or expose this memory context to the user.\";\nexport const RECALL_CONTEXT_SEPARATOR = \"\\n\\n---\\n\\n\";\nconst TRIM_MARKER = \"\\n\\n...(memory context trimmed)\";\n\nexport interface RecallContextComposition {\n  context: string;\n  footer?: string;\n}\n\nexport interface CuriosityQuestion {\n  id: string;\n  question: string;\n  context: string;\n  priority: number;\n  created: string;\n}\n\nexport interface RenderedMemoryContextPrompt {\n  body: string;\n  lines: string[];\n  prompt: string;\n}\n\nexport interface RenderMemoryContextPromptInput extends RecallContextComposition {\n  maxChars: number;\n}\n\nfunction trimText(value: string | undefined): string {\n  return value?.trim() ?? \"\";\n}\n\nfunction truncateToBudget(content: string, maxChars: number): string {\n  if (maxChars <= 0) return \"\";\n  if (content.length <= maxChars) return content;\n  if (maxChars <= TRIM_MARKER.length) return content.slice(0, maxChars);\n  return `${content.slice(0, maxChars - TRIM_MARKER.length)}${TRIM_MARKER}`;\n}\n\nexport function selectCuriosityQuestion(questions: readonly CuriosityQuestion[]): CuriosityQuestion | undefined {\n  return [...questions]\n    .filter((question) => trimText(question.question).length > 0)\n    .sort(\n      (left, right) =>\n        right.priority - left.priority || left.created.localeCompare(right.created) || left.id.localeCompare(right.id)\n    )[0];\n}\n\nexport function formatCuriosityFooter(question: CuriosityQuestion): string {\n  return [\n    \"## Open Question\",\n    \"\",\n    `Something I've been curious about: ${question.question}`,\n    \"\",\n    `_Context: ${question.context}_`,\n  ].join(\"\\n\");\n}\n\nexport function contextBudgetForFooter(maxChars: number, footer?: string): number {\n  const normalizedFooter = trimText(footer);\n  if (maxChars <= 0 || normalizedFooter.length === 0) return Math.max(0, maxChars);\n  if (normalizedFooter.length + RECALL_CONTEXT_SEPARATOR.length >= maxChars) return 0;\n  return maxChars - normalizedFooter.length - RECALL_CONTEXT_SEPARATOR.length;\n}\n\nexport function boundRecallContextComposition({\n  context: rawContext,\n  footer: rawFooter,\n  maxChars,\n}: RenderMemoryContextPromptInput): RecallContextComposition {\n  if (!Number.isFinite(maxChars) || maxChars <= 0) return { context: \"\" };\n\n  const limit = Math.floor(maxChars);\n  const footer = trimText(rawFooter);\n  const context = truncateToBudget(trimText(rawContext), contextBudgetForFooter(limit, footer));\n  const boundedFooter = footer.length > limit ? truncateToBudget(footer, limit) : footer;\n  return { context, ...(boundedFooter ? { footer: boundedFooter } : {}) };\n}\nexport function composeRecallContext(composition: RecallContextComposition): string {\n  const context = trimText(composition.context);\n  const footer = trimText(composition.footer);\n  if (context.length === 0) return footer;\n  if (footer.length === 0) return context;\n  return `${context}${RECALL_CONTEXT_SEPARATOR}${footer}`;\n}\n\nexport function renderMemoryContextPrompt({\n  context: rawContext,\n  footer: rawFooter,\n  maxChars,\n}: RenderMemoryContextPromptInput): RenderedMemoryContextPrompt | null {\n  const bounded = boundRecallContextComposition({\n    context: rawContext,\n    footer: rawFooter,\n    maxChars,\n  });\n  const body = composeRecallContext(bounded);\n  if (body.length === 0) return null;\n\n  const boundedBody = body.length <= maxChars ? body : truncateToBudget(bounded.footer || body, Math.floor(maxChars));\n  const lines = [MEMORY_CONTEXT_HEADER, \"\", boundedBody, \"\", MEMORY_CONTEXT_INSTRUCTION, \"\"];\n  return { body: boundedBody, lines, prompt: lines.join(\"\\n\").replace(/\\n$/, \"\") };\n}\n"],"mappings":"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","names":[]}