# Interventions Contract (Idempotent, Explicit Guarantees)

This document describes the intervention contract used by Entropic Core runtime components.

## Goals

- Make interventions safe to apply multiple times (idempotent).
- Make guarantees explicit and testable.
- Keep core behavior stable even if wrappers are nested or re-entrant.

## Contract Primitives

Implemented in `entropic_core/core/intervention_contract.py`.

- `InterventionKind`: stable labels for intervention types.
- `InterventionSpec`: kind + reason + params + `idempotency_key`.
- `make_idempotency_key(kind, scope, reason, params)`: stable key generator.
- `ensure_entropic_meta(request)`, `already_applied(request, key)`, `mark_applied(request, key)`:
  request-scoped bookkeeping on `request["_entropic"]["applied"]`.

## Grounding Injection (LLMMiddleware)

Where: `entropic_core/core/llm_middleware.py`

### What it does

Injects a system message instructing the model to ground its answer in verifiable context and to use explicit evidence ids (E1, E2, ...).

### Guarantees

- Idempotent: the same grounding injection will not be added twice for a single request object.
- Safe: does not remove or rewrite existing messages.
- Observable: `modified_request["_interventions"]` includes `grounding_added` when applied.

### Marker

Injected system messages include a stable marker:

`[ENTROPIC_CORE:GROUNDING key=<id>]`

## Consensus (Multi-Agent)

Where: `entropic_core/core/consensus_engine.py`

### What it does

`ConsensusEngine.consensus_for_text_outputs(outputs, confidences, entropies, method)` converts each agent output into a vote and chooses a winner using the configured method (default: entropy-weighted).

### Guarantees

- Deterministic: identical inputs produce the same `idempotency_key` and the same output.
- Observable: returns vote breakdown, dissenting agents, and confidence.

## Auto-Heal / Rollback

Where: `entropic_core/core/auto_healer.py`

### What it does

- `checkpoint(agent_id, state, entropy)` stores a deep copy snapshot.
- `rollback_snapshot(agent_id, checkpoint_id=None)` returns a deep copy of the stored snapshot.

### Guarantees

- Idempotent: repeated rollbacks return equivalent snapshots without mutating checkpoint history.
- Safe: rollback snapshot does not mutate the agent (caller applies the snapshot as appropriate).

## Context Pruning Safe (LLMMiddleware)

Where: `entropic_core/core/llm_middleware.py`

### What it does

Prunes the request message list to fit a token budget while preserving essential context.

### Guarantees

- Never removes system messages.
- Never removes tool outputs (`role == "tool"`).
- Never removes messages marked keep: `entropic_keep` / `_entropic_keep` / `metadata.entropic_keep`.
- Never removes messages that contain evidence ids like `E1` or `[E1]`.
- Always keeps the last 4 exchanges (8 non-system messages).
- If pinned messages alone exceed budget, it returns pinned messages (safety wins over budget).
- Idempotent per request object via `request["_entropic"]["applied"]`.

