crp.continuation¶

Auto-generated reference for the crp.continuation subpackage.

`continuation`¶

`crp.continuation` ¶

Continuation engine - wall detection, gap analysis, stitch, completion.

`CompletionConfig` `dataclass` ¶

Configuration for completion detection.

`CompletionDetector` ¶

Multi-signal completion with self-calibrating baselines (§4.3).

`evaluate(text, facts_produced, tokens_consumed, structural_state=None)` ¶

Evaluate all 4 completion signals for a window output.

`reset()` ¶

Clear all state.

`CompletionResult` `dataclass` ¶

Aggregated completion assessment.

`CompletionSignal` ¶

Bases: str, Enum

The four completion signals.

`SignalState` `dataclass` ¶

State of a single completion signal.

`ChainDegradation` ¶

Track cumulative degradation across continuation windows (§04 §3.5.3).

Formula: d_chain(n) = 1 - ∏(1 - d_i) where d_i is per-window degradation based on extraction quality drop.

Triggers regrounding every N=5 windows to reconcile drifted facts.

`chain_degradation` `property` ¶

Current cumulative chain degradation d_chain(n).

`window_count` `property` ¶

Return the current window count.

`history` `property` ¶

Return the history.

`record(window_id, facts_expected, facts_produced, quality_score=1.0)` ¶

Record per-window degradation.

d_i estimated from: - fact count drop: (expected - produced) / expected - quality score inversion: 1 - quality_score Combined with equal weight.

`should_reground()` ¶

Whether regrounding is due (every N windows).

`reground(current_facts, regrounded_facts)` ¶

Reconcile current facts against re-extracted facts.

Compare by text similarity (word overlap). Facts with overlap < 0.5 are considered drifted.

`reset()` ¶

Clear all state.

`DegradationMetrics` `dataclass` ¶

Per-window degradation measurement.

`RegroundingResult` `dataclass` ¶

Result of regrounding: re-extracting from raw outputs.

`DocumentMap` `dataclass` ¶

Incremental table-of-contents tracker (§04 §3.5.2).

Maintains a running TOC as the LLM generates content across windows. Tracks heading hierarchy, list positions, and structural completeness.

`update(text, window_id)` ¶

Process a window output and update the document map.

Returns new headings found in this window. Deduplicates headings by section number to prevent the same section from being tracked multiple times across windows (GAP C fix).

`get_toc()` ¶

Render the current TOC as markdown.

`progress()` ¶

Estimate document completion progress (0.0–1.0).

`missing_sections(expected)` ¶

Compare against expected sections and return missing ones.

`to_dict()` ¶

Serialize the document map state to a JSON-ready dict.

`from_dict(data)` `classmethod` ¶

Create a new instance from a dictionary.

Parameters:

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

Returns:

Type	Description
`DocumentMap`	`DocumentMap`.

`HeadingEntry` `dataclass` ¶

A single heading in the document map.

`FlowMetrics` `dataclass` ¶

Current information flow metrics.

`InformationFlowMonitor` ¶

Measures Δfacts/Δtokens rolling rate across windows (§4.3).

Tracks how much new information the LLM is producing per token. When flow drops to zero, the model has stopped producing new facts.

`sample_count` `property` ¶

Return the current sample count.

`record(window_id, facts_produced, tokens_consumed, timestamp=0.0)` ¶

Record a new flow sample after a window completes.

`current_rate()` ¶

Facts per 1000 tokens for the most recent window.

`rolling_average()` ¶

Rolling average rate over the last N windows.

`trend()` ¶

Rate of change: positive = flow increasing, negative = decreasing.

Computed as linear slope over rolling window.

`is_alive()` ¶

True if information flow is still positive.

`metrics()` ¶

Get current flow metrics snapshot.

`reset()` ¶

Clear all samples.

`ResidualTaskAnchor` ¶

Forward-looking continuation context (SPEC-004 v4 amendment).

Replaces the v3 backward-looking text summary approach.

v3 approach (problem): continuation_context = f"Previously covered: {summary_of_done_work}" → context grew with each window, dominated token budget by W5

v4 approach (fix): continuation_context = f"Still to cover: {', '.join(remaining[:5])}" → fixed size regardless of how many windows have run → model focuses forward, not backward

Usage::

anchor = ResidualTaskAnchor(task_sections=["intro", "arch", "deploy"])
anchor.mark_complete("intro")
anchor.to_prompt_prefix()  # → "Still to cover: arch, deploy"

Maximum max_remaining items rendered (default 5) keeps the anchor a fixed token cost throughout all windows.

`set_sections(sections)` ¶

Set (or replace) the full task section list.

`mark_complete(section)` ¶

Mark a section as completed.

`mark_complete_batch(sections)` ¶

Mark multiple sections as completed.

`remaining()` ¶

Return the list of not-yet-completed sections.

`to_prompt_prefix(label='Still to cover')` ¶

Render as a fixed-size prompt prefix for the next window.

Returns an empty string when all sections are complete.

`completion_fraction()` ¶

Fraction of sections completed (0.0–1.0).

`is_complete()` ¶

Return True when all task sections have been marked complete.

`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`.

`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.

`GoalState` `dataclass` ¶

Universal window contract (SPEC-030 §4).

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

`GoalMode` ¶

Bases: str, Enum

Window execution mode (SPEC-030 §4.2).

`ProvenanceKind` ¶

Bases: str, Enum

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

`GapResult` `dataclass` ¶

Result of gap analysis between requirements and output facts.

`is_complete` `property` ¶

Return whether this object is complete.

`Requirement` `dataclass` ¶

A single task requirement at a specific analysis level.

`ContinuationConfig` `dataclass` ¶

Configuration for the continuation manager.

Attributes:

Name	Type	Description
`max_continuations`	`int`	Safety bound on continuation windows.
`max_output_tokens`	`int \| None`	Provider output limit.
`reground_interval`	`int`	Windows between regrounding checks.
`content_type`	`str`	Content type hint for completion detection.
`style_anchor_sentences`	`int`	Sentences to extract as style anchor.
`l3_extractor`	`Any`	LLM-assisted requirement extractor callback (§5B.1).
`embedding_fn`	`Any`	Text→embedding function for semantic gap analysis (§5B.3).
`max_accumulated_facts`	`int`	Cap on accumulated facts to bound memory (§audit H7).

`ContinuationManager` ¶

Master continuation loop with 3-way termination (§4.7).

Orchestrates: trigger → gap analysis → envelope → dispatch → extract → stitch → completion check → repeat or terminate.

Termination conditions (ANY triggers stop): 1. gap_is_zero: all task requirements fulfilled 2. all_signals_dead: no completion signal is alive 3. count >= max: safety bound on continuation count

`state` `property` ¶

Current continuation loop state.

`voice_profile` `property` ¶

Extracted voice profile from the first window.

`document_map` `property` ¶

Document map showing completed vs remaining sections.

`flow_monitor` `property` ¶

Information-flow monitor.

`quality_monitor` `property` ¶

Generation quality monitor.

`degradation` `property` ¶

Chain degradation tracker.

`build_continuation_envelope(task_intent, gap_result=None, structural_state=None, last_output='')` ¶

Build a continuation envelope: directive + map + gap + style anchor (§04 §3.2).

The continuation prompt includes: 1. Explicit continuation directive (FIRST - dominant signal) 2. Document map showing completed vs remaining sections 3. Unfulfilled requirements with specific section numbers 4. Style anchor from last output 5. Key findings summary

Parameters:

Name	Type	Description	Default
`task_intent`	`str`	Original task description.	required
`gap_result`	`GapResult \| None`	Latest gap analysis result.	`None`
`structural_state`	`dict[str, object] \| None`	Structural position (section, list position, etc.).	`None`
`last_output`	`str`	Last generated output for style anchoring.	`''`

Returns:

Type	Description
`str`	Continuation envelope text.

`process_window(task_intent, output, finish_reason, output_tokens, facts, window_id='')` ¶

Process a completed window and determine next action.

This is the per-window step of the master loop. Call repeatedly until state.finished is True.

Incremental extraction: processes only this window's output (O(N) not O(N²)).

Parameters:

Name	Type	Description	Default
`task_intent`	`str`	Original task description.	required
`output`	`str`	Generated text from this window.	required
`finish_reason`	`str \| None`	Provider finish reason.	required
`output_tokens`	`int`	Number of tokens generated.	required
`facts`	`list[Fact]`	Facts extracted from this window's output.	required
`window_id`	`str`	Identifier for this window.	`''`

Returns:

Type	Description
`ContinuationState`	Updated `ContinuationState`.

`run(task_intent, dispatcher, initial_output='', initial_finish_reason=None, initial_output_tokens=0, initial_facts=None)` ¶

Full autonomous continuation loop with 3-way termination (§5G.1).

Orchestrates: trigger → gap analysis → envelope → dispatch → extract → stitch → completion check → repeat or terminate.

Parameters:

Name	Type	Description	Default
`task_intent`	`str`	Original task description.	required
`dispatcher`	`LLMDispatcher`	Callable that dispatches a prompt and returns a result.	required
`initial_output`	`str`	Output from the initial window.	`''`
`initial_finish_reason`	`str \| None`	Finish reason from the initial window.	`None`
`initial_output_tokens`	`int`	Token count from the initial window.	`0`
`initial_facts`	`list[Fact] \| None`	Facts extracted from the initial window.	`None`

Returns:

Type	Description
`ContinuationState`	Final `ContinuationState` after termination.

`reset()` ¶

Reset all continuation state for a new task.

`get_context_summary()` ¶

Return a structured summary of continuation progress.

Includes window count, key findings, gap status, and document progress. Can be injected into external prompts that need awareness of in-progress continuation state.

Returns:

Type	Description
`str`	Multi-line summary string.

`ContinuationState` `dataclass` ¶

Current state of the continuation loop.

Attributes:

Name	Type	Description
`window_count`	`int`	Number of continuation windows processed.
`total_tokens`	`int`	Cumulative generated tokens.
`total_facts`	`int`	Cumulative extracted facts.
`gap_result`	`GapResult \| None`	Latest gap analysis result.
`completion_result`	`CompletionResult \| None`	Latest completion-detection result.
`trigger_result`	`TriggerResult \| None`	Latest continuation-trigger result.
`voice_profile`	`VoiceProfile \| None`	Extracted voice profile from the first window.
`chain_degradation`	`float`	Current chain degradation score.
`stitched_output`	`str`	Accumulated stitched output.
`finished`	`bool`	True when the loop terminates.
`termination_reason`	`str`	Why the loop terminated.
`quality_anomaly`	`bool`	True if a quality anomaly was detected.
`regrounded`	`bool`	True if regrounding occurred this window.
`window_outputs`	`list[dict[str, Any]]`	Per-window raw outputs with metadata.

`DispatchResult` `dataclass` ¶

Result from a single LLM dispatch.

Attributes:

Name	Type	Description
`output`	`str`	Generated text.
`finish_reason`	`str \| None`	Provider finish reason (e.g. "stop", "length").
`output_tokens`	`int`	Number of tokens generated.
`facts`	`list[Fact]`	Facts extracted from the output.
`window_id`	`str`	Identifier for the generated window.

`GenerationQualityMonitor` ¶

Real-time Q(t,w) scoring: information density + coherence + novelty (§10).

Detects quality anomalies (sudden Q(t,w) drops) to trigger re-evaluation.

`history` `property` ¶

Return the history.

`score(text, facts_produced, window_id='')` ¶

Compute Q(t,w) for a generation window output.

`detect_anomaly()` ¶

Check if latest score is an anomaly (sudden drop).

`rolling_quality()` ¶

Rolling average Q(t,w) over last N windows.

`reset()` ¶

Clear all state.

`QualityConfig` `dataclass` ¶

Weights for Q(t,w) sub-scores.

`QualityScore` `dataclass` ¶

Q(t,w) composite quality score and sub-scores.

`is_anomaly` `property` ¶

Sudden quality drop: overall < 0.2.

`ContentBoundary` ¶

Bases: str, Enum

Content type for boundary-aware stitching.

`StitchConfig` `dataclass` ¶

Configuration for the stitch algorithm.

`StitchResult` `dataclass` ¶

Result of stitching two outputs together.

`TriggerConfig` `dataclass` ¶

Configuration for continuation triggering.

`TriggerResult` `dataclass` ¶

Result of continuation trigger evaluation.

`VoiceProfile` `dataclass` ¶

Captured voice characteristics from the first generation window.

`to_dict()` ¶

Serialize the voice profile to a JSON-ready dict.

`from_dict(data)` `classmethod` ¶

Create a new instance from a dictionary.

Parameters:

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

Returns:

Type	Description
`VoiceProfile`	`VoiceProfile`.

`should_terminate(window_number, max_windows, *, completeness_score=0.0, completeness_threshold=0.92, ckf_mean_novelty=1.0, ckf_exhaustion_threshold=0.15, safety_budget=1.0, safety_budget_min=0.1, finish_reason='')` ¶

Formal loop exit rules (SPEC-024 §5.2, SPEC-004 amendment).

Returns (should_stop: bool, reason: str).

Exit conditions (any one sufficient): 1. completeness_score >= threshold - task complete per DPE 2. window_number >= max_windows - hard window cap 3. ckf_mean_novelty < threshold - CKF exhausted (CDR signal) 4. safety_budget <= min - safety budget depleted 5. finish_reason == "stop" - model explicitly stopped

`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

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

Note

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

`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.

`clear_requirement_cache()` ¶

Clear the requirement cache (for testing).

`extract_task_requirements(task_intent, l3_extractor=None)` ¶

Extract requirements at L1 (structural) and L2 (semantic) levels.

L3 (LLM-assisted) can be provided via l3_extractor callback (§5B.1). Results are cached by content hash (singleton pattern per §3.5).

`gap_analysis(task_intent, output_facts, requirements=None, embedding_fn=None, document_headings=None)` ¶

Compute gap between task requirements and produced facts (§3.5).

For each requirement, find best-matching fact. Uses cosine similarity when embedding_fn is provided (§5B.3), otherwise falls back to word overlap. Threshold: 0.65.

When document_headings is provided (from the DocumentMap), section- level requirements are also matched against actual headings produced, enabling accurate per-section tracking.

`detect_echo(prior, continuation, config=None)` ¶

Detect echoed content at the start of continuation.

Strategy: 1. Suffix-prefix overlap (exact boundary echo) 2. LCS on last/first 2000 chars (partial echo)

`stitch_many(outputs, config=None)` ¶

N-way iterative stitch for 50+ windows.

Applies pairwise stitch left-to-right, accumulating the result.

`stitch_outputs(prior, continuation, config=None)` ¶

Stitch prior output with continuation output (§4.8, §04 §3.4).

Algorithm: 1. Detect echo (LCS on last/first 2000 chars, min 20 chars) 2. Remove echo from continuation start 3. Content-type-aware boundary detection 4. No-echo fallback: structural continuation, bridge insertion 5. Post-stitch validation 6. Store any trimmed fragments (never silently discard)

`detect_wall_hit(finish_reason, output_tokens=None, max_output_tokens=None)` ¶

Detect physical context-window wall hit.

Primary: finish_reason == "length" (universal across providers). Fallback: output_tokens / max_output_tokens >= 0.95 when finish_reason unavailable.

`evaluate_continuation(*, finish_reason, output_tokens=None, max_output_tokens=None, gap_score=1.0, info_flow=1.0, continuation_count=0, config=None)` ¶

Evaluate whether continuation should proceed.

Three conditions must ALL be met (§4.2): 1. Wall hit detected (physical truncation) 2. Gap score > min_gap_score (unfulfilled requirements remain) 3. Info flow > min_info_flow (model still producing useful content) 4. continuation_count < max_continuations (safety bound)

`extract_voice_profile(text)` ¶

Extract a voice profile from the first window's output (§04 §3.5.1).

`continuation.completion`¶

`crp.continuation.completion` ¶

Multi-signal completion detection (§4.3).

Four signals, weighted by content type, with grace periods and self-calibrating baselines.

`CompletionSignal` ¶

Bases: str, Enum

The four completion signals.

`SignalState` `dataclass` ¶

State of a single completion signal.

`CompletionResult` `dataclass` ¶

Aggregated completion assessment.

`CompletionConfig` `dataclass` ¶

Configuration for completion detection.

`CompletionDetector` ¶

Multi-signal completion with self-calibrating baselines (§4.3).

`evaluate(text, facts_produced, tokens_consumed, structural_state=None)` ¶

Evaluate all 4 completion signals for a window output.

`reset()` ¶

Clear all state.

`continuation.degradation`¶

`crp.continuation.degradation` ¶

Chain degradation tracking and regrounding (§04 §3.5.3).

d_chain(n) = 1 - ∏(1 - d_i) where d_i is per-window degradation. Regrounding: re-extract from raw outputs every N=5 windows.

`DegradationMetrics` `dataclass` ¶

Per-window degradation measurement.

`RegroundingResult` `dataclass` ¶

Result of regrounding: re-extracting from raw outputs.

`ChainDegradation` ¶

Track cumulative degradation across continuation windows (§04 §3.5.3).

Formula: d_chain(n) = 1 - ∏(1 - d_i) where d_i is per-window degradation based on extraction quality drop.

Triggers regrounding every N=5 windows to reconcile drifted facts.

`chain_degradation` `property` ¶

Current cumulative chain degradation d_chain(n).

`window_count` `property` ¶

Return the current window count.

`history` `property` ¶

Return the history.

`record(window_id, facts_expected, facts_produced, quality_score=1.0)` ¶

Record per-window degradation.

d_i estimated from: - fact count drop: (expected - produced) / expected - quality score inversion: 1 - quality_score Combined with equal weight.

`should_reground()` ¶

Whether regrounding is due (every N windows).

`reground(current_facts, regrounded_facts)` ¶

Reconcile current facts against re-extracted facts.

Compare by text similarity (word overlap). Facts with overlap < 0.5 are considered drifted.

`reset()` ¶

Clear all state.

`continuation.document_map`¶

`crp.continuation.document_map` ¶

Document map - incremental TOC tracking across windows (§04 §3.5.2).

`HeadingEntry` `dataclass` ¶

A single heading in the document map.

`DocumentMap` `dataclass` ¶

Incremental table-of-contents tracker (§04 §3.5.2).

Maintains a running TOC as the LLM generates content across windows. Tracks heading hierarchy, list positions, and structural completeness.

`update(text, window_id)` ¶

Process a window output and update the document map.

Returns new headings found in this window. Deduplicates headings by section number to prevent the same section from being tracked multiple times across windows (GAP C fix).

`get_toc()` ¶

Render the current TOC as markdown.

`progress()` ¶

Estimate document completion progress (0.0–1.0).

`missing_sections(expected)` ¶

Compare against expected sections and return missing ones.

`to_dict()` ¶

Serialize the document map state to a JSON-ready dict.

`from_dict(data)` `classmethod` ¶

Create a new instance from a dictionary.

Parameters:

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

Returns:

Type	Description
`DocumentMap`	`DocumentMap`.

`continuation.flow`¶

`crp.continuation.flow` ¶

Information flow monitor - Δfacts/Δtokens rolling measurement (§4.3).

v4 amendment (SPEC-004): adds ResidualTaskAnchor - a forward-looking continuation context that replaces the v3 backward-looking text summary.

Instead of carrying a growing summary of what has been done, the anchor carries only what still needs to be done - a fixed-size list of remaining sub-topics. This eliminates the "backward-looking bloat" problem where continuation context grew with each window and eventually dominated the token budget.

Also adds should_terminate() - formal loop exit rules (SPEC-024 §5.2 and SPEC-004 amendment).

`FlowSample` `dataclass` ¶

Single measurement point in the flow monitor.

`FlowMetrics` `dataclass` ¶

Current information flow metrics.

`InformationFlowMonitor` ¶

Measures Δfacts/Δtokens rolling rate across windows (§4.3).

Tracks how much new information the LLM is producing per token. When flow drops to zero, the model has stopped producing new facts.

`sample_count` `property` ¶

Return the current sample count.

`record(window_id, facts_produced, tokens_consumed, timestamp=0.0)` ¶

Record a new flow sample after a window completes.

`current_rate()` ¶

Facts per 1000 tokens for the most recent window.

`rolling_average()` ¶

Rolling average rate over the last N windows.

`trend()` ¶

Rate of change: positive = flow increasing, negative = decreasing.

Computed as linear slope over rolling window.

`is_alive()` ¶

True if information flow is still positive.

`metrics()` ¶

Get current flow metrics snapshot.

`reset()` ¶

Clear all samples.

`ResidualTaskAnchor` ¶

Forward-looking continuation context (SPEC-004 v4 amendment).

Replaces the v3 backward-looking text summary approach.

v3 approach (problem): continuation_context = f"Previously covered: {summary_of_done_work}" → context grew with each window, dominated token budget by W5

v4 approach (fix): continuation_context = f"Still to cover: {', '.join(remaining[:5])}" → fixed size regardless of how many windows have run → model focuses forward, not backward

Usage::

anchor = ResidualTaskAnchor(task_sections=["intro", "arch", "deploy"])
anchor.mark_complete("intro")
anchor.to_prompt_prefix()  # → "Still to cover: arch, deploy"

Maximum max_remaining items rendered (default 5) keeps the anchor a fixed token cost throughout all windows.

`set_sections(sections)` ¶

Set (or replace) the full task section list.

`mark_complete(section)` ¶

Mark a section as completed.

`mark_complete_batch(sections)` ¶

Mark multiple sections as completed.

`remaining()` ¶

Return the list of not-yet-completed sections.

`to_prompt_prefix(label='Still to cover')` ¶

Render as a fixed-size prompt prefix for the next window.

Returns an empty string when all sections are complete.

`completion_fraction()` ¶

Fraction of sections completed (0.0–1.0).

`is_complete()` ¶

Return True when all task sections have been marked complete.

`should_terminate(window_number, max_windows, *, completeness_score=0.0, completeness_threshold=0.92, ckf_mean_novelty=1.0, ckf_exhaustion_threshold=0.15, safety_budget=1.0, safety_budget_min=0.1, finish_reason='')` ¶

Formal loop exit rules (SPEC-024 §5.2, SPEC-004 amendment).

Returns (should_stop: bool, reason: str).

Exit conditions (any one sufficient): 1. completeness_score >= threshold - task complete per DPE 2. window_number >= max_windows - hard window cap 3. ckf_mean_novelty < threshold - CKF exhausted (CDR signal) 4. safety_budget <= min - safety budget depleted 5. finish_reason == "stop" - model explicitly stopped

`continuation.gap`¶

`crp.continuation.gap` ¶

Gap analysis - L1/L2/L3 requirement extraction and fulfillment scoring (§3.5).

`Requirement` `dataclass` ¶

A single task requirement at a specific analysis level.

`GapResult` `dataclass` ¶

Result of gap analysis between requirements and output facts.

`is_complete` `property` ¶

Return whether this object is complete.

`extract_task_requirements(task_intent, l3_extractor=None)` ¶

Extract requirements at L1 (structural) and L2 (semantic) levels.

L3 (LLM-assisted) can be provided via l3_extractor callback (§5B.1). Results are cached by content hash (singleton pattern per §3.5).

`clear_requirement_cache()` ¶

Clear the requirement cache (for testing).

`discover_adaptive_requirements(existing_reqs, document_headings=None)` ¶

Discover new requirements from document headings not yet covered.

As continuation windows produce new sections, the DocumentMap tracks headings. This function creates L2 requirements for sections that appeared in the output but were not anticipated by the original task analysis, ensuring the gap score tracks actual document completeness.

`gap_analysis(task_intent, output_facts, requirements=None, embedding_fn=None, document_headings=None)` ¶

Compute gap between task requirements and produced facts (§3.5).

For each requirement, find best-matching fact. Uses cosine similarity when embedding_fn is provided (§5B.3), otherwise falls back to word overlap. Threshold: 0.65.

When document_headings is provided (from the DocumentMap), section- level requirements are also matched against actual headings produced, enabling accurate per-section tracking.

`continuation.input_planner`¶

`crp.continuation.input_planner` ¶

Input-side continuation planner - split oversized tasks into full windows (§4.6).

When a task or input context exceeds a single model window, this module plans a sequence of input-processing windows. Each window consumes a chunk of the input, extracts facts, and relays them to the next chunk. After all chunks have been processed, the accumulated facts replace the bulky input so the final answer window can run inside a normal context budget.

This realizes the CRP unbounded-context guarantee for inputs: a 4K model can transparently process a 12K prompt across three full windows rather than silently compacting or truncating it.

`InputChunk` `dataclass` ¶

A single input-continuation window payload.

`InputContinuationPlan` `dataclass` ¶

Plan produced for an oversized input.

`InputContinuationPlanner` ¶

Plan how to process an oversized input across multiple full windows.

The planner respects natural boundaries (paragraphs, then sentences, then words) so that chunks are semantically coherent. It leaves room for the system prompt, a small generation reserve (the model only extracts facts), and a fixed continuation directive.

`plan(task_input, system_prompt, context_window)` ¶

Create a multi-window plan for task_input.

Parameters:

Name	Type	Description	Default
`task_input`	`str`	The oversized user task or context.	required
`system_prompt`	`str`	System prompt that will be included in every window.	required
`context_window`	`int`	Model context window size.	required

Returns:

Type	Description
`InputContinuationPlan`	InputContinuationPlan with semantically-bounded chunks.

`build_chunk_task(chunk, original_task_summary, prior_summary=None)` ¶

Build the task text for a single input-continuation window.

Parameters:

Name	Type	Description	Default
`chunk`	`InputChunk`	Chunk to process.	required
`original_task_summary`	`str`	Short summary of the overall task/question.	required
`prior_summary`	`str \| None`	Optional summary of facts from prior chunks.	`None`

Returns:

Type	Description
`str`	Task text ready for dispatch.

`build_final_task_reference(original_task_input)` ¶

Build a compact reference to the original task after input processing.

The original bulky input has been replaced by extracted facts in the warm store / CKF. This reference reminds the model of the question.

`default_input_planner(count_tokens)` ¶

Factory for the default planner.

`continuation.manager`¶

`crp.continuation.manager` ¶

Continuation manager - envelope builder, master loop, 3-way termination (§4.7).

Implements the continuation loop that decides when to keep generating, what context to carry forward, and when to stop. Combines gap analysis, completion detection, information-flow monitoring, and chain degradation tracking into a single per-window step.

`LLMDispatcher` ¶

Bases: Protocol

Protocol for an LLM dispatch callback used by the continuation loop.

`dispatch(prompt, **kwargs)` ¶

Send a prompt to the LLM and return the dispatch result.

`DispatchResult` `dataclass` ¶

Result from a single LLM dispatch.

Attributes:

Name	Type	Description
`output`	`str`	Generated text.
`finish_reason`	`str \| None`	Provider finish reason (e.g. "stop", "length").
`output_tokens`	`int`	Number of tokens generated.
`facts`	`list[Fact]`	Facts extracted from the output.
`window_id`	`str`	Identifier for the generated window.

`ContinuationConfig` `dataclass` ¶

Configuration for the continuation manager.

Attributes:

Name	Type	Description
`max_continuations`	`int`	Safety bound on continuation windows.
`max_output_tokens`	`int \| None`	Provider output limit.
`reground_interval`	`int`	Windows between regrounding checks.
`content_type`	`str`	Content type hint for completion detection.
`style_anchor_sentences`	`int`	Sentences to extract as style anchor.
`l3_extractor`	`Any`	LLM-assisted requirement extractor callback (§5B.1).
`embedding_fn`	`Any`	Text→embedding function for semantic gap analysis (§5B.3).
`max_accumulated_facts`	`int`	Cap on accumulated facts to bound memory (§audit H7).

`ContinuationState` `dataclass` ¶

Current state of the continuation loop.

Attributes:

Name	Type	Description
`window_count`	`int`	Number of continuation windows processed.
`total_tokens`	`int`	Cumulative generated tokens.
`total_facts`	`int`	Cumulative extracted facts.
`gap_result`	`GapResult \| None`	Latest gap analysis result.
`completion_result`	`CompletionResult \| None`	Latest completion-detection result.
`trigger_result`	`TriggerResult \| None`	Latest continuation-trigger result.
`voice_profile`	`VoiceProfile \| None`	Extracted voice profile from the first window.
`chain_degradation`	`float`	Current chain degradation score.
`stitched_output`	`str`	Accumulated stitched output.
`finished`	`bool`	True when the loop terminates.
`termination_reason`	`str`	Why the loop terminated.
`quality_anomaly`	`bool`	True if a quality anomaly was detected.
`regrounded`	`bool`	True if regrounding occurred this window.
`window_outputs`	`list[dict[str, Any]]`	Per-window raw outputs with metadata.

`ContinuationManager` ¶

Master continuation loop with 3-way termination (§4.7).

Orchestrates: trigger → gap analysis → envelope → dispatch → extract → stitch → completion check → repeat or terminate.

Termination conditions (ANY triggers stop): 1. gap_is_zero: all task requirements fulfilled 2. all_signals_dead: no completion signal is alive 3. count >= max: safety bound on continuation count

`state` `property` ¶

Current continuation loop state.

`voice_profile` `property` ¶

Extracted voice profile from the first window.

`document_map` `property` ¶

Document map showing completed vs remaining sections.

`flow_monitor` `property` ¶

Information-flow monitor.

`quality_monitor` `property` ¶

Generation quality monitor.

`degradation` `property` ¶

Chain degradation tracker.

`build_continuation_envelope(task_intent, gap_result=None, structural_state=None, last_output='')` ¶

Build a continuation envelope: directive + map + gap + style anchor (§04 §3.2).

The continuation prompt includes: 1. Explicit continuation directive (FIRST - dominant signal) 2. Document map showing completed vs remaining sections 3. Unfulfilled requirements with specific section numbers 4. Style anchor from last output 5. Key findings summary

Parameters:

Name	Type	Description	Default
`task_intent`	`str`	Original task description.	required
`gap_result`	`GapResult \| None`	Latest gap analysis result.	`None`
`structural_state`	`dict[str, object] \| None`	Structural position (section, list position, etc.).	`None`
`last_output`	`str`	Last generated output for style anchoring.	`''`

Returns:

Type	Description
`str`	Continuation envelope text.

`process_window(task_intent, output, finish_reason, output_tokens, facts, window_id='')` ¶

Process a completed window and determine next action.

This is the per-window step of the master loop. Call repeatedly until state.finished is True.

Incremental extraction: processes only this window's output (O(N) not O(N²)).

Parameters:

Name	Type	Description	Default
`task_intent`	`str`	Original task description.	required
`output`	`str`	Generated text from this window.	required
`finish_reason`	`str \| None`	Provider finish reason.	required
`output_tokens`	`int`	Number of tokens generated.	required
`facts`	`list[Fact]`	Facts extracted from this window's output.	required
`window_id`	`str`	Identifier for this window.	`''`

Returns:

Type	Description
`ContinuationState`	Updated `ContinuationState`.

`run(task_intent, dispatcher, initial_output='', initial_finish_reason=None, initial_output_tokens=0, initial_facts=None)` ¶

Full autonomous continuation loop with 3-way termination (§5G.1).

Orchestrates: trigger → gap analysis → envelope → dispatch → extract → stitch → completion check → repeat or terminate.

Parameters:

Name	Type	Description	Default
`task_intent`	`str`	Original task description.	required
`dispatcher`	`LLMDispatcher`	Callable that dispatches a prompt and returns a result.	required
`initial_output`	`str`	Output from the initial window.	`''`
`initial_finish_reason`	`str \| None`	Finish reason from the initial window.	`None`
`initial_output_tokens`	`int`	Token count from the initial window.	`0`
`initial_facts`	`list[Fact] \| None`	Facts extracted from the initial window.	`None`

Returns:

Type	Description
`ContinuationState`	Final `ContinuationState` after termination.

`reset()` ¶

Reset all continuation state for a new task.

`get_context_summary()` ¶

Return a structured summary of continuation progress.

Includes window count, key findings, gap status, and document progress. Can be injected into external prompts that need awareness of in-progress continuation state.

Returns:

Type	Description
`str`	Multi-line summary string.

`continuation.quality_monitor`¶

`crp.continuation.quality_monitor` ¶

Generation quality monitor - Q(t,w) real-time scoring (§10).

`QualityScore` `dataclass` ¶

Q(t,w) composite quality score and sub-scores.

`is_anomaly` `property` ¶

Sudden quality drop: overall < 0.2.

`QualityConfig` `dataclass` ¶

Weights for Q(t,w) sub-scores.

`GenerationQualityMonitor` ¶

Real-time Q(t,w) scoring: information density + coherence + novelty (§10).

Detects quality anomalies (sudden Q(t,w) drops) to trigger re-evaluation.

`history` `property` ¶

Return the history.

`score(text, facts_produced, window_id='')` ¶

Compute Q(t,w) for a generation window output.

`detect_anomaly()` ¶

Check if latest score is an anomaly (sudden drop).

`rolling_quality()` ¶

Rolling average Q(t,w) over last N windows.

`reset()` ¶

Clear all state.

`continuation.stitch`¶

`crp.continuation.stitch` ¶

Stitch algorithm - echo detection, content-aware stitching, validation (§4.8, §04 §3.4).

`ContentBoundary` ¶

Bases: str, Enum

Content type for boundary-aware stitching.

`StitchResult` `dataclass` ¶

Result of stitching two outputs together.

`StitchConfig` `dataclass` ¶

Configuration for the stitch algorithm.

`detect_echo(prior, continuation, config=None)` ¶

Detect echoed content at the start of continuation.

Strategy: 1. Suffix-prefix overlap (exact boundary echo) 2. LCS on last/first 2000 chars (partial echo)

`stitch_outputs(prior, continuation, config=None)` ¶

Stitch prior output with continuation output (§4.8, §04 §3.4).

Algorithm: 1. Detect echo (LCS on last/first 2000 chars, min 20 chars) 2. Remove echo from continuation start 3. Content-type-aware boundary detection 4. No-echo fallback: structural continuation, bridge insertion 5. Post-stitch validation 6. Store any trimmed fragments (never silently discard)

`stitch_many(outputs, config=None)` ¶

N-way iterative stitch for 50+ windows.

Applies pairwise stitch left-to-right, accumulating the result.

`continuation.trigger`¶

`crp.continuation.trigger` ¶

Continuation trigger - wall detection and continuation conditions (§4.2).

`TriggerConfig` `dataclass` ¶

Configuration for continuation triggering.

`TriggerResult` `dataclass` ¶

Result of continuation trigger evaluation.

`detect_wall_hit(finish_reason, output_tokens=None, max_output_tokens=None)` ¶

Detect physical context-window wall hit.

Primary: finish_reason == "length" (universal across providers). Fallback: output_tokens / max_output_tokens >= 0.95 when finish_reason unavailable.

`evaluate_continuation(*, finish_reason, output_tokens=None, max_output_tokens=None, gap_score=1.0, info_flow=1.0, continuation_count=0, config=None)` ¶

Evaluate whether continuation should proceed.

Three conditions must ALL be met (§4.2): 1. Wall hit detected (physical truncation) 2. Gap score > min_gap_score (unfulfilled requirements remain) 3. Info flow > min_info_flow (model still producing useful content) 4. continuation_count < max_continuations (safety bound)

`continuation.voice`¶

`crp.continuation.voice` ¶

Voice profile - tone, terminology, style extraction from first window (§04 §3.5.1).

`VoiceProfile` `dataclass` ¶

Captured voice characteristics from the first generation window.

`to_dict()` ¶

Serialize the voice profile to a JSON-ready dict.

`from_dict(data)` `classmethod` ¶

Create a new instance from a dictionary.

Parameters:

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

Returns:

Type	Description
`VoiceProfile`	`VoiceProfile`.

`extract_voice_profile(text)` ¶

Extract a voice profile from the first window's output (§04 §3.5.1).

crp.continuation¶

continuation¶

crp.continuation ¶

CompletionConfig dataclass ¶

CompletionDetector ¶

evaluate(text, facts_produced, tokens_consumed, structural_state=None) ¶

reset() ¶

CompletionResult dataclass ¶

CompletionSignal ¶

SignalState dataclass ¶

ChainDegradation ¶

chain_degradation property ¶

window_count property ¶

history property ¶

record(window_id, facts_expected, facts_produced, quality_score=1.0) ¶

should_reground() ¶

reground(current_facts, regrounded_facts) ¶

reset() ¶

DegradationMetrics dataclass ¶

RegroundingResult dataclass ¶

DocumentMap dataclass ¶

update(text, window_id) ¶

get_toc() ¶

progress() ¶

missing_sections(expected) ¶

to_dict() ¶

from_dict(data) classmethod ¶

HeadingEntry dataclass ¶

FlowMetrics dataclass ¶

InformationFlowMonitor ¶

sample_count property ¶

record(window_id, facts_produced, tokens_consumed, timestamp=0.0) ¶

current_rate() ¶

rolling_average() ¶

trend() ¶

is_alive() ¶

metrics() ¶

reset() ¶

ResidualTaskAnchor ¶

set_sections(sections) ¶

mark_complete(section) ¶

mark_complete_batch(sections) ¶

remaining() ¶

to_prompt_prefix(label='Still to cover') ¶

completion_fraction() ¶

is_complete() ¶

CognitiveStateObject dataclass ¶

add_tool_observation(observation) ¶

record_preventive_halt(frame) ¶

to_prompt_context(max_facts=10, max_decisions=5) ¶

preservation_score(prior) ¶

repair_from(prior) ¶

invalidate_fact(fact_id) ¶

compute_hmac(key) ¶

extend_hmac_chain(prior_hash, key) ¶

to_dict() ¶

from_dict(data) classmethod ¶

EstablishedFact dataclass ¶

Decision dataclass ¶

GoalState dataclass ¶

GoalMode ¶

ProvenanceKind ¶

GapResult dataclass ¶

is_complete property ¶

Requirement dataclass ¶

ContinuationConfig dataclass ¶

ContinuationManager ¶

state property ¶

voice_profile property ¶

document_map property ¶

flow_monitor property ¶

quality_monitor property ¶

degradation property ¶

build_continuation_envelope(task_intent, gap_result=None, structural_state=None, last_output='') ¶

process_window(task_intent, output, finish_reason, output_tokens, facts, window_id='') ¶

run(task_intent, dispatcher, initial_output='', initial_finish_reason=None, initial_output_tokens=0, initial_facts=None) ¶

reset() ¶

get_context_summary() ¶

ContinuationState dataclass ¶

DispatchResult dataclass ¶

`continuation`¶

`crp.continuation` ¶

`CompletionConfig` `dataclass` ¶

`CompletionDetector` ¶

`evaluate(text, facts_produced, tokens_consumed, structural_state=None)` ¶

`reset()` ¶

`CompletionResult` `dataclass` ¶

`CompletionSignal` ¶

`SignalState` `dataclass` ¶

`ChainDegradation` ¶

`chain_degradation` `property` ¶

`window_count` `property` ¶

`history` `property` ¶

`record(window_id, facts_expected, facts_produced, quality_score=1.0)` ¶

`should_reground()` ¶

`reground(current_facts, regrounded_facts)` ¶

`reset()` ¶

`DegradationMetrics` `dataclass` ¶

`RegroundingResult` `dataclass` ¶

`DocumentMap` `dataclass` ¶

`update(text, window_id)` ¶

`get_toc()` ¶

`progress()` ¶

`missing_sections(expected)` ¶

`to_dict()` ¶

`from_dict(data)` `classmethod` ¶

`HeadingEntry` `dataclass` ¶

`FlowMetrics` `dataclass` ¶

`InformationFlowMonitor` ¶

`sample_count` `property` ¶

`record(window_id, facts_produced, tokens_consumed, timestamp=0.0)` ¶

`current_rate()` ¶

`rolling_average()` ¶

`trend()` ¶

`is_alive()` ¶

`metrics()` ¶

`reset()` ¶

`ResidualTaskAnchor` ¶

`set_sections(sections)` ¶

`mark_complete(section)` ¶

`mark_complete_batch(sections)` ¶

`remaining()` ¶

`to_prompt_prefix(label='Still to cover')` ¶

`completion_fraction()` ¶

`is_complete()` ¶

`CognitiveStateObject` `dataclass` ¶

`add_tool_observation(observation)` ¶

`record_preventive_halt(frame)` ¶

`to_prompt_context(max_facts=10, max_decisions=5)` ¶

`preservation_score(prior)` ¶

`repair_from(prior)` ¶

`invalidate_fact(fact_id)` ¶

`compute_hmac(key)` ¶

`extend_hmac_chain(prior_hash, key)` ¶

`to_dict()` ¶

`from_dict(data)` `classmethod` ¶

`EstablishedFact` `dataclass` ¶

`Decision` `dataclass` ¶

`GoalState` `dataclass` ¶

`GoalMode` ¶

`ProvenanceKind` ¶

`GapResult` `dataclass` ¶

`is_complete` `property` ¶

`Requirement` `dataclass` ¶

`ContinuationConfig` `dataclass` ¶

`ContinuationManager` ¶

`state` `property` ¶

`voice_profile` `property` ¶

`document_map` `property` ¶

`flow_monitor` `property` ¶

`quality_monitor` `property` ¶

`degradation` `property` ¶

`build_continuation_envelope(task_intent, gap_result=None, structural_state=None, last_output='')` ¶

`process_window(task_intent, output, finish_reason, output_tokens, facts, window_id='')` ¶

`run(task_intent, dispatcher, initial_output='', initial_finish_reason=None, initial_output_tokens=0, initial_facts=None)` ¶

`reset()` ¶

`get_context_summary()` ¶

`ContinuationState` `dataclass` ¶

`DispatchResult` `dataclass` ¶

`GenerationQualityMonitor` ¶