---
name: "Core Context Submodule Spec"
description: "Specification for :core:context – context synthesis and compression"
depth: 2
links: ["../index.md", "../architecture/context-layers.md", "./core-artifacts-submodule-spec.md"]
---

# :core:context module specification

version: 0.1-draft
status: foundational specification

---

# 1. purpose

`:core:context` is responsible for synthesizing minimal, relevant, token‑efficient context packs that are fed to models before each inference call.

It owns:

* context layer architecture (L0–L4)
* compression strategies
* token budgeting
* relevance ranking
* deduplication
* context pack building
* context event ownership

Context synthesis is the primary defense against context window overflow and degradation of model performance due to irrelevant history.

---

# 2. responsibilities

`:core:context` owns:

* context layer definitions
* compression strategy contracts
* token budget model
* relevance ranking algorithms
* deduplication logic
* context pack structure
* rebuild triggers
* context synthesis events
* router context management (separate L2 for router)
* session‑level context cap enforcement

---

# 3. non-responsibilities

`:core:context` MUST NOT own:

* long‑term memory persistence (that’s infrastructure)
* model execution
* tool execution
* approval decisions
* transition logic
* archiving policy (archival layer L4 is defined, but storage mechanics are external)

---

# 4. architectural role

`:core:context` acts as:

* the information bottleneck
* a stateless synthesizer that transforms raw event history into a compressed, actionable model prompt
* the owner of what the model “sees”

---

# 5. design principles

## 5.1 context is synthesized, not accumulated

Raw events are never fed to models. They are filtered, ranked, compressed, and bounded.

## 5.2 layers separate freshness from history

* L0 – live execution stream (current stage inputs/outputs)
* L1 – stage‑local context (artifacts from the current stage)
* L2 – compressed session memory (summaries of completed stages)
* L3 – durable project memory (key decisions, architecture, persistent facts)
* L4 – archival history (full event log, used only for deep replay)

Only L0–L2 are included in the context pack for a typical inference.

## 5.3 token budgets are enforced

Every context pack has a hard token limit. The budget is configurable per model and per stage. The context processor must trim aggressively.

## 5.4 router context is separate

The router has its own L2 memory, rebuilt from summaries after each stage. It never sees raw execution context unless needed for a specific user query.

---

# 6. context pack model

```kotlin
data class ContextPack(
    val layers: Map<ContextLayer, List<ContextEntry>>,
    val budgetUsed: Int,
    val budgetLimit: Int,
    val compressionMetadata: CompressionMetadata
)
```

Context entries are structured records pointing to artifact excerpts, summaries, policy hints, and steering notes.

---

# 7. synthesis pipeline

Pipeline steps (executed in order):

1. Retrieve relevant events from projection store (cursor‑based).
2. Deduplicate – remove repeated identical tool outputs, duplicate artifact versions.
3. Rank – score entries by relevance to current stage goals (may use a quick heuristic or a tiny model).
4. Compress – apply layer‑specific strategies (summarize tool logs, keep only latest valid artifact, semantic conversation compression).
5. Inject policies – insert active constraints relevant to the stage.
6. Tokenize and trim to budget.
7. Assemble final `ContextPack`.

---

# 8. compression strategies

Config‑driven, per data type:

| data type | default strategy |
|-----------|------------------|
| tool output | summarize (extract errors, key values) |
| artifacts | latest valid only |
| events | deduplicate + temporal decay |
| conversation | semantic summary (L2 only) |
| approvals | retain all (small) |
| steering notes | retain verbatim |

Semantic compression may use a dedicated small local model, but it must be deterministic‑enough (same model, same prompt → same compressed output). The harness treats compression as an inference call of its own, recorded as a `CompressionEvent`.

---

# 9. token budget model

Budgets are defined per model and per stage, with enforcement:

* hard limit on total context pack tokens
* reservation for system prompt/policies
* dynamic overflow: if compression cannot fit within limit, oldest L2 entries are dropped first.

---

# 10. session‑level token cap

A session‑wide total token cap exists for L2 memory. When exceeded, older L2 entries are merged into L3 project memory, and L2 is truncated. This prevents silent memory bloat in long sessions.

---

# 11. event ownership

`:core:context` emits:

* `ContextBuildingStarted`
* `ContextPackBuilt`
* `CompressionApplied`
* `LayerTruncated`

These events carry causation from the preceding stage schedule event.

---

# 12. consumed events

Consumes:

* `StageScheduled` (trigger)
* All domain events that feed the projection needed for context retrieval.

---

# 13. replay semantics

During replay, context compressions are either replayed from compression events (if available) or re‑executed deterministically. For inference‑skipping replay, context packs are still built to validate budget logic but not fed to models.

---

# 14. threading/concurrency

Context building is a CPU‑bound operation that runs within the orchestration coroutine. It must be cancellable and should not block the event loop for extreme histories (use batching/sampling if needed).

---

# 15. failure semantics

If context building fails (e.g., compression model unavailable), the stage cannot proceed. Event `ContextBuildingFailed` is emitted, and the transition engine may retry or fail the session.

---

# 16. observability requirements

* token usage per stage
* compression effectiveness (e.g., compression ratio)
* L2 memory size over time
* context building duration
* deduplication hit rate

---

# 17. security boundaries

Context packs may contain sensitive data. The module must support redaction/secret scrubbing before delivery to models (plugin point). No model should see raw secrets.

---

# 18. extension model

Extensions may provide:

* custom rankers
* custom compressors
* additional context layers (if needed)

All extensions must produce valid `ContextEntry` types and respect the token budget.

---

# 19. forbidden patterns

* raw event accumulation in context pack
* unbounded context growth
* mutable context state (context packs are ephemeral, built per stage)
* cross‑session context leaking
* hidden injection of unauthorized data

---

# 20. testing requirements

* determinism of deduction/ranking (given fixed input)
* token budget compliance
* compression quality metrics
* replay of context building
* router context isolation

---

# 21. philosophy

The context processor is the harness’s memory manager. It ensures that models never drown in their own history, and that every inference receives a sharp, purposeful slice of the past—nothing more, nothing less.