Context Items and Receipts

The core surface of StatePlane is a small set of typed models that make context selection explainable and replayable.

Core Models

SourceRef

Captures provenance for a context item:

• source type
• title
• URI
• optional retrieval or author metadata

ContextItem

Represents one provider-neutral context candidate before provider rendering.

Important fields:

• id
• kind
• content
• source_ref
• created_at
• sensitivity
• stable_hash

CompilationRequest

Bundles the input set for one compile step:

• model/provider identifiers
• task summary
• context items
• token budget
• response reserve

CompilationDecision

Explains one item-level decision:

• include or exclude
• reason code
• token accounting
• score breakdown

CompiledContext

Stores the final selection receipts:

• selected item ids
• excluded item ids
• decisions
• token allocation
• stable and volatile hashes

CompilationReport

Joins decisions back to source items in a form that CLIs, dashboards, and future recorders can reuse directly.

Why These Models Matter

The point is not only to decide what context fits. The point is to leave receipts behind so we can answer:

• what was selected
• what was dropped
• why it was dropped
• how much budget it consumed
• whether the result is reproducible

Dynamic Data Policy

StatePlane uses pydantic.JsonValue only at genuine dynamic JSON boundaries, such as provider payloads or tool output. Known domain shapes should be promoted to explicit Pydantic models.