Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
51.8 KB
Raw Blame
/**
 * Turn-context assembly (agent-bootstrap plan: S3#1, ENG-1, ENG-11, CX-P1.2).
 *
 * Server-side builder behind the IPC v2 `turn_context` kind: given a rolling
 * conversation window, assemble ONE injectable context block from three
 * existing, deterministic sources —
 *
 *   1. reflex pointers   — extractCandidatesFromWindow → resolveEntitiesToPointers
 *                          (slug-only suppression, the windowed contract;
 *                          private pages excluded like remote search, N8-2)
 *   2. volunteered pages — volunteerContext (confidence-gated, ≤3, deduped
 *                          against section 1 via excludeSlugs)
 *   3. hot facts         — getBrainHotMemoryMeta's cache + shape [ENG-11], with
 *                          a remote:true OperationContext so visibility is
 *                          ['world'] ALWAYS [S3#1] — the IPC path must never
 *                          widen what MCP would return.
 *
 * The output text is wrapped in the subordinate provenance envelope
 * [CX-P1.2] and budgeted to ≤ maxBytes (default 8KB — the Claude Code hook
 * output cap [ENG-1]) by trimming facts first, then pointers/pages, lowest
 * confidence first.
 *
 * Engine-agnostic: every collaborator already runs on both PGLite and
 * Postgres engines; nothing here touches engine-specific SQL.
 */

import { appendRelationshipNotes } from '../link-relationship-notes.ts';
import type { BrainEngine } from '../engine.ts';
import type { OperationContext } from '../operations.ts';
import type { GBrainConfig } from '../config.ts';
import { extractCandidatesFromWindow, type WindowTurn } from './entity-salience.ts';
import {
  renderPointerLine,
  resolveEntitiesToPointers,
  DEFAULT_MAX_POINTERS,
  type ReflexPointer,
} from './retrieval-reflex.ts';
import { volunteerContext, type VolunteeredPage } from './volunteer.ts';
import { getBrainHotMemoryMeta } from '../facts/meta-hook.ts';
import { collapseHotFacts } from '../facts/capture-dedup.ts';
import type { ArmStatus, RawFactRef } from './delta-cursor.ts';
import { buildEntityCard, RECENT_FACTS_CAP, type EntityCard, type EntityOpenThread } from '../verbs/entity-card.ts';
import type { FactRow } from '../engine.ts';
import { isNewerMentionsEnabled, readNewerMentions, renderNewerMentionRow, NEWER_MENTIONS_HEADER, NEWER_MENTIONS_PACK_CHARS, type NewerMentions } from '../mentions/newer-mentions.ts';
import { estimateTokens } from '../search/token-budget.ts';
import type { DecideSlotMeta } from '../search/decide-stage.ts';
import { admitsTrust, type TrustTier } from '../trust/tier.ts';
import { resolveReadEligibility, type ReadEligibility } from '../eligibility/policy.ts';
import { proactiveEligibility } from '../eligibility/registry.ts';
import { pageActivationVerdicts, pageKey, suppressionSummary, type SuppressionSummary } from '../eligibility/activation.ts';
import { renderTrustedInline, trustFields, type TrustFields } from '../eligibility/labels.ts';
import { TURN_CONTEXT_ENVELOPE } from './turn-context-envelope.ts';
import { neutralizeForPrompt } from '../think/sanitize.ts';
import { quoteFacts, quotesTier, unquoteFactText } from '../search/transcript-quote.ts';

/**
 * v0.45.7 ambient recall (issue #1). The per-turn assembler is extended into the
 * shared core for the two new frozen verbs (`context_pack`, `delta`) AND the
 * boundary hook runtime, via `mode`:
 *   - 'turn'  — the existing per-turn push path (UNCHANGED; window-driven,
 *               world-only always).
 *   - 'pack'  — session-start / post-compaction bundle: entity cards +
 *               open-threads + hot facts for a set of standing entities.
 *   - 'delta' — heartbeat "what changed since T": pages updated after `since`
 *               + facts newer than `since` + open-thread events after `since`.
 *
 * Visibility is WORLD-ONLY by default on every arm (a pack is injected into an
 * agent context window that may be logged or synced to a cloud model). The
 * `includePrivate` opt widens ALL arms in lockstep (never a partial widen);
 * the push hook path NEVER sets it. See D2=A in the plan.
 */
export type ContextMode = 'turn' | 'pack' | 'delta';

export { TURN_CONTEXT_ENVELOPE };

/** [ENG-1] Default assembled-block budget (Claude Code hook output cap headroom). */
export const TURN_CONTEXT_DEFAULT_MAX_BYTES = 8192;

/** Max volunteered pages per turn (mirrors VOLUNTEER_DEFAULT_MAX_PAGES). */
const MAX_VOLUNTEERED_PAGES = 3;

/** One hot fact as carried by the meta-hook payload (shape reuse, ENG-11). */
export interface TurnContextFact {
  id: number;
  fact: string;
  kind: string;
  notability?: string | null;
  entity_slug: string | null;
  /** #5888: every entity of a collapsed duplicate group (representative first). */
  entity_slugs?: string[];
  valid_from?: string;
  /** Recording time (v0.45.7) — delta's "new since" filter prefers this over valid_from. */
  created_at?: string;
  /** #4206: provenance context (e.g. extract_facts' source_slug). */
  context?: string | null;
  /** Who asserted the claim; rendered so an assistant suggestion never reads as the user's own claim. */
  attributed_to?: 'user' | 'assistant' | 'other' | null;
  confidence: number;
  /** #5575 A6: the fact's trust tier and short write origin (rendered as a compact label; absent from older serves). */
  trust_tier?: TrustTier;
  origin?: string;
  /** #8042: a fact saved from a chat page, returned fenced as quoted source material (search/transcript-quote.ts). */
  quoted?: 'transcript';
}

/**
 * #6724: one fact about a packed entity, from the rows its card already read,
 * attributed to the card's (source_id, slug). `provenance` is the stored
 * `facts.source`.
 */
export interface EntityFact extends TurnContextFact {
  source_id: string;
  slug: string;
  provenance: string | null;
}

/** Up to RECENT_FACTS_CAP of a card's fact rows (newest first) as entity facts. */
function entityFactsOf(card: EntityCard, rows: FactRow[]): EntityFact[] {
  const iso = (v: Date | string | null | undefined) => (v == null ? undefined : v instanceof Date ? v.toISOString() : String(v));
  return rows.slice(0, RECENT_FACTS_CAP).map((f) => ({
    id: Number(f.id), fact: f.fact, kind: f.kind, notability: f.notability ?? null, entity_slug: f.entity_slug,
    valid_from: iso(f.valid_from), created_at: iso(f.created_at), context: f.context ?? null, attributed_to: f.attributed_to ?? null,
    confidence: Number(f.confidence), ...trustFields(f.trust_tier, f.write_origin),
    source_id: card.entity.source_id, slug: card.entity.slug, provenance: f.source ?? null,
  }));
}

/** One page in a `delta` result (updated after the cursor). */
export interface DeltaPage {
  slug: string;
  source_id: string;
  title: string;
  updated_at: string;
  /** #5575 A6: the page's trust tier and short write origin. */
  trust_tier?: TrustTier;
  origin?: string;
}

export interface TurnContextResult {
  /** Rendered block ('' when there is nothing to inject). */
  text: string;
  /**
   * Always-loaded core block (core-memory.ts) on session-start and coreOnly
   * requests; absent from older serves and from every other trigger.
   */
  core?: { text: string; revision: string; chars_used: number; chars_limit: number; truncated: boolean };
  /**
   * #5575 ENG-11, coreOnly requests: the core block's trust cache identity
   * (eligibility/generation.ts). `unchanged` answers a request whose
   * `coreIdentity` still matches, without `core`. Absent when the serve
   * cannot read it (the client then does not memoize the block).
   */
  coreTrust?: { identity: string; unchanged: boolean };
  /** Context-pressure gate (pressure.ts), serve-sourced; an older serve omits it and no notice fires. */
  pressure?: import('./pressure.ts').PressureGate;
  /** Reflex pointers that survived suppression + budget. */
  pointers: ReflexPointer[];
  /**
   * Volunteered pages that survived dedupe + budget — exactly what the
   * rendered text carries. Exposed so the IPC delivery point can log them to
   * context_volunteer_events with channel attribution (the #2095 feedback
   * loop); without this the hook lane fires invisibly to `--stats`/doctor.
   * Optional for wire back-compat (an older serve's block omits it).
   */
  volunteered?: VolunteeredPage[];
  /** Hot facts included after budget trimming. */
  factsCount: number;
  degradedReason?: string;
  /** pack mode — entity cards assembled for the standing entities. */
  cards?: EntityCard[];
  /** pack/delta mode — open-thread events (post-`since` in delta mode). */
  openThreads?: EntityOpenThread[];
  /** delta mode — pages updated after the cursor, OLDEST first (at-least-once cursor semantics). */
  deltaPages?: DeltaPage[];
  /**
   * delta mode — true when MORE pages changed than the fetch limit returned.
   * The caller must advance its cursor only to the newest DELIVERED page
   * (never to now()), so the overflow surfaces on the next wake.
   */
  deltaOverflow?: boolean;
  /** pack/delta mode — the hot facts included (structured, for the verb JSON). */
  facts?: TurnContextFact[];
  /** #6724 pack mode — the packed entities' own facts (each card's newest, eligibility applied), deduplicated by id. */
  entityFacts?: EntityFact[];
  /**
   * delta mode — per-arm completion captured in the SAME snapshot as the
   * arrays: `ok` (read completed), `failed` (read threw), `unknown` (the
   * deadline fired first). The verb advances only `ok` arms.
   */
  deltaArms?: { pages: ArmStatus; facts: ArmStatus; threads: ArmStatus };
  /** delta mode — every raw fact row the facts arm read (oldest first) with its collapsed representative. */
  deltaFactsRaw?: RawFactRef[];
  /** delta mode — the facts arm's limit+1 probe row when more facts are waiting. */
  deltaFactsOverflowRow?: { id: number; at: string } | null;
  /** The mode this result was assembled in. */
  mode?: ContextMode;
  /**
   * Cathedral 5 (additive, wire back-compat like `volunteered`) — banked
   * compaction-checkpoint links for the session (newest-first). Carried on
   * the pack/manifestOnly responses so the post-compaction SessionStart and
   * the OpenClaw assemble poll can render/match them. `seg` is the segment
   * content hash the harvest banked from (the poll's completion key).
   */
  checkpointLinks?: Array<{ slug: string; title: string; at?: string; n?: number; seg?: string }>;
  /**
   * Cathedral 5 (additive) — typed ack for a bankOnly `flushCorpusFile`
   * request: the harvest was scheduled, or skipped with a reason code.
   */
  checkpointFlush?: { status: 'scheduled' | 'skipped'; reason?: string };
  /** System One (turn mode): present only when S6 recall_needed is not off — what it did this turn. */
  decide?: { recall_needed: DecideSlotMeta };
  /**
   * #5575 DX-10: authorized memories activation control withheld from this
   * block (unconfirmed, agent-written, instruction-like): a count and the
   * owner's review command, never the content.
   */
  suppressed?: SuppressionSummary;
  /**
   * Wave 5 D5 (additive, wire back-compat): the proactive brief carried in
   * `text`, present only when `context.proactive_brief` is on and the gate
   * fired. The IPC delivery point logs and ledgers these items.
   */
  brief?: import('./proactive-brief.ts').BriefView;
}

export interface AssembleTurnContextOpts {
  sourceId: string;
  /** Recent turns, oldest → newest. Optional for pack/delta (may run cold). */
  window?: WindowTurn[];
  /** Already-surfaced context — drives slug-only suppression + volunteer dedupe. */
  priorContextText?: string;
  /** Opaque session identity — keys the hot-memory cache (CX2-11). */
  sessionId?: string;
  /**
   * `context.hot_memory.session_only`, read by the IPC handlers: hot facts
   * come from this session only, never from the source's newest 24h facts
   * when the session has none of its own.
   */
  sessionOnly?: boolean;
  maxBytes?: number;
  /** v0.46.15: lexical-arms kill switch — see ResolvePointersOpts.lexicalArms. */
  lexicalArms?: boolean;
  // ── v0.45.7 ambient recall ──────────────────────────────────────────────
  /** Assembly mode. Default 'turn' (existing behavior). */
  mode?: ContextMode;
  /** pack/delta — standing entity names to bundle (resolved to cards). */
  entities?: string[];
  /** delta — ISO cursor; only pages/facts/threads newer than this are returned. */
  since?: string;
  /**
   * Cathedral 5 (pack mode) — banked compaction-checkpoint links to render as
   * a self-capped section (pack mode does NOT enforce maxBytes; the section
   * caps itself at CHECKPOINT_LINKS_RENDER_CAP) and carry on the result.
   */
  checkpointLinks?: TurnContextResult['checkpointLinks'];
  /**
   * delta — keyset slug paired with `since` (v0.45.7): pages are fetched with
   * `(updated_at, slug) > (since, sinceSlug)` so a >limit cluster at one
   * timestamp pages deterministically. Facts/threads still use `since` (time).
   */
  sinceSlug?: string;
  /**
   * delta — the facts arm's own keyset (contributor audit wave P0): facts
   * strictly after `(at, id)` (`id: null` = strictly after `at`). Defaults to
   * `{ at: since, id: null }`, the legacy shared time cursor.
   */
  factsAfter?: { at: string; id: number | null };
  /**
   * Widen ALL arms to include private facts. Default false = world-only
   * (the safe injected-context posture). Fail-closed: only an explicit `true`
   * widens; anything else is world. The push hook path never sets this.
   */
  includePrivate?: boolean;
  /**
   * pack/delta (GST-687): the verb's caller is untrusted (MCP, `ctx.remote !== false`): hot and entity facts below the
   * owner's tier come back quoted, in the structured facts and the rendered text alike. The push pack sets it too
   * (#8377); the per-turn push hook always quotes its hot facts.
   */
  untrusted?: boolean;
  /** pack — cap on entity-card fan-out (default 8; push path passes smaller). */
  maxEntities?: number;
  /**
   * #6723 pack — the sources an unqualified entity name resolves in, home
   * first (verbs/entity-source.ts). Absent: `sourceId` alone.
   */
  sources?: readonly string[];
  /** #6723 pack — source-qualified entities, each resolved in its own source only (after `entities`, inside the same cap). */
  entityRefs?: ReadonlyArray<{ name: string; sourceId: string }>;
  /**
   * Wall-clock budget (ms). When set, arms race the deadline and whatever has
   * resolved is returned as a PARTIAL pack (degradedReason 'deadline'); the
   * push path passes ~TURN_CONTEXT_SERVER_BUDGET_MS so it never overruns.
   */
  deadlineMs?: number;
  /**
   * #5575: the read eligibility the calling surface resolved (token floor,
   * min_trust, activation control). Absent: turn mode applies the
   * `hook.user_prompt` surface policy, pack the `context_pack` policy, delta
   * the brain's read policy.
   */
  eligibility?: ReadEligibility;
  /** #5575 ENG-15: an authorized caller asked for quarantined pages' cards (otherwise they are left out). */
  includeQuarantined?: boolean;
}

/** Default entity-card fan-out cap for pack mode. */
export const PACK_DEFAULT_MAX_ENTITIES = 8;

const noopLogger = { info: () => {}, warn: () => {}, error: () => {} };

/**
 * Assemble the per-turn context block. Each section degrades independently
 * (an error in one arm empties that arm, never the whole block); the function
 * itself never throws for data reasons.
 */
export async function assembleTurnContext(
  engine: BrainEngine,
  opts: AssembleTurnContextOpts,
): Promise<TurnContextResult> {
  // v0.45.7 — mode dispatch. pack/delta run through the ambient-recall arms;
  // 'turn' (default) keeps the original per-turn path below, byte-identical.
  const mode = opts.mode ?? 'turn';
  if (mode === 'pack') return assemblePack(engine, opts);
  if (mode === 'delta') return assembleDelta(engine, opts);

  const maxBytes =
    typeof opts.maxBytes === 'number' && Number.isFinite(opts.maxBytes) && opts.maxBytes > 0
      ? Math.floor(opts.maxBytes)
      : TURN_CONTEXT_DEFAULT_MAX_BYTES;
  const window = Array.isArray(opts.window) ? opts.window : [];
  // System One S6 runs concurrently with the reflex arms under its own
  // deadline; the reflex block below is assembled first and stands unchanged
  // unless S6 finishes in time and acts (src/core/context/recall-needed.ts,
  // loaded lazily so pack/delta and envelope importers stay light).
  const startedAt = Date.now();
  // #5575 (CEO-20, DX-10): one proactive policy for every arm of this turn.
  const policy: ReadEligibility = opts.eligibility ?? await proactiveEligibility({ engine }, 'hook.user_prompt').catch(() => ({ suppressFlagged: true }));
  // Pages withheld by both the pointer and the volunteer arm count once.
  const withheldPages = new Set<string>();
  let withheldFacts = 0;
  const onWithheld = (keys: string[]) => { for (const k of keys) withheldPages.add(k); };
  const s6Module = import('./recall-needed.ts');
  const recall = s6Module.then((m) => m.startRecallNeeded(engine, { sourceId: opts.sourceId, window, sessionId: opts.sessionId, startedAt }));
  recall.catch(() => {});

  // Sections 1+2 form a dependent chain (volunteer dedupes against the
  // pointers surfaced THIS turn); section 3 is independent, so the two arms
  // run concurrently — the caller sits behind the 400ms IPC server budget
  // [G11], and serializing an independent DB read wastes it. Each arm keeps
  // its own try/catch degradation (an error empties that arm, never the block).

  // Arm A: reflex pointers → volunteered pages.
  const pointersVolunteerArm = (async (): Promise<{
    pointers: ReflexPointer[];
    volunteered: VolunteeredPage[];
  }> => {
    // 1. Reflex pointers — window candidate extraction + precision-biased
    //    resolution, slug-only suppression (the windowed contract, codex D7).
    let pointers: ReflexPointer[] = [];
    try {
      const candidates = extractCandidatesFromWindow(window);
      if (candidates.length) {
        const block = await resolveEntitiesToPointers(engine, opts.sourceId, candidates, {
          priorContextText: opts.priorContextText,
          suppression: 'slug-only',
          maxPointers: DEFAULT_MAX_POINTERS,
          lexicalArms: opts.lexicalArms,
          excludePrivate: true,
          eligibility: policy,
          onWithheld,
        });
        pointers = block?.pointers ?? [];
      }
    } catch {
      pointers = [];
    }

    // 2. Volunteered pages (≤3), excluding slugs already surfaced as pointers
    //    this turn; priorContextText suppression handles earlier turns.
    let volunteered: VolunteeredPage[] = [];
    try {
      if (window.length) {
        const excludeSlugs = new Set(pointers.map((p) => p.slug));
        volunteered = await volunteerContext(engine, window, {
          sourceIds: [opts.sourceId],
          priorContext: opts.priorContextText,
          excludeSlugs,
          maxPages: MAX_VOLUNTEERED_PAGES,
          // v0.46.15+ lexical-arms kill switch rides the same threading as the
          // pointer arm above (ResolvePointersOpts.lexicalArms).
          lexicalArms: opts.lexicalArms,
          excludePrivate: true,
          eligibility: policy,
          onWithheld,
        });
      }
    } catch {
      volunteered = [];
    }
    await appendRelationshipNotes(engine, [...pointers, ...volunteered]);
    return { pointers, volunteered };
  })();

  // Arm B: hot facts through the meta-hook's cache + payload shape [ENG-11].
  //    remote: true is the load-bearing bit [S3#1]: it pins the meta-hook's
  //    visibility tier to ['world'] so a private fact can NEVER cross the IPC
  //    boundary, exactly matching what a remote MCP caller would see.
  const factsArm = (async (): Promise<TurnContextFact[]> => {
    try {
      const metaCtx: OperationContext = {
        engine,
        config: {} as GBrainConfig,
        logger: noopLogger,
        dryRun: false,
        remote: true, // S3#1 — never widen past the remote/world posture
        sourceId: opts.sourceId,
        sessionId: opts.sessionId,
        takesHoldersAllowList: ['world'],
        ...(policy.floor ? { auth: { minTrust: policy.floor } as OperationContext['auth'] } : {}),
      };
      // #8377 (decision A): the injected facts reach a model, so a fact below the owner's tier is quoted, as on every pull path.
      const meta = await getBrainHotMemoryMeta('turn_context', metaCtx, { sessionOnly: opts.sessionOnly, untrusted: true });
      const hot = meta?.brain_hot_memory as { facts?: TurnContextFact[]; suppressed?: SuppressionSummary } | undefined;
      withheldFacts += hot?.suppressed?.withheld ?? 0;
      const all = Array.isArray(hot?.facts) ? [...hot.facts] : [];
      // Cross-turn dedupe, same contract as volunteered pages: a fact already
      // injected this session is not repeated. The key is the line render()
      // emits (renderFactLine: attribution, label or data envelope included),
      // without the trailing confidence, which drifts as facts age. Its
      // unlabeled form still matches, so a fact injected before labels (or
      // before its tier changed) stays injected.
      const prior = opts.priorContextText;
      return prior ? all.filter((f) => !factDedupeKeys(f).some((k) => prior.includes(k))) : all;
    } catch {
      return [];
    }
  })();

  const [reflex, facts] = await Promise.all([pointersVolunteerArm, factsArm]);
  let { pointers, volunteered } = reflex;
  let { text, degradedReason } = renderWithinBudget(pointers, volunteered, facts, maxBytes);

  const s6 = await s6Module.then((m) => m.applyRecallNeeded(engine, recall, {
    startedAt, prompt: window.at(-1)?.text ?? '', priorContextText: opts.priorContextText, pointers, volunteered,
  })).catch(() => null);
  if (s6?.window) {
    ({ pointers, volunteered } = s6.window);
    ({ text, degradedReason } = renderWithinBudget(pointers, volunteered, facts, maxBytes));
  }

  return {
    text,
    pointers,
    // Post-trim survivors: budget trimming mutates these arrays in place, so
    // this is exactly the set present in `text` — never the pre-budget pool
    // (logging a trimmed-out page would corrupt the precision stats).
    volunteered,
    factsCount: facts.length,
    ...(degradedReason ? { degradedReason } : {}),
    ...(s6 ? { decide: { recall_needed: s6.meta } } : {}),
    ...(withheldPages.size + withheldFacts ? { suppressed: suppressionSummary(withheldPages.size + withheldFacts) } : {}),
  };
}

/**
 * 4. Render + budget [ENG-1]: trim facts first, then volunteered pages, then
 * pointers — always lowest-confidence first. Trims the arrays in place.
 */
function renderWithinBudget(
  pointers: ReflexPointer[],
  volunteered: VolunteeredPage[],
  facts: TurnContextFact[],
  maxBytes: number,
): { text: string; degradedReason?: string } {
  let text = render(pointers, volunteered, facts);
  if (byteLen(text) <= maxBytes) return { text };
  while (byteLen(text) > maxBytes && facts.length) {
    dropLowestConfidence(facts);
    text = render(pointers, volunteered, facts);
  }
  while (byteLen(text) > maxBytes && volunteered.length) {
    dropLowestConfidence(volunteered);
    text = render(pointers, volunteered, facts);
  }
  while (byteLen(text) > maxBytes && pointers.length) {
    dropLowestConfidence(pointers);
    text = render(pointers, volunteered, facts);
  }
  // Even the bare envelope exceeds an absurdly small budget → inject nothing.
  if (byteLen(text) > maxBytes) text = '';
  return { text, degradedReason: 'budget_trimmed' };
}

function byteLen(s: string): number {
  return Buffer.byteLength(s, 'utf8');
}

function dropLowestConfidence(items: Array<{ confidence: number }>): void {
  if (!items.length) return;
  let idx = 0;
  for (let i = 1; i < items.length; i++) {
    if (items[i].confidence < items[idx].confidence) idx = i;
  }
  items.splice(idx, 1);
}

/** Render the envelope + labeled sections. '' when every section is empty. */
function render(
  pointers: ReflexPointer[],
  volunteered: VolunteeredPage[],
  facts: TurnContextFact[],
): string {
  if (!pointers.length && !volunteered.length && !facts.length) return '';
  const lines: string[] = [TURN_CONTEXT_ENVELOPE];
  if (pointers.length) {
    lines.push('', '## Brain pages mentioned this turn');
    for (const p of pointers) lines.push(renderPointerLine(p));
  }
  if (volunteered.length) {
    lines.push('', '## Brain pages the brain volunteers');
    for (const v of volunteered) {
      const syn = v.trust_tier ? ` — ${renderTrustedInline(v.synopsis, labelOf(v))}` : v.synopsis ? ` — ${v.synopsis}` : '';
      lines.push(`- **${v.display}** → \`${v.slug}\` (${v.confidence.toFixed(2)}, ${v.rationale})${syn}`);
    }
  }
  if (facts.length) lines.push('', '## Hot memory (recent facts)', ...facts.map(renderFactLine));
  return lines.join('\n');
}

// ─────────────────────────────────────────────────────────────────────────
// v0.45.7 ambient recall — pack / delta modes (issue #1)
// ─────────────────────────────────────────────────────────────────────────

function clampPositive(n: number | undefined, dflt: number): number {
  return typeof n === 'number' && Number.isFinite(n) && n > 0 ? Math.floor(n) : dflt;
}

/**
 * Cursor comparison robust to timestamp FORMAT differences (ISO vs PG local-tz
 * text vs bare 'YYYY-MM-DD' dates). Parses both to epoch when possible; falls
 * back to lexicographic only when neither parses. Exported: the verb handlers
 * apply the same filter when they recompute budget-packed sets.
 */
export function isAfter(value: string | null | undefined, since: string): boolean {
  if (typeof value !== 'string' || !value) return false;
  const v = Date.parse(value);
  const s = Date.parse(since);
  if (Number.isFinite(v) && Number.isFinite(s)) return v > s;
  return value > since;
}

/**
 * Race `work` against a wall-clock budget. Returns 'deadline' if the timer
 * fired first (the caller then renders whatever its accumulator collected — a
 * PARTIAL pack), or undefined if the work finished in time. This is the
 * substrate the push path's 400ms budget needs; assembleTurnContext has no
 * built-in abort, so arms must mutate a shared accumulator as they resolve.
 */
async function raceDeadline(work: Promise<void>, ms?: number): Promise<string | undefined> {
  if (!ms || ms <= 0) {
    await work.catch(() => {});
    return undefined;
  }
  let timer: ReturnType<typeof setTimeout> | undefined;
  const timeout = new Promise<'deadline'>((resolve) => {
    timer = setTimeout(() => resolve('deadline'), ms);
  });
  const done = work.then(() => undefined).catch(() => undefined);
  const result = await Promise.race([done, timeout]);
  if (timer) clearTimeout(timer);
  return result === 'deadline' ? 'deadline' : undefined;
}

/**
 * Hot-facts arm shared by pack/delta. World-only unless `remote === false`
 * (include_private). Fail-soft: any error empties the arm, never throws.
 */
async function fetchHotFacts(
  engine: BrainEngine,
  opts: AssembleTurnContextOpts,
  remote: boolean,
  floor?: TrustTier,
): Promise<{ facts: TurnContextFact[]; withheld: number }> {
  try {
    const metaCtx: OperationContext = {
      engine,
      config: {} as GBrainConfig,
      logger: noopLogger,
      dryRun: false,
      remote, // false only when include_private explicitly widened the pack
      sourceId: opts.sourceId,
      sessionId: opts.sessionId,
      takesHoldersAllowList: ['world'],
      // #5575 CEO-18: the calling connection's floor keys and filters hot memory too.
      ...(floor ? { auth: { minTrust: floor } as OperationContext['auth'] } : {}),
    };
    const meta = await getBrainHotMemoryMeta('turn_context', metaCtx, { sessionOnly: opts.sessionOnly, untrusted: opts.untrusted === true });
    const hot = meta?.brain_hot_memory as { facts?: TurnContextFact[]; suppressed?: SuppressionSummary } | undefined;
    const facts = Array.isArray(hot?.facts) ? hot.facts.filter(f => !floor || admitsTrust(f.trust_tier ?? 'unknown', floor)) : [];
    return { facts, withheld: hot?.suppressed?.withheld ?? 0 };
  } catch {
    return { facts: [], withheld: 0 };
  }
}

/**
 * pack mode — session-start / post-compaction bundle for a set of standing
 * entities: entity cards + open-threads + hot facts. World-only by default;
 * include_private widens the card + facts arms in lockstep. Sequential card
 * builds (PGLite is single-connection) so a deadline keeps the cards already built.
 */
async function assemblePack(
  engine: BrainEngine,
  opts: AssembleTurnContextOpts,
): Promise<TurnContextResult> {
  const remote = opts.includePrivate !== true; // fail-closed: only explicit true widens
  const maxEntities = clampPositive(opts.maxEntities, PACK_DEFAULT_MAX_ENTITIES);
  const sources = opts.sources?.length ? opts.sources : [opts.sourceId];
  const entities = [
    ...(opts.entities ?? []).filter((e) => typeof e === 'string' && e.trim()).map((name) => ({ name, sources })),
    ...(opts.entityRefs ?? []).map((ref) => ({ name: ref.name, sources: [ref.sourceId] })),
  ].slice(0, maxEntities);

  // Cards and their newer mentions are keyed by (source_id, slug): two pages sharing a slug in two sources are two entities.
  const acc: { cards: EntityCard[]; facts: TurnContextFact[]; entityFacts: EntityFact[]; withheld: number; mentions: Map<string, NewerMentions> } = { cards: [], facts: [], entityFacts: [], withheld: 0, mentions: new Map() };
  const keyOf = (c: EntityCard) => pageKey({ source_id: c.entity.source_id, slug: c.entity.slug });
  // #5575 (CEO-20): context_pack is a proactive surface.
  const policy: ReadEligibility = opts.eligibility ?? await proactiveEligibility({ engine }, 'context_pack').catch(() => ({ suppressFlagged: true }));
  // Cooperative deadline (perf review): raceDeadline abandons but cannot stop
  // the build, and on PGLite's single connection orphaned card queries would
  // queue AHEAD of the caller's next work. Check between iterations so no new
  // query is issued after the deadline fires.
  const deadlineAt =
    typeof opts.deadlineMs === 'number' && opts.deadlineMs > 0 ? Date.now() + opts.deadlineMs : null;
  const build = (async () => {
    for (const { name, sources: nameSources } of entities) {
      if (deadlineAt !== null && Date.now() >= deadlineAt) return;
      try {
        const res = await buildEntityCard(engine, nameSources[0]!, name, { remote, readerRemote: opts.untrusted === true, eligibility: policy, omitQuarantined: opts.includeQuarantined !== true, sources: nameSources });
        if (res.found && res.card && !acc.cards.some((c) => keyOf(c) === keyOf(res.card!))) {
          // The card's OWN source decides activation: a same-slug page in another source never gates or admits it.
          const ref = { source_id: res.card.entity.source_id, slug: res.card.entity.slug };
          const verdict = (await pageActivationVerdicts(engine, [ref], policy)).get(pageKey(ref));
          if (verdict?.suppressed) acc.withheld++;
          // Under trust.agent_activation=allow (the default) a flagged entity page stays, labeled unconfirmed.
          else if (verdict && !verdict.belowFloor) {
            acc.cards.push(verdict.unconfirmed ? { ...res.card, unconfirmed: true as const } : res.card);
            acc.entityFacts.push(...entityFactsOf(res.card, res.factRows ?? []).filter((f) => !acc.entityFacts.some((e) => e.id === f.id)));
          }
        }
      } catch {
        /* fail-soft: skip this entity */
      }
    }
    if (deadlineAt !== null && Date.now() >= deadlineAt) return;
    const hot = await fetchHotFacts(engine, opts, remote, policy.floor);
    acc.facts = hot.facts;
    acc.withheld += hot.withheld;
    // Newer mentions read last: a deadline drops them before a card or a fact.
    if (!acc.cards.length || !(await isNewerMentionsEnabled(engine))) return;
    const { resolveExcludePrivatePages } = await import('../search/private-visibility.ts');
    const excludePrivate = await resolveExcludePrivatePages(engine, remote ? undefined : false);
    let left = NEWER_MENTIONS_PACK_CHARS;
    for (const card of acc.cards) {
      if (left <= 0 || (deadlineAt !== null && Date.now() >= deadlineAt)) return;
      const m = await readNewerMentions(engine, card.entity.source_id, card.entity.slug,
        { excludePrivate, keepVisibility: remote ? ['world'] : ['private', 'world'], charBudget: left, eligibility: policy, includeQuarantined: opts.includeQuarantined === true });
      if (!m) continue;
      acc.mentions.set(keyOf(card), m);
      left -= renderNewerMentionLines({ ...card, newer_mentions: m }, sources[0], opts.untrusted === true).join('\n').length + 1;
    }
  })();

  const degradedReason = await raceDeadline(build, opts.deadlineMs);
  // Snapshot copies (adversarial review P3): on a deadline return, `build` is
  // still running and keeps MUTATING acc — a live array reference in the
  // response could diverge from the rendered text after the first await
  // downstream. Copies freeze the delivered view.
  const mentions = new Map(acc.mentions);
  const cards = acc.cards.map((c) => (mentions.has(keyOf(c)) ? { ...c, newer_mentions: mentions.get(keyOf(c)) } : c));
  const facts = [...acc.facts];
  // GST-687: an entity fact reaches an untrusted reader as hot memory does (quoteFacts); a failed lookup withholds them,
  // counted in `suppressed` as recall counts its own (#8377).
  let unquotable = 0;
  const entityFacts = opts.untrusted === true
    ? await quoteFacts(engine, [...acc.entityFacts], true).catch(() => { unquotable = acc.entityFacts.length; return []; })
    : [...acc.entityFacts];
  const withheld = acc.withheld + unquotable;
  // `since` filter (adversarial review: was documented but dead) — open-thread
  // events are cut to those after the cursor, matching the verb contract.
  const since = typeof opts.since === 'string' && opts.since.trim() ? opts.since : undefined;
  const openThreads = cards
    .flatMap((c) => c.open_threads ?? [])
    .filter((t) => !since || (t.date !== null && isAfter(t.date, since)));
  const text = renderPack(cards, openThreads, facts, opts.checkpointLinks, sources[0], entityFacts, opts.untrusted === true);
  return {
    text,
    pointers: [],
    factsCount: facts.length,
    cards,
    openThreads,
    facts,
    ...(entityFacts.length ? { entityFacts } : {}),
    mode: 'pack',
    ...(opts.checkpointLinks?.length ? { checkpointLinks: opts.checkpointLinks } : {}),
    ...(degradedReason ? { degradedReason } : {}),
    ...(withheld ? { suppressed: suppressionSummary(withheld) } : {}),
  };
}

/**
 * delta mode — "what changed since `since`": pages updated after the cursor +
 * hot facts newer than the cursor + open-thread events after the cursor.
 */
/** Max changed pages fetched per delta call (+1 probe row detects overflow). */
export const DELTA_PAGE_FETCH_LIMIT = 50;
/** Max facts fetched per delta call (+1 probe row detects overflow). */
export const DELTA_FACT_FETCH_LIMIT = 50;

async function assembleDelta(
  engine: BrainEngine,
  opts: AssembleTurnContextOpts,
): Promise<TurnContextResult> {
  const remote = opts.includePrivate !== true;
  const since = typeof opts.since === 'string' && opts.since.trim() ? opts.since : undefined;
  // #5575: delta is an explicit read (labels, floor, quarantined-page hiding), not activation-controlled.
  const policy: ReadEligibility = opts.eligibility ?? await resolveReadEligibility({ engine }).catch(() => ({}));
  // Each arm publishes its result in ONE assignment when it completes, so the
  // snapshot taken after the deadline race sees an arm either whole or absent
  // (`unknown`), never half-filled.
  const acc: {
    pages?: { status: 'ok'; rows: DeltaPage[]; overflow: boolean } | { status: 'failed' };
    facts?:
      | { status: 'ok'; facts: TurnContextFact[]; raw: RawFactRef[]; overflowRow: { id: number; at: string } | null }
      | { status: 'failed' };
    threads?: { status: ArmStatus; items: EntityOpenThread[] };
  } = {};
  const deadlineAt =
    typeof opts.deadlineMs === 'number' && opts.deadlineMs > 0 ? Date.now() + opts.deadlineMs : null;
  const pastDeadline = () => deadlineAt !== null && Date.now() >= deadlineAt;

  const build = (async () => {
    if (since) {
      try {
        // OLDEST first + limit+1 probe: with the (updated_at, slug) TOTAL order
        // the delivered set is a contiguous prefix from the cursor, so the
        // caller advances its keyset to the last DELIVERED (ts, slug) and the
        // tail surfaces on the next wake — at-least-once, and a >limit cluster
        // at ONE timestamp pages cleanly via the slug keyset (red-team F1).
        const pages = await engine.listPages({
          ...(opts.sinceSlug !== undefined
            ? { updatedAfterKeyset: { updatedAt: since, slug: opts.sinceSlug } }
            : { updated_after: since }),
          sourceId: opts.sourceId,
          // Match the facts + entity-card arms: delta is world-only unless a
          // trusted local caller explicitly sets includePrivate.  Without
          // this engine-level filter, a default/remote delta exposed private
          // page titles and slugs even though its fact payload was filtered.
          excludePrivate: remote,
          limit: DELTA_PAGE_FETCH_LIMIT + 1,
          sort: 'updated_asc',
        });
        const window = pages.slice(0, DELTA_PAGE_FETCH_LIMIT);
        // Labels are best-effort on an unfloored read; with a floor, an unreadable tier fails the arm closed.
        const verdicts = await pageActivationVerdicts(engine, window.map(p => ({ source_id: opts.sourceId, slug: p.slug })), { floor: policy.floor })
          .catch((error: unknown) => {
            if (policy.floor) throw error;
            return new Map(window.map(p => [pageKey({ source_id: opts.sourceId, slug: p.slug }),
              { tier: 'unknown' as const, origin: { channel: 'unrecorded' }, belowFloor: false, suppressed: false, unconfirmed: false }]));
          });
        acc.pages = {
          status: 'ok',
          overflow: pages.length > DELTA_PAGE_FETCH_LIMIT,
          rows: window.flatMap((p) => {
            const v = verdicts.get(pageKey({ source_id: opts.sourceId, slug: p.slug }));
            return v && !v.belowFloor ? [{ p, trust: { ...trustFields(v.tier, v.origin), ...(v.unconfirmed ? { unconfirmed: true as const } : {}), ...('guest' in v && v.guest ? { origin: 'guest', guest: v.guest } : {}) } }] : [];
          }).map(({ p, trust }) => ({
            slug: p.slug,
            source_id: opts.sourceId,
            title: p.title,
            // Column-precision cursor: `next_cursor.since` minted from a JS Date
            // re-selects every same-millisecond row on the next wake.
            updated_at:
              p.updated_at_iso ?? (p.updated_at instanceof Date ? p.updated_at.toISOString() : String(p.updated_at)),
            ...trust,
          })),
        };
      } catch {
        acc.pages = { status: 'failed' };
      }
    }
    // Facts arm: query the store DIRECTLY by recording time (pre-landing
    // review): the hot-memory meta hook's fallback window is 24h/topK-25, so a
    // cursor older than a day would silently miss facts recorded between the
    // cursor and yesterday. Contributor audit wave P0: OLDEST first after the
    // arm's own (created_at, id) keyset with a limit+1 probe, so the facts
    // dropped by the limit are the NEWEST ones, past the advanced keyset.
    if (!pastDeadline()) {
      try {
        const after = opts.factsAfter ?? (since ? { at: since, id: null } : null);
        const { resolveExcludePrivatePages, worldOnlyFacts } = await import('../search/private-visibility.ts');
        const visibility = worldOnlyFacts(remote) ? (['world'] as ('private' | 'world')[]) : undefined;
        const excludePrivate = await resolveExcludePrivatePages(engine, remote ? undefined : false);
        const rows = await engine.listFactsKeyset(
          opts.sourceId,
          after ? { createdAt: after.at, id: after.id } : null,
          { activeOnly: true, limit: DELTA_FACT_FETCH_LIMIT + 1, visibility, excludePrivate, fingerprint: true, eligibility: { floor: policy.floor } },
        );
        const kept = rows.slice(0, DELTA_FACT_FETCH_LIMIT);
        const probe = rows.length > DELTA_FACT_FETCH_LIMIT ? rows[DELTA_FACT_FETCH_LIMIT] : null;
        const iso = (r: (typeof rows)[number]) => r.created_at_iso ?? r.created_at.toISOString();
        const members = new Map<number, number>();
        // #5888: duplicates collapse to their newest representative, as in hot memory.
        const collapsed = await collapseHotFacts(engine, opts.sourceId, kept, members);
        // #8042: a remote reader gets a fact taken from third-party text quoted.
        const shown: Array<(typeof collapsed)[number] & { quoted?: 'transcript' }> = remote ? await quoteFacts(engine, collapsed, opts.untrusted === true) : collapsed;
        acc.facts = {
          status: 'ok',
          raw: kept.map((r) => ({ id: r.id, at: iso(r), repId: members.get(r.id) ?? r.id })),
          overflowRow: probe ? { id: probe.id, at: iso(probe) } : null,
          facts: shown.map((r) => ({
            id: r.id,
            fact: r.fact,
            kind: r.kind,
            notability: r.notability,
            entity_slug: r.entity_slug,
            ...(r.entity_slugs ? { entity_slugs: r.entity_slugs } : {}),
            valid_from: r.valid_from.toISOString(),
            created_at: r.created_at.toISOString(),
            // #4206: provenance context rides delta like the other projections.
            context: r.context ?? null,
            confidence: r.confidence,
            ...(r.attributed_to ? { attributed_to: r.attributed_to } : {}),
            ...trustFields(r.trust_tier, r.write_origin),
            ...(r.quoted ? { quoted: r.quoted } : {}),
          })),
        };
      } catch {
        acc.facts = { status: 'failed' };
      }
    }

    // Threads are best-effort: buildEntityCard caps and swallows internally,
    // and thread events key on event date, not a keyset. A throw still marks
    // the arm `failed` (degraded_reason `threads`) and holds the time cursor
    // the events follow.
    const entities = (opts.entities ?? [])
      .filter((e) => typeof e === 'string' && e.trim())
      .slice(0, clampPositive(opts.maxEntities, PACK_DEFAULT_MAX_ENTITIES));
    const items: EntityOpenThread[] = [];
    let failed = false;
    for (const name of entities) {
      if (pastDeadline()) return;
      try {
        const res = await buildEntityCard(engine, opts.sourceId, name, { remote, readerRemote: opts.untrusted === true, eligibility: { floor: policy.floor }, omitQuarantined: true });
        if (res.found && res.card) {
          for (const t of res.card.open_threads ?? []) {
            if (!since || (t.date && isAfter(t.date, since))) items.push(t);
          }
        }
      } catch {
        failed = true;
      }
    }
    acc.threads = { status: failed ? 'failed' : 'ok', items };
  })();

  const deadlineReason = await raceDeadline(build, opts.deadlineMs);
  // ONE snapshot: arm flags and arrays come from the same read of `acc`.
  const snap = { ...acc };
  const pagesArm = snap.pages;
  const factsArm = snap.facts;
  const threadsArm = snap.threads;
  const arms = {
    pages: (since ? pagesArm?.status ?? 'unknown' : 'ok') as ArmStatus,
    facts: (factsArm?.status ?? 'unknown') as ArmStatus,
    threads: (threadsArm?.status ?? 'unknown') as ArmStatus,
  };
  const failedArms = (['pages', 'facts', 'threads'] as const).filter((a) => arms[a] === 'failed');
  const degradedReason = [deadlineReason, ...failedArms].filter(Boolean).join(',') || undefined;
  const pages = pagesArm?.status === 'ok' ? [...pagesArm.rows] : [];
  const facts = factsArm?.status === 'ok' ? [...factsArm.facts] : [];
  const threads = [...(threadsArm?.items ?? [])];
  const text = renderDelta(pages, facts, threads, since);
  return {
    text,
    pointers: [],
    factsCount: facts.length,
    deltaPages: pages,
    deltaOverflow: pagesArm?.status === 'ok' && pagesArm.overflow,
    openThreads: threads,
    facts,
    mode: 'delta',
    deltaArms: arms,
    deltaFactsRaw: factsArm?.status === 'ok' ? factsArm.raw : [],
    deltaFactsOverflowRow: factsArm?.status === 'ok' ? factsArm.overflowRow : null,
    ...(degradedReason ? { degradedReason } : {}),
  };
}

/** Thin wrappers so the verb + hook layers read intent-first. */
export function assembleContextPack(
  engine: BrainEngine,
  opts: Omit<AssembleTurnContextOpts, 'mode'>,
): Promise<TurnContextResult> {
  return assembleTurnContext(engine, { ...opts, mode: 'pack' });
}
export function assembleDeltaContext(
  engine: BrainEngine,
  opts: Omit<AssembleTurnContextOpts, 'mode'>,
): Promise<TurnContextResult> {
  return assembleTurnContext(engine, { ...opts, mode: 'delta' });
}

/** Exported (v0.45.7 adversarial review): the verb handlers re-render `text`
 * from the FINAL (budget-packed) sets — the injectable field must honor the
 * same budget + dedup contract as the structured arrays. */
/** Self-cap on the rendered checkpoint-links section (cathedral 5 — pack mode
 * does not enforce maxBytes, so the section bounds itself). */
export const CHECKPOINT_LINKS_RENDER_CAP = 10;

// #4761: ONE template per item, shared by the renderers below and the budget
// packers in ops/facts.ts — the packer prices exactly the bytes the renderer
// emits, so `text` honors budget_tokens instead of overshooting it.
// #5575 A6: an item carrying a trust tier renders its compact label (an
// external item is wrapped inline as data); an unlabeled item renders as before.
const labelOf = (item: { trust_tier?: TrustTier; origin?: string; guest?: TrustFields['guest'] }): TrustFields =>
  ({ trust_tier: item.trust_tier ?? 'unknown', origin: item.origin ?? 'legacy', ...(item.guest ? { guest: item.guest } : {}) });
const labeled = (item: { trust_tier?: TrustTier; origin?: string }, text: string): string =>
  item.trust_tier ? renderTrustedInline(text, labelOf(item)) : text;
const cardSummary = (c: EntityCard, text: string): string =>
  c.quarantined ? renderTrustedInline(text, { trust_tier: 'external_untrusted', origin: 'quarantined' }) : labeled(c, text);
/** #8384: for an untrusted reader a card below the owner's tier carries its title under the card's label too; otherwise as stored. */
const cardTitle = (c: EntityCard, untrusted: boolean): string => (untrusted && c.trust_tier && quotesTier(c.trust_tier) ? cardSummary(c, c.entity.title) : c.entity.title);
/** #6723: a card from outside the pack's home source names its source, so a follow-up reads the right page. */
const sourceNote = (c: EntityCard, home?: string): string =>
  home !== undefined && c.entity.source_id !== undefined && c.entity.source_id !== home ? ` (source ${c.entity.source_id})` : '';
export const renderCardLine = (c: EntityCard, home?: string, untrusted = false): string =>
  `- **${cardTitle(c, untrusted)}** → \`${c.entity.slug}\`${sourceNote(c, home)}${c.summary ? ` — ${cardSummary(c, c.summary)}` : c.trust_tier ? ` — ${cardSummary(c, '')}` : ''}${c.relationship_note ? ` [${c.relationship_note}]` : ''} (use get_page/entity before relying on details)`;
export const renderThreadLine = (t: EntityOpenThread): string =>
  `- [${t.kind}] ${labeled(t, t.text)}${t.date ? ` (${t.date})` : ''}`;
/** A quoted fact's fence closes on its own line (GST-687): its label rides the marker line and the slug and confidence follow the fence. */
export const renderFactLine = (f: TurnContextFact): string =>
  `- ${f.attributed_to === 'assistant' ? '(assistant said) ' : ''}${labeled(f, f.quoted ? `${neutralizeForPrompt(f.fact).text}\n` : neutralizeForPrompt(f.fact).text)}${f.entity_slug ? ` [${f.entity_slug}]` : ''} (${f.confidence.toFixed(2)})`;
/**
 * #7023: the substrings that mark a fact as already injected: its rendered line, then its unlabeled form, each without the "- " bullet and the confidence.
 * #8377: a quoted fact also matches its line from before the push hook quoted it.
 */
const factDedupeKeys = (f: TurnContextFact): string[] =>
  [f, ...(f.quoted ? [{ ...f, fact: unquoteFactText(f.fact), quoted: undefined }] : [])]
    .flatMap((g) => [g, { ...g, trust_tier: undefined }])
    .map((g) => renderFactLine(g).slice(2).replace(/ \([0-9.]+\)$/, ' ('));
export const renderPageLine = (p: DeltaPage): string => `- **${labeled(p, p.title)}** → \`${p.slug}\` (${p.updated_at})`;

/** One card's newer-mentions block: a line naming the entity and its page date, then one line per page. [] when there are none. */
export const renderNewerMentionLines = (c: EntityCard, home?: string, untrusted = false): string[] => {
  const m = c.newer_mentions;
  if (!m?.rows.length) return [];
  return [
    `- **${cardTitle(c, untrusted)}** (\`${c.entity.slug}\`${sourceNote(c, home)}, page dated ${m.since.slice(0, 10)}):`,
    ...m.rows.map(renderNewerMentionRow),
    ...(m.more ? [`  - more pages dated after ${m.since.slice(0, 10)} mention it: entity("${c.entity.slug}"${sourceNote(c, home) ? `, source_id "${c.entity.source_id}"` : ''}) lists them all`] : []),
  ];
};

const PACK_HEADERS = ['## Standing entities', '## Open threads', '## Hot memory (recent facts)'] as const;
/** #6724: the packed entities' own facts render under their own header, before hot memory; a fact in both renders once, here. */
export const ENTITY_FACTS_HEADER = '## Entity facts (about the standing entities)';
const deltaHeaders = (since?: string): readonly [string, string, string] => {
  const s = since ? ` since ${since}` : '';
  return [`## Pages changed${s}`, `## New facts${s}`, `## Thread updates${s}`];
};
/** Tokens the envelope + every section header cost once rendered (each header
 * rides a blank line before it). The packers reserve this up front so
 * estimateTokens(text) <= budget_tokens holds whenever any item fits; a
 * section that ends up empty is over-reserved — the safe direction. */
const headerCost = (headers: readonly string[]): number =>
  estimateTokens([TURN_CONTEXT_ENVELOPE, ...headers.flatMap((h) => ['', h])].join('\n') + '\n');
export const packHeaderCost = (): number => headerCost(PACK_HEADERS);
export const deltaHeaderCost = (since?: string): number => headerCost(deltaHeaders(since));

export function renderPack(
  cards: EntityCard[],
  openThreads: EntityOpenThread[],
  facts: TurnContextFact[],
  checkpointLinks?: TurnContextResult['checkpointLinks'],
  home?: string,
  entityFacts: TurnContextFact[] = [],
  untrusted = false,
): string {
  const links = checkpointLinks ?? [];
  const shown = new Set(entityFacts.map((f) => f.id));
  const hot = facts.filter((f) => !shown.has(f.id));
  if (!cards.length && !openThreads.length && !hot.length && !entityFacts.length && !links.length) return '';
  const lines: string[] = [TURN_CONTEXT_ENVELOPE];
  if (links.length) {
    lines.push('', '## Compaction checkpoints');
    for (const l of links.slice(0, CHECKPOINT_LINKS_RENDER_CAP)) {
      lines.push(`- brain://${l.slug} — ${l.title}`);
    }
    lines.push(
      'Checkpoint saved to the brain at compaction; facts harvested moments later — ' +
      're-pull with get_page. Trust these links over the compaction summary.',
    );
  }
  if (cards.length) lines.push('', PACK_HEADERS[0], ...cards.map((c) => renderCardLine(c, home, untrusted)));
  if (openThreads.length) lines.push('', PACK_HEADERS[1], ...openThreads.map(renderThreadLine));
  if (entityFacts.length) lines.push('', ENTITY_FACTS_HEADER, ...entityFacts.map(renderFactLine));
  if (hot.length) lines.push('', PACK_HEADERS[2], ...hot.map(renderFactLine));
  const mentionLines = cards.flatMap((c) => renderNewerMentionLines(c, home, untrusted));
  if (mentionLines.length) lines.push('', NEWER_MENTIONS_HEADER, ...mentionLines);
  return lines.join('\n');
}

/** Exported (v0.45.7 adversarial review) — see renderPack. */
export function renderDelta(
  pages: DeltaPage[],
  facts: TurnContextFact[],
  threads: EntityOpenThread[],
  since?: string,
): string {
  if (!pages.length && !facts.length && !threads.length) return '';
  const lines: string[] = [TURN_CONTEXT_ENVELOPE];
  const [pagesHeader, factsHeader, threadsHeader] = deltaHeaders(since);
  if (pages.length) lines.push('', pagesHeader, ...pages.map(renderPageLine));
  if (facts.length) lines.push('', factsHeader, ...facts.map(renderFactLine));
  if (threads.length) lines.push('', threadsHeader, ...threads.map(renderThreadLine));
  return lines.join('\n');
}