Module compose 

Deterministic context composition (docs/context-reuse.md §1).

Provider prompt caches (Anthropic’s 0.1× cache reads, OpenAI’s and Gemini’s automatic prefix caching) reward a byte-stable prompt prefix, and retrieved context is the part of a prompt most likely to destroy that stability: a host that re-queries every turn and pastes frames in arrival order emits a different prefix each turn, silently forfeiting the cache and multiplying the very token costs this protocol exists to make honest.

compose_context is the reference answer. It renders a frame set into a block that is a pure function of the frames’ content identity:

• frames are emitted in the protocol’s canonical order — sorted by FrameId, i.e. by (provider id, frame id, content digest) — so the same set renders byte-identically across turns and across hosts;
• the per-frame rendering excludes score (query-dependent relevance) and token_cost (a derived quantity), so a re-query that only re-ranks the same frames does not bust the cached prefix;
• identical identities are de-duplicated, so a frame served by two queries contributes one block, not two.

Frame content is untrusted data: it is emitted inside an explicit <frame>…</frame> fence as quoted material, never as instructions (docs/protocol-surface.md R3). Hardened injection-resistant delimiting (an unguessable fence, dedup-by-content, budget packing) is the reference composition module’s job (issue #15); this function is the narrower determinism contract any composition — reference or not — can satisfy.

Structs

AuditEntry

One line of the composition audit: which frame, and what became of it.

Citation

One entry of a composed prompt’s citation map: the human label rendered in a frame’s fence, resolved to the frame’s stable identity and merged provenance — so a model’s citation-by-label walks back to exactly which bytes, from which source, it quoted.

ComposedPrompt

A prompt composed from a frame set: the rendered text, the citation map, and the audit — the full return of compose_for_prompt.

CompositionAudit

The record of how a composed prompt was assembled (issue #15): one AuditEntry per frame the host offered, the budget it was packed against, and the canonical token cost actually used. The audit is a total partition — every offered frame is either included or excluded with a reason — so a host can answer “why is this evidence not in the prompt?” and “why is the prompt within budget?” from the record alone.

DedupDrop

One frame dropped by dedup_cross_provider as a cross-provider duplicate, paired with the identity of the frame that absorbed it.

Deduped

The outcome of dedup_cross_provider: the surviving frames plus the record of every cross-provider duplicate that was collapsed, so a composition audit can explain each drop.

Enums

ExclusionReason

Why a frame did not make it into the composed prompt (issue #15 audit). Every excluded frame carries exactly one of these, so the audit explains every drop rather than silently shrinking the evidence set.

FrameDisposition

One frame’s disposition in a composition: included (with its verification state) or excluded (with the reason). Exactly one per input frame, so the audit is a total partition of the evidence the host handed the composer.

VerificationState

Whether a frame’s content can be independently revalidated — it carries a content_digest a provider can answer context/verify against. Recorded per included frame in the CompositionAudit so a reader knows which quoted evidence is anchored to a checkable hash and which is trust-on-first-use.

Constants

EVIDENCE_PREAMBLE

The fixed preamble every composed prompt opens with: it tells the model the fenced blocks are quoted evidence, never instructions — the rendered form of R3. A constant (not a per-turn string), so it never perturbs the byte-stable prefix that the escaping in [neutralize_fence_tokens] exists to protect.

Functions

budget_split

Split a global composition budget into one max_tokens share per capability-matching provider, computed before any provider’s query is built so honest legs sum to <= global_budget (issue #15, allocation).

compose_context

Render a set of (provider id, frame) pairs into a byte-stable context block (docs/context-reuse.md §1).

compose_for_prompt

Compose an accepted frame set into a prompt-ready block: the R3 preamble, the value-ordered fenced frames, a citation map, and a CompositionAudit that explains every included and excluded frame (issue #15). This is the reference answer to “the host has honest frames — now what?”, layered on compose_context’s [render_frame] so the fencing and escaping are identical to the determinism floor.

dedup_cross_provider

Collapse the same evidence arriving from more than one provider into a single frame, keeping the higher-scored copy and merging provenance — the cross-provider dedup compose_context’s identity-only dedup cannot do (issue #15). Wire this in before compose_context: frame id is provider-scoped, so two providers returning the same file region under different ids survive the identity dedup as two blocks.

order_by_value

Order frames for placement in the prompt, highest value at the attention-favored edges — the Lost-in-the-Middle placement (Liu et al., TACL 2024, arXiv:2307.03172; docs/protocol-advantages.md §12), which shows an LLM attends most to the top and bottom of a long context and least to its middle.