Skip to main content

crp.state

Auto-generated reference for the crp.state subpackage.

state

crp.state

State management - facts, warm store, event log, snapshots, cold storage.

PersistedStateHeader dataclass

Schema-versioned header for cold storage files (§3.6).

to_dict()

Serialize the persisted-state header to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
PersistedStateHeader	PersistedStateHeader.

CompactionConfig dataclass

Tuneable compaction parameters.

CompactionResult dataclass

Result of a compaction pass.

CriticalState dataclass

Tier-0 critical state - ALWAYS included in every envelope (§3.1).

Tracks the task's fundamental parameters that must survive every window.

to_sections()

Convert to envelope section dict for the formatter.

update(**kwargs)

Partial update of critical state fields.

to_dict()

Serialize critical state to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
CriticalState	CriticalState.

StructuralState dataclass

Document structure tracking for continuation stitching (§04 §3.5.2).

Tracks where the LLM is in its output so continuation windows can resume from the correct position.

to_dict()

Serialize structural state to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
StructuralState	StructuralState.

FactEventLog

Append-only immutable event log for fact lifecycle (§3.2).

Supports: - append(): add new event with monotonic ID - state_at_window(): replay events to reconstruct state at a point - facts_between(): range query - supersession_chain(): full lifecycle trail for a fact - Temporal queries: events_since, events_for_fact

size property

Return the current size count.

append(event_type, fact_id, window_id, payload=None)

Record an immutable event. Returns the created event.

record_fact_created(fact, window_id)

Convenience: record a fact creation event.

record_supersession(old_fact_id, new_fact_id, window_id, confidence=1.0)

Record that old_fact_id was superseded by new_fact_id.

record_compaction(fact_id, window_id, summary_id='')

Record that fact_id was compacted into summary_id.

record_archived(fact_id, window_id)

Record that fact_id was archived.

record_restored(fact_id, window_id)

Record that fact_id was restored from archive.

record_edge_added(edge, window_id)

Record that a graph edge was added.

state_at_window(window_id)

Replay events up to window_id and return the set of active fact IDs.

An active fact is one that was created and not yet superseded/compacted/archived.

facts_between(start_window, end_window)

Return events between two windows (inclusive).

supersession_chain(fact_id)

Return the full supersession lifecycle trail for fact_id.

events_since(timestamp)

Return all events after timestamp.

events_for_fact(fact_id)

Return all events for a specific fact.

events_by_type(event_type)

Filter events by type.

events_in_window(window_id)

Return all events for a specific window.

all_events()

Return a copy of all events.

to_list()

Serialize all events for persistence.

load_from_list(events)

Restore from serialized event list.

truncate_before(event_id)

Remove events before event_id. Returns removed events for archival.

StateFact dataclass

Fact extended with state-management metadata (§3.1).

Wraps an extraction Fact and adds: - Lazy embedding (computed on first access, cached) - age_in_windows - updated each window by the warm store - seen_count - how many envelopes this fact appeared in - consumed_by_windows - which windows used this fact - graph_edges - IDs of connected FactEdges

id property

Return the id.

text property

Return the text.

category property

Return the category.

confidence property

Return the confidence.

source_window_id property

Return the source window identifier.

created_at property

Return the created at.

extraction_stage property

Return the extraction stage.

superseded_by property writable

Return the superseded by.

embedding property writable

Lazy-compute embedding on first access.

is_superseded property

Return whether this object is superseded.

has_embedding()

Return True if an embedding has been computed or assigned.

mark_seen(window_id)

Record that this fact was included in an envelope for window_id.

increment_age()

Advance age by one window.

supersede(by_fact_id, confidence=1.0)

Mark this fact as superseded.

to_dict()

Serialize to dict for persistence (including embeddings §4D.1).

from_fact(fact) classmethod

Wrap an extraction Fact into a StateFact.

from_dict(data) classmethod

Deserialize from dict.

FactGraphSerializer

Serialize/deserialize FactGraph to/from disk (§22).

Format: JSON with header + nodes + edges. Schema-versioned for forward/backward compatibility.

serialize(graph) staticmethod

Serialize a FactGraph to a dict.

deserialize(data) staticmethod

Deserialize a dict into a FactGraph. Returns (graph, warnings).

save_to_file(graph, path) classmethod

Serialize and write to file.

load_from_file(path) classmethod

Load from file. Returns (graph, warnings).

EventLogSnapshot dataclass

Captured state at a point in time (§3.3).

compute_checksum()

Compute integrity checksum over the snapshot payload.

verify_checksum()

Verify the stored checksum matches the payload.

to_dict()

Serialize the snapshot to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
EventLogSnapshot	EventLogSnapshot.

SnapshotManager

Manages periodic snapshots of warm store state (§3.3).

Usage

mgr = SnapshotManager(warm_store, event_log) mgr.maybe_snapshot(window_id) # called each window

On resume:

mgr.restore_from_file(path)

snapshot_count property

Return the current snapshot count.

last_snapshot property

Return the last snapshot.

snapshot(window_id)

Create a snapshot of the current warm store state.

maybe_snapshot(window_id)

Create snapshot if interval has elapsed.

truncate_before_snapshot()

Truncate event log before the last snapshot. Returns events removed.

restore_from_snapshot(snapshot)

Restore warm store from snapshot, returning validation warnings.

Performs consistency checks (§22.4): 1. Schema version compatibility 2. Checksum integrity 3. Fact count consistency 4. Edge integrity (both endpoints exist) 5. No orphaned edges 6. Critical state present 7. Window count non-negative 8. Fact IDs unique 9. No circular supersession 10. Timestamps reasonable

save_to_file(path)

Save latest snapshot to disk using atomic write (§4G.4).

restore_from_file(path)

Load snapshot from disk, verify, restore. Returns warnings.

Handles partial-write corruption by checking for .tmp files (§4G.4). After snapshot restore, replays event log entries since the snapshot to rebuild full state (§4D.3).

InMemoryBackend

Bases: StorageBackend

Simple in-memory key–value store with optional TTL.

Thread-safe via RLock.

get(key)

Execute get and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
Any	Any.

set(key, value, ttl=None)

Execute set and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required
value	Any	The value value.	required
ttl	int | None	The ttl value.	None

Returns:

Type	Description
None	None.

delete(key)

Execute delete and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
None	None.

keys()

Execute keys and return the result.

Returns:

Type	Description
list[str]	list[str].

size()

Return the current size count.

Returns:

Type	Description
int	int.

StorageBackend

Bases: ABC

Base class for pluggable storage. Implement to use your own store.

All methods are synchronous by default. Async variants may be added by subclasses for network-backed stores.

get(key) abstractmethod

Retrieve a value by key. Returns None if missing.

set(key, value, ttl=None) abstractmethod

Store a value. ttl is seconds until expiry (None = no expiry).

delete(key) abstractmethod

Remove a key.

keys() abstractmethod

Return all keys in the store.

size() abstractmethod

Return approximate number of entries.

overview()

Return visibility metadata for this backend.

StorageBackendError

Bases: Exception

Raised when a storage backend operation fails.

WarmStateStore

In-memory warm state (Tier 2) with thread-safe access.

Provides: - add_facts / get_facts / get_ranked_facts / mark_seen / supersede - Critical state & structural state management - Optional async SQLite WAL persistence (Phase 4E)

fact_count property

Number of facts currently stored.

graph property

Underlying fact graph.

critical_state property

Current critical state (goal, phase, blockers, constraints).

structural_state property

Current structural state.

window_count property

Number of windows that have advanced through this store.

add_facts(facts, edges=None)

Add extraction facts to the warm store, wrapping them as StateFacts.

Parameters:

Name	Type	Description	Default
facts	list[Fact]	Facts to add.	required
edges	list[FactEdge] | None	Optional graph edges linking the facts.	None

Returns:

Type	Description
list[StateFact]	List of newly added StateFact objects. Duplicate IDs or content
list[StateFact]	hashes are skipped.

get_facts(*, include_superseded=False)

Return all active facts (or all including superseded).

Parameters:

Name	Type	Description	Default
include_superseded	bool	Whether to include superseded facts.	False

Returns:

Type	Description
list[StateFact]	List of matching StateFact objects.

get_fact(fact_id)

Get a specific fact by ID.

Parameters:

Name	Type	Description	Default
fact_id	str	Fact identifier.	required

Returns:

Type	Description
StateFact | None	The StateFact or None if not found.

get_active_facts_as_extraction()

Return active facts as extraction Fact objects (for envelope builder).

CRP 2.2: every returned fact is stamped with a :class:~crp.core.context_source.ContextSource of kind :data:~crp.core.context_source.SourceKind.WARM_STORE when its source is unset - making provenance explicit for envelope consumers and the attestation pipeline.

Trust: TrustLevel.UNKNOWN. Warm-store content may have originated from any upstream tier, including untrusted external retrieval; CRP cannot safely upgrade trust here. Integrators who can prove warm-store contents were vetted should override fact.source upstream before the fact enters the store.

get_ranked_facts(*, top_k=None, limit=None)

Return active facts sorted by relevance heuristic (confidence × recency).

Parameters:

Name	Type	Description	Default
top_k	int | None	Maximum number of facts to return (alias for limit).	None
limit	int | None	Maximum number of facts to return.	None

Returns:

Type	Description
list[StateFact]	Active facts ranked by confidence * (1 / (1 + age_in_windows)).

mark_seen(fact_ids, window_id)

Record that facts were included in an envelope for window_id.

Parameters:

Name	Type	Description	Default
fact_ids	list[str]	List of fact IDs that appeared in the envelope.	required
window_id	str	Window that consumed the facts.	required

supersede(old_fact_id, new_fact_id, confidence=1.0)

Mark old_fact_id as superseded by new_fact_id.

Parameters:

Name	Type	Description	Default
old_fact_id	str	Fact being replaced.	required
new_fact_id	str	Fact that replaces it.	required
confidence	float	Confidence in the supersession relationship.	1.0

remove_fact(fact_id)

Remove a fact (for compaction/archival).

Parameters:

Name	Type	Description	Default
fact_id	str	Fact to remove.	required

Returns:

Type	Description
StateFact | None	The removed StateFact or None if not found.

boost_confidence(fact_id, delta)

Increase a fact's confidence by delta, capped at 1.0 (§22 curation).

Parameters:

Name	Type	Description	Default
fact_id	str	Fact to boost.	required
delta	float	Amount to add to the fact's confidence.	required

reduce_confidence(fact_id, delta)

Decrease a fact's confidence by delta, floored at 0.0 (§22 curation).

Parameters:

Name	Type	Description	Default
fact_id	str	Fact to reduce.	required
delta	float	Amount to subtract from the fact's confidence.	required

advance_window(window_id)

Called when a new window begins - age all facts, update window tracking.

Parameters:

Name	Type	Description	Default
window_id	str	Identifier for the new window.	required

get_critical_state()

Return the current critical state.

update_critical_state(**kwargs)

Update critical state fields (goal, phase, blockers, constraints).

Parameters:

Name	Type	Description	Default
**kwargs	Any	Key-value pairs to set on the critical state.	{}

update_phase(phase)

Update the current phase and window id.

Parameters:

Name	Type	Description	Default
phase	str	New phase string.	required

get_structural_state()

Return the current structural state.

update_structural_state(**kwargs)

Update structural state fields.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Key-value pairs to set on the structural state.	{}

get_seen_counts()

Return {fact_id: seen_count} for all facts.

Returns:

Type	Description
dict[str, int]	Mapping of fact ID to number of times it has been seen in envelopes.

get_fact_window_indices()

Return {fact_id: creation_window_index} for scoring recency.

Returns:

Type	Description
dict[str, int]	Mapping of fact ID to the window index at which it was created.

on_fact_added(callback)

Subscribe a callback invoked when a fact is added.

Parameters:

Name	Type	Description	Default
callback	Callable[[StateFact], None]	Function receiving the newly added StateFact.	required

on_fact_superseded(callback)

Subscribe a callback invoked when a fact is superseded.

Parameters:

Name	Type	Description	Default
callback	Callable[[StateFact, str], None]	Function receiving the superseded StateFact and the replacement fact ID.	required

needs_compaction()

Check if warm store exceeds compaction thresholds.

Returns:

Type	Description
bool	True if fact_count exceeds compact_threshold.

to_dict()

Serialize entire warm store state.

Returns:

Type	Description
dict[str, Any]	Dict containing facts, edges, critical/structural state, and window info.

load_from_dict(data)

Restore warm store from serialized dict.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dict produced by to_dict.	required

Raises:

Type	Description
ValueError	If the session file schema version is newer than supported.

WarmStoreConfig dataclass

Configuration for the warm state store.

Attributes:

Name	Type	Description
max_facts	int	Maximum number of facts to retain in memory.
persist_enabled	bool	Whether to write state to SQLite WAL on change.
persist_path	str	Filesystem path for persistence (when enabled).
compact_threshold	int	Fact count that triggers compaction consideration.
compact_latency_ms	float	Target maximum compaction latency in milliseconds.

CoverageEntry dataclass

A single addressed sub-query, embedded and weighted (SPEC-024 §2.1).

embedding - dense vector of the sub-query text. MUST use the same model as the CKF fact embeddings (hard requirement, see §2.5).

depth_weight - how thoroughly this sub-query was addressed (0.0–1.0). See the depth weight table in §3.2: 0.90 thorough (dedicated section, multiple paragraphs) 0.70 adequate (full paragraph) 0.40 partial (single sentence or brief mention) 0.15 marginal (passing reference only)

window_number - which window addressed it. text - the sub-query text (kept for debugging / introspection).

CoverageSet

Session-scoped list of covered sub-query embeddings with depth weights.

This is the core state the CDR formula reads every time it ranks a fact. Updated after each window via update().

Embedding model consistency: all embeddings (Coverage Set + CKF facts) MUST use the same model. Record the model id when creating the session coverage set and reject mismatched updates.

coverage_score(fact_embedding)

Weighted mean cosine similarity to all Coverage Set entries.

Parameters:

Name	Type	Description	Default
fact_embedding	list[float]	Dense embedding vector for the fact.	required

Returns:

Type	Description
float	0.0 if the Coverage Set is empty (Window 1 behaviour - every fact
float	is fully novel at Window 1). Otherwise the weighted mean cosine
float	similarity over all entries. Uses weighted mean, NOT maximum -
float	see SPEC-024 §2.3.

residual_pull(fact_embedding)

Maximum cosine similarity to any residual (unaddressed) sub-query.

Parameters:

Name	Type	Description	Default
fact_embedding	list[float]	Dense embedding vector for the fact.	required

Returns:

Type	Description
float	0.0 if the Residual Set is empty. Otherwise the maximum cosine
float	similarity, implementing the "pull toward what has not yet been
float	written" signal from SPEC-024 §2.2.

novelty(fact_embedding)

Compute novelty score for a fact (SPEC-024 §2.2–2.4).

Parameters:

Name	Type	Description	Default
fact_embedding	list[float]	Dense embedding vector for the fact.	required

Returns:

Type	Description
float	Novelty score in [0.0, 1.0]. Computes
float	max(1.0 - coverage_penalty, MIN_NOVELTY_FLOOR) where
float	coverage_penalty = min(coverage_score, COVERAGE_PENALTY_CAP).
float	Adds a 0.20 × residual_pull boost for facts aligned with
float	still-unaddressed topics. Returns 1.0 when Coverage Set is empty
float	(Window 1 - all fresh).

mean_novelty(sample_embeddings)

Average novelty across a sample of fact embeddings.

Parameters:

Name	Type	Description	Default
sample_embeddings	list[list[float]]	List of fact embedding vectors.	required

Returns:

Type	Description
float	Average novelty score. Used by CDR exhaustion detection: if
float	mean_novelty < 0.15, the CKF has run out of fresh material
float	for this session (SPEC-024 §5.2).

update(addressed_sub_queries, all_sub_queries=None, window_number=0, embedding_model_id='')

Add coverage entries for all addressed sub-queries in this window.

Parameters:

Name	Type	Description	Default
addressed_sub_queries	list[dict[str, Any]]	List of dicts with keys: text (str), embedding (list[float]), depth_weight (float, optional - defaults to 0.5), id (str, optional).	required
all_sub_queries	list[dict[str, Any]] | None	If provided, updates the Residual Set by removing addressed sub-queries (SPEC-024 §3.1).	None
window_number	int	Window that addressed the sub-queries.	0
embedding_model_id	str	Embedding model id. Must match self.embedding_model_id or a ValueError is raised (SPEC-024 §2.5).	''

Raises:

Type	Description
ValueError	If embedding_model_id conflicts with the Coverage Set's recorded model id.

set_residual(residual_items)

Directly replace the Residual Set (e.g. on session restore).

Parameters:

Name	Type	Description	Default
residual_items	list[ResidualItem]	New residual items.	required

Returns:

Type	Description
None	None.

entry_count()

Number of coverage entries.

residual_count()

Number of residual (unaddressed) sub-queries.

entries()

Return a copy of all coverage entries.

residuals()

Return a copy of all residual items.

reset()

Clear all state (e.g. on session reset).

Returns:

Type	Description
None	None.

ResidualItem dataclass

A sub-query that has NOT yet been addressed.

Built by subtracting Coverage Set topics from the original task decomposition (SPEC-024 §3.1).

CognitiveStateObject dataclass

The relay primitive that replaces the v3 text summary (SPEC-030 §2).

Produced at the end of every window; consumed at the start of the next. Verified by relay_cso() before forwarding - preservation guaranteed.

add_tool_observation(observation)

Store a tool observation and mirror it as a typed established fact.

Accepts a ToolObservation (duck-typed via to_dict) or a dict. The raw payload stays compact; the established fact carries provenance=TOOL so the observation enters the reasoning graph and survives state relay - this is what keeps a 300-tool report from losing its evidence (fixes the WASA M1 failure).

record_preventive_halt(frame)

Record a preventive-safety halt frame (CRP-SPEC-050 §10).

to_prompt_context(max_facts=10, max_decisions=5)

Render the CSO as structured context for the next window.

Parameters:

Name	Type	Description	Default
max_facts	int	Maximum established facts to include.	10
max_decisions	int	Maximum decisions to include.	5

Returns:

Type	Description
str	Compact, token-efficient representation - NOT a prose summary.
str	The goal_state.remaining field is the forward-looking anchor
str	(replacing ResidualTaskAnchor - SPEC-030 §2.3).

preservation_score(prior)

Fraction of still-valid prior facts present in this CSO.

Parameters:

Name	Type	Description	Default
prior	CognitiveStateObject	Previous window's CSO.	required

Returns:

Type	Description
float	1.0 when all prior valid facts survive relay. A score < 1.0 means
float	facts were silently dropped and the relay MUST repair.

repair_from(prior)

Re-inject any dropped facts/decisions from prior CSO.

Parameters:

Name	Type	Description	Default
prior	CognitiveStateObject	Previous window's CSO.	required

Returns:

Type	Description
CognitiveStateObject	self (mutated in place for efficiency).

Note

Called when preservation_score < 1.0 - ensures no silent state loss.

invalidate_fact(fact_id)

Invalidate a fact and propagate to dependent decisions/facts.

Parameters:

Name	Type	Description	Default
fact_id	str	ID of the fact to invalidate.	required

Returns:

Type	Description
set[str]	Set of all affected item IDs (the fact plus transitive dependents).

compute_hmac(key)

Compute tamper-evident HMAC over CSO content.

Parameters:

Name	Type	Description	Default
key	bytes	HMAC signing key.	required

Returns:

Type	Description
str	Hex-encoded HMAC-SHA256 digest over a canonical CSO payload.

extend_hmac_chain(prior_hash, key)

Extend the HMAC chain: prior_hash → this window's hash.

Parameters:

Name	Type	Description	Default
prior_hash	str	HMAC of the previous CSO (empty string for window 1).	required
key	bytes	HMAC signing key.	required

Returns:

Type	Description
str	The new HMAC to be stored as the next window's prior_hash.

Side effects

Sets self.prior_cso_hash and self.cso_hmac.

to_dict()

Serialise to a JSON-safe dict for session storage.

Returns:

Type	Description
dict[str, Any]	Dict representation of the full CSO, including facts, decisions,
dict[str, Any]	goal state, dependency graph, and integrity fields.

from_dict(data) classmethod

Restore a CSO from a serialised dict.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dict produced by to_dict.	required

Returns:

Type	Description
CognitiveStateObject	Reconstructed CognitiveStateObject.

Decision dataclass

A decision made in a window, with its full rationale (SPEC-030 §2.2).

The rationale field is the single most important addition over text relay - it records WHY, not just what, so later windows can evaluate whether the reason still holds.

DependencyEdge dataclass

Directed dependency edge in the reasoning graph (SPEC-030 §3).

EstablishedFact dataclass

A single fact established and verified during a window (SPEC-030 §2.1).

provenance_ref points to the specific CKF fact_id, scratch entry id, or turn id that is the source - enabling full traceability (SPEC-029 §8.2).

GoalMode

Bases: str, Enum

Window execution mode (SPEC-030 §4.2).

GoalState dataclass

Universal window contract (SPEC-030 §4).

Replaces mode-specific anchors (ResidualTaskAnchor for documents, Active Thread Summary for conversations) with one structure.

ProvenanceKind

Bases: str, Enum

Source of an established fact (SPEC-030 §2.1).

ContextTier

Bases: str, Enum

The three context tiers of the Multi-Horizon Model (SPEC-028 §2.1).

MultiHorizonContext dataclass

Unified envelope assembler for the three context tiers (SPEC-028 §2.2).

Attributes:

Name	Type	Description
turn_log	list[TurnEntry]	Ordered list of turn entries (Tier C).
max_turn_log	int	Maximum turns to retain in conversational memory.

classify_intent(turn)

Detect topic shift, reference resolution, clarification need (SPEC-028 §5).

Returns dict with

intent: str - "explore" | "drill_down" | "clarify" | "reference" confidence: float

resolve_reference(reference, turn_history)

Resolve "it", "that approach", "what you said about X" etc. (SPEC-028 §4).

Returns the best-matching prior turn content, or empty string if none.

blend_for_operation(operation, weights=None)

Per-turn tier blend: different operations need different balances (SPEC-028 §2.2).

Parameters:

Name	Type	Description	Default
operation	str	One of the STL operations (RETRIEVE, SYNTHESISE, etc.)	required
weights	dict[str, float] | None	Optional override weights.	None

Returns:

Type	Description
dict[str, float]	Dict with keys persistent, conversational, ephemeral summing to 1.0.

add_turn(role, content, topic_tags=None)

Append a turn to the conversational log.

get_recent_turns(n=5)

Return the last n turns.

get_turns_by_topic(topic)

Return turns tagged with a given topic.

TurnEntry dataclass

One entry in the Conversational Turn Log (Tier C).

ScratchBuffer dataclass

Tier E store - high-volume working data with pointer-based access (SPEC-029).

Data stays in memory/disk; only pointers and summaries live in the session.

store(data, entry_id, tool_name='', freshness_ttl=30, structure='auto')

Store data and return a pointer. Data written to ephemeral store.

Parameters:

Name	Type	Description	Default
data	Any	The raw output to store.	required
entry_id	str	Addressable ID, e.g. "scratch_sql_001".	required
tool_name	str	Which tool produced this.	''
freshness_ttl	int	Seconds until entry becomes stale.	30
structure	str	"auto" | "tabular" | "json" | "code" | "text".	'auto'

get_fresh(entry_id)

Returns None if entry has expired.

summarise(entry_id, max_tokens=200)

Structure-aware summarisation for inclusion in Operation Frames.

get_provenance(entry_id)

SPEC-029 §6: TOOL_GROUNDED provenance for decisions based on tool output.

pin(entry_id)

Promote an entry from ephemeral to pinned persistence.

purge_expired()

Remove expired ephemeral entries. Returns count removed.

ScratchEntry dataclass

One item in the Scratch Buffer.

is_fresh property

Return whether this object is fresh.

ScratchPersistence

Bases: str, Enum

How long a scratch entry lives.

StorageRouter

Unified storage router - selects the right primitive per access pattern.

The CKF graph (Primitive 1) is NOT owned by this router - it lives in ContextualKnowledgeFabric and is passed in via set_ckf(). The router provides access to Primitives 2–5.

Usage::

router = StorageRouter()
# Recency
entries = router.get_recent_turns(n=5)
# Exact
facts = router.exact_lookup("pod_ip_fact")
# Cache
cached = router.get_cached(query_emb, ckf_hash)
# Ephemeral
ptr = router.store_ephemeral(tool_output, provenance="TOOL_GROUNDED")
data = router.get_ephemeral(ptr)

set_ckf(ckf)

Register the CKF instance for semantic / graph access.

append_turn(content, window_number=0, entry_id='', metadata=None)

Append a turn to the rolling context log.

get_recent_turns(n=10)

Return the n most recent turns from the rolling log.

get_recent_content(n=10)

Return content strings for the n most recent turns.

get_cached(query_embedding, ckf_state_hash)

Return cached retrieval result, or None if not cached / stale.

put_cached(query_embedding, ckf_state_hash, value)

Store a retrieval result in the hot cache.

invalidate_cache(ckf_state_hash='')

Invalidate the cache (called on CKF state change).

index_fact(fact_id, fact, text='', keys=None)

Index a fact for exact-match lookup.

exact_lookup(key)

Exact key lookup - returns facts matching the key.

term_lookup(term)

Single-term lookup.

remove_from_index(fact_id)

Remove a fact from the exact index (e.g. on GC/tombstone).

store_ephemeral(data, entry_id='', ttl_seconds=300.0, structure='auto', provenance='UNKNOWN', metadata=None)

Store large working data; returns pointer (entry_id).

get_ephemeral(entry_id)

Retrieve ephemeral data by pointer; None if expired.

summarise_ephemeral(entry_id, max_tokens=200)

Structure-aware summary for Operation Frame inclusion.

get_ephemeral_provenance(entry_id)

Provenance record for decisions based on ephemeral data.

overview()

Return a summary of all active storage primitives.

AccessPattern

Bases: str, Enum

The six access patterns CRP supports (SPEC-035 §1.1).

RollingContextLog

Fixed-capacity append-only ring buffer for sequential recency access.

When capacity is exceeded, oldest entries are discarded from the tail. Reading recent entries is a deque-slice - no search or embedding needed.

append(entry)

Append an entry; oldest auto-discarded when capacity exceeded.

append_turn(content, window_number=0, entry_id='', metadata=None)

Convenience: append a conversation turn.

get_recent(n=10)

Return the n most recent entries (newest last).

get_recent_content(n=10)

Return content strings for the n most recent entries.

get_window(window_number)

Return all entries from a specific window.

entry_count()

Return the number of entries currently in the log.

capacity()

Return the maximum number of entries the log can hold.

clear()

Remove all entries from the log.

HotCache

LRU cache for repeat retrieval acceleration.

Keys are (query_embedding_hash, ckf_state_hash) tuples. Entries are invalidated when ckf_state_hash changes or TTL expires.

set_ckf_state(state_hash)

Update the current CKF state hash. Clears cache on change.

make_key(query_embedding, ckf_state_hash) staticmethod

Build a cache key from query embedding + CKF state hash.

get(key)

Return cached value or None if not found / expired.

put(key, value)

Store a value; evict LRU entry if over capacity.

invalidate(key)

Remove a single entry from the cache.

clear()

Remove all entries from the cache.

size()

Return the number of cached entries.

capacity()

Return the maximum number of entries the cache can hold.

InvertedIndex

Exact-match inverted index for fast keyed and term-based lookup.

Maintains two indexes: - _term_index: term → {fact_id} for token-based search - _key_index: key → {fact_id} for exact named lookup - _facts: fact_id → IndexedFact for O(1) retrieval

add(fact_id, fact, text='', keys=None)

Index a fact by its text terms and optional explicit keys.

remove(fact_id)

Remove a fact from all indexes.

lookup_key(key)

Exact key lookup - returns facts matching the key exactly.

lookup_term(term)

Single-term lookup - returns all facts containing the term.

lookup_terms(terms, mode='any')

Multi-term lookup.

mode="any" - facts matching ANY of the terms (union) mode="all" - facts matching ALL of the terms (intersection)

get_fact(fact_id)

Direct fact_id → fact lookup.

fact_count()

Return the number of facts in the index.

term_count()

Return the number of unique terms in the index.

clear()

Remove all facts and terms from the index.

EphemeralStore

Pointer-based ephemeral store for high-volume working data.

Store data with store() → get back a pointer (entry_id). Retrieve with get() - returns None if expired. Summarise with summarise() for inclusion in Operation Frames.

store(data, entry_id='', ttl_seconds=300.0, structure='auto', provenance='UNKNOWN', metadata=None)

Store data and return its pointer (entry_id).

If entry_id is empty, a UUID is generated. structure="auto" detects structure heuristically.

get(entry_id)

Return data for entry_id if fresh, None if expired or missing.

get_entry(entry_id)

Return the full EphemeralEntry (with metadata).

get_provenance(entry_id)

Return provenance record for decisions based on this data.

summarise(entry_id, max_tokens=200)

Structure-aware summary for inclusion in Operation Frames.

entry_count()

Return the number of entries currently stored.

clear()

Remove all entries from the store.

persist_to_cold(warm_store, event_log, path, session_id='', community_map=None, hmac_key=None)

Persist warm store + event log to cold storage.

File format: JSON with header + payload. Includes community IDs (§4E.1) and HMAC chain (§4G.3) when provided. Uses atomic writes to prevent partial-write corruption (§4G.4).

restore_from_cold(warm_store, event_log, path, hmac_key=None)

Load cold storage into warm store + event log.

Returns (header, warnings, community_map) where: - warnings list integrity issues - community_map has restored community assignments (§4E.1)

Performs HMAC chain verification when key provided (§4G.3). Handles partial-write corruption (§4G.4). Applies schema migrations (§4G.2).

compact(store, event_log, window_id, config=None)

Run a compaction pass on the warm store.

1. Archive superseded facts → cold (emit ARCHIVED events)
2. Cluster remaining active facts by similarity
3. Summarize multi-fact clusters → single representative fact
4. Update graph with summary facts

set_embedding_function(fn)

Register the global embedding function for lazy compute.

extract_cso(window_output, window_number, prior_cso=None, dpe_report=None, goal_sections=None)

Extract a CSO from window output (lightweight, no external NLP).

For production use, the DPE's 13-stage analysis pipeline provides richer extraction. This function is the baseline extraction for CRP core (zero heavy dependencies).

Parameters:

Name	Type	Description	Default
window_output	str	Raw LLM output for the current window.	required
window_number	int	Current window number.	required
prior_cso	CognitiveStateObject | None	Optional previous window CSO to carry forward.	None
dpe_report	dict[str, Any] | None	Optional DPE report for richer extraction (currently advisory).	None
goal_sections	list[str] | None	Optional list of remaining goal sections.	None

Returns:

Type	Description
CognitiveStateObject	New CognitiveStateObject populated with extracted facts and goal state.

Strategy

• Parse sentences as candidate facts.
• Carry forward prior CSO's goal_state, advancing completion.
• Inherit open_questions and constraints unless resolved in output.
• Mark window_number on all new facts/decisions.

preservation_report(prior, current)

Generate data for CRP-Relay-Preservation header (SPEC-030 §5.3).

Parameters:

Name	Type	Description	Default
prior	CognitiveStateObject	Previous window's CSO.	required
current	CognitiveStateObject	Current window's CSO.	required

Returns:

Type	Description
dict[str, Any]	Dict with preservation score, repaired count, and fact counts.

relay_cso(prior_cso, window_output, window_number, dpe_report=None, hmac_key=None, goal_sections=None)

Relay the CSO from window N to window N+1 (SPEC-030 §5).

Parameters:

Name	Type	Description	Default
prior_cso	CognitiveStateObject | None	Previous window's CSO, if any.	required
window_output	str	Raw LLM output for the current window.	required
window_number	int	Current window number.	required
dpe_report	dict[str, Any] | None	Optional DPE report for richer extraction.	None
hmac_key	bytes | None	Optional HMAC key for chain integrity.	None
goal_sections	list[str] | None	Optional list of remaining goal sections.	None

Returns:

Type	Description
CognitiveStateObject	Verified, complete CSO for the next window.

Steps

1. Extract new CSO from window_output.
2. Check preservation score against prior CSO.
3. If score < 1.0 → repair (re-inject dropped facts/decisions).
4. Extend HMAC chain.
5. Mark verified=True.
6. Return verified CSO for next window.

Note

This replaces the v3 text summary continuation approach: continuation_context = relay_cso(...).to_prompt_context().

state.backends

crp.state.backends

Pluggable storage backends for CRP state (SPEC-038).

Backends

InMemoryBackend - default for development SQLiteBackend - local persistent storage RedisBackend - production cache layer S3Backend - cold storage for documents

Visibility API

client.storage.overview() → {primitive: str, backend: str, size: int}[] client.knowledge.location → "in-memory" | "sqlite" | "redis" | "s3"

StorageBackend

Bases: ABC

Base class for pluggable storage. Implement to use your own store.

All methods are synchronous by default. Async variants may be added by subclasses for network-backed stores.

get(key) abstractmethod

Retrieve a value by key. Returns None if missing.

set(key, value, ttl=None) abstractmethod

Store a value. ttl is seconds until expiry (None = no expiry).

delete(key) abstractmethod

Remove a key.

keys() abstractmethod

Return all keys in the store.

size() abstractmethod

Return approximate number of entries.

overview()

Return visibility metadata for this backend.

StorageBackendError

Bases: Exception

Raised when a storage backend operation fails.

InMemoryBackend

Bases: StorageBackend

Simple in-memory key–value store with optional TTL.

Thread-safe via RLock.

get(key)

Execute get and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
Any	Any.

set(key, value, ttl=None)

Execute set and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required
value	Any	The value value.	required
ttl	int | None	The ttl value.	None

Returns:

Type	Description
None	None.

delete(key)

Execute delete and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
None	None.

keys()

Execute keys and return the result.

Returns:

Type	Description
list[str]	list[str].

size()

Return the current size count.

Returns:

Type	Description
int	int.

state.backends.base

crp.state.backends.base

StorageBackend ABC - base class for pluggable storage (SPEC-038 §2).

StorageBackendError

Bases: Exception

Raised when a storage backend operation fails.

StorageBackend

Bases: ABC

Base class for pluggable storage. Implement to use your own store.

All methods are synchronous by default. Async variants may be added by subclasses for network-backed stores.

get(key) abstractmethod

Retrieve a value by key. Returns None if missing.

set(key, value, ttl=None) abstractmethod

Store a value. ttl is seconds until expiry (None = no expiry).

delete(key) abstractmethod

Remove a key.

keys() abstractmethod

Return all keys in the store.

size() abstractmethod

Return approximate number of entries.

overview()

Return visibility metadata for this backend.

state.backends.memory

crp.state.backends.memory

InMemoryBackend - default development storage (SPEC-038 §3).

InMemoryBackend

Bases: StorageBackend

Simple in-memory key–value store with optional TTL.

Thread-safe via RLock.

get(key)

Execute get and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
Any	Any.

set(key, value, ttl=None)

Execute set and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required
value	Any	The value value.	required
ttl	int | None	The ttl value.	None

Returns:

Type	Description
None	None.

delete(key)

Execute delete and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
None	None.

keys()

Execute keys and return the result.

Returns:

Type	Description
list[str]	list[str].

size()

Return the current size count.

Returns:

Type	Description
int	int.

state.backends.redis

crp.state.backends.redis

RedisBackend - production cache layer (SPEC-038 §3).

Optional dependency: redis package. Falls back to import-time error with helpful message if unavailable.

RedisBackend

Bases: StorageBackend

Redis-backed storage with native TTL support.

get(key)

Execute get and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
Any	Any.

set(key, value, ttl=None)

Execute set and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required
value	Any	The value value.	required
ttl	int | None	The ttl value.	None

Returns:

Type	Description
None	None.

delete(key)

Execute delete and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
None	None.

keys()

Execute keys and return the result.

Returns:

Type	Description
list[str]	list[str].

size()

Return the current size count.

Returns:

Type	Description
int	int.

state.backends.s3

crp.state.backends.s3

S3Backend - cold storage for large documents (SPEC-038 §3).

Optional dependency: boto3 package. Falls back to import-time error with helpful message if unavailable.

S3Backend

Bases: StorageBackend

S3-backed storage for large / archival objects.

TTL is simulated via object metadata (S3 does not natively support per-object TTL). Expired objects are skipped on get/keys.

get(key)

Execute get and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
Any	Any.

set(key, value, ttl=None)

Execute set and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required
value	Any	The value value.	required
ttl	int | None	The ttl value.	None

Returns:

Type	Description
None	None.

delete(key)

Execute delete and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
None	None.

keys()

Execute keys and return the result.

Returns:

Type	Description
list[str]	list[str].

size()

Return the current size count.

Returns:

Type	Description
int	int.

state.backends.sqlite

crp.state.backends.sqlite

SQLiteBackend - local persistent storage (SPEC-038 §3).

SQLiteBackend

Bases: StorageBackend

SQLite-backed persistent key–value store with TTL support.

get(key)

Execute get and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
Any	Any.

set(key, value, ttl=None)

Execute set and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required
value	Any	The value value.	required
ttl	int | None	The ttl value.	None

Returns:

Type	Description
None	None.

delete(key)

Execute delete and return the result.

Parameters:

Name	Type	Description	Default
key	str	The key value.	required

Returns:

Type	Description
None	None.

keys()

Execute keys and return the result.

Returns:

Type	Description
list[str]	list[str].

size()

Return the current size count.

Returns:

Type	Description
int	int.

state.cold_storage

crp.state.cold_storage

Cold storage - Tier 3 cross-session persistence (§3.6).

Persists facts, graph structure, community IDs, and metadata to disk. PersistedStateHeader provides schema versioning + integrity checksums.

PersistedStateHeader dataclass

Schema-versioned header for cold storage files (§3.6).

to_dict()

Serialize the persisted-state header to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
PersistedStateHeader	PersistedStateHeader.

persist_to_cold(warm_store, event_log, path, session_id='', community_map=None, hmac_key=None)

Persist warm store + event log to cold storage.

File format: JSON with header + payload. Includes community IDs (§4E.1) and HMAC chain (§4G.3) when provided. Uses atomic writes to prevent partial-write corruption (§4G.4).

restore_from_cold(warm_store, event_log, path, hmac_key=None)

Load cold storage into warm store + event log.

Returns (header, warnings, community_map) where: - warnings list integrity issues - community_map has restored community assignments (§4E.1)

Performs HMAC chain verification when key provided (§4G.3). Handles partial-write corruption (§4G.4). Applies schema migrations (§4G.2).

state.compaction

crp.state.compaction

Compaction engine - deduplicate and summarize warm state (§3.6).

Trigger: fact_count > 5000 OR envelope_latency > 500ms. Algorithm: 1. Archive superseded facts 2. Cluster remaining by cosine similarity (>0.80 threshold) 3. TextRank summarize clusters 4. Rebuild ANN index 5. Compact graph

CompactionConfig dataclass

Tuneable compaction parameters.

CompactionResult dataclass

Result of a compaction pass.

should_compact(store, last_envelope_latency_ms=0.0, config=None)

Check if compaction should run.

compact(store, event_log, window_id, config=None)

Run a compaction pass on the warm store.

1. Archive superseded facts → cold (emit ARCHIVED events)
2. Cluster remaining active facts by similarity
3. Summarize multi-fact clusters → single representative fact
4. Update graph with summary facts

state.coverage_set

crp.state.coverage_set

Coverage Set - session-scoped novelty tracker for CDR (SPEC-024 §2.1–3.2).

The Coverage Set is the CDR mechanism's memory of what has been addressed. After each window the Coverage Set is updated with embeddings of the sub-queries that window's output covered, weighted by how thoroughly they were covered.

CDR uses the Coverage Set to score each fact by how novel it is relative to what has already been written - ensuring Window 5 receives different, fresh material rather than the same facts that Window 1 received.

Embedding model consistency is enforced: every entry MUST use the same model as the CKF facts. The model id is recorded on construction and mismatches are rejected (SPEC-024 §2.5).

CoverageEntry dataclass

A single addressed sub-query, embedded and weighted (SPEC-024 §2.1).

embedding - dense vector of the sub-query text. MUST use the same model as the CKF fact embeddings (hard requirement, see §2.5).

depth_weight - how thoroughly this sub-query was addressed (0.0–1.0). See the depth weight table in §3.2: 0.90 thorough (dedicated section, multiple paragraphs) 0.70 adequate (full paragraph) 0.40 partial (single sentence or brief mention) 0.15 marginal (passing reference only)

window_number - which window addressed it. text - the sub-query text (kept for debugging / introspection).

ResidualItem dataclass

A sub-query that has NOT yet been addressed.

Built by subtracting Coverage Set topics from the original task decomposition (SPEC-024 §3.1).

CoverageSet

Session-scoped list of covered sub-query embeddings with depth weights.

This is the core state the CDR formula reads every time it ranks a fact. Updated after each window via update().

Embedding model consistency: all embeddings (Coverage Set + CKF facts) MUST use the same model. Record the model id when creating the session coverage set and reject mismatched updates.

coverage_score(fact_embedding)

Weighted mean cosine similarity to all Coverage Set entries.

Parameters:

Name	Type	Description	Default
fact_embedding	list[float]	Dense embedding vector for the fact.	required

Returns:

Type	Description
float	0.0 if the Coverage Set is empty (Window 1 behaviour - every fact
float	is fully novel at Window 1). Otherwise the weighted mean cosine
float	similarity over all entries. Uses weighted mean, NOT maximum -
float	see SPEC-024 §2.3.

residual_pull(fact_embedding)

Maximum cosine similarity to any residual (unaddressed) sub-query.

Parameters:

Name	Type	Description	Default
fact_embedding	list[float]	Dense embedding vector for the fact.	required

Returns:

Type	Description
float	0.0 if the Residual Set is empty. Otherwise the maximum cosine
float	similarity, implementing the "pull toward what has not yet been
float	written" signal from SPEC-024 §2.2.

novelty(fact_embedding)

Compute novelty score for a fact (SPEC-024 §2.2–2.4).

Parameters:

Name	Type	Description	Default
fact_embedding	list[float]	Dense embedding vector for the fact.	required

Returns:

Type	Description
float	Novelty score in [0.0, 1.0]. Computes
float	max(1.0 - coverage_penalty, MIN_NOVELTY_FLOOR) where
float	coverage_penalty = min(coverage_score, COVERAGE_PENALTY_CAP).
float	Adds a 0.20 × residual_pull boost for facts aligned with
float	still-unaddressed topics. Returns 1.0 when Coverage Set is empty
float	(Window 1 - all fresh).

mean_novelty(sample_embeddings)

Average novelty across a sample of fact embeddings.

Parameters:

Name	Type	Description	Default
sample_embeddings	list[list[float]]	List of fact embedding vectors.	required

Returns:

Type	Description
float	Average novelty score. Used by CDR exhaustion detection: if
float	mean_novelty < 0.15, the CKF has run out of fresh material
float	for this session (SPEC-024 §5.2).

update(addressed_sub_queries, all_sub_queries=None, window_number=0, embedding_model_id='')

Add coverage entries for all addressed sub-queries in this window.

Parameters:

Name	Type	Description	Default
addressed_sub_queries	list[dict[str, Any]]	List of dicts with keys: text (str), embedding (list[float]), depth_weight (float, optional - defaults to 0.5), id (str, optional).	required
all_sub_queries	list[dict[str, Any]] | None	If provided, updates the Residual Set by removing addressed sub-queries (SPEC-024 §3.1).	None
window_number	int	Window that addressed the sub-queries.	0
embedding_model_id	str	Embedding model id. Must match self.embedding_model_id or a ValueError is raised (SPEC-024 §2.5).	''

Raises:

Type	Description
ValueError	If embedding_model_id conflicts with the Coverage Set's recorded model id.

set_residual(residual_items)

Directly replace the Residual Set (e.g. on session restore).

Parameters:

Name	Type	Description	Default
residual_items	list[ResidualItem]	New residual items.	required

Returns:

Type	Description
None	None.

entry_count()

Number of coverage entries.

residual_count()

Number of residual (unaddressed) sub-queries.

entries()

Return a copy of all coverage entries.

residuals()

Return a copy of all residual items.

reset()

Clear all state (e.g. on session reset).

Returns:

Type	Description
None	None.

state.critical_state

crp.state.critical_state

Critical & structural state - always-included envelope sections (§3.1).

CriticalState: goal, phase, blockers, constraints (Tier 0 - never evicted). StructuralState: continuation tracking for document position (§04 §3.5.2).

CriticalState dataclass

Tier-0 critical state - ALWAYS included in every envelope (§3.1).

Tracks the task's fundamental parameters that must survive every window.

to_sections()

Convert to envelope section dict for the formatter.

update(**kwargs)

Partial update of critical state fields.

to_dict()

Serialize critical state to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
CriticalState	CriticalState.

StructuralState dataclass

Document structure tracking for continuation stitching (§04 §3.5.2).

Tracks where the LLM is in its output so continuation windows can resume from the correct position.

to_dict()

Serialize structural state to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
StructuralState	StructuralState.

state.cso

crp.state.cso

Cognitive State Object (CSO) - SPEC-030.

The CSO is the structured, verifiable, revisable state that is relayed between continuation windows in place of the v3 text summary.

Unlike a text summary (lossy, reasoning-blind, irreversible, contractless), the CSO carries: - established_facts with provenance - WHAT was learned and WHERE from - decisions with rationale - WHAT was decided and WHY - open_questions - what the next window must still address - goal_state - the universal window contract (§4) - dependency_graph - which decisions/facts depend on which (§3) - HMAC chain - tamper-evident link to predecessor (SPEC-011)

Preservation guarantee (§5.2): every still-valid prior fact MUST survive relay or be repaired before forwarding. relay_cso() enforces this.

SPEC-030 §2.3 defines which prior mechanisms the CSO supersedes: - SPEC-004 text continuation summary → established_facts + decisions - SPEC-024 ResidualTaskAnchor → goal_state.remaining - SPEC-029 tool-result→decision link → decisions[].provenance_ref

ProvenanceKind

Bases: str, Enum

Source of an established fact (SPEC-030 §2.1).

GoalMode

Bases: str, Enum

Window execution mode (SPEC-030 §4.2).

EstablishedFact dataclass

A single fact established and verified during a window (SPEC-030 §2.1).

provenance_ref points to the specific CKF fact_id, scratch entry id, or turn id that is the source - enabling full traceability (SPEC-029 §8.2).

Decision dataclass

A decision made in a window, with its full rationale (SPEC-030 §2.2).

The rationale field is the single most important addition over text relay - it records WHY, not just what, so later windows can evaluate whether the reason still holds.

DependencyEdge dataclass

Directed dependency edge in the reasoning graph (SPEC-030 §3).

GoalState dataclass

Universal window contract (SPEC-030 §4).

Replaces mode-specific anchors (ResidualTaskAnchor for documents, Active Thread Summary for conversations) with one structure.

CognitiveStateObject dataclass

The relay primitive that replaces the v3 text summary (SPEC-030 §2).

Produced at the end of every window; consumed at the start of the next. Verified by relay_cso() before forwarding - preservation guaranteed.

add_tool_observation(observation)

Store a tool observation and mirror it as a typed established fact.

Accepts a ToolObservation (duck-typed via to_dict) or a dict. The raw payload stays compact; the established fact carries provenance=TOOL so the observation enters the reasoning graph and survives state relay - this is what keeps a 300-tool report from losing its evidence (fixes the WASA M1 failure).

record_preventive_halt(frame)

Record a preventive-safety halt frame (CRP-SPEC-050 §10).

to_prompt_context(max_facts=10, max_decisions=5)

Render the CSO as structured context for the next window.

Parameters:

Name	Type	Description	Default
max_facts	int	Maximum established facts to include.	10
max_decisions	int	Maximum decisions to include.	5

Returns:

Type	Description
str	Compact, token-efficient representation - NOT a prose summary.
str	The goal_state.remaining field is the forward-looking anchor
str	(replacing ResidualTaskAnchor - SPEC-030 §2.3).

preservation_score(prior)

Fraction of still-valid prior facts present in this CSO.

Parameters:

Name	Type	Description	Default
prior	CognitiveStateObject	Previous window's CSO.	required

Returns:

Type	Description
float	1.0 when all prior valid facts survive relay. A score < 1.0 means
float	facts were silently dropped and the relay MUST repair.

repair_from(prior)

Re-inject any dropped facts/decisions from prior CSO.

Parameters:

Name	Type	Description	Default
prior	CognitiveStateObject	Previous window's CSO.	required

Returns:

Type	Description
CognitiveStateObject	self (mutated in place for efficiency).

Note

Called when preservation_score < 1.0 - ensures no silent state loss.

invalidate_fact(fact_id)

Invalidate a fact and propagate to dependent decisions/facts.

Parameters:

Name	Type	Description	Default
fact_id	str	ID of the fact to invalidate.	required

Returns:

Type	Description
set[str]	Set of all affected item IDs (the fact plus transitive dependents).

compute_hmac(key)

Compute tamper-evident HMAC over CSO content.

Parameters:

Name	Type	Description	Default
key	bytes	HMAC signing key.	required

Returns:

Type	Description
str	Hex-encoded HMAC-SHA256 digest over a canonical CSO payload.

extend_hmac_chain(prior_hash, key)

Extend the HMAC chain: prior_hash → this window's hash.

Parameters:

Name	Type	Description	Default
prior_hash	str	HMAC of the previous CSO (empty string for window 1).	required
key	bytes	HMAC signing key.	required

Returns:

Type	Description
str	The new HMAC to be stored as the next window's prior_hash.

Side effects

Sets self.prior_cso_hash and self.cso_hmac.

to_dict()

Serialise to a JSON-safe dict for session storage.

Returns:

Type	Description
dict[str, Any]	Dict representation of the full CSO, including facts, decisions,
dict[str, Any]	goal state, dependency graph, and integrity fields.

from_dict(data) classmethod

Restore a CSO from a serialised dict.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dict produced by to_dict.	required

Returns:

Type	Description
CognitiveStateObject	Reconstructed CognitiveStateObject.

extract_cso(window_output, window_number, prior_cso=None, dpe_report=None, goal_sections=None)

Extract a CSO from window output (lightweight, no external NLP).

For production use, the DPE's 13-stage analysis pipeline provides richer extraction. This function is the baseline extraction for CRP core (zero heavy dependencies).

Parameters:

Name	Type	Description	Default
window_output	str	Raw LLM output for the current window.	required
window_number	int	Current window number.	required
prior_cso	CognitiveStateObject | None	Optional previous window CSO to carry forward.	None
dpe_report	dict[str, Any] | None	Optional DPE report for richer extraction (currently advisory).	None
goal_sections	list[str] | None	Optional list of remaining goal sections.	None

Returns:

Type	Description
CognitiveStateObject	New CognitiveStateObject populated with extracted facts and goal state.

Strategy

• Parse sentences as candidate facts.
• Carry forward prior CSO's goal_state, advancing completion.
• Inherit open_questions and constraints unless resolved in output.
• Mark window_number on all new facts/decisions.

relay_cso(prior_cso, window_output, window_number, dpe_report=None, hmac_key=None, goal_sections=None)

Relay the CSO from window N to window N+1 (SPEC-030 §5).

Parameters:

Name	Type	Description	Default
prior_cso	CognitiveStateObject | None	Previous window's CSO, if any.	required
window_output	str	Raw LLM output for the current window.	required
window_number	int	Current window number.	required
dpe_report	dict[str, Any] | None	Optional DPE report for richer extraction.	None
hmac_key	bytes | None	Optional HMAC key for chain integrity.	None
goal_sections	list[str] | None	Optional list of remaining goal sections.	None

Returns:

Type	Description
CognitiveStateObject	Verified, complete CSO for the next window.

Steps

1. Extract new CSO from window_output.
2. Check preservation score against prior CSO.
3. If score < 1.0 → repair (re-inject dropped facts/decisions).
4. Extend HMAC chain.
5. Mark verified=True.
6. Return verified CSO for next window.

Note

This replaces the v3 text summary continuation approach: continuation_context = relay_cso(...).to_prompt_context().

preservation_report(prior, current)

Generate data for CRP-Relay-Preservation header (SPEC-030 §5.3).

Parameters:

Name	Type	Description	Default
prior	CognitiveStateObject	Previous window's CSO.	required
current	CognitiveStateObject	Current window's CSO.	required

Returns:

Type	Description
dict[str, Any]	Dict with preservation score, repaired count, and fact counts.

state.event_log

crp.state.event_log

Event sourcing - append-only immutable fact lifecycle log (§3.2).

Every fact mutation (create, supersede, compact, archive, restore) is recorded as a FactEvent. The log supports temporal queries: state_at_window, facts_between, supersession_chain.

FactEvent dataclass

Immutable audit-log entry for a fact lifecycle event.

to_dict()

Serialize the event to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
FactEvent	FactEvent.

FactEventLog

Append-only immutable event log for fact lifecycle (§3.2).

Supports: - append(): add new event with monotonic ID - state_at_window(): replay events to reconstruct state at a point - facts_between(): range query - supersession_chain(): full lifecycle trail for a fact - Temporal queries: events_since, events_for_fact

size property

Return the current size count.

append(event_type, fact_id, window_id, payload=None)

Record an immutable event. Returns the created event.

record_fact_created(fact, window_id)

Convenience: record a fact creation event.

record_supersession(old_fact_id, new_fact_id, window_id, confidence=1.0)

Record that old_fact_id was superseded by new_fact_id.

record_compaction(fact_id, window_id, summary_id='')

Record that fact_id was compacted into summary_id.

record_archived(fact_id, window_id)

Record that fact_id was archived.

record_restored(fact_id, window_id)

Record that fact_id was restored from archive.

record_edge_added(edge, window_id)

Record that a graph edge was added.

state_at_window(window_id)

Replay events up to window_id and return the set of active fact IDs.

An active fact is one that was created and not yet superseded/compacted/archived.

facts_between(start_window, end_window)

Return events between two windows (inclusive).

supersession_chain(fact_id)

Return the full supersession lifecycle trail for fact_id.

events_since(timestamp)

Return all events after timestamp.

events_for_fact(fact_id)

Return all events for a specific fact.

events_by_type(event_type)

Filter events by type.

events_in_window(window_id)

Return all events for a specific window.

all_events()

Return a copy of all events.

to_list()

Serialize all events for persistence.

load_from_list(events)

Restore from serialized event list.

truncate_before(event_id)

Remove events before event_id. Returns removed events for archival.

state.fact

crp.state.fact

State-layer Fact model - extends extraction Fact with lazy embedding, age tracking, and seen_count for the 4-tier memory hierarchy (§3.1).

StateFact wraps extraction.types.Fact with additional state-management fields that the warm store, envelope builder, and compaction engine need.

StateFact dataclass

Fact extended with state-management metadata (§3.1).

Wraps an extraction Fact and adds: - Lazy embedding (computed on first access, cached) - age_in_windows - updated each window by the warm store - seen_count - how many envelopes this fact appeared in - consumed_by_windows - which windows used this fact - graph_edges - IDs of connected FactEdges

id property

Return the id.

text property

Return the text.

category property

Return the category.

confidence property

Return the confidence.

source_window_id property

Return the source window identifier.

created_at property

Return the created at.

extraction_stage property

Return the extraction stage.

superseded_by property writable

Return the superseded by.

embedding property writable

Lazy-compute embedding on first access.

is_superseded property

Return whether this object is superseded.

has_embedding()

Return True if an embedding has been computed or assigned.

mark_seen(window_id)

Record that this fact was included in an envelope for window_id.

increment_age()

Advance age by one window.

supersede(by_fact_id, confidence=1.0)

Mark this fact as superseded.

to_dict()

Serialize to dict for persistence (including embeddings §4D.1).

from_fact(fact) classmethod

Wrap an extraction Fact into a StateFact.

from_dict(data) classmethod

Deserialize from dict.

set_embedding_function(fn)

Register the global embedding function for lazy compute.

state.horizons

crp.state.horizons

Multi-Horizon Context Model - Persistent, Conversational, Ephemeral tiers (SPEC-028).

Three context tiers with fundamentally different lifecycles and retrieval policies

PERSISTENT → CKF (months–years, novelty-weighted CDR/CDGR) CONVERSATIONAL → Turn Log (session-scoped, recency + reference resolution) EPHEMERAL → Scratch Buffer (seconds–minutes, freshness-gated)

The envelope assembler blends them per-turn according to detected intent.

ContextTier

Bases: str, Enum

The three context tiers of the Multi-Horizon Model (SPEC-028 §2.1).

TurnEntry dataclass

One entry in the Conversational Turn Log (Tier C).

MultiHorizonContext dataclass

Unified envelope assembler for the three context tiers (SPEC-028 §2.2).

Attributes:

Name	Type	Description
turn_log	list[TurnEntry]	Ordered list of turn entries (Tier C).
max_turn_log	int	Maximum turns to retain in conversational memory.

classify_intent(turn)

Detect topic shift, reference resolution, clarification need (SPEC-028 §5).

Returns dict with

intent: str - "explore" | "drill_down" | "clarify" | "reference" confidence: float

resolve_reference(reference, turn_history)

Resolve "it", "that approach", "what you said about X" etc. (SPEC-028 §4).

Returns the best-matching prior turn content, or empty string if none.

blend_for_operation(operation, weights=None)

Per-turn tier blend: different operations need different balances (SPEC-028 §2.2).

Parameters:

Name	Type	Description	Default
operation	str	One of the STL operations (RETRIEVE, SYNTHESISE, etc.)	required
weights	dict[str, float] | None	Optional override weights.	None

Returns:

Type	Description
dict[str, float]	Dict with keys persistent, conversational, ephemeral summing to 1.0.

add_turn(role, content, topic_tags=None)

Append a turn to the conversational log.

get_recent_turns(n=5)

Return the last n turns.

get_turns_by_topic(topic)

Return turns tagged with a given topic.

state.scratch_buffer

crp.state.scratch_buffer

Scratch Buffer - structured, freshness-gated, reference-addressable store for ephemeral context (SPEC-029).

Tier E of the Multi-Horizon Model. Manages tool outputs, intermediate results, and working data with instant-decay lifecycle.

ScratchPersistence

Bases: str, Enum

How long a scratch entry lives.

ScratchEntry dataclass

One item in the Scratch Buffer.

is_fresh property

Return whether this object is fresh.

ScratchBuffer dataclass

Tier E store - high-volume working data with pointer-based access (SPEC-029).

Data stays in memory/disk; only pointers and summaries live in the session.

store(data, entry_id, tool_name='', freshness_ttl=30, structure='auto')

Store data and return a pointer. Data written to ephemeral store.

Parameters:

Name	Type	Description	Default
data	Any	The raw output to store.	required
entry_id	str	Addressable ID, e.g. "scratch_sql_001".	required
tool_name	str	Which tool produced this.	''
freshness_ttl	int	Seconds until entry becomes stale.	30
structure	str	"auto" | "tabular" | "json" | "code" | "text".	'auto'

get_fresh(entry_id)

Returns None if entry has expired.

summarise(entry_id, max_tokens=200)

Structure-aware summarisation for inclusion in Operation Frames.

get_provenance(entry_id)

SPEC-029 §6: TOOL_GROUNDED provenance for decisions based on tool output.

pin(entry_id)

Promote an entry from ephemeral to pinned persistence.

purge_expired()

Remove expired ephemeral entries. Returns count removed.

state.serialization

crp.state.serialization

FactGraph serialization - on-disk format with schema versioning (§22).

Provides forward/backward compatible serialization of the full fact graph including nodes, edges, and metadata.

GraphSerializationHeader dataclass

Header for serialized FactGraph files.

FactGraphSerializer

Serialize/deserialize FactGraph to/from disk (§22).

Format: JSON with header + nodes + edges. Schema-versioned for forward/backward compatibility.

serialize(graph) staticmethod

Serialize a FactGraph to a dict.

deserialize(data) staticmethod

Deserialize a dict into a FactGraph. Returns (graph, warnings).

save_to_file(graph, path) classmethod

Serialize and write to file.

load_from_file(path) classmethod

Load from file. Returns (graph, warnings).

state.session_cleanup

crp.state.session_cleanup

Session file TTL cleanup - automatic expiry of persisted sessions (§audit H11).

Production deployments accumulate session JSON files indefinitely. This module provides automatic cleanup based on file age.

cleanup_expired_sessions(sessions_dir=None, ttl_seconds=DEFAULT_TTL_SECONDS, dry_run=False)

Remove session files older than ttl_seconds.

Parameters:

Name	Type	Description	Default
sessions_dir	str | None	Path to the session storage directory. Defaults to ./crp_sessions.	None
ttl_seconds	float	Maximum age in seconds (default 7 days).	DEFAULT_TTL_SECONDS
dry_run	bool	If True, list but do not delete files.	False

Returns:

Type	Description
list[str]	List of removed (or would-be-removed) file paths.

state.snapshot

crp.state.snapshot

Snapshots & session resume - periodic checkpoint + restore (§3.3, §22.4).

Snapshots capture warm store state at regular intervals so the event log can be truncated. Session resume protocol: load snapshot → verify integrity → replay events → rebuild ANN.

EventLogSnapshot dataclass

Captured state at a point in time (§3.3).

compute_checksum()

Compute integrity checksum over the snapshot payload.

verify_checksum()

Verify the stored checksum matches the payload.

to_dict()

Serialize the snapshot to a dict.

from_dict(data) classmethod

Create a new instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The data value.	required

Returns:

Type	Description
EventLogSnapshot	EventLogSnapshot.

SnapshotManager

Manages periodic snapshots of warm store state (§3.3).

Usage

mgr = SnapshotManager(warm_store, event_log) mgr.maybe_snapshot(window_id) # called each window

On resume:

mgr.restore_from_file(path)

snapshot_count property

Return the current snapshot count.

last_snapshot property

Return the last snapshot.

snapshot(window_id)

Create a snapshot of the current warm store state.

maybe_snapshot(window_id)

Create snapshot if interval has elapsed.

truncate_before_snapshot()

Truncate event log before the last snapshot. Returns events removed.

restore_from_snapshot(snapshot)

Restore warm store from snapshot, returning validation warnings.

Performs consistency checks (§22.4): 1. Schema version compatibility 2. Checksum integrity 3. Fact count consistency 4. Edge integrity (both endpoints exist) 5. No orphaned edges 6. Critical state present 7. Window count non-negative 8. Fact IDs unique 9. No circular supersession 10. Timestamps reasonable

save_to_file(path)

Save latest snapshot to disk using atomic write (§4G.4).

restore_from_file(path)

Load snapshot from disk, verify, restore. Returns warnings.

Handles partial-write corruption by checking for .tmp files (§4G.4). After snapshot restore, replays event log entries since the snapshot to rebuild full state (§4D.3).

state.storage

crp.state.storage

5-Primitive Storage Engine - public API (SPEC-035).

Exports

StorageRouter - unified access router (the main entry point) AccessPattern - access pattern enum RollingContextLog - Primitive 2: sequential recency LogEntry - rolling log entry HotCache - Primitive 3: repeat-access acceleration InvertedIndex - Primitive 4: exact-match lookup EphemeralStore - Primitive 5: pointer-based large working data EphemeralEntry - ephemeral store entry DataStructure - structure type constants

DataStructure

Detected structure types for ephemeral entries.

EphemeralEntry dataclass

A pointer-addressed ephemeral data entry.

is_fresh()

True if the entry has not expired.

age_seconds()

Return the elapsed seconds since the entry was created.

EphemeralStore

Pointer-based ephemeral store for high-volume working data.

Store data with store() → get back a pointer (entry_id). Retrieve with get() - returns None if expired. Summarise with summarise() for inclusion in Operation Frames.

store(data, entry_id='', ttl_seconds=300.0, structure='auto', provenance='UNKNOWN', metadata=None)

Store data and return its pointer (entry_id).

If entry_id is empty, a UUID is generated. structure="auto" detects structure heuristically.

get(entry_id)

Return data for entry_id if fresh, None if expired or missing.

get_entry(entry_id)

Return the full EphemeralEntry (with metadata).

get_provenance(entry_id)

Return provenance record for decisions based on this data.

summarise(entry_id, max_tokens=200)

Structure-aware summary for inclusion in Operation Frames.

entry_count()

Return the number of entries currently stored.

clear()

Remove all entries from the store.

HotCache

LRU cache for repeat retrieval acceleration.

Keys are (query_embedding_hash, ckf_state_hash) tuples. Entries are invalidated when ckf_state_hash changes or TTL expires.

set_ckf_state(state_hash)

Update the current CKF state hash. Clears cache on change.

make_key(query_embedding, ckf_state_hash) staticmethod

Build a cache key from query embedding + CKF state hash.

get(key)

Return cached value or None if not found / expired.

put(key, value)

Store a value; evict LRU entry if over capacity.

invalidate(key)

Remove a single entry from the cache.

clear()

Remove all entries from the cache.

size()

Return the number of cached entries.

capacity()

Return the maximum number of entries the cache can hold.

InvertedIndex

Exact-match inverted index for fast keyed and term-based lookup.

Maintains two indexes: - _term_index: term → {fact_id} for token-based search - _key_index: key → {fact_id} for exact named lookup - _facts: fact_id → IndexedFact for O(1) retrieval

add(fact_id, fact, text='', keys=None)

Index a fact by its text terms and optional explicit keys.

remove(fact_id)

Remove a fact from all indexes.

lookup_key(key)

Exact key lookup - returns facts matching the key exactly.

lookup_term(term)

Single-term lookup - returns all facts containing the term.

lookup_terms(terms, mode='any')

Multi-term lookup.

mode="any" - facts matching ANY of the terms (union) mode="all" - facts matching ALL of the terms (intersection)

get_fact(fact_id)

Direct fact_id → fact lookup.

fact_count()

Return the number of facts in the index.

term_count()

Return the number of unique terms in the index.

clear()

Remove all facts and terms from the index.

LogEntry dataclass

A single entry in the rolling context log.

RollingContextLog

Fixed-capacity append-only ring buffer for sequential recency access.

When capacity is exceeded, oldest entries are discarded from the tail. Reading recent entries is a deque-slice - no search or embedding needed.

append(entry)

Append an entry; oldest auto-discarded when capacity exceeded.

append_turn(content, window_number=0, entry_id='', metadata=None)

Convenience: append a conversation turn.

get_recent(n=10)

Return the n most recent entries (newest last).

get_recent_content(n=10)

Return content strings for the n most recent entries.

get_window(window_number)

Return all entries from a specific window.

entry_count()

Return the number of entries currently in the log.

capacity()

Return the maximum number of entries the log can hold.

clear()

Remove all entries from the log.

AccessPattern

Bases: str, Enum

The six access patterns CRP supports (SPEC-035 §1.1).

StorageRouter

Unified storage router - selects the right primitive per access pattern.

The CKF graph (Primitive 1) is NOT owned by this router - it lives in ContextualKnowledgeFabric and is passed in via set_ckf(). The router provides access to Primitives 2–5.

Usage::

router = StorageRouter()
# Recency
entries = router.get_recent_turns(n=5)
# Exact
facts = router.exact_lookup("pod_ip_fact")
# Cache
cached = router.get_cached(query_emb, ckf_hash)
# Ephemeral
ptr = router.store_ephemeral(tool_output, provenance="TOOL_GROUNDED")
data = router.get_ephemeral(ptr)

set_ckf(ckf)

Register the CKF instance for semantic / graph access.

append_turn(content, window_number=0, entry_id='', metadata=None)

Append a turn to the rolling context log.

get_recent_turns(n=10)

Return the n most recent turns from the rolling log.

get_recent_content(n=10)

Return content strings for the n most recent turns.

get_cached(query_embedding, ckf_state_hash)

Return cached retrieval result, or None if not cached / stale.

put_cached(query_embedding, ckf_state_hash, value)

Store a retrieval result in the hot cache.

invalidate_cache(ckf_state_hash='')

Invalidate the cache (called on CKF state change).

index_fact(fact_id, fact, text='', keys=None)

Index a fact for exact-match lookup.

exact_lookup(key)

Exact key lookup - returns facts matching the key.

term_lookup(term)

Single-term lookup.

remove_from_index(fact_id)

Remove a fact from the exact index (e.g. on GC/tombstone).

store_ephemeral(data, entry_id='', ttl_seconds=300.0, structure='auto', provenance='UNKNOWN', metadata=None)

Store large working data; returns pointer (entry_id).

get_ephemeral(entry_id)

Retrieve ephemeral data by pointer; None if expired.

summarise_ephemeral(entry_id, max_tokens=200)

Structure-aware summary for Operation Frame inclusion.

get_ephemeral_provenance(entry_id)

Provenance record for decisions based on ephemeral data.

overview()

Return a summary of all active storage primitives.

state.storage.ephemeral_store

crp.state.storage.ephemeral_store

Ephemeral Store - pointer-based large working data primitive (SPEC-035 §2.5).

High-volume tool output, intermediate results, and scratch data are stored here as pointer-addressed entries. The data lives in memory (or optionally on disk); only the pointer (a short ID) lives in the session context.

Structure-aware: knows if content is tabular, JSON, code, or text. Freshness-gated: each entry has a TTL. Expired entries are excluded from Operation Frames and return None.

This is the correct primitive for "these 5,000 tool-output rows" - never force large working data through the vector index.

DataStructure

Detected structure types for ephemeral entries.

EphemeralEntry dataclass

A pointer-addressed ephemeral data entry.

is_fresh()

True if the entry has not expired.

age_seconds()

Return the elapsed seconds since the entry was created.

EphemeralStore

Pointer-based ephemeral store for high-volume working data.

Store data with store() → get back a pointer (entry_id). Retrieve with get() - returns None if expired. Summarise with summarise() for inclusion in Operation Frames.

store(data, entry_id='', ttl_seconds=300.0, structure='auto', provenance='UNKNOWN', metadata=None)

Store data and return its pointer (entry_id).

If entry_id is empty, a UUID is generated. structure="auto" detects structure heuristically.

get(entry_id)

Return data for entry_id if fresh, None if expired or missing.

get_entry(entry_id)

Return the full EphemeralEntry (with metadata).

get_provenance(entry_id)

Return provenance record for decisions based on this data.

summarise(entry_id, max_tokens=200)

Structure-aware summary for inclusion in Operation Frames.

entry_count()

Return the number of entries currently stored.

clear()

Remove all entries from the store.

state.storage.hot_cache

crp.state.storage.hot_cache

Hot Cache - repeat-access acceleration primitive (SPEC-035 §2.3).

LRU cache keyed by (query_hash, ckf_state_hash). When the same query is issued against an unchanged CKF, the prior assembled result is returned directly without re-running CDR/CDGR.

This turns repeat retrieval (retries, parallel branches, follow-ups) into a hash lookup - microseconds instead of milliseconds.

Invalidated when the CKF state changes (tracked via state_hash). Short TTL (default 60 s) as a secondary safety net.

CacheEntry dataclass

A cached retrieval result.

HotCache

LRU cache for repeat retrieval acceleration.

Keys are (query_embedding_hash, ckf_state_hash) tuples. Entries are invalidated when ckf_state_hash changes or TTL expires.

set_ckf_state(state_hash)

Update the current CKF state hash. Clears cache on change.

make_key(query_embedding, ckf_state_hash) staticmethod

Build a cache key from query embedding + CKF state hash.

get(key)

Return cached value or None if not found / expired.

put(key, value)

Store a value; evict LRU entry if over capacity.

invalidate(key)

Remove a single entry from the cache.

clear()

Remove all entries from the cache.

size()

Return the number of cached entries.

capacity()

Return the maximum number of entries the cache can hold.

state.storage.inverted_index

crp.state.storage.inverted_index

Inverted Index - exact-match lookup primitive (SPEC-035 §2.4).

Term-to-fact and key-to-fact inverted index for exact-match retrieval. Microsecond lookups for named entities, identifiers, and structured fields.

This is the right primitive when the access pattern is "the fact named X" or "facts mentioning entity Y exactly" - as opposed to "facts similar in meaning to X" (that's the CKF graph).

IndexedFact dataclass

A fact stored in the inverted index with its terms and keys.

InvertedIndex

Exact-match inverted index for fast keyed and term-based lookup.

Maintains two indexes: - _term_index: term → {fact_id} for token-based search - _key_index: key → {fact_id} for exact named lookup - _facts: fact_id → IndexedFact for O(1) retrieval

add(fact_id, fact, text='', keys=None)

Index a fact by its text terms and optional explicit keys.

remove(fact_id)

Remove a fact from all indexes.

lookup_key(key)

Exact key lookup - returns facts matching the key exactly.

lookup_term(term)

Single-term lookup - returns all facts containing the term.

lookup_terms(terms, mode='any')

Multi-term lookup.

mode="any" - facts matching ANY of the terms (union) mode="all" - facts matching ALL of the terms (intersection)

get_fact(fact_id)

Direct fact_id → fact lookup.

fact_count()

Return the number of facts in the index.

term_count()

Return the number of unique terms in the index.

clear()

Remove all facts and terms from the index.

state.storage.rolling_log

crp.state.storage.rolling_log

Rolling Context Log - sequential recency primitive (SPEC-035 §2.2).

Append-only ring buffer: new entries append at the head; old entries roll off the tail when capacity is exceeded. Reading "the last N" is O(N) via list slice - no search, no embedding required.

This is the Turn Log and recent-operations store. It is NOT the vector index - it is the "what just happened" store, accessed by position.

Access cost target: microseconds (list slice).

LogEntry dataclass

A single entry in the rolling context log.

RollingContextLog

Fixed-capacity append-only ring buffer for sequential recency access.

When capacity is exceeded, oldest entries are discarded from the tail. Reading recent entries is a deque-slice - no search or embedding needed.

append(entry)

Append an entry; oldest auto-discarded when capacity exceeded.

append_turn(content, window_number=0, entry_id='', metadata=None)

Convenience: append a conversation turn.

get_recent(n=10)

Return the n most recent entries (newest last).

get_recent_content(n=10)

Return content strings for the n most recent entries.

get_window(window_number)

Return all entries from a specific window.

entry_count()

Return the number of entries currently in the log.

capacity()

Return the maximum number of entries the log can hold.

clear()

Remove all entries from the log.

state.storage.router

crp.state.storage.router

Storage Access Router - selects the right primitive per access pattern (SPEC-035 §3).

The router is the unified entry point for all context storage and retrieval in CRP v4. It holds instances of all five primitives and dispatches each access to the optimal one:

SEMANTIC   → CKF graph (associative recall + CDGR multi-hop)
RECENCY    → RollingContextLog (sequential, position-based)
EXACT      → InvertedIndex (key/term exact match)
CACHED     → HotCache (repeat query acceleration)
LARGE      → EphemeralStore (pointer-addressed high-volume data)

The performance target from SPEC-035 §1.1: RECENCY / EXACT / CACHED: microseconds (no embedding, no search) SEMANTIC / CDGR: sub-millisecond to ~2 ms

AccessPattern

Bases: str, Enum

The six access patterns CRP supports (SPEC-035 §1.1).

StorageRouter

Unified storage router - selects the right primitive per access pattern.

The CKF graph (Primitive 1) is NOT owned by this router - it lives in ContextualKnowledgeFabric and is passed in via set_ckf(). The router provides access to Primitives 2–5.

Usage::

router = StorageRouter()
# Recency
entries = router.get_recent_turns(n=5)
# Exact
facts = router.exact_lookup("pod_ip_fact")
# Cache
cached = router.get_cached(query_emb, ckf_hash)
# Ephemeral
ptr = router.store_ephemeral(tool_output, provenance="TOOL_GROUNDED")
data = router.get_ephemeral(ptr)

set_ckf(ckf)

Register the CKF instance for semantic / graph access.

append_turn(content, window_number=0, entry_id='', metadata=None)

Append a turn to the rolling context log.

get_recent_turns(n=10)

Return the n most recent turns from the rolling log.

get_recent_content(n=10)

Return content strings for the n most recent turns.

get_cached(query_embedding, ckf_state_hash)

Return cached retrieval result, or None if not cached / stale.

put_cached(query_embedding, ckf_state_hash, value)

Store a retrieval result in the hot cache.

invalidate_cache(ckf_state_hash='')

Invalidate the cache (called on CKF state change).

index_fact(fact_id, fact, text='', keys=None)

Index a fact for exact-match lookup.

exact_lookup(key)

Exact key lookup - returns facts matching the key.

term_lookup(term)

Single-term lookup.

remove_from_index(fact_id)

Remove a fact from the exact index (e.g. on GC/tombstone).

store_ephemeral(data, entry_id='', ttl_seconds=300.0, structure='auto', provenance='UNKNOWN', metadata=None)

Store large working data; returns pointer (entry_id).

get_ephemeral(entry_id)

Retrieve ephemeral data by pointer; None if expired.

summarise_ephemeral(entry_id, max_tokens=200)

Structure-aware summary for Operation Frame inclusion.

get_ephemeral_provenance(entry_id)

Provenance record for decisions based on ephemeral data.

overview()

Return a summary of all active storage primitives.

state.warm_store

crp.state.warm_store

Warm state store - in-memory Tier 2 with optional SQLite WAL persist (§3.0, §3.1).

The warm store holds all active facts, their graph, and provides the ranked retrieval interface used by the envelope builder.

WarmStoreConfig dataclass

Configuration for the warm state store.

Attributes:

Name	Type	Description
max_facts	int	Maximum number of facts to retain in memory.
persist_enabled	bool	Whether to write state to SQLite WAL on change.
persist_path	str	Filesystem path for persistence (when enabled).
compact_threshold	int	Fact count that triggers compaction consideration.
compact_latency_ms	float	Target maximum compaction latency in milliseconds.

WarmStateStore

In-memory warm state (Tier 2) with thread-safe access.

Provides: - add_facts / get_facts / get_ranked_facts / mark_seen / supersede - Critical state & structural state management - Optional async SQLite WAL persistence (Phase 4E)

fact_count property

Number of facts currently stored.

graph property

Underlying fact graph.

critical_state property

Current critical state (goal, phase, blockers, constraints).

structural_state property

Current structural state.

window_count property

Number of windows that have advanced through this store.

add_facts(facts, edges=None)

Add extraction facts to the warm store, wrapping them as StateFacts.

Parameters:

Name	Type	Description	Default
facts	list[Fact]	Facts to add.	required
edges	list[FactEdge] | None	Optional graph edges linking the facts.	None

Returns:

Type	Description
list[StateFact]	List of newly added StateFact objects. Duplicate IDs or content
list[StateFact]	hashes are skipped.

get_facts(*, include_superseded=False)

Return all active facts (or all including superseded).

Parameters:

Name	Type	Description	Default
include_superseded	bool	Whether to include superseded facts.	False

Returns:

Type	Description
list[StateFact]	List of matching StateFact objects.

get_fact(fact_id)

Get a specific fact by ID.

Parameters:

Name	Type	Description	Default
fact_id	str	Fact identifier.	required

Returns:

Type	Description
StateFact | None	The StateFact or None if not found.

get_active_facts_as_extraction()

Return active facts as extraction Fact objects (for envelope builder).

CRP 2.2: every returned fact is stamped with a :class:~crp.core.context_source.ContextSource of kind :data:~crp.core.context_source.SourceKind.WARM_STORE when its source is unset - making provenance explicit for envelope consumers and the attestation pipeline.

Trust: TrustLevel.UNKNOWN. Warm-store content may have originated from any upstream tier, including untrusted external retrieval; CRP cannot safely upgrade trust here. Integrators who can prove warm-store contents were vetted should override fact.source upstream before the fact enters the store.

get_ranked_facts(*, top_k=None, limit=None)

Return active facts sorted by relevance heuristic (confidence × recency).

Parameters:

Name	Type	Description	Default
top_k	int | None	Maximum number of facts to return (alias for limit).	None
limit	int | None	Maximum number of facts to return.	None

Returns:

Type	Description
list[StateFact]	Active facts ranked by confidence * (1 / (1 + age_in_windows)).

mark_seen(fact_ids, window_id)

Record that facts were included in an envelope for window_id.

Parameters:

Name	Type	Description	Default
fact_ids	list[str]	List of fact IDs that appeared in the envelope.	required
window_id	str	Window that consumed the facts.	required

supersede(old_fact_id, new_fact_id, confidence=1.0)

Mark old_fact_id as superseded by new_fact_id.

Parameters:

Name	Type	Description	Default
old_fact_id	str	Fact being replaced.	required
new_fact_id	str	Fact that replaces it.	required
confidence	float	Confidence in the supersession relationship.	1.0

remove_fact(fact_id)

Remove a fact (for compaction/archival).

Parameters:

Name	Type	Description	Default
fact_id	str	Fact to remove.	required

Returns:

Type	Description
StateFact | None	The removed StateFact or None if not found.

boost_confidence(fact_id, delta)

Increase a fact's confidence by delta, capped at 1.0 (§22 curation).

Parameters:

Name	Type	Description	Default
fact_id	str	Fact to boost.	required
delta	float	Amount to add to the fact's confidence.	required

reduce_confidence(fact_id, delta)

Decrease a fact's confidence by delta, floored at 0.0 (§22 curation).

Parameters:

Name	Type	Description	Default
fact_id	str	Fact to reduce.	required
delta	float	Amount to subtract from the fact's confidence.	required

advance_window(window_id)

Called when a new window begins - age all facts, update window tracking.

Parameters:

Name	Type	Description	Default
window_id	str	Identifier for the new window.	required

get_critical_state()

Return the current critical state.

update_critical_state(**kwargs)

Update critical state fields (goal, phase, blockers, constraints).

Parameters:

Name	Type	Description	Default
**kwargs	Any	Key-value pairs to set on the critical state.	{}

update_phase(phase)

Update the current phase and window id.

Parameters:

Name	Type	Description	Default
phase	str	New phase string.	required

get_structural_state()

Return the current structural state.

update_structural_state(**kwargs)

Update structural state fields.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Key-value pairs to set on the structural state.	{}

get_seen_counts()

Return {fact_id: seen_count} for all facts.

Returns:

Type	Description
dict[str, int]	Mapping of fact ID to number of times it has been seen in envelopes.

get_fact_window_indices()

Return {fact_id: creation_window_index} for scoring recency.

Returns:

Type	Description
dict[str, int]	Mapping of fact ID to the window index at which it was created.

on_fact_added(callback)

Subscribe a callback invoked when a fact is added.

Parameters:

Name	Type	Description	Default
callback	Callable[[StateFact], None]	Function receiving the newly added StateFact.	required

on_fact_superseded(callback)

Subscribe a callback invoked when a fact is superseded.

Parameters:

Name	Type	Description	Default
callback	Callable[[StateFact, str], None]	Function receiving the superseded StateFact and the replacement fact ID.	required

needs_compaction()

Check if warm store exceeds compaction thresholds.

Returns:

Type	Description
bool	True if fact_count exceeds compact_threshold.

to_dict()

Serialize entire warm store state.

Returns:

Type	Description
dict[str, Any]	Dict containing facts, edges, critical/structural state, and window info.

load_from_dict(data)

Restore warm store from serialized dict.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dict produced by to_dict.	required

Raises:

Type	Description
ValueError	If the session file schema version is newer than supported.