crprotocol 2.2.0__tar.gz → 2.3.1__tar.gz

{crprotocol-2.2.0 → crprotocol-2.3.1}/CHANGELOG.md

@@ -1,414 +1,519 @@
-<!--
-  Copyright (c) 2026 Constantinos Vidiniotis. All rights reserved.
-  Licensed under the terms described in LICENSE.md in the root of this repository.
--->
-
-# Changelog
-
-All notable changes to the CRP specification will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- (none yet)
-
-## [2.2.0] - 2026-04-23
-
-### Added — Miscellaneous (from 2.1 Unreleased pool)
-- Trademark notice: "Context Relay Protocol" (application pending, Class 9)
-- Contact emails: info@crprotocol.io (general), contact@crprotocol.io (enterprise)
-- GitHub Discussions enabled
-- Operational runbook (`docs/OPERATIONS_RUNBOOK.md`) — deployment, monitoring, incident response
-- Integrity chain external verification (`export_for_verification()`, `verify_external()`)
-- `/metrics` endpoint on HTTP sidecar (Prometheus format)
-- Session file schema versioning with forward-compatible migration path
-- Bounded ingest queue (`maxsize=1000`) prevents unbounded memory growth
-- Pipeline short-circuit — skips late extraction stages when early stages produce enough facts
-- Config file layer — YAML/JSON config files (`~/.crp/config.yaml`, `.crp.yaml`)
-- Structured logging wired into orchestrator initialization
-- Metadata size limits on `Fact` (64 keys, 128-char key length, 4096-char value size)
-- `TypeAlias` annotations and extended type aliases in `crp/_typing.py`
-- All error types and config classes exported from `crp.__init__`
-
-### Changed — Miscellaneous (from 2.1 Unreleased pool)
-- `FactGraph` edge lookups now O(1) via indexed dicts (was O(n) list scan)
-- Provider error responses sanitized — no internal details leak to clients
-- Envelope builder truncates when exceeding token budget, clamps saturation to 1.0
-- Test fixtures use `tmp_path` pytest fixture instead of `tempfile.TemporaryDirectory()`
-- Correlation IDs propagated through ingest path
-
-### Fixed — Miscellaneous (from 2.1 Unreleased pool)
-- Unknown config kwargs now produce a warning log instead of silent ignore
-
-### Added — Enforcement Pipeline, Ledger & Injection Detection (§7.14.4–§7.14.5)
-
-CRP 2.1 defined the **vocabulary** for context-source provenance
-(`ContextSource`, `ContextManifest`). CRP 2.2 defines the **enforcement
-point** — the single wire-side choke-point every envelope assembly flows
-through — plus cross-turn persistence, key rotation, and content-side
-verification of declared trust labels. This closes the gap between
-"context is labelled" and "context is actually enforced on the wire".
-
-- New module `crp.core.context_enforcer` (§7.14.4):
-  - `EnforcementPolicy` (`OBSERVE` / `WARN` / `REJECT`) — application-
-    level policy for what happens on a violation.
-  - `ContextEnforcer` — composes manifest signature-verify, expiry
-    check, attestation mismatch scan (`check_attestation`), and
-    injection-signal scan into a single `check(manifest, observed)`
-    call. Under `REJECT`, raises `CRPError(CONTEXT_ATTESTATION_MISMATCH)`
-    or `CRPError(CONTEXT_MANIFEST_INVALID)`. Under `OBSERVE` / `WARN`,
-    emits audit events and continues.
-  - `detect_injection_signals()` — six high-precision regex patterns
-    (instruction override, role jailbreak, secret exfil, delimiter
-    forgery, dangerous payload URLs, embedded tool calls) applied to
-    sources declared `TrustLevel.TRUSTED`. Addresses the gap between
-    *declared* and *actual* trust — developers marking a system prompt
-    as TRUSTED doesn't make templated user input safe.
-  - `AuditSink` protocol + `LoggingAuditSink` + thread-safe
-    `InMemoryAuditSink` (bounded ring buffer). Every mismatch and
-    injection signal is emitted as a structured event for SIEM / audit
-    pipelines.
-  - `default_enforcer()` / `set_default_enforcer()` — process-wide
-    opt-in installer so libraries (dispatch router, CKF, warm store)
-    can find a configured enforcer without explicit plumbing.
-  - `observed_content(source, text)` helper for presenting source +
-    payload pairs to the enforcer for content scanning.
-
-- New module `crp.core.manifest_ledger` (§7.14.5):
-  - `ManifestLedger` — append-only JSONL store
-    (`crp_sessions/<session_id>.manifest.jsonl`) of every manifest ever
-    attached to a session. Supports `record()`, `load()`, `history()`,
-    `latest()`, `find_by_source_id()`, `find_by_kind()`, and
-    `verify_signatures()` for periodic integrity audits.
-  - `KeyProvider` abstraction with two implementations:
-    - `EnvVarKeyProvider` — reads HMAC secret from an environment
-      variable, auto-detects hex encoding, enforces ≥32-byte minimum.
-    - `RotatingKeyProvider` — current + retired key ring with
-      configurable grace window, allowing in-flight manifests signed
-      under the previous key to continue verifying after rotation.
-
-### Added — Consumer-Side Integration (§7.14.4 wire point)
-
-- `crp.core.dispatch_router.assemble_messages()` now accepts optional
-  `manifest`, `observed_sources`, and `enforcer` keyword arguments.
-  When supplied (or a process-wide default enforcer is installed),
-  every envelope assembly runs the full enforcement pipeline
-  **before** messages are constructed. Zero-cost when no enforcer is
-  configured — fully backward compatible with CRP 2.1 call sites.
-
-- `crp.state.warm_store.get_active_facts_as_extraction()` now stamps
-  every un-sourced fact with
-  `ContextSource(kind=WARM_STORE, origin=OBSERVED, trust_level=TRUSTED)`.
-
-- `crp.ckf.fabric.ContextKnowledgeFabric.retrieve()` now stamps every
-  un-sourced merged fact with `ContextSource(kind=CKF_RETRIEVAL, ...)`
-  carrying the retrieval modes and score in `metadata`.
-
-### Changed — Source-Kind Detection
-
-- `crp.core.context_source.detect_source_kind()` strengthened:
-  - New structural hint parser: attempts `json.loads(content)` and
-    inspects object keys (`function_name` + `arguments` → `FUNCTION_CALL`,
-    `mcp` / `mcp_server` → `MCP_TOOL`, `url` + `snippet` →
-    `WEB_SEARCH`, `embedding` / `vector` → `VECTOR_DB`).
-  - Six new heuristic regex patterns for JSON/XML/YAML code blocks,
-    SQL DML, Cypher / graph query keywords, SERPAPI / Google / Bing
-    signatures, common vector-DB provider names (Pinecone, Weaviate,
-    Qdrant, Chroma, pgvector, Milvus), and `function_name` / `tool_name`
-    tokens.
-  - Structural hints are preferred over regex when parsing succeeds.
-
-### Security
-
-- Manifest verification is now always attempted when both a signature
-  and a secret are present, even if `require_signed_manifest=False`.
-  Tampered signatures are detected and emitted as
-  `CONTEXT_MANIFEST_INVALID` audit events.
-- `ManifestLedger` rejects session IDs that sanitize to empty
-  (prevents directory traversal via crafted session identifiers).
-- HMAC verification continues to use `hmac.compare_digest` (constant
-  time). `RotatingKeyProvider` iterates candidate keys for verification
-  so key rotation does not create a signature-oracle side channel.
-
-### Tests
-
-- 38 new tests in `tests/test_context_enforcer.py` (injection patterns,
-  audit sinks, all three policies, default-enforcer install, integration
-  with `assemble_messages`).
-- 34 new tests in `tests/test_manifest_ledger.py` (JSONL round-trip,
-  cross-instance rehydration, lineage queries, key rotation, hex/utf-8
-  env secret decode, grace-window verification).
-- Total suite: **182 passing** (110 pre-2.2 baseline + 72 new).
-
-## [2.1.0] - 2026-04-23
-
-### Added — Context-Source Provenance (§7.14.3)
-- Contact emails: info@crprotocol.io (general), contact@crprotocol.io (enterprise)
-- GitHub Discussions enabled
-- Operational runbook (`docs/OPERATIONS_RUNBOOK.md`) — deployment, monitoring, incident response
-- Integrity chain external verification (`export_for_verification()`, `verify_external()`)
-- `/metrics` endpoint on HTTP sidecar (Prometheus format)
-- Session file schema versioning with forward-compatible migration path
-- Bounded ingest queue (`maxsize=1000`) prevents unbounded memory growth
-- Pipeline short-circuit — skips late extraction stages when early stages produce enough facts
-- Config file layer — YAML/JSON config files (`~/.crp/config.yaml`, `.crp.yaml`)
-- Structured logging wired into orchestrator initialization
-- Metadata size limits on `Fact` (64 keys, 128-char key length, 4096-char value size)
-- `TypeAlias` annotations and extended type aliases in `crp/_typing.py`
-- All error types and config classes exported from `crp.__init__`
-
-### Changed
-- `FactGraph` edge lookups now O(1) via indexed dicts (was O(n) list scan)
-- Provider error responses sanitized — no internal details leak to clients
-- Envelope builder truncates when exceeding token budget, clamps saturation to 1.0
-- Test fixtures use `tmp_path` pytest fixture instead of `tempfile.TemporaryDirectory()`
-- Correlation IDs propagated through ingest path
-
-### Fixed
-- Unknown config kwargs now produce a warning log instead of silent ignore
-
-## [2.1.0] - 2026-04-23
-
-### Added — Context-Source Provenance (§7.14.3)
-
-CRP's Decision Provenance Engine already classifies every *output* claim as
-`CONTEXT_GROUNDED | PARAMETRIC | MIXED | UNCERTAIN`. This release adds the
-symmetric **input-side** primitive: every fact that enters the envelope
-can now carry a record of *where it came from* (RAG chunk, vector DB,
-database read, MCP tool, function call, web search, user turn, file upload,
-agent memory, or parametric). This is foundational for ISO/IEC 42001 §4
-(Context of the organisation), EU AI Act Art. 10 (Data governance),
-GDPR Art. 30 (Records of Processing), and NIST AI RMF MAP-4.
-
-- New module `crp.core.context_source` with:
-  - `SourceKind` — closed enumeration (14 values) of upstream source
-    categories. Additions require an RFC.
-  - `ContextSource` — immutable (`frozen=True`) record: `kind`, `source_id`,
-    `origin` (declared / observed / heuristic), `trust_level`,
-    `contains_pii`, `sensitivity`, `region`, `retrieval_query`,
-    `retrieved_at`, `upstream_uri`, `declared_by_manifest_id`, `metadata`.
-  - `ContextManifest` — customer-authored declarative attestation of
-    intended upstream sources. HMAC-SHA256 signed over canonical JSON,
-    with `sign()` / `verify()` using constant-time comparison and
-    `is_expired()` helpers.
-  - `detect_source_kind(content, role=…)` — detective-mode heuristic
-    parser that classifies message content by OpenAI-style role plus a
-    conservative pattern library (`<RAG>`, `[retrieved]`, `<mcp:>`,
-    `SELECT … FROM …`, web-search markers, etc.).
-  - `check_attestation(observed, manifest)` — returns a list of
-    `AttestationMismatch` rows (reasons: `no_manifest`,
-    `manifest_expired`, `unattested_kind`, `unattested_source_id`).
-    `to_audit_event()` produces the §7.14.2 audit-event envelope shape.
-- `Fact.source: ContextSource | None` — optional field; defaults to
-  `None` so v2.0 callers see zero behavioural change.
-- Envelope section `[CONTEXT_SOURCES]` registered in the Tier 3 priority
-  list (`crp/envelope/formatter.py::TIER_3_SECTIONS`).
-- Error codes `CONTEXT_ATTESTATION_MISMATCH = 1040` and
-  `CONTEXT_MANIFEST_INVALID = 1041`.
-- `ManifestValidationError` raised on malformed JSON / empty signing key.
-- All primitives exported from `crp` (`SourceKind`, `SourceOrigin`,
-  `TrustLevel`, `ContextSource`, `ContextManifest`, `AttestationMismatch`,
-  `ManifestValidationError`, `detect_source_kind`, `check_attestation`).
-- 41-test suite (`tests/test_context_source.py`) covering frozen
-  invariant, size limits, JSON round-trip, HMAC sign / verify, expiry,
-  detective-mode classification, attestation-mismatch edge cases, audit
-  event shape, and public API surface.
-
-### Changed
-
-- `docs/CRP_CAPABILITIES.md` now lists context-source provenance as a
-  first-class capability.
-- MkDocs site gains a dedicated *Protocol → Context Sources* page.
-
-### Migration notes
-
-This release is **fully backward-compatible**. `Fact.source` defaults to
-`None`; consumers that ignore the field continue to work unchanged. To
-adopt, wrap retrieved chunks with `ContextSource` at ingestion time:
-
-```python
-from crp import ContextSource, SourceKind, SourceOrigin, Fact
-
-fact = Fact(
-    text=chunk.text,
-    source=ContextSource(
-        kind=SourceKind.VECTOR_DB,
-        source_id="acme-hr-policies-vdb",
-        origin=SourceOrigin.OBSERVED,
-        contains_pii=True,
-        region="eu-west-1",
-        retrieval_query=user_query,
-    ),
-)
-```
-
-See `docs/protocol/context-sources.md` (published on crprotocol.io) for
-the full integration guide.
-
-## [2.0.0] - 2026-04-06
-
-### Added
-
-- **HTTP Sidecar Security Hardening & Full Protocol Surface** (§F2-security)
-  - Defense-in-depth security model: 8 layers enforced on every request
-  - Bearer-token authentication with timing-safe comparison (`secrets.compare_digest`)
-  - Session ownership: sessions bound to SHA-256 hash of the creating token, other tokens get `403 Forbidden`
-  - Per-IP rate limiting with monotonic-clock sliding window (default 120 req/60s, configurable)
-  - Request body size limit: 10 MB cap, returns `413 Payload Too Large` when exceeded
-  - Concurrent session cap: default 64, returns `503 Service Unavailable` when exceeded
-  - Security headers on every response: `X-Content-Type-Options: nosniff`, `Cache-Control: no-store`
-  - `--bind-all` security gate: requires `--auth-token` unless `--allow-unauthenticated` explicitly set
-  - Full protocol surface exposed: all 6 dispatch variants (basic, tools, reflexive, progressive, stream-augmented, agentic) over HTTP
-  - New endpoints: `/facts/feedback` (boost/penalize/reject), `/providers` (register fallback), `/estimate` (cost estimation)
-  - Input validation on all endpoints: variant validation, required fields, capped limits
-  - CLI options: `--max-sessions`, `--rate-limit`, `--allow-unauthenticated`
-  - README: dedicated "Inter-LLM Context Sharing" section with endpoint reference, security model, and usage examples
-
-- **Deep Audit Gap Fixes — F1-F6, D1-D9** (§gap-audit)
-  - F1: README provider claims corrected — removed false Google/vLLM/HuggingFace references
-  - F2: `crp serve` HTTP sidecar implemented (`crp/cli/sidecar.py`) — full REST API with inter-LLM context sharing via `/facts/share` endpoint
-  - F3: Provider fallback chain — `LLMProviderManager.generate_with_fallback()` tries primary then registered providers
-  - F4: README RBAC enforcement note corrected — now accurately reflects full enforcement
-  - F5: Test count updated 266 → 351
-  - F6: `EventEmitter` wired into orchestrator — 30+ event types emitted at all pipeline stages (dispatch.started/completed, envelope.built, window.opened/continued/completed, fact.created, extraction.completed, session.closed)
-  - D1: `CQSDetector` wired — context hunger detection after LLM generation
-  - D2: `CrossWindowValidator` wired — extraction-based consistency validation after continuation loop
-  - D3: `FeedbackLoop` wired — confidence adjustments after extraction, public API (boost/penalize/reject)
-  - D4: `ParallelFanOut` wired — instantiated with dispatch/extract callables
-  - D5: `ReviewCycleManager` wired — checkpoint_review in continuation loop
-  - D6: `ScaleModeSelector` wired — configured at dispatch start from session processing_mode
-  - D7: `EventEmitter` wired (same as F6)
-  - D8: `TelemetryWriter` wired — optional JSONL sink for window telemetry
-  - D9: `LLMProviderManager` wired with fallback chain (same as F3)
-  - Public API: `emitter` property, `on()` subscription, `feedback` property, `boost_fact()`/`penalize_fact()`/`reject_fact()`, `register_provider()`, `parallel` property
-  - HTTP sidecar endpoints: POST /sessions, GET /sessions/:id/status, POST /sessions/:id/dispatch, POST /sessions/:id/ingest, GET /sessions/:id/facts, POST /sessions/:id/facts/share, POST /sessions/:id/close, GET /health
-  - All 351 tests passing after changes
-
-- **Adaptive Resource Allocation & Efficiency-First Optimization** (§resource-alloc)
-  - `AdaptiveAllocator` — dynamic pipeline tuning based on real-time overhead + memory pressure
-  - **Efficiency-first philosophy**: ML extraction stages (GLiNER, UIE, discourse) are core intelligence — never disabled
-  - `PROTECTED_INTELLIGENCE` frozenset — ML features excluded from shedding cascade and stage scheduling
-  - Throughput-based throttling: normal → throttled → constrained (adjusts fact limits, batch sizes, packing) instead of disabling stages
-  - `PromptEfficiency` dataclass — LLM-side optimization hints: fact deduplication, system prompt caching, envelope compression, connection reuse, estimated cache hit percentage
-  - EWMA-smoothed overhead tracking with configurable cap (default 15%)
-  - `_adapt_throughput()` — adjusts throughput level based on overhead trends without sacrificing intelligence
-  - `OverheadBudgetManager` wired into orchestrator — shedding cascade now live, ML features protected
-  - `ExtractionProfile` / `EnvelopeProfile` — recommended configurations based on resource state (stages always enabled)
-  - Consecutive over-cap detection: 3+ consecutive windows triggers throughput reduction
-  - `detect_hardware()` — auto-detects CPU count, total/available RAM (Windows + POSIX)
-  - `WindowOverheadRecord` per-window metrics with features shed + stages skipped tracking
-  - `ResourceManager.mark_unloaded()` / `trigger_gc()` — model lifecycle + conditional GC
-  - `_record_dispatch_overhead()` on orchestrator — feeds overhead to allocator after every dispatch
-  - `_allocator_fields()` → 4 new WindowMetrics fields: `adaptive_ewma_overhead_pct`, `adaptive_features_shed`, `adaptive_stages_disabled`, `adaptive_consecutive_over`
-  - All 6 dispatch variants wired: dispatch, dispatch_with_tools, dispatch_reflexive, dispatch_progressive, dispatch_stream_augmented, dispatch_agentic
-  - Tests covering hardware detection, EWMA smoothing, throughput adaptation, ML protection, prompt efficiency, profile generation, model lifecycle, edge cases
-  - Test count: 266 → 351
-
-- **Resource Management & Meta-Learning Hardening** (§audit R2)
-  - `ResourceManager` — centralized model registry, memory pressure tracking, GC orchestration
-  - `ResourceSnapshot` dataclass — point-in-time view of memory budget, model utilization, pressure level
-  - Pressure levels: none/low/medium/high/critical based on estimated CRP memory vs. budget
-  - Model lifecycle tracking: register, load, use, unload, idle detection
-  - Platform-aware RSS reading (Windows ctypes + POSIX /proc/self/status)
-  - `CalibrationState` adaptive recalibration — drift detection replaces permanent baseline lock
-  - Rolling window analysis (last 10 windows) with 30% drift threshold triggers recalibration
-  - `calibration_epoch` counter tracks how many times baselines have been recalibrated
-  - WindowMetrics `ram_available_mb`, `ram_used_by_crp_mb`, `pressure_level` now live-computed
-  - WindowMetrics `marginal_gain` now computed as new-fact ratio per window
-  - WindowMetrics `sections_covered` now counts unique Markdown headers in output
-  - All 5 formerly-dead WindowMetrics fields are now populated across all 6 dispatch variants
-  - `_resource_fields()` and `_marginal_fields()` helpers on orchestrator
-  - GC runs automatically on `close()` for clean session teardown
-  - 38 tests covering ResourceManager, CalibrationState recalibration, marginal gain, sections
-
-- **§22 — LLM-in-the-Loop Agentic Architecture** (PARADIGM SHIFT)
-  - CRPFacilitator cognitive engine with 6 LLM-driven decision modules
-  - Task analysis (§22.1) — LLM semantically understands task complexity
-  - Strategy routing (§22.2) — LLM chooses optimal dispatch strategy
-  - Fact synthesis (§22.3) — LLM merges/compresses knowledge base facts
-  - Output evaluation (§22.4) — LLM assesses output quality
-  - Memory curation (§22.5) — LLM manages CRP's knowledge base
-  - Execution planning (§22.6) — LLM decomposes complex tasks into multi-step plans
-  - Multi-step plan execution — each plan step dispatches with its own strategy
-  - Enhanced revision loop — structured evaluation feedback, strategy adjustment
-  - Post-revision curation — iterative knowledge refinement
-  - Continuation awareness — inner dispatch continuation state feeds into evaluation
-  - 12 agentic telemetry fields in WindowMetrics
-  - 84 tests covering all cognitive modules and integration paths
-
-- **Multi-Perspective Audit & CKF Gate Fix**
-  - 5-perspective audit documented in CRP_MULTI_PERSPECTIVE_AUDIT.md
-  - CKF Phase 6 gate reworked: budget reservation (15% or 120 tokens min) ensures CKF retrieval fires even at high envelope saturation
-  - CKF_GATE_TOKENS lowered from 500 to 120 tokens
-  - CKF_RESERVE_RATIO constant (0.15) reserves budget before warm store packing
-  - Concurrency model documented in README.md
-  - README badge corrected (709 → 185 tests)
-  - 11 CKF gate tests added (test_ckf_gate.py)
-
-- **§21 — Novel Relay Strategies**
-  - Reflexive dispatch — generate-then-verify with fact-checking
-  - Progressive dispatch — compact index with on-demand expansion
-  - Stream-augmented dispatch — mid-generation context injection
-  - 61 tests covering all three strategies
-
-- **§20 — Tool-Mediated Dispatch**
-  - `dispatch_with_tools()` — LLM requests context via tool calls
-  - Multi-round tool negotiation with safety cap
-  - Fact extraction from tool dispatch outputs
-  - 34 tests covering tool relay pipeline
-
-- **Complete CRP v2.0 Specification** — 9 documents, ~19,200 lines
-  - 01_RESEARCH_FOUNDATIONS.md — Academic research backing (9 research areas, 40+ papers)
-  - 02_CORE_PROTOCOL.md — Core specification (29 sections, ~6,800 lines)
-  - 03_CONTEXT_ENVELOPE.md — Context envelope architecture
-  - 04_TOKEN_GENERATION_PROTOCOL.md — Unbounded output via continuation
-  - 05_SYSTEM_WIDE_INTEGRATION.md — Integration architecture (87+ call sites)
-  - 06_IMPLEMENTATION_PLAN.md — Implementation roadmap
-  - 07_SECURITY.md — Security architecture (OWASP-aligned, 14 sections)
-  - 08_MONETIZATION.md — Business model (PostgreSQL model — full capability free)
-  - 09_DEPLOYMENT.md — Deployment architecture (embedded library)
-
-- **JSON Schemas** (Draft 2020-12) for all API types:
-  - task-intent.json, quality-report.json, session-status.json
-  - cost-estimate.json, envelope-preview.json, session-handle.json
-  - stream-event.json, crp-error.json, persisted-state-header.json
-
-- **Contextual Knowledge Fabric (CKF)** — normative knowledge layer:
-  - Graph walk, pattern query, semantic fallback, community summary retrieval
-  - Event-sourced history, pub-sub architecture
-  - Cross-session persistence
-
-- **6-Stage Extraction Pipeline** (blackboard-reactive):
-  - Regex → Statistical (TextRank) → GLiNER NER → UIE Relations → RST Discourse → LLM-Assisted Relational
-
-- **Quality Tier System** — S/A/B/C/D with degradation model
-
-- **Multi-Signal Completion Detection** — fact flow + structural flow + vocabulary novelty + structural completion
-
-- **Meta-Learning Architecture** — ORC + ICML + RTL for small model reasoning amplification
-
-- **Security Architecture** — HMAC binding, RBAC, encryption at rest, fact integrity chains, OWASP mapping
-
-- **API Formalism** (§6.10) — RFC 2119 operation contracts, error taxonomy (13 codes), streaming API, async API, stability tiers
-
-- **Concurrency Model** (§23) — thread safety, lock ordering, session-level serialization
-
-- **Observability & Audit** (§24) — event model, telemetry, window DAG traceability
-
-- **Configuration Management** (§25) — 5-layer hierarchy
-
-- **Multi-Provider LLM Interface** (§26) — provider-agnostic adapter pattern
-
-- **Deployment Architecture** (§27 + 09_DEPLOYMENT) — embedded library, Lambda/K8s scenarios
-
-- **Publication & Adoption Strategy** (§28) — repo structure, visibility strategy, standards track
-
-### Design Decisions
-
-- CKF is **free and normative** — ships with every conformant SDK (PostgreSQL model)
-- CRP is an **embedded library**, not a server — zero deployment overhead
-- Protocol is **language-neutral** — JSON Schema for all types, pseudocode for algorithms
-- All 11 Knowledge Backend Interface operations are **REQUIRED**
-- GLiNER domain models are **FUTURE** work (Phase 3+)
+<!--
+  Copyright (c) 2026 Constantinos Vidiniotis. All rights reserved.
+  Licensed under the terms described in LICENSE.md in the root of this repository.
+-->
+
+# Changelog
+
+All notable changes to the CRP specification will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- (none yet)
+
+## [2.3.1] - 2026-04-24
+
+### Fixed
+
+- **Dispatch infinite-loop on trivial provider outputs** — fixed a hang in
+  `DispatchMixin` where the continuation loop could fire repeatedly against
+  a provider returning tiny/stop-reason outputs (common with mock/thin
+  providers and very cheap local models).
+  - `crp.continuation.trigger.TriggerConfig` gained
+    `gap_override_min_output_tokens` (default `16`): the gap-score override
+    path is now suppressed when the observed output is below this threshold
+    **and** the provider already reported `finish_reason="stop"`.
+  - `crp.core.config` gained a new `continuation_pause_s` key
+    (default `0.0`, bounds `[0.0, 60.0]`) that replaces the previously
+    hardcoded `time.sleep(2)` between continuation windows in
+    `DispatchMixin`. Local/slow-backend users can opt back in by setting
+    `continuation_pause_s=2.0` in their CRP config.
+  - Test assertions in `tests/test_phase1.py` were relaxed from exact
+    equality to `startswith("fake output")` so they tolerate the CRP 2.3
+    tamper-evidence signature tail (`<!-- CRP | ELv2 | ... -->`).
+  - Verified: `pytest tests/test_phase1.py::TestOrchestrator` now passes
+    16/16 in ~75s (previously hung indefinitely).
+
+## [2.3.0] - 2026-04-23
+
+### Added — Closes all 5 protocol-oversight gaps identified in 2.2
+
+- **G1 — Provider/framework hooks (`crp.integrations`)**: auto-instrument
+  uninstrumented call sites so CRP sees every model call even when the
+  integrator hand-builds requests or uses a third-party framework.
+  - `crp.integrations.openai_hook.install()` / `uninstall()` — monkey-patches
+    `openai.OpenAI.chat.completions.create` (sync + async) to route through
+    the configured `ContextEnforcer` before dispatch.
+  - `crp.integrations.anthropic_hook.install()` / `uninstall()` — same for
+    `anthropic.Anthropic.messages.create`.
+  - `crp.integrations.langchain_hook.CRPCallbackHandler` — LangChain
+    `BaseCallbackHandler` that records every LLM/chain/tool invocation to
+    the ledger and enforces policy pre-flight.
+  - New exports: `install_openai_hook`, `install_anthropic_hook`,
+    `CRPCallbackHandler` on the top-level `crp` package.
+
+- **G2 — Derived manifests (`crp.core.manifest_derive`)**: infer a manifest
+  from observed bytes when integrators skip declaration. Distinguishes
+  *lazy* (content exists but no stamp) from *genuinely ephemeral* (no
+  durable source to stamp).
+  - `derive_manifest_from_content(...)` — SHA-256 digest, heuristic
+    `SourceKind` classification, `TrustLevel.UNKNOWN` stamp.
+  - `derive_manifest_batch(...)` — batch-derive across a list of observed
+    payloads.
+  - Integrators who never stamp sources now get OBSERVE-level enforcement
+    benefit: derived manifests flow through the ledger just like declared
+    ones, with an explicit `origin=SourceOrigin.DERIVED` marker.
+
+- **G3 — Turn-level enforcement**: `ContextEnforcer` re-validates every
+  turn, including `tool_result` injections mid-conversation.
+  - `ContextEnforcer.check_messages(messages, observed=...)` — runs the
+    full enforcement pipeline against an entire chat-completions-shape
+    message list.
+  - `ContextEnforcer.check_tool_result(tool_call_id, content, ...)` —
+    re-validates a single `tool_result` before it re-enters the prompt.
+
+- **G4 — Ledger hardening (`ManifestLedger`)**: tamper-evident hash chain,
+  SIEM/JSONL forwarding, pluggable backends.
+  - Every appended entry now carries `prev_hash` + `entry_hash`. Breaking
+    the chain is detected by `ManifestLedger.verify_chain(session_id)`.
+  - `ManifestLedger(forward_to=[AuditSink(...)])` — optional list of audit
+    sinks; each recorded entry is also emitted as an audit event so SIEM
+    forwarders / syslog / JSONL replicators see the ledger write in real
+    time. Forwarding never blocks ledger writes.
+  - `crp.core.ledger_backends` — `LedgerBackend` protocol plus
+    `JsonlFileSink` and `SyslogSink` reference implementations.
+
+- **G5 — Default observe enforcer**: `assemble_messages` now auto-installs
+  an `OBSERVE`-mode enforcer if the integrator forgot to configure one.
+  Safer-by-default; closes the silent-skip footgun.
+
+- **Custom / local-endpoint providers**: `OpenAIAdapter` now accepts
+  empty-string or `None` `api_key` when `base_url` is set. Unblocks
+  LM Studio, vLLM, llama.cpp server, Ollama OpenAI-compat, TGI, and any
+  unauthenticated local endpoint. Verified live against
+  `gemma-3-270m-it-qat` on LM Studio (`http://192.168.0.6:1234`).
+
+### Changed
+
+- `ContextEnforcer.__init__` gained `key_provider`, `ledger`, and
+  `session_id` kwargs (additive; all optional). No existing call site
+  needs to change.
+- `ManifestLedgerEntry` now always contains `prev_hash` + `entry_hash` on
+  newly written entries; legacy entries without hash fields are treated
+  as "chain origin" and do not break verification.
+
+### Fixed
+
+- `AttestationMismatch.observed_source` attribute access regression
+  (previously crashed when an enforcer rejected a manifest mismatch).
+
+### Verification
+
+- 30 new tests in `tests/test_gaps_2_3.py` covering all 5 gaps end-to-end.
+- Live end-to-end verification against LM Studio (`gemma-3-270m-it-qat`)
+  — 4/4 stages pass: empty-key adapter, basic generation, dispatch
+  through `ContextEnforcer` (OBSERVE) + `ManifestLedger`, multi-turn
+  sequential generation with explicit resource management.
+- 163 core + gap tests pass serial (no parallelism).
+
+## [2.2.0] - 2026-04-23
+
+### Added — Miscellaneous (from 2.1 Unreleased pool)
+- Trademark notice: "Context Relay Protocol" (application pending, Class 9)
+- Contact emails: info@crprotocol.io (general), contact@crprotocol.io (enterprise)
+- GitHub Discussions enabled
+- Operational runbook (`docs/OPERATIONS_RUNBOOK.md`) — deployment, monitoring, incident response
+- Integrity chain external verification (`export_for_verification()`, `verify_external()`)
+- `/metrics` endpoint on HTTP sidecar (Prometheus format)
+- Session file schema versioning with forward-compatible migration path
+- Bounded ingest queue (`maxsize=1000`) prevents unbounded memory growth
+- Pipeline short-circuit — skips late extraction stages when early stages produce enough facts
+- Config file layer — YAML/JSON config files (`~/.crp/config.yaml`, `.crp.yaml`)
+- Structured logging wired into orchestrator initialization
+- Metadata size limits on `Fact` (64 keys, 128-char key length, 4096-char value size)
+- `TypeAlias` annotations and extended type aliases in `crp/_typing.py`
+- All error types and config classes exported from `crp.__init__`
+
+### Changed — Miscellaneous (from 2.1 Unreleased pool)
+- `FactGraph` edge lookups now O(1) via indexed dicts (was O(n) list scan)
+- Provider error responses sanitized — no internal details leak to clients
+- Envelope builder truncates when exceeding token budget, clamps saturation to 1.0
+- Test fixtures use `tmp_path` pytest fixture instead of `tempfile.TemporaryDirectory()`
+- Correlation IDs propagated through ingest path
+
+### Fixed — Miscellaneous (from 2.1 Unreleased pool)
+- Unknown config kwargs now produce a warning log instead of silent ignore
+
+### Added — Enforcement Pipeline, Ledger & Injection Detection (§7.14.4–§7.14.5)
+
+CRP 2.1 defined the **vocabulary** for context-source provenance
+(`ContextSource`, `ContextManifest`). CRP 2.2 defines the **enforcement
+point** — the single wire-side choke-point every envelope assembly flows
+through — plus cross-turn persistence, key rotation, and content-side
+verification of declared trust labels. This closes the gap between
+"context is labelled" and "context is actually enforced on the wire".
+
+- New module `crp.core.context_enforcer` (§7.14.4):
+  - `EnforcementPolicy` (`OBSERVE` / `WARN` / `REJECT`) — application-
+    level policy for what happens on a violation.
+  - `ContextEnforcer` — composes manifest signature-verify, expiry
+    check, attestation mismatch scan (`check_attestation`), and
+    injection-signal scan into a single `check(manifest, observed)`
+    call. Under `REJECT`, raises `CRPError(CONTEXT_ATTESTATION_MISMATCH)`
+    or `CRPError(CONTEXT_MANIFEST_INVALID)`. Under `OBSERVE` / `WARN`,
+    emits audit events and continues.
+  - `detect_injection_signals()` — six high-precision regex patterns
+    (instruction override, role jailbreak, secret exfil, delimiter
+    forgery, dangerous payload URLs, embedded tool calls) applied to
+    sources declared `TrustLevel.TRUSTED`. Addresses the gap between
+    *declared* and *actual* trust — developers marking a system prompt
+    as TRUSTED doesn't make templated user input safe.
+  - `AuditSink` protocol + `LoggingAuditSink` + thread-safe
+    `InMemoryAuditSink` (bounded ring buffer). Every mismatch and
+    injection signal is emitted as a structured event for SIEM / audit
+    pipelines.
+  - `default_enforcer()` / `set_default_enforcer()` — process-wide
+    opt-in installer so libraries (dispatch router, CKF, warm store)
+    can find a configured enforcer without explicit plumbing.
+  - `observed_content(source, text)` helper for presenting source +
+    payload pairs to the enforcer for content scanning.
+
+- New module `crp.core.manifest_ledger` (§7.14.5):
+  - `ManifestLedger` — append-only JSONL store
+    (`crp_sessions/<session_id>.manifest.jsonl`) of every manifest ever
+    attached to a session. Supports `record()`, `load()`, `history()`,
+    `latest()`, `find_by_source_id()`, `find_by_kind()`, and
+    `verify_signatures()` for periodic integrity audits.
+  - `KeyProvider` abstraction with two implementations:
+    - `EnvVarKeyProvider` — reads HMAC secret from an environment
+      variable, auto-detects hex encoding, enforces ≥32-byte minimum.
+    - `RotatingKeyProvider` — current + retired key ring with
+      configurable grace window, allowing in-flight manifests signed
+      under the previous key to continue verifying after rotation.
+
+### Added — Consumer-Side Integration (§7.14.4 wire point)
+
+- `crp.core.dispatch_router.assemble_messages()` now accepts optional
+  `manifest`, `observed_sources`, and `enforcer` keyword arguments.
+  When supplied (or a process-wide default enforcer is installed),
+  every envelope assembly runs the full enforcement pipeline
+  **before** messages are constructed. Zero-cost when no enforcer is
+  configured — fully backward compatible with CRP 2.1 call sites.
+
+- `crp.state.warm_store.get_active_facts_as_extraction()` now stamps
+  every un-sourced fact with
+  `ContextSource(kind=WARM_STORE, origin=OBSERVED, trust_level=TRUSTED)`.
+
+- `crp.ckf.fabric.ContextKnowledgeFabric.retrieve()` now stamps every
+  un-sourced merged fact with `ContextSource(kind=CKF_RETRIEVAL, ...)`
+  carrying the retrieval modes and score in `metadata`.
+
+### Changed — Source-Kind Detection
+
+- `crp.core.context_source.detect_source_kind()` strengthened:
+  - New structural hint parser: attempts `json.loads(content)` and
+    inspects object keys (`function_name` + `arguments` → `FUNCTION_CALL`,
+    `mcp` / `mcp_server` → `MCP_TOOL`, `url` + `snippet` →
+    `WEB_SEARCH`, `embedding` / `vector` → `VECTOR_DB`).
+  - Six new heuristic regex patterns for JSON/XML/YAML code blocks,
+    SQL DML, Cypher / graph query keywords, SERPAPI / Google / Bing
+    signatures, common vector-DB provider names (Pinecone, Weaviate,
+    Qdrant, Chroma, pgvector, Milvus), and `function_name` / `tool_name`
+    tokens.
+  - Structural hints are preferred over regex when parsing succeeds.
+
+### Security
+
+- Manifest verification is now always attempted when both a signature
+  and a secret are present, even if `require_signed_manifest=False`.
+  Tampered signatures are detected and emitted as
+  `CONTEXT_MANIFEST_INVALID` audit events.
+- `ManifestLedger` rejects session IDs that sanitize to empty
+  (prevents directory traversal via crafted session identifiers).
+- HMAC verification continues to use `hmac.compare_digest` (constant
+  time). `RotatingKeyProvider` iterates candidate keys for verification
+  so key rotation does not create a signature-oracle side channel.
+
+### Tests
+
+- 38 new tests in `tests/test_context_enforcer.py` (injection patterns,
+  audit sinks, all three policies, default-enforcer install, integration
+  with `assemble_messages`).
+- 34 new tests in `tests/test_manifest_ledger.py` (JSONL round-trip,
+  cross-instance rehydration, lineage queries, key rotation, hex/utf-8
+  env secret decode, grace-window verification).
+- Total suite: **182 passing** (110 pre-2.2 baseline + 72 new).
+
+## [2.1.0] - 2026-04-23
+
+### Added — Context-Source Provenance (§7.14.3)
+- Contact emails: info@crprotocol.io (general), contact@crprotocol.io (enterprise)
+- GitHub Discussions enabled
+- Operational runbook (`docs/OPERATIONS_RUNBOOK.md`) — deployment, monitoring, incident response
+- Integrity chain external verification (`export_for_verification()`, `verify_external()`)
+- `/metrics` endpoint on HTTP sidecar (Prometheus format)
+- Session file schema versioning with forward-compatible migration path
+- Bounded ingest queue (`maxsize=1000`) prevents unbounded memory growth
+- Pipeline short-circuit — skips late extraction stages when early stages produce enough facts
+- Config file layer — YAML/JSON config files (`~/.crp/config.yaml`, `.crp.yaml`)
+- Structured logging wired into orchestrator initialization
+- Metadata size limits on `Fact` (64 keys, 128-char key length, 4096-char value size)
+- `TypeAlias` annotations and extended type aliases in `crp/_typing.py`
+- All error types and config classes exported from `crp.__init__`
+
+### Changed
+- `FactGraph` edge lookups now O(1) via indexed dicts (was O(n) list scan)
+- Provider error responses sanitized — no internal details leak to clients
+- Envelope builder truncates when exceeding token budget, clamps saturation to 1.0
+- Test fixtures use `tmp_path` pytest fixture instead of `tempfile.TemporaryDirectory()`
+- Correlation IDs propagated through ingest path
+
+### Fixed
+- Unknown config kwargs now produce a warning log instead of silent ignore
+
+## [2.1.0] - 2026-04-23
+
+### Added — Context-Source Provenance (§7.14.3)
+
+CRP's Decision Provenance Engine already classifies every *output* claim as
+`CONTEXT_GROUNDED | PARAMETRIC | MIXED | UNCERTAIN`. This release adds the
+symmetric **input-side** primitive: every fact that enters the envelope
+can now carry a record of *where it came from* (RAG chunk, vector DB,
+database read, MCP tool, function call, web search, user turn, file upload,
+agent memory, or parametric). This is foundational for ISO/IEC 42001 §4
+(Context of the organisation), EU AI Act Art. 10 (Data governance),
+GDPR Art. 30 (Records of Processing), and NIST AI RMF MAP-4.
+
+- New module `crp.core.context_source` with:
+  - `SourceKind` — closed enumeration (14 values) of upstream source
+    categories. Additions require an RFC.
+  - `ContextSource` — immutable (`frozen=True`) record: `kind`, `source_id`,
+    `origin` (declared / observed / heuristic), `trust_level`,
+    `contains_pii`, `sensitivity`, `region`, `retrieval_query`,
+    `retrieved_at`, `upstream_uri`, `declared_by_manifest_id`, `metadata`.
+  - `ContextManifest` — customer-authored declarative attestation of
+    intended upstream sources. HMAC-SHA256 signed over canonical JSON,
+    with `sign()` / `verify()` using constant-time comparison and
+    `is_expired()` helpers.
+  - `detect_source_kind(content, role=…)` — detective-mode heuristic
+    parser that classifies message content by OpenAI-style role plus a
+    conservative pattern library (`<RAG>`, `[retrieved]`, `<mcp:>`,
+    `SELECT … FROM …`, web-search markers, etc.).
+  - `check_attestation(observed, manifest)` — returns a list of
+    `AttestationMismatch` rows (reasons: `no_manifest`,
+    `manifest_expired`, `unattested_kind`, `unattested_source_id`).
+    `to_audit_event()` produces the §7.14.2 audit-event envelope shape.
+- `Fact.source: ContextSource | None` — optional field; defaults to
+  `None` so v2.0 callers see zero behavioural change.
+- Envelope section `[CONTEXT_SOURCES]` registered in the Tier 3 priority
+  list (`crp/envelope/formatter.py::TIER_3_SECTIONS`).
+- Error codes `CONTEXT_ATTESTATION_MISMATCH = 1040` and
+  `CONTEXT_MANIFEST_INVALID = 1041`.
+- `ManifestValidationError` raised on malformed JSON / empty signing key.
+- All primitives exported from `crp` (`SourceKind`, `SourceOrigin`,
+  `TrustLevel`, `ContextSource`, `ContextManifest`, `AttestationMismatch`,
+  `ManifestValidationError`, `detect_source_kind`, `check_attestation`).
+- 41-test suite (`tests/test_context_source.py`) covering frozen
+  invariant, size limits, JSON round-trip, HMAC sign / verify, expiry,
+  detective-mode classification, attestation-mismatch edge cases, audit
+  event shape, and public API surface.
+
+### Changed
+
+- `docs/CRP_CAPABILITIES.md` now lists context-source provenance as a
+  first-class capability.
+- MkDocs site gains a dedicated *Protocol → Context Sources* page.
+
+### Migration notes
+
+This release is **fully backward-compatible**. `Fact.source` defaults to
+`None`; consumers that ignore the field continue to work unchanged. To
+adopt, wrap retrieved chunks with `ContextSource` at ingestion time:
+
+```python
+from crp import ContextSource, SourceKind, SourceOrigin, Fact
+
+fact = Fact(
+    text=chunk.text,
+    source=ContextSource(
+        kind=SourceKind.VECTOR_DB,
+        source_id="acme-hr-policies-vdb",
+        origin=SourceOrigin.OBSERVED,
+        contains_pii=True,
+        region="eu-west-1",
+        retrieval_query=user_query,
+    ),
+)
+```
+
+See `docs/protocol/context-sources.md` (published on crprotocol.io) for
+the full integration guide.
+
+## [2.0.0] - 2026-04-06
+
+### Added
+
+- **HTTP Sidecar Security Hardening & Full Protocol Surface** (§F2-security)
+  - Defense-in-depth security model: 8 layers enforced on every request
+  - Bearer-token authentication with timing-safe comparison (`secrets.compare_digest`)
+  - Session ownership: sessions bound to SHA-256 hash of the creating token, other tokens get `403 Forbidden`
+  - Per-IP rate limiting with monotonic-clock sliding window (default 120 req/60s, configurable)
+  - Request body size limit: 10 MB cap, returns `413 Payload Too Large` when exceeded
+  - Concurrent session cap: default 64, returns `503 Service Unavailable` when exceeded
+  - Security headers on every response: `X-Content-Type-Options: nosniff`, `Cache-Control: no-store`
+  - `--bind-all` security gate: requires `--auth-token` unless `--allow-unauthenticated` explicitly set
+  - Full protocol surface exposed: all 6 dispatch variants (basic, tools, reflexive, progressive, stream-augmented, agentic) over HTTP
+  - New endpoints: `/facts/feedback` (boost/penalize/reject), `/providers` (register fallback), `/estimate` (cost estimation)
+  - Input validation on all endpoints: variant validation, required fields, capped limits
+  - CLI options: `--max-sessions`, `--rate-limit`, `--allow-unauthenticated`
+  - README: dedicated "Inter-LLM Context Sharing" section with endpoint reference, security model, and usage examples
+
+- **Deep Audit Gap Fixes — F1-F6, D1-D9** (§gap-audit)
+  - F1: README provider claims corrected — removed false Google/vLLM/HuggingFace references
+  - F2: `crp serve` HTTP sidecar implemented (`crp/cli/sidecar.py`) — full REST API with inter-LLM context sharing via `/facts/share` endpoint
+  - F3: Provider fallback chain — `LLMProviderManager.generate_with_fallback()` tries primary then registered providers
+  - F4: README RBAC enforcement note corrected — now accurately reflects full enforcement
+  - F5: Test count updated 266 → 351
+  - F6: `EventEmitter` wired into orchestrator — 30+ event types emitted at all pipeline stages (dispatch.started/completed, envelope.built, window.opened/continued/completed, fact.created, extraction.completed, session.closed)
+  - D1: `CQSDetector` wired — context hunger detection after LLM generation
+  - D2: `CrossWindowValidator` wired — extraction-based consistency validation after continuation loop
+  - D3: `FeedbackLoop` wired — confidence adjustments after extraction, public API (boost/penalize/reject)
+  - D4: `ParallelFanOut` wired — instantiated with dispatch/extract callables
+  - D5: `ReviewCycleManager` wired — checkpoint_review in continuation loop
+  - D6: `ScaleModeSelector` wired — configured at dispatch start from session processing_mode
+  - D7: `EventEmitter` wired (same as F6)
+  - D8: `TelemetryWriter` wired — optional JSONL sink for window telemetry
+  - D9: `LLMProviderManager` wired with fallback chain (same as F3)
+  - Public API: `emitter` property, `on()` subscription, `feedback` property, `boost_fact()`/`penalize_fact()`/`reject_fact()`, `register_provider()`, `parallel` property
+  - HTTP sidecar endpoints: POST /sessions, GET /sessions/:id/status, POST /sessions/:id/dispatch, POST /sessions/:id/ingest, GET /sessions/:id/facts, POST /sessions/:id/facts/share, POST /sessions/:id/close, GET /health
+  - All 351 tests passing after changes
+
+- **Adaptive Resource Allocation & Efficiency-First Optimization** (§resource-alloc)
+  - `AdaptiveAllocator` — dynamic pipeline tuning based on real-time overhead + memory pressure
+  - **Efficiency-first philosophy**: ML extraction stages (GLiNER, UIE, discourse) are core intelligence — never disabled
+  - `PROTECTED_INTELLIGENCE` frozenset — ML features excluded from shedding cascade and stage scheduling
+  - Throughput-based throttling: normal → throttled → constrained (adjusts fact limits, batch sizes, packing) instead of disabling stages
+  - `PromptEfficiency` dataclass — LLM-side optimization hints: fact deduplication, system prompt caching, envelope compression, connection reuse, estimated cache hit percentage
+  - EWMA-smoothed overhead tracking with configurable cap (default 15%)
+  - `_adapt_throughput()` — adjusts throughput level based on overhead trends without sacrificing intelligence
+  - `OverheadBudgetManager` wired into orchestrator — shedding cascade now live, ML features protected
+  - `ExtractionProfile` / `EnvelopeProfile` — recommended configurations based on resource state (stages always enabled)
+  - Consecutive over-cap detection: 3+ consecutive windows triggers throughput reduction
+  - `detect_hardware()` — auto-detects CPU count, total/available RAM (Windows + POSIX)
+  - `WindowOverheadRecord` per-window metrics with features shed + stages skipped tracking
+  - `ResourceManager.mark_unloaded()` / `trigger_gc()` — model lifecycle + conditional GC
+  - `_record_dispatch_overhead()` on orchestrator — feeds overhead to allocator after every dispatch
+  - `_allocator_fields()` → 4 new WindowMetrics fields: `adaptive_ewma_overhead_pct`, `adaptive_features_shed`, `adaptive_stages_disabled`, `adaptive_consecutive_over`
+  - All 6 dispatch variants wired: dispatch, dispatch_with_tools, dispatch_reflexive, dispatch_progressive, dispatch_stream_augmented, dispatch_agentic
+  - Tests covering hardware detection, EWMA smoothing, throughput adaptation, ML protection, prompt efficiency, profile generation, model lifecycle, edge cases
+  - Test count: 266 → 351
+
+- **Resource Management & Meta-Learning Hardening** (§audit R2)
+  - `ResourceManager` — centralized model registry, memory pressure tracking, GC orchestration
+  - `ResourceSnapshot` dataclass — point-in-time view of memory budget, model utilization, pressure level
+  - Pressure levels: none/low/medium/high/critical based on estimated CRP memory vs. budget
+  - Model lifecycle tracking: register, load, use, unload, idle detection
+  - Platform-aware RSS reading (Windows ctypes + POSIX /proc/self/status)
+  - `CalibrationState` adaptive recalibration — drift detection replaces permanent baseline lock
+  - Rolling window analysis (last 10 windows) with 30% drift threshold triggers recalibration
+  - `calibration_epoch` counter tracks how many times baselines have been recalibrated
+  - WindowMetrics `ram_available_mb`, `ram_used_by_crp_mb`, `pressure_level` now live-computed
+  - WindowMetrics `marginal_gain` now computed as new-fact ratio per window
+  - WindowMetrics `sections_covered` now counts unique Markdown headers in output
+  - All 5 formerly-dead WindowMetrics fields are now populated across all 6 dispatch variants
+  - `_resource_fields()` and `_marginal_fields()` helpers on orchestrator
+  - GC runs automatically on `close()` for clean session teardown
+  - 38 tests covering ResourceManager, CalibrationState recalibration, marginal gain, sections
+
+- **§22 — LLM-in-the-Loop Agentic Architecture** (PARADIGM SHIFT)
+  - CRPFacilitator cognitive engine with 6 LLM-driven decision modules
+  - Task analysis (§22.1) — LLM semantically understands task complexity
+  - Strategy routing (§22.2) — LLM chooses optimal dispatch strategy
+  - Fact synthesis (§22.3) — LLM merges/compresses knowledge base facts
+  - Output evaluation (§22.4) — LLM assesses output quality
+  - Memory curation (§22.5) — LLM manages CRP's knowledge base
+  - Execution planning (§22.6) — LLM decomposes complex tasks into multi-step plans
+  - Multi-step plan execution — each plan step dispatches with its own strategy
+  - Enhanced revision loop — structured evaluation feedback, strategy adjustment
+  - Post-revision curation — iterative knowledge refinement
+  - Continuation awareness — inner dispatch continuation state feeds into evaluation
+  - 12 agentic telemetry fields in WindowMetrics
+  - 84 tests covering all cognitive modules and integration paths
+
+- **Multi-Perspective Audit & CKF Gate Fix**
+  - 5-perspective audit documented in CRP_MULTI_PERSPECTIVE_AUDIT.md
+  - CKF Phase 6 gate reworked: budget reservation (15% or 120 tokens min) ensures CKF retrieval fires even at high envelope saturation
+  - CKF_GATE_TOKENS lowered from 500 to 120 tokens
+  - CKF_RESERVE_RATIO constant (0.15) reserves budget before warm store packing
+  - Concurrency model documented in README.md
+  - README badge corrected (709 → 185 tests)
+  - 11 CKF gate tests added (test_ckf_gate.py)
+
+- **§21 — Novel Relay Strategies**
+  - Reflexive dispatch — generate-then-verify with fact-checking
+  - Progressive dispatch — compact index with on-demand expansion
+  - Stream-augmented dispatch — mid-generation context injection
+  - 61 tests covering all three strategies
+
+- **§20 — Tool-Mediated Dispatch**
+  - `dispatch_with_tools()` — LLM requests context via tool calls
+  - Multi-round tool negotiation with safety cap
+  - Fact extraction from tool dispatch outputs
+  - 34 tests covering tool relay pipeline
+
+- **Complete CRP v2.0 Specification** — 9 documents, ~19,200 lines
+  - 01_RESEARCH_FOUNDATIONS.md — Academic research backing (9 research areas, 40+ papers)
+  - 02_CORE_PROTOCOL.md — Core specification (29 sections, ~6,800 lines)
+  - 03_CONTEXT_ENVELOPE.md — Context envelope architecture
+  - 04_TOKEN_GENERATION_PROTOCOL.md — Unbounded output via continuation
+  - 05_SYSTEM_WIDE_INTEGRATION.md — Integration architecture (87+ call sites)
+  - 06_IMPLEMENTATION_PLAN.md — Implementation roadmap
+  - 07_SECURITY.md — Security architecture (OWASP-aligned, 14 sections)
+  - 08_MONETIZATION.md — Business model (PostgreSQL model — full capability free)
+  - 09_DEPLOYMENT.md — Deployment architecture (embedded library)
+
+- **JSON Schemas** (Draft 2020-12) for all API types:
+  - task-intent.json, quality-report.json, session-status.json
+  - cost-estimate.json, envelope-preview.json, session-handle.json
+  - stream-event.json, crp-error.json, persisted-state-header.json
+
+- **Contextual Knowledge Fabric (CKF)** — normative knowledge layer:
+  - Graph walk, pattern query, semantic fallback, community summary retrieval
+  - Event-sourced history, pub-sub architecture
+  - Cross-session persistence
+
+- **6-Stage Extraction Pipeline** (blackboard-reactive):
+  - Regex → Statistical (TextRank) → GLiNER NER → UIE Relations → RST Discourse → LLM-Assisted Relational
+
+- **Quality Tier System** — S/A/B/C/D with degradation model
+
+- **Multi-Signal Completion Detection** — fact flow + structural flow + vocabulary novelty + structural completion
+
+- **Meta-Learning Architecture** — ORC + ICML + RTL for small model reasoning amplification
+
+- **Security Architecture** — HMAC binding, RBAC, encryption at rest, fact integrity chains, OWASP mapping
+
+- **API Formalism** (§6.10) — RFC 2119 operation contracts, error taxonomy (13 codes), streaming API, async API, stability tiers
+
+- **Concurrency Model** (§23) — thread safety, lock ordering, session-level serialization
+
+- **Observability & Audit** (§24) — event model, telemetry, window DAG traceability
+
+- **Configuration Management** (§25) — 5-layer hierarchy
+
+- **Multi-Provider LLM Interface** (§26) — provider-agnostic adapter pattern
+
+- **Deployment Architecture** (§27 + 09_DEPLOYMENT) — embedded library, Lambda/K8s scenarios
+
+- **Publication & Adoption Strategy** (§28) — repo structure, visibility strategy, standards track
+
+### Design Decisions
+
+- CKF is **free and normative** — ships with every conformant SDK (PostgreSQL model)
+- CRP is an **embedded library**, not a server — zero deployment overhead
+- Protocol is **language-neutral** — JSON Schema for all types, pseudocode for algorithms
+- All 11 Knowledge Backend Interface operations are **REQUIRED**
+- GLiNER domain models are **FUTURE** work (Phase 3+)