Classes
class	RegenerateError
class	SchemaError

Functions
int	exit_code_for (BaseException error)
dict[str, Any]	build_envelope (Optional[BaseException] error, *, Optional[str] raw_source_tree_hash=None, Optional[str] source_hash=None, Optional[str] logical_state_hash=None, Optional[str] message=None, Optional[str] rollback=None, Optional[str] journal_path=None, Optional[Sequence[str]] remaining_paths=None, Optional[bool] journal_unresolved=None)

Variables
str	SRC_BAD_TRACK_CODES = "SRC_BAD_TRACK_CODES"
str	SRC_DANGLING_DEPENDS_ON = "SRC_DANGLING_DEPENDS_ON"
str	SRC_BAD_DEPENDENCY_KIND = "SRC_BAD_DEPENDENCY_KIND"
str	SRC_DEPENDENCY_CYCLE = "SRC_DEPENDENCY_CYCLE"
str	SRC_SUCCESSOR_CYCLE = "SRC_SUCCESSOR_CYCLE"
str	SRC_DONE_PARENT_LIVE_CHILD = "SRC_DONE_PARENT_LIVE_CHILD"
str	SRC_DONE_MISSING_CLOSED_VERSION = "SRC_DONE_MISSING_CLOSED_VERSION"
str	SRC_NON_PHASE_HAS_PHASE = "SRC_NON_PHASE_HAS_PHASE"
str	SRC_DUPLICATE_ORDER = "SRC_DUPLICATE_ORDER"
str	SRC_DUPLICATE_CODE = "SRC_DUPLICATE_CODE"
str	SRC_DUPLICATE_RENDER_SECTION = "SRC_DUPLICATE_RENDER_SECTION"
str	SRC_LIFECYCLE_CROSSFIELD = "SRC_LIFECYCLE_CROSSFIELD"
str	SRC_EMPTY_PURPOSE = "SRC_EMPTY_PURPOSE"
str	SRC_VERSION_METADATA_CONFLICT = "SRC_VERSION_METADATA_CONFLICT"
str	SRC_ITEM_ID_COLLISION = "SRC_ITEM_ID_COLLISION"
str	SRC_ROADMAP_CHANGELOG_SEQ = "SRC_ROADMAP_CHANGELOG_SEQ"
str	SRC_PRODUCT_CHANGELOG_SEQ = "SRC_PRODUCT_CHANGELOG_SEQ"
str	SRC_FRAMING_DANGLING_ANCHOR = "SRC_FRAMING_DANGLING_ANCHOR"
str	SRC_FRAMING_DUPLICATE_ANCHOR = "SRC_FRAMING_DUPLICATE_ANCHOR"
str	SRC_TREE_DIRTY = "SRC_TREE_DIRTY"
str	SRC_TREE_NOT_VERSIONED = "SRC_TREE_NOT_VERSIONED"
str	SRC_NO_MIGRATION = "SRC_NO_MIGRATION"
str	SRC_SOURCE_MUTATED = "SRC_SOURCE_MUTATED"
str	SRC_UNSAFE_PATH = "SRC_UNSAFE_PATH"
str	SRC_MIGRATION_INVALID = "SRC_MIGRATION_INVALID"
str	SRC_MIGRATION_OUTPUT_INVALID = "SRC_MIGRATION_OUTPUT_INVALID"
str	SRC_JOURNAL_UNRESOLVED = "SRC_JOURNAL_UNRESOLVED"
str	SRC_JOURNAL_WRITE_FAILED = "SRC_JOURNAL_WRITE_FAILED"
str	SRC_MIGRATION_WRITE_FAILED = "SRC_MIGRATION_WRITE_FAILED"
str	SRC_MIGRATION_TARGET_INVALID = "SRC_MIGRATION_TARGET_INVALID"
str	SRC_LEDGER_ENTRY_INVALID = "SRC_LEDGER_ENTRY_INVALID"
str	SRC_LEDGER_BASELINE_DRIFT = "SRC_LEDGER_BASELINE_DRIFT"
str	SRC_ACTIVE_EXEMPTION_NOT_TERMINAL = "SRC_ACTIVE_EXEMPTION_NOT_TERMINAL"
str	SRC_LEDGER_HISTORY_UNAVAILABLE = "SRC_LEDGER_HISTORY_UNAVAILABLE"
str	SRC_LEDGER_REOPEN_DETECTED_NULL_CLOSE = "SRC_LEDGER_REOPEN_DETECTED_NULL_CLOSE"
str	SRC_LEDGER_LIFECYCLE_LOG_DIVERGENCE = "SRC_LEDGER_LIFECYCLE_LOG_DIVERGENCE"
str	REGEN_BUILD_FAILED = "REGEN_BUILD_FAILED"
str	REGEN_NOT_BYTE_STABLE = "REGEN_NOT_BYTE_STABLE"
str	REGEN_SCOPE_CONFLICT = "REGEN_SCOPE_CONFLICT"
str	REGEN_LOCK_HELD = "REGEN_LOCK_HELD"
str	REGEN_SOURCE_MUTATED = "REGEN_SOURCE_MUTATED"
str	REGEN_UNVERIFIED_PROJECTION = "REGEN_UNVERIFIED_PROJECTION"
str	REGEN_UNSUPPORTED_BACKEND = "REGEN_UNSUPPORTED_BACKEND"
str	SCHEMA_TOO_OLD = "SCHEMA_TOO_OLD"
str	SCHEMA_TOO_NEW = "SCHEMA_TOO_NEW"
frozenset	ALL_CODES

Detailed Description

The durable error-code enum + JSON envelope for ``regenerate`` (§10).

Purpose
-------
Define the complete, granular ``SRC_*``/``REGEN_*``/``SCHEMA_*`` code enum
(Registry Source & Storage Spec V0.22 §10 — two conditions never share a code,
AC §8.53), the ``RegenerateError``/``SchemaError`` types, and the single JSON
envelope ``{ok, code, message, records, raw_source_tree_hash, source_hash,
logical_state_hash, hint, scan_error?}`` every non-zero exit emits, plus the
exit-code mapping (§5.3).

Responsibilities
----------------
- Re-export the P1.3 ``SRC_*`` codes + add the cross-record / rebuild / schema
  codes; expose ``ALL_CODES`` (the enum-completeness anchor).
- ``build_envelope`` (success or error) + ``exit_code_for``.

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - envelope assembly
    L3 - code/exit mapping
    L4 - hash-field nullability

Contracts
---------
- ``code`` is the durable machine token, NOT the exception class name.
- The three hash fields follow the §10 stage nullability (via P1.3 stage_hashes).

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.source.errors (the P1.3 SourceError hierarchy + SRC_* codes)

Function Documentation

◆ build_envelope()

dict[str, Any] oc_chat.registry.regenerate.envelope.build_envelope	(	Optional[BaseException]	error,
		*	,
		Optional[str]	raw_source_tree_hash = None,
		Optional[str]	source_hash = None,
		Optional[str]	logical_state_hash = None,
		Optional[str]	message = None,
		Optional[str]	rollback = None,
		Optional[str]	journal_path = None,
		Optional[Sequence[str]]	remaining_paths = None,
		Optional[bool]	journal_unresolved = None )

Assemble the §10 JSON envelope for a success (``error=None``) or failure.

The migrate (Plan 142m) recovery fields ``rollback`` / ``journal_path`` /
``remaining_paths`` / ``journal_unresolved`` are **additive keyword
arguments** (Sonnet5-R02-P1 / DeepSeek-R03-NP1-3 Option B): each is emitted
into the envelope **only when non-``None``** (``journal_unresolved`` only when
``True``), so a non-migrate caller — which never passes them — sees a
byte-identical envelope to before. They describe the recovery *attempt* and
are passed explicitly by the migrate runner (NOT ``getattr``-read off the
exception, which carries only the error condition).

Definition at line 235 of file envelope.py.

◆ exit_code_for()

int oc_chat.registry.regenerate.envelope.exit_code_for ( BaseException error )

Map an exception to the §5.3 exit code.

Definition at line 223 of file envelope.py.

Variable Documentation

◆ ALL_CODES

frozenset oc_chat.registry.regenerate.envelope.ALL_CODES

Initial value:

=  frozenset(
    {
        SRC_SCAN_FAILED, SRC_UNKNOWN_FILE, SRC_BAD_PHASE_PATH, SRC_BAD_YAML,
        SRC_BAD_YAML_FEATURE, SRC_STRICT_TYPE, SRC_NOT_CANONICAL,
        SRC_DUP_OR_STEM_MISMATCH, SRC_BAD_TRACK_CODES, SRC_DANGLING_DEPENDS_ON,
        SRC_BAD_DEPENDENCY_KIND, SRC_DEPENDENCY_CYCLE, SRC_SUCCESSOR_CYCLE,
        SRC_DONE_PARENT_LIVE_CHILD, SRC_DONE_MISSING_CLOSED_VERSION,
        SRC_LEDGER_ENTRY_INVALID, SRC_LEDGER_BASELINE_DRIFT,
        SRC_ACTIVE_EXEMPTION_NOT_TERMINAL, SRC_LEDGER_HISTORY_UNAVAILABLE,
        SRC_LEDGER_REOPEN_DETECTED_NULL_CLOSE, SRC_LEDGER_LIFECYCLE_LOG_DIVERGENCE,
        SRC_NON_PHASE_HAS_PHASE, SRC_DUPLICATE_ORDER, SRC_DUPLICATE_CODE,
        SRC_DUPLICATE_RENDER_SECTION, SRC_LIFECYCLE_CROSSFIELD, SRC_EMPTY_PURPOSE,
        SRC_VERSION_METADATA_CONFLICT, SRC_BAD_QUERY_PARAMS, SRC_ITEM_ID_COLLISION,
        SRC_ROADMAP_CHANGELOG_SEQ, SRC_PRODUCT_CHANGELOG_SEQ,
        SRC_FRAMING_DANGLING_ANCHOR, SRC_FRAMING_DUPLICATE_ANCHOR, SRC_TREE_DIRTY,
        SRC_TREE_NOT_VERSIONED, SRC_NO_MIGRATION, SRC_SOURCE_MUTATED,
        SRC_UNSAFE_PATH, SRC_MIGRATION_INVALID, SRC_MIGRATION_OUTPUT_INVALID,
        SRC_JOURNAL_UNRESOLVED, SRC_JOURNAL_WRITE_FAILED,
        SRC_MIGRATION_WRITE_FAILED, SRC_MIGRATION_TARGET_INVALID,
        REGEN_BUILD_FAILED, REGEN_NOT_BYTE_STABLE, REGEN_SCOPE_CONFLICT,
        REGEN_LOCK_HELD, REGEN_SOURCE_MUTATED, REGEN_UNVERIFIED_PROJECTION,
        REGEN_UNSUPPORTED_BACKEND, SCHEMA_TOO_OLD, SCHEMA_TOO_NEW,
    }
)

Definition at line 139 of file envelope.py.

◆ REGEN_BUILD_FAILED

str oc_chat.registry.regenerate.envelope.REGEN_BUILD_FAILED = "REGEN_BUILD_FAILED"

Definition at line 124 of file envelope.py.

◆ REGEN_LOCK_HELD

str oc_chat.registry.regenerate.envelope.REGEN_LOCK_HELD = "REGEN_LOCK_HELD"

Definition at line 127 of file envelope.py.

◆ REGEN_NOT_BYTE_STABLE

str oc_chat.registry.regenerate.envelope.REGEN_NOT_BYTE_STABLE = "REGEN_NOT_BYTE_STABLE"

Definition at line 125 of file envelope.py.

◆ REGEN_SCOPE_CONFLICT

str oc_chat.registry.regenerate.envelope.REGEN_SCOPE_CONFLICT = "REGEN_SCOPE_CONFLICT"

Definition at line 126 of file envelope.py.

◆ REGEN_SOURCE_MUTATED

str oc_chat.registry.regenerate.envelope.REGEN_SOURCE_MUTATED = "REGEN_SOURCE_MUTATED"

Definition at line 132 of file envelope.py.

◆ REGEN_UNSUPPORTED_BACKEND

str oc_chat.registry.regenerate.envelope.REGEN_UNSUPPORTED_BACKEND = "REGEN_UNSUPPORTED_BACKEND"

Definition at line 134 of file envelope.py.

◆ REGEN_UNVERIFIED_PROJECTION

str oc_chat.registry.regenerate.envelope.REGEN_UNVERIFIED_PROJECTION = "REGEN_UNVERIFIED_PROJECTION"

Definition at line 133 of file envelope.py.

◆ SCHEMA_TOO_NEW

str oc_chat.registry.regenerate.envelope.SCHEMA_TOO_NEW = "SCHEMA_TOO_NEW"

Definition at line 136 of file envelope.py.

◆ SCHEMA_TOO_OLD

str oc_chat.registry.regenerate.envelope.SCHEMA_TOO_OLD = "SCHEMA_TOO_OLD"

Definition at line 135 of file envelope.py.

◆ SRC_ACTIVE_EXEMPTION_NOT_TERMINAL

str oc_chat.registry.regenerate.envelope.SRC_ACTIVE_EXEMPTION_NOT_TERMINAL = "SRC_ACTIVE_EXEMPTION_NOT_TERMINAL"

Definition at line 118 of file envelope.py.

◆ SRC_BAD_DEPENDENCY_KIND

str oc_chat.registry.regenerate.envelope.SRC_BAD_DEPENDENCY_KIND = "SRC_BAD_DEPENDENCY_KIND"

Definition at line 69 of file envelope.py.

◆ SRC_BAD_TRACK_CODES

str oc_chat.registry.regenerate.envelope.SRC_BAD_TRACK_CODES = "SRC_BAD_TRACK_CODES"

Definition at line 67 of file envelope.py.

◆ SRC_DANGLING_DEPENDS_ON

str oc_chat.registry.regenerate.envelope.SRC_DANGLING_DEPENDS_ON = "SRC_DANGLING_DEPENDS_ON"

Definition at line 68 of file envelope.py.

◆ SRC_DEPENDENCY_CYCLE

str oc_chat.registry.regenerate.envelope.SRC_DEPENDENCY_CYCLE = "SRC_DEPENDENCY_CYCLE"

Definition at line 70 of file envelope.py.

◆ SRC_DONE_MISSING_CLOSED_VERSION

str oc_chat.registry.regenerate.envelope.SRC_DONE_MISSING_CLOSED_VERSION = "SRC_DONE_MISSING_CLOSED_VERSION"

Definition at line 73 of file envelope.py.

◆ SRC_DONE_PARENT_LIVE_CHILD

str oc_chat.registry.regenerate.envelope.SRC_DONE_PARENT_LIVE_CHILD = "SRC_DONE_PARENT_LIVE_CHILD"

Definition at line 72 of file envelope.py.

◆ SRC_DUPLICATE_CODE

str oc_chat.registry.regenerate.envelope.SRC_DUPLICATE_CODE = "SRC_DUPLICATE_CODE"

Definition at line 76 of file envelope.py.

◆ SRC_DUPLICATE_ORDER

str oc_chat.registry.regenerate.envelope.SRC_DUPLICATE_ORDER = "SRC_DUPLICATE_ORDER"

Definition at line 75 of file envelope.py.

◆ SRC_DUPLICATE_RENDER_SECTION

str oc_chat.registry.regenerate.envelope.SRC_DUPLICATE_RENDER_SECTION = "SRC_DUPLICATE_RENDER_SECTION"

Definition at line 77 of file envelope.py.

◆ SRC_EMPTY_PURPOSE

str oc_chat.registry.regenerate.envelope.SRC_EMPTY_PURPOSE = "SRC_EMPTY_PURPOSE"

Definition at line 79 of file envelope.py.

◆ SRC_FRAMING_DANGLING_ANCHOR

str oc_chat.registry.regenerate.envelope.SRC_FRAMING_DANGLING_ANCHOR = "SRC_FRAMING_DANGLING_ANCHOR"

Definition at line 92 of file envelope.py.

◆ SRC_FRAMING_DUPLICATE_ANCHOR

str oc_chat.registry.regenerate.envelope.SRC_FRAMING_DUPLICATE_ANCHOR = "SRC_FRAMING_DUPLICATE_ANCHOR"

Definition at line 93 of file envelope.py.

◆ SRC_ITEM_ID_COLLISION

str oc_chat.registry.regenerate.envelope.SRC_ITEM_ID_COLLISION = "SRC_ITEM_ID_COLLISION"

Definition at line 81 of file envelope.py.

◆ SRC_JOURNAL_UNRESOLVED

str oc_chat.registry.regenerate.envelope.SRC_JOURNAL_UNRESOLVED = "SRC_JOURNAL_UNRESOLVED"

Definition at line 111 of file envelope.py.

◆ SRC_JOURNAL_WRITE_FAILED

str oc_chat.registry.regenerate.envelope.SRC_JOURNAL_WRITE_FAILED = "SRC_JOURNAL_WRITE_FAILED"

Definition at line 112 of file envelope.py.

◆ SRC_LEDGER_BASELINE_DRIFT

str oc_chat.registry.regenerate.envelope.SRC_LEDGER_BASELINE_DRIFT = "SRC_LEDGER_BASELINE_DRIFT"

Definition at line 117 of file envelope.py.

◆ SRC_LEDGER_ENTRY_INVALID

str oc_chat.registry.regenerate.envelope.SRC_LEDGER_ENTRY_INVALID = "SRC_LEDGER_ENTRY_INVALID"

Definition at line 116 of file envelope.py.

◆ SRC_LEDGER_HISTORY_UNAVAILABLE

str oc_chat.registry.regenerate.envelope.SRC_LEDGER_HISTORY_UNAVAILABLE = "SRC_LEDGER_HISTORY_UNAVAILABLE"

Definition at line 119 of file envelope.py.

◆ SRC_LEDGER_LIFECYCLE_LOG_DIVERGENCE

str oc_chat.registry.regenerate.envelope.SRC_LEDGER_LIFECYCLE_LOG_DIVERGENCE = "SRC_LEDGER_LIFECYCLE_LOG_DIVERGENCE"

Definition at line 121 of file envelope.py.

◆ SRC_LEDGER_REOPEN_DETECTED_NULL_CLOSE

str oc_chat.registry.regenerate.envelope.SRC_LEDGER_REOPEN_DETECTED_NULL_CLOSE = "SRC_LEDGER_REOPEN_DETECTED_NULL_CLOSE"

Definition at line 120 of file envelope.py.

◆ SRC_LIFECYCLE_CROSSFIELD

str oc_chat.registry.regenerate.envelope.SRC_LIFECYCLE_CROSSFIELD = "SRC_LIFECYCLE_CROSSFIELD"

Definition at line 78 of file envelope.py.

◆ SRC_MIGRATION_INVALID

str oc_chat.registry.regenerate.envelope.SRC_MIGRATION_INVALID = "SRC_MIGRATION_INVALID"

Definition at line 109 of file envelope.py.

◆ SRC_MIGRATION_OUTPUT_INVALID

str oc_chat.registry.regenerate.envelope.SRC_MIGRATION_OUTPUT_INVALID = "SRC_MIGRATION_OUTPUT_INVALID"

Definition at line 110 of file envelope.py.

◆ SRC_MIGRATION_TARGET_INVALID

str oc_chat.registry.regenerate.envelope.SRC_MIGRATION_TARGET_INVALID = "SRC_MIGRATION_TARGET_INVALID"

Definition at line 114 of file envelope.py.

◆ SRC_MIGRATION_WRITE_FAILED

str oc_chat.registry.regenerate.envelope.SRC_MIGRATION_WRITE_FAILED = "SRC_MIGRATION_WRITE_FAILED"

Definition at line 113 of file envelope.py.

◆ SRC_NO_MIGRATION

str oc_chat.registry.regenerate.envelope.SRC_NO_MIGRATION = "SRC_NO_MIGRATION"

Definition at line 106 of file envelope.py.

◆ SRC_NON_PHASE_HAS_PHASE

str oc_chat.registry.regenerate.envelope.SRC_NON_PHASE_HAS_PHASE = "SRC_NON_PHASE_HAS_PHASE"

Definition at line 74 of file envelope.py.

◆ SRC_PRODUCT_CHANGELOG_SEQ

str oc_chat.registry.regenerate.envelope.SRC_PRODUCT_CHANGELOG_SEQ = "SRC_PRODUCT_CHANGELOG_SEQ"

Definition at line 88 of file envelope.py.

◆ SRC_ROADMAP_CHANGELOG_SEQ

str oc_chat.registry.regenerate.envelope.SRC_ROADMAP_CHANGELOG_SEQ = "SRC_ROADMAP_CHANGELOG_SEQ"

Definition at line 84 of file envelope.py.

◆ SRC_SOURCE_MUTATED

str oc_chat.registry.regenerate.envelope.SRC_SOURCE_MUTATED = "SRC_SOURCE_MUTATED"

Definition at line 107 of file envelope.py.

◆ SRC_SUCCESSOR_CYCLE

str oc_chat.registry.regenerate.envelope.SRC_SUCCESSOR_CYCLE = "SRC_SUCCESSOR_CYCLE"

Definition at line 71 of file envelope.py.

◆ SRC_TREE_DIRTY

str oc_chat.registry.regenerate.envelope.SRC_TREE_DIRTY = "SRC_TREE_DIRTY"

Definition at line 100 of file envelope.py.

◆ SRC_TREE_NOT_VERSIONED

str oc_chat.registry.regenerate.envelope.SRC_TREE_NOT_VERSIONED = "SRC_TREE_NOT_VERSIONED"

Definition at line 105 of file envelope.py.

◆ SRC_UNSAFE_PATH

str oc_chat.registry.regenerate.envelope.SRC_UNSAFE_PATH = "SRC_UNSAFE_PATH"

Definition at line 108 of file envelope.py.

◆ SRC_VERSION_METADATA_CONFLICT

str oc_chat.registry.regenerate.envelope.SRC_VERSION_METADATA_CONFLICT = "SRC_VERSION_METADATA_CONFLICT"

Definition at line 80 of file envelope.py.

Classes

Functions

Variables