oc_chat.registry.round.resume Namespace Reference

Functions
RoundCloseResult	resume_round (RoundContext ctx, *, bool interactive=False, Prompter|None prompter=None)
Escalation|None	_check_divergence (RoundContext ctx, *, dict[str, object] job, list[dict[str, object]] done_rows, str next_phase)
Escalation	_diverged (RoundContext ctx, *, str|None expected, str|None actual)
str|None	_text (object value)

Variables
tuple	RESUMABLE_STATUSES = ("running", "paused", "failed")

Detailed Description

Resume protocol for crashed or paused round-close jobs.

Purpose
-------
Given a round number, find the most recent resumable round-job, verify
the on-disk staging branch matches recorded state, and dispatch the next
pending step through the same executors used on the first run (OI-315).

Responsibilities
----------------
- Resolve the resumable job and compute the highest completed step.
- Verify the staging branch HEAD against known-good recorded heads.
- Emit STAGING_BRANCH_DIVERGED (empty resume_command) on real divergence.
- Re-enter the state-machine driver at the next pending step.

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - resume decisions
    L3 - head comparison details
    L4 - deep tracing

Contracts
---------
- Resume is itself idempotent; re-running after success is a no-op.
- A diverged staging branch is never auto-merged; rollback is the only path.
- Crash-after-merge (git done, DB pending) re-attempts the idempotent step.

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.round.state_machine (build_step_plan and drive_steps - re-entering the driver at the next pending step)
- oc_chat.registry.round.executors (RoundContext - the shared executor inputs)
- oc_chat.registry.round.escalation (make_escalation - the STAGING_BRANCH_DIVERGED escalation)
- oc_chat.registry.round.preflight (preflight_resume - the resume preflight check)
- oc_chat.registry.errors (PreflightFailedError - raised when the resume preflight fails)

Function Documentation

_check_divergence()

Escalation | None oc_chat.registry.round.resume._check_divergence ( RoundContext ctx, * , dict[str, object] job, list[dict[str, object]] done_rows, str next_phase )

protected

Definition at line 121 of file resume.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_diverged()

Escalation oc_chat.registry.round.resume._diverged ( RoundContext ctx, * , str | None expected, str | None actual )

protected

Definition at line 154 of file resume.py.

Here is the caller graph for this function:

_text()

str | None oc_chat.registry.round.resume._text ( object value )

protected

Definition at line 172 of file resume.py.

Here is the caller graph for this function:

resume_round()

RoundCloseResult oc_chat.registry.round.resume.resume_round	(	RoundContext	ctx,
		*	,
		bool	interactive = False,
		Prompter | None	prompter = None )

Resume the most recent resumable round-job for ``ctx.round_no``.

Definition at line 70 of file resume.py.

Here is the call graph for this function:

Variable Documentation

RESUMABLE_STATUSES

tuple oc_chat.registry.round.resume.RESUMABLE_STATUSES = ("running", "paused", "failed")

Definition at line 67 of file resume.py.