Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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');
}