@remnic/core 9.62.0 → 9.62.2

package/src/lifecycle/tombstones.test.ts

@@ -829,6 +829,140 @@ describe("TombstoneStore — revocation supersedes tombstone", () => {
   });
 });
 
+describe("TombstoneStore — rebuild identity preservation (issue #2367)", () => {
+  it("repairs a CJK collision instead of indexing the empty legacy skeleton (issue #2367)", async () => {
+    const env = await makeStore("default");
+    // Two distinct CJK-only strings collide under the lossy legacy normalizer
+    // (both skeletons are empty), so a persisted legacy hash of the source
+    // numerically equals the legacy hash of the body. The empty skeleton
+    // identifies nothing, so rebuild must repair the row to the current body
+    // hash rather than publish the collision key on the exact tier.
+    const source = "利用者は紅茶を好む。";
+    const body = "利用者は珈琲を好む。";
+    const unrelated = "利用者は抹茶を好む。";
+    const persistedHash = computeLegacyContentHash(source);
+    assert.equal(persistedHash, computeLegacyContentHash(body));
+    assert.notEqual(computeHash(source), computeHash(body));
+
+    await env.store.rebuild([
+      {
+        memoryId: "fact-cjk-override",
+        rawContent: body,
+        contentHash: persistedHash,
+        reason: "correction",
+        createdBy: "user_correction",
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+
+    const entry = env.store.snapshot().find((e) => e.kind === "tombstone");
+    assert.ok(entry);
+    assert.equal(entry.contentHash, computeHash(body));
+    assert.equal(entry.currentContentHashAlias, undefined);
+    // The body stays blocked; the shared empty-skeleton key is NOT indexed,
+    // so unrelated CJK bodies (and empty-content writes) are not blocked
+    // through it.
+    assert.equal(
+      env.store.lookup({ namespace: "default", contentHash: computeHash(body) })?.matchedTier,
+      "exact",
+    );
+    assert.equal(
+      env.store.lookup({ namespace: "default", contentHash: computeHash(unrelated) }),
+      null,
+    );
+    assert.equal(
+      env.store.lookup({ namespace: "default", contentHash: computeLegacyContentHash(unrelated) }),
+      null,
+    );
+  });
+
+  it("preserves an explicit identity hash on an empty-skeleton body instead of repairing it", async () => {
+    const env = await makeStore("default");
+    // A CJK-only body normalizes to an empty legacy skeleton, but the
+    // persisted hash here is a DISTINCT explicit contentHashSource — it does
+    // not equal the body's legacy hash, so it identifies an external source,
+    // not the body. Rebuild must keep it (plus the body alias), not replace
+    // it with the current body hash.
+    const body = "利用者は紅茶を好む。";
+    const source = "canonical://source/fact-cjk-explicit";
+    const explicitHash = computeHash(source);
+    assert.notEqual(explicitHash, computeLegacyContentHash(body));
+    assert.notEqual(explicitHash, computeHash(body));
+
+    await env.store.rebuild([
+      {
+        memoryId: "fact-cjk-explicit",
+        rawContent: body,
+        contentHash: explicitHash,
+        reason: "correction",
+        createdBy: "user_correction",
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+
+    const entry = env.store.snapshot().find((e) => e.kind === "tombstone");
+    assert.ok(entry);
+    assert.equal(entry.contentHash, explicitHash);
+    assert.equal(entry.currentContentHashAlias, computeHash(body));
+    // The explicit identity and the body are both blocked.
+    assert.equal(
+      env.store.lookup({ namespace: "default", contentHash: explicitHash })?.matchedTier,
+      "exact",
+    );
+    assert.equal(
+      env.store.lookup({ namespace: "default", contentHash: computeHash(body) })?.matchedTier,
+      "exact",
+    );
+  });
+
+  it("preserves a persisted hash whose ASCII skeleton collides with an accented body", async () => {
+    const env = await makeStore("default");
+    const body = "The user prefers café.";
+    await env.store.rebuild([
+      {
+        memoryId: "fact-accented-override",
+        rawContent: body,
+        contentHash: computeLegacyContentHash(body),
+        reason: "correction",
+        createdBy: "user_correction",
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+    const entry = env.store.snapshot().find((e) => e.kind === "tombstone");
+    assert.ok(entry);
+    // The legacy equality is ambiguous (the skeleton "the user prefers caf"
+    // is shared with distinct strings), so the persisted identity is kept and
+    // the current body hash rides along as the alias.
+    assert.equal(entry.contentHash, computeLegacyContentHash(body));
+    assert.equal(entry.currentContentHashAlias, computeHash(body));
+    assert.equal(
+      env.store.lookup({ namespace: "default", contentHash: computeHash(body) })?.matchedTier,
+      "exact",
+    );
+  });
+
+  it("keeps a single identity when the persisted hash already equals the current body hash", async () => {
+    const env = await makeStore("default");
+    const body = "The cache uses Redis.";
+    await env.store.rebuild([
+      {
+        memoryId: "fact-unambiguous",
+        rawContent: body,
+        contentHash: computeLegacyContentHash(body),
+        reason: "correction",
+        createdBy: "user_correction",
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+    const entry = env.store.snapshot().find((e) => e.kind === "tombstone");
+    assert.ok(entry);
+    // Pure-ASCII body: legacy and current normalizers agree, so the legacy
+    // hash equals the current hash and there is nothing to preserve.
+    assert.equal(entry.contentHash, computeHash(body));
+    assert.equal(entry.currentContentHashAlias, undefined);
+  });
+});
+
 describe("TombstoneStore — rebuild equivalence", () => {
   it("rebuild from a fixture corpus reproduces identical lookup decisions", async () => {
     const env = await makeStore("default");

package/src/lifecycle/tombstones.ts

@@ -41,7 +41,11 @@
 // ---------------------------------------------------------------------------
 
 import { serializeMutations, withHeldFileLock } from "../utils/serialize-mutations.js";
-import { computeLegacyContentHash } from "../content-hash.js";
+import {
+  computeLegacyContentHash,
+  isUnambiguousLegacyContentHash,
+  normalizeLegacyContent,
+} from "../content-hash.js";
 
 /** Why a tombstone was emitted. */
 export type TombstoneReason =
@@ -896,10 +900,33 @@ export class TombstoneStore {
           const currentHash = this.options.hashContent(m.rawContent);
           const currentNormalizedText = this.options.normalizeText(m.rawContent);
           const persistedHash = m.contentHash;
+          // A persisted hash equal to the body's LEGACY hash only proves the
+          // record predates the Unicode normalizer when that legacy hash is
+          // unambiguous. When the legacy normalizer is lossy for this body
+          // (any body whose ASCII skeleton collides with a distinct
+          // contentHashSource), the equality cannot distinguish "old body
+          // hash" from "explicit source identity" — replacing the persisted
+          // hash would displace a live identity (issue #2367). Preserving
+          // keeps BOTH keys: contentHash stays the persisted identity and
+          // currentContentHashAlias still blocks the body.
+
+          // Repair only when the persisted hash provably identifies THIS
+          // body's stale legacy hash: either the unambiguous case (legacy and
+          // current normalizations agree), or the empty-skeleton case — every
+          // non-ASCII-only body normalizes to the empty legacy skeleton, so a
+          // persisted hash equal to hash("") is the shared non-identifying
+          // legacy body hash and publishing it on the exact tier would
+          // collide unrelated tombstones. Any OTHER persisted hash on an
+          // empty-skeleton body is a distinct explicit identity (e.g.
+          // contentHashSource) and must be preserved.
+          const legacyBodyHash = computeLegacyContentHash(m.rawContent);
+          const repairEmptySkeleton =
+            normalizeLegacyContent(m.rawContent).length === 0 && persistedHash === legacyBodyHash;
           const preserveOverride =
             persistedHash !== undefined &&
             persistedHash !== currentHash &&
-            persistedHash !== computeLegacyContentHash(m.rawContent);
+            !repairEmptySkeleton &&
+            !isUnambiguousLegacyContentHash(m.rawContent, persistedHash, currentNormalizedText);
           return {
             id:
               existingBySource.get(`${m.memoryId}\u{0000}${m.supersessionKey ?? ""}`) ??

package/src/orchestration/episodic-context-section.ts

@@ -0,0 +1,255 @@
+/**
+ * Episodic-context recall section (issue #2331, harmonic-memory P3).
+ *
+ * Extracted sibling of `recallInternal`'s final assembly phase: resolves the
+ * structured `sources` provenance of the top recalled facts to LCM archive
+ * turn ranges, groups overlapping ranges into episodes, and appends the raw
+ * turns as a `## Source Episodes` section — pure lookup + formatting, no LLM
+ * calls, read-only archive access, inside the enrichment deadline.
+ *
+ * Opt-in: the registry entry is gated on `episodicContextEnabled === true`
+ * (default off), so flag-off returns before touching the archive and recall
+ * output stays byte-identical.
+ */
+
+import { lcmSessionKeyForNamespace } from "../coding/coding-namespace.js";
+import { type EpisodicFactInput, planEpisodeWindowsWithFallback } from "../episodic-context.js";
+import type { LcmMessage } from "../lcm/archive.js";
+import { log } from "../logger.js";
+import {
+  type RecallSectionMetric,
+  resolveRecallCoreSectionDeadlineMs,
+  runRecallSectionWithinDeadline,
+} from "../recall-qos.js";
+import { cleanArchivedUserMessage } from "../user-message-cleaning.js";
+import type { RecallSectionBuckets } from "./recall-section-coordinator.js";
+import type { RecallInternalDeps } from "./recall-internal-deps.js";
+import type { ScopePlan } from "../scopes/scope-plan.js";
+
+/** Cap on recalled facts whose provenance is read per recall. */
+const EPISODIC_FACT_SCAN_LIMIT = 8;
+/** Per-turn character cap inside a Source Episodes block. */
+const EPISODIC_TURN_CHAR_LIMIT = 300;
+
+export async function appendEpisodicContextSection(
+  deps: RecallInternalDeps,
+  options: {
+    sectionBuckets: RecallSectionBuckets;
+    recalledMemoryPaths: string[];
+    recalledMemoryNamespaces: Array<string | undefined>;
+    scopePlan: ScopePlan;
+    namespacesEnabled: boolean;
+    enrichmentSectionDeadlineMs: number;
+    recallOuterTimeoutMs: number;
+    recallStart: number;
+    abortSignal?: AbortSignal;
+    recordMetric: (metric: RecallSectionMetric) => void;
+  },
+): Promise<void> {
+  const engine = deps.lcmEngine;
+  if (!engine?.enabled) return;
+  if (!deps.isRecallSectionEnabled("episodic-context", false)) return;
+  const maxEpisodes =
+    deps.getRecallSectionNumber("episodic-context", "maxResults") ?? 2;
+  const maxTurns = deps.getRecallSectionNumber("episodic-context", "maxTurns") ?? 8;
+  const skip = (timing: string) =>
+    options.recordMetric({
+      section: "episodicContext",
+      priority: "enrichment",
+      durationMs: 0,
+      deadlineMs: options.enrichmentSectionDeadlineMs,
+      source: "skip",
+      success: true,
+      timing,
+    });
+  if (maxEpisodes <= 0 || maxTurns <= 0) {
+    // Zero semantics (checklist item 33): disable before any archive query.
+    skip("skip(limit=0)");
+    return;
+  }
+  if (options.recalledMemoryPaths.length === 0) {
+    skip("skip(no-memories)");
+    return;
+  }
+
+  const outerDeadlineAtMs =
+    options.recallOuterTimeoutMs > 0
+      ? options.recallStart + options.recallOuterTimeoutMs
+      : null;
+  const remainingOuterMs =
+    outerDeadlineAtMs === null ? null : outerDeadlineAtMs - deps.recallAssemblyClockMs();
+  const deadlineMs = resolveRecallCoreSectionDeadlineMs({
+    configuredCoreDeadlineMs: options.enrichmentSectionDeadlineMs,
+    remainingOuterMs,
+  });
+
+  const outcome = await runRecallSectionWithinDeadline<string | null>({
+    deadlineMs,
+    fallback: null,
+    parentSignal: options.abortSignal,
+    run: async (signal) => {
+      // 1. Structured provenance from the top recalled facts. Facts whose
+      // frontmatter carries no `sources` array are silently skipped (no
+      // legacy scalar `source` parsing — issue non-goal).
+      const facts: EpisodicFactInput[] = [];
+      const scanLimit = Math.min(
+        options.recalledMemoryPaths.length,
+        EPISODIC_FACT_SCAN_LIMIT,
+      );
+      for (let index = 0; index < scanLimit; index += 1) {
+        const memoryPath = options.recalledMemoryPaths[index]!;
+        const namespace = options.recalledMemoryNamespaces[index];
+        try {
+          const storage = await deps.storageRouter.storageFor(
+            namespace ?? deps.config.defaultNamespace,
+          );
+          const memory = await storage.readMemoryByPath(memoryPath);
+          const sources = memory?.frontmatter?.sources;
+          if (memory && Array.isArray(sources) && sources.length > 0) {
+            facts.push({
+              memoryId: memory.frontmatter.id,
+              rank: index,
+              sources,
+            });
+          }
+        } catch (err) {
+          log.debug(
+            `episodic-context: provenance read failed for ${memoryPath}`,
+            err,
+          );
+        }
+      }
+      if (facts.length === 0) return null;
+
+      // 2. Authoritative LCM session ids for a provenance sessionKey
+      // (checklist item 30): only keys framed under the caller's authorized read
+      // namespaces. A foreign session's rows live under a foreign namespace
+      // frame and are unreachable through this mapping.
+      const readNamespaces = options.namespacesEnabled
+        ? options.scopePlan.lcmReadNamespaces
+        : [deps.config.defaultNamespace];
+      const candidateSessionIds = (sessionKey: string): string[] => {
+        const seen = new Set<string>();
+        const out: string[] = [];
+        for (const namespace of readNamespaces) {
+          const key =
+            lcmSessionKeyForNamespace(
+              namespace,
+              sessionKey,
+              deps.config.defaultNamespace,
+            ) ?? sessionKey;
+          if (!seen.has(key)) {
+            seen.add(key);
+            out.push(key);
+          }
+        }
+        return out;
+      };
+
+      // 3. Plan windows (pure) with the single documented quote fallback.
+      const windows = await planEpisodeWindowsWithFallback({
+        recalledFacts: facts,
+        maxEpisodes,
+        maxTurnsPerEpisode: maxTurns,
+        locateQuote: async (quote, sessionKey) => {
+          for (const sessionId of candidateSessionIds(sessionKey)) {
+            try {
+              const hits = await engine.searchContextFull(quote, 1, sessionId);
+              if (hits.length > 0) return hits[0]!.turn_index;
+            } catch (err) {
+              // One failing session read must not sink the fallback; try the
+              // next candidate (fail-open per candidate).
+              log.debug(
+                `episodic-context: quote search failed for session ${sessionId}`,
+                err,
+              );
+            }
+          }
+          return null;
+        },
+      });
+      if (windows.length === 0) return null;
+
+      // 4. Fetch + clean raw turns. `getMessages` bounds are inclusive, so
+      // the exclusive `toTurn` passes as `toTurn - 1`.
+      const episodes: Array<{
+        sessionKey: string;
+        fromTurn: number;
+        toTurn: number;
+        memoryIds: readonly string[];
+        turns: ReadonlyArray<{ role: string; content: string }>;
+      }> = [];
+      for (const window of windows) {
+        if (signal.aborted) break;
+        let rows: LcmMessage[] = [];
+        for (const sessionId of candidateSessionIds(window.sessionKey)) {
+          try {
+            const fetched = await engine.getTurnRange(
+              sessionId,
+              window.fromTurn,
+              window.toTurn - 1,
+            );
+            if (fetched.length > 0) {
+              rows = fetched;
+              break;
+            }
+          } catch (err) {
+            // A failing session read skips that candidate only; the window
+            // is dropped when every candidate fails (fail-open).
+            log.debug(
+              `episodic-context: turn-range read failed for session ${sessionId}`,
+              err,
+            );
+          }
+        }
+        if (rows.length === 0) continue;
+        const turns = rows
+          .filter((m) => m.role === "user" || m.role === "assistant")
+          .map((m) => ({
+            role: m.role,
+            content:
+              m.role === "user"
+                ? cleanArchivedUserMessage(m.content)
+                : m.content,
+          }))
+          .map((turn) => ({
+            ...turn,
+            content:
+              turn.content.length > EPISODIC_TURN_CHAR_LIMIT
+                ? `${turn.content.slice(0, EPISODIC_TURN_CHAR_LIMIT)}…`
+                : turn.content,
+          }));
+        if (turns.length === 0) continue;
+        episodes.push({
+          sessionKey: window.sessionKey,
+          fromTurn: window.fromTurn,
+          toTurn: window.toTurn,
+          memoryIds: window.memoryIds,
+          turns,
+        });
+      }
+      return episodes.length > 0
+        ? deps.recallResultFormatter.formatEpisodicContext(episodes)
+        : null;
+    },
+  });
+
+  options.recordMetric({
+    section: "episodicContext",
+    priority: "enrichment",
+    durationMs: outcome.durationMs,
+    deadlineMs,
+    source: outcome.timedOut ? "timeout" : "fresh",
+    success: true,
+    ...(outcome.timedOut
+      ? { timing: `timeout(${Math.max(0, Math.round(outcome.durationMs))}ms)` }
+      : {}),
+  });
+  if (outcome.value === null) return;
+  const maxChars = deps.getRecallSectionMaxChars("episodic-context");
+  const body =
+    typeof maxChars === "number"
+      ? deps.truncateRecallSectionToBudget(outcome.value, maxChars)
+      : outcome.value;
+  deps.appendRecallSection(options.sectionBuckets, "episodic-context", body);
+}

package/src/orchestration/recall-internal-deps.ts

@@ -13,6 +13,7 @@ import type { EvalShadowRecallRecord } from "../evals.js";
 import type { HarmonicRetrievalResult } from "../harmonic-retrieval.js";
 import type { StorageManager } from "../index.js";
 import type { LcmEngine } from "../lcm/index.js";
+import type { RecallResultFormatter } from "./recall-result-formatter.js";
 import type { NamespaceCatalog } from "../namespaces/catalog.js";
 import type { NamespaceStorageRouter } from "../namespaces/storage.js";
 import type { ObjectiveStateSearchResult } from "../objective-state.js";
@@ -248,6 +249,7 @@ export interface RecallInternalDeps {
   formatHarmonicRetrievalResults(
     results: HarmonicRetrievalResult[],
   ): string;
+  readonly recallResultFormatter: RecallResultFormatter;
   formatObjectiveStateResults(
     results: ObjectiveStateSearchResult[],
   ): string;

package/src/orchestration/recall-internal.ts

@@ -70,9 +70,9 @@ import { isDisagreementPrompt } from "../signal.js";
 import { buildTargetedFactRecallSection, shouldRecallTargetedFactEvidence } from "../targeted-fact-recall.js";
 import { shouldFilterSupersededFromRecall } from "../temporal-supersession.js";
 import { queryTemporalTimelineAsync } from "../temporal-index.js";
-import { buildTemporalTimelineRecallSection, type TemporalTimelineRecallItem } from "../temporal-timeline-recall.js";
-import { isValidAsOf } from "../temporal-validity.js";
 import { type TrustStageResultItem, projectTrustForXray } from "../trust-score-stage.js";
+import { isValidAsOf } from "../temporal-validity.js";
+import { buildTemporalTimelineRecallSection, type TemporalTimelineRecallItem } from "../temporal-timeline-recall.js";
 import { searchTrustZoneRecords } from "../trust-zones.js";
 import type { IdentityInjectionMode, MemoryFile, QmdSearchResult, RecallPlanMode } from "../types.js";
 import { type VerifiedEpisodeResult, compareVerifiedEpisodeResults, searchVerifiedEpisodes } from "../verified-recall.js";
@@ -105,6 +105,7 @@ import {
   type RecallResultPartitionSink,
 } from "./recall-rerank-coordinator.js";
 import type { RecallInternalDeps } from "./recall-internal-deps.js";
+import { appendEpisodicContextSection } from "./episodic-context-section.js";
 import { resolveCompositeProfileStorage } from "./recall-profile-storage.js";
 
 export class RecallInternalCoordinator {
@@ -469,29 +470,16 @@ export class RecallInternalCoordinator {
       scopeProfilePlan,
       lcmReadSessionIds,
     } = scopePlan;
-    // Query an LCM-backed read across the ordered read key set and return the
-    // FIRST non-empty result (#1505 fallback-namespace unification). The primary
-    // overlay key is tried first; if a branch-scoped session has no rows under its
-    // branch key, the project / root fallback keys are tried in order.
-    //
-    // #1505 codex P2 ("Merge LCM fallback reads instead of short-circuiting"): the
-    // query-SCORED sections (explicit-cue, targeted-facts, focused-list,
-    // response-guidance, event-order, structured message-parts) no longer use this
-    // helper — they MERGE candidates across EVERY authorized key under their single
-    // budget (a weak primary-key hit must not mask stronger fallback evidence; the
-    // section builders take `sessionIds`, structured-parts merges inline below).
-    // This first-non-empty helper now serves ONLY the compressed-history section,
-    // which is a per-session HOLISTIC DAG narrative with no per-item id to merge or
-    // dedupe on — see its call site for the rationale.
-    //
-    // When the set is a single key (single-user / no-overlay / explicit-namespace),
-    // this is exactly one call — unchanged. `lcmSessionId` is `string | undefined`:
-    // a legacy SESSIONLESS recall yields the single `undefined` key so the read
-    // runs ONE archive-wide read with no `session_id` filter (pre-#1505 behavior).
-    // Hosted scope profiles are stricter: without a session key there is no
-    // namespace-scoped LCM key to query, so the key set stays empty and LCM cannot
-    // bypass the profile read stack via an archive-wide read. NEVER the literal
-    // "default" session id (codex P2).
+    // `firstNonEmptyLcmRead`: query the ordered LCM read key set, return the
+    // FIRST non-empty result (#1505). The query-SCORED sections no longer use
+    // it — they MERGE candidates across every authorized key (a weak primary
+    // hit must not mask stronger fallback evidence); this helper now serves
+    // only compressed-history, a holistic per-session DAG narrative with no
+    // per-item id to merge on. A single-key set is exactly one call. A legacy
+    // SESSIONLESS recall yields one `undefined` key: one archive-wide read,
+    // no `session_id` filter. Hosted scope profiles without a session key get
+    // an EMPTY key set, so LCM cannot bypass the profile read stack. NEVER
+    // the literal "default" session id (codex P2).
     const firstNonEmptyLcmRead = async <T>(
       read: (lcmSessionId: string | undefined) => Promise<T>,
       isEmpty: (value: T) => boolean,
@@ -4926,6 +4914,32 @@ export class RecallInternalCoordinator {
       recallPlan: timings.recallPlan,
       queryPolicy: timings.queryPolicy,
     });
+    // Episodic context (#2331): opt-in raw-turn episodes for the top recalled
+    // facts; flag off is a no-op so recall output stays byte-identical.
+    // Namespaces must be index-aligned with recalledMemoryPaths here — every
+    // recall branch populates xrayRecalledResults from the same array it
+    // mapped paths from, so per-path namespaces derive from those results
+    // (the assembly-time assignment below runs after this section).
+    const episodicNamespaceByPath = new Map<string, string | undefined>();
+    for (const result of xrayRecalledResults) {
+      if (result.path) episodicNamespaceByPath.set(result.path, result.namespace);
+    }
+    const episodicMemoryNamespaces = recalledMemoryPaths.map((memoryPath) =>
+      episodicNamespaceByPath.get(memoryPath),
+    );
+    // The section is advisory context: an archive error degrades the
+    // section, never the recall (fail-open).
+    try {
+      await appendEpisodicContextSection(this.deps, {
+        sectionBuckets, recalledMemoryPaths,
+        recalledMemoryNamespaces: episodicMemoryNamespaces,
+        scopePlan, namespacesEnabled,
+        enrichmentSectionDeadlineMs, recallOuterTimeoutMs, recallStart,
+        recordMetric: recordRecallSectionMetric, abortSignal: options.abortSignal,
+      });
+    } catch (err) {
+      log.debug("episodic-context: section degraded after error", err);
+    }
     const recallBudgetChars = this.deps.getRecallBudgetChars(options.budgetCharsOverride);
     const assembledRecall = this.deps.assembleRecallSections(
       sectionBuckets, contextBudgetForFooter(recallBudgetChars, curiosityFooter),
@@ -5326,4 +5340,5 @@ export class RecallInternalCoordinator {
       closeProfileTrace();
     }
   }
+
 }

package/src/orchestration/recall-result-formatter.ts

@@ -384,6 +384,43 @@ export class RecallResultFormatter {
     return `## Harmonic Retrieval\n\n${lines.join("\n\n")}`;
   }
 
+  /**
+   * Render grouped raw-turn episodes for the top recalled facts (issue #2331).
+   * Returns `null` for zero episodes so the section is omitted entirely —
+   * never an empty header.
+   */
+  formatEpisodicContext(
+    episodes: ReadonlyArray<{
+      sessionKey: string;
+      fromTurn: number;
+      toTurn: number;
+      memoryIds: readonly string[];
+      turns: ReadonlyArray<{ role: string; content: string }>;
+    }>,
+  ): string | null {
+    if (episodes.length === 0) return null;
+    const blocks = episodes.map((episode) => {
+      const shortKey =
+        episode.sessionKey.length > 8
+          ? `${episode.sessionKey.slice(0, 8)}…`
+          : episode.sessionKey;
+      const header =
+        `### Episode: ${shortKey} turns ${episode.fromTurn}-${episode.toTurn - 1} ` +
+        `(supports [${episode.memoryIds.join(", ")}])`;
+      const lines = episode.turns.map((turn) => {
+        // Archived conversation turns carry no origin: least-privilege
+        // fencing applies when origin authority is enabled (issue #2331).
+        const content = renderAuthorityBoundContent(turn.content, undefined, {
+          enabled: this.originAuthorityEnabled,
+          untrustedOrigins: this.config.untrustedOrigins,
+        });
+        return `${turn.role}: ${content}`;
+      });
+      return [header, ...lines].join("\n");
+    });
+    return `## Source Episodes\n\n${blocks.join("\n\n")}`;
+  }
+
   formatWorkProductResults(
     results: WorkProductLedgerSearchResult[],
   ): string {