Classes
class	Result
class	Source

Functions
Source	_load_source (Path source_dir)
int	_seq (object model)
list[tuple[object, str]]	_ordered (dict records, list[str] slugs)
tuple[dict, dict]	_framing_maps (list framings)
str	reconstruct_roadmap (Source source, list[str] legacy_slugs, str header, str footer)
str	reconstruct_product (Source source, list[str] legacy_slugs, str header)
Result	verify (Path product_backup, Path roadmap_backup, Path source_dir)
str	_first_diff (str recon, str oracle)
None	_check_product_oracle (str raw, str canon, Result result)
str	_independent_body (str segment)
None	_check_product_profile (Source source, Result result)
int	main (list[str]\|None argv=None)

Variables
	_ROOT = Path(__file__).resolve().parents[1]
str	_SEAM = "\n\n---\n\n"
	_SEMVER_RE = re.compile(r"^v?\d+\.\d+\.\d+$")
	_ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
str	_ERA = "v3"
str	_LEGACY_SLUGS_PATH = _ROOT / "tools" / "144_legacy_content_slugs.json"

Detailed Description

The Plan-144 §9 **byte-exact reconstruction gate** (both axes) — the
destructive-op safety control (spec REGISTRY_SOURCE_AND_STORAGE_SPEC_V0_24.md §9).

Purpose
-------
Prove the Plan-144 changelog+framing migration is **lossless** before any framing
record is retired: reconstruct the *pre-migration legacy layout* of BOTH changelog
axes from the NEW store (content records + ``era.banner`` + ``framing`` entities,
with the boundary header/footer chrome pinned from the frozen oracle) and assert
**byte-equality** against the pinned frozen receipts. Retained as a pinned
regression test (spec §9 — the third losslessness proof alongside git history +
the untouched frozen archive).

This supersedes the Plan-142 product-only role (which asserted ``render(--db) ==
canonicalize(backup)``): post-Plan-144 the live render is descending + generated
framing, so it no longer reproduces the legacy layout — the *reconstruction*
(legacy-ascending, framing re-inlined at its anchors) does. The legacy content
selection is a **frozen** ordered slug list (``tools/144_legacy_content_slugs.json``)
so the gate is durable against changelog growth (new records are not in the set)
while ordering by the live ``changelog_seq`` catches a renumber regression.

Pinned oracles (never a glob — H4):
- roadmap: ``historical-archive-DO-NOT-DELETE/ROADMAP-CHANGELOG-FROZEN-2026-07-07-pre-144.md``
- product: ``historical-archive-DO-NOT-DELETE/root-CHANGELOG-FROZEN-2026-06-29-pre-product-migration.md``

The boundary chrome (roadmap ``001`` header + ``058`` footer, product ``001``
header) is version-specific prose the live render regenerates; the gate reproduces
it from the frozen oracle (the "pin as frozen constants" decision) — the migration
being proven lossless covers the *content* (the 52+64 entries) + the four roadmap
banners + the split product entry, not the regenerated chrome.

Invocation (worktree root): ``python -m tools.verify_142_product_changelog_fidelity
--backup <product-oracle> --roadmap-backup <roadmap-oracle>``; the direct
``python tools/…`` also works via the ``sys.path`` bootstrap.

Responsibilities
----------------
- ``verify(product_backup, roadmap_backup, source_dir)`` → a structured result (CI exit 0/1).

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - verification lifecycle
    L3 - per-check / per-axis results
    L4 - per-segment comparison

Contracts
---------
- Read-only over the committed source + the pinned frozen oracles; never writes.

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.regenerate (imported for the contracts bootstrap it runs)
- oc_chat.registry.source.canonical (load_record - reads the version, framing and era records)
- oc_chat.registry.source.canonical_product (split_segments, segment_line_ranges and product_changelog_canonicalize - the product oracle checks)
- oc_chat.registry.source.scanner (scan_source_tree - walks the committed source tree)

Function Documentation

◆ _check_product_oracle()

None verify_142_product_changelog_fidelity._check_product_oracle	(	str	raw,
		str	canon,
		Result	result )

protected

Independent segmentation round-trip + per-segment line-range coverage of the
product oracle (an oracle of the oracle — does NOT reuse _normalize_body).

Definition at line 264 of file verify_142_product_changelog_fidelity.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _check_product_profile()

None verify_142_product_changelog_fidelity._check_product_profile	(	Source	source,
		Result	result )

protected

Every product record: era v3, SemVer version, ISO date, empty entries,
unique positive-int changelog_seq.

Definition at line 312 of file verify_142_product_changelog_fidelity.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _first_diff()

str verify_142_product_changelog_fidelity._first_diff	(	str	recon,
		str	oracle )

protected

Definition at line 254 of file verify_142_product_changelog_fidelity.py.

Here is the caller graph for this function:

◆ _framing_maps()

tuple[dict, dict] verify_142_product_changelog_fidelity._framing_maps ( list framings )

protected

``(before_map, after_map)``: version-slug -> framings, each sorted by the
§3.3 anchor ``order`` (an unset order sorts after any set order = +∞).

Definition at line 160 of file verify_142_product_changelog_fidelity.py.

Here is the caller graph for this function:

◆ _independent_body()

str verify_142_product_changelog_fidelity._independent_body ( str segment )

protected

An INDEPENDENT re-implementation of ``canonical._normalize_body`` (F3 — a
real oracle, not X == X): CRLF/CR→LF, drop leading/trailing blank lines,
per-line trailing-whitespace strip.

Definition at line 299 of file verify_142_product_changelog_fidelity.py.

Here is the caller graph for this function:

◆ _load_source()

Source verify_142_product_changelog_fidelity._load_source ( Path source_dir )

protected

Definition at line 128 of file verify_142_product_changelog_fidelity.py.

Here is the caller graph for this function:

◆ _ordered()

list[tuple[object, str]] verify_142_product_changelog_fidelity._ordered	(	dict	records,
		list[str]	slugs )

protected

The frozen legacy content, ORDERED by the live ``changelog_seq`` (descending,
newest-first) — selection is the frozen slug set (durable), order is live (a
renumber regression re-tiles the bytes and fails the byte comparison).

Definition at line 151 of file verify_142_product_changelog_fidelity.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _seq()

int verify_142_product_changelog_fidelity._seq ( object model )

protected

Definition at line 147 of file verify_142_product_changelog_fidelity.py.

Here is the caller graph for this function:

◆ main()

int verify_142_product_changelog_fidelity.main ( list[str] | None argv = None )

CI entry point: exit 0 if all checks pass, 1 otherwise.

Definition at line 339 of file verify_142_product_changelog_fidelity.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ reconstruct_product()

str verify_142_product_changelog_fidelity.reconstruct_product	(	Source	source,
		list[str]	legacy_slugs,
		str	header )

Rebuild the legacy product-changelog body: the pinned header fused into the
first (newest) segment, then the product content tiled newest-first.

Definition at line 200 of file verify_142_product_changelog_fidelity.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ reconstruct_roadmap()

str verify_142_product_changelog_fidelity.reconstruct_roadmap	(	Source	source,
		list[str]	legacy_slugs,
		str	header,
		str	footer )

Rebuild the legacy roadmap-changelog body: pinned header, then the era
banner at each era boundary, the legacy content tiled newest-first with the
``framing`` entities re-inlined at their anchors, then the pinned footer.

Definition at line 178 of file verify_142_product_changelog_fidelity.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verify()

Result verify_142_product_changelog_fidelity.verify	(	Path	product_backup,
		Path	roadmap_backup,
		Path	source_dir )

Run the both-axes byte-exact reconstruction gate + the product profile.

Definition at line 210 of file verify_142_product_changelog_fidelity.py.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ _ERA

str verify_142_product_changelog_fidelity._ERA = "v3"

protected

Definition at line 100 of file verify_142_product_changelog_fidelity.py.

◆ _ISO_DATE_RE

verify_142_product_changelog_fidelity._ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")

protected

Definition at line 99 of file verify_142_product_changelog_fidelity.py.

◆ _LEGACY_SLUGS_PATH

str verify_142_product_changelog_fidelity._LEGACY_SLUGS_PATH = _ROOT / "tools" / "144_legacy_content_slugs.json"

protected

Definition at line 102 of file verify_142_product_changelog_fidelity.py.

◆ _ROOT

verify_142_product_changelog_fidelity._ROOT = Path(__file__).resolve().parents[1]

protected

Definition at line 80 of file verify_142_product_changelog_fidelity.py.

◆ _SEAM

str verify_142_product_changelog_fidelity._SEAM = "\n\n---\n\n"

protected

Definition at line 97 of file verify_142_product_changelog_fidelity.py.

◆ _SEMVER_RE

verify_142_product_changelog_fidelity._SEMVER_RE = re.compile(r"^v?\d+\.\d+\.\d+$")

protected

Definition at line 98 of file verify_142_product_changelog_fidelity.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _check_product_oracle()

◆ _check_product_profile()

◆ _first_diff()

◆ _framing_maps()

◆ _independent_body()

◆ _load_source()

◆ _ordered()

◆ _seq()

◆ main()

◆ reconstruct_product()

◆ reconstruct_roadmap()

◆ verify()

Variable Documentation

◆ _ERA

◆ _ISO_DATE_RE

◆ _LEGACY_SLUGS_PATH

◆ _ROOT

◆ _SEAM

◆ _SEMVER_RE