Cognitive State Object API¶
The client.cso namespace exposes the Cognitive State Object (CSO), which preserves established facts, decisions, and dependencies across continuation windows.
SDK proxy¶
crp.sdk.proxies._CSOProxy ¶
Cognitive State Object proxy (SPEC-030).
Exposes the current CSO and its components (decisions, goals, dependencies, established facts).
get() ¶
Return the current CognitiveStateObject.
If the orchestrator session holds a CSO, that object is returned. Otherwise a CSO is built from the warm store and any available decisions.
Returns:
| Type | Description |
|---|---|
Any | CognitiveStateObject instance. |
decisions() ¶
Return the list of CSO decisions.
goals() ¶
Return the list of goal states.
dependencies() ¶
Return the CSO dependency edges.
established_facts() ¶
Return established facts from the current CSO.
Cognitive State Object¶
crp.state.cso.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 |
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 |
|
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 |
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 | required |
Returns:
| Type | Description |
|---|---|
CognitiveStateObject | Reconstructed |