cctally 1.116.1 → 1.117.2

package/bin/_lib_rederive.py

@@ -12,14 +12,16 @@ No filesystem, SQLite, provider, alert, or journal operation belongs here.
 
 from __future__ import annotations
 
+import bisect
 import dataclasses
 import datetime as dt
 import hashlib
 import json
 import math
-from collections.abc import Iterable, Mapping
+from collections.abc import Iterable, Mapping, Sequence
 
 import _lib_accounts
+import _lib_journal
 from _lib_cost_provenance import (
     HISTORICAL_CLOSE_BASIS, RECORDED_CLOSE_CORRECTION_BASIS,
 )
@@ -82,6 +84,12 @@ _EVT_CLASSIFICATIONS = {
         "rederived", "Claude weekly reset or credit decision"),
     "five_hour_credit": KindClassification(
         "rederived", "Claude five-hour credit decision"),
+    # #943 spec 4.2.2: the exact boundary companion of a five-hour credit.
+    "five_hour_credit_boundary": KindClassification(
+        "rederived", "Claude five-hour credit boundary"),
+    # #956 spec 4.6.1: every five-hour block creation's opening fact.
+    "five_hour_block_open": KindClassification(
+        "rederived", "Claude five-hour block opening"),
     "five_hour_block_close": KindClassification(
         "rederived", "closed Claude five-hour projection"),
     "percent_milestone": KindClassification(
@@ -115,6 +123,12 @@ _EVT_CLASSIFICATIONS = {
     "meter_rate_change": KindClassification(
         "retained",
         "the metering-rate latch is replayed, never re-derived"),
+    # #1015 spec 5.7: the terminal supersession of one metering-rate
+    # transition identity. `retained` like its latch: a self-sufficient
+    # payload replayed by its own natural-key fold, never re-derived.
+    "meter_rate_change_supersession": KindClassification(
+        "retained",
+        "a transition's supersession is replayed, never re-derived"),
 }
 
 _OP_CLASSIFICATIONS = {
@@ -145,6 +159,13 @@ _OP_CLASSIFICATIONS = {
         "retained", "operator Codex window attribution is outside claude-usage"),
     "codex_window_attribution_retract": KindClassification(
         "retained", "operator Codex window retraction is outside claude-usage"),
+    # #944 spec 5.10: the durable Claude cost attribution decision. `retained`
+    # like `codex_file_account`: it is replayed by the Claude cache leg into
+    # `claude_cost_decisions`, and re-derivation reads the decided
+    # `session_entries.account_key` it materialized rather than deriving it.
+    "claude_cost_account": KindClassification(
+        "retained", "Claude cost attribution decisions are replayed by the "
+        "cache leg, never re-derived"),
     # #825/#832 spec 5.1. The versioned reviewed decision is replayed into
     # scratch exactly like its previous-release twin.
     "claude_weekly_observation_decision_v2": KindClassification(
@@ -171,6 +192,25 @@ _OP_CLASSIFICATIONS = {
         "re-derived"),
     "journal_protocol_resolution_v3": KindClassification(
         "retained", "journal-repair acknowledgements are audit records"),
+    # #1019/#1014 spec 4.7 C2, C5: the revision-3 boundary and the v4
+    # acknowledgement, likewise.
+    "account_bound_revision_v3": KindClassification(
+        "retained", "the revision-3 journal fence is replayed, never "
+        "re-derived"),
+    "journal_protocol_resolution_v4": KindClassification(
+        "retained", "journal-repair acknowledgements are audit records"),
+    # #948 spec 6.2: the outcome quarantine's recovery ops are preserved
+    # machinery. The fold replays them in journal order; nothing in the
+    # claude-usage family derives them.
+    "legacy_spool_inventory_completion": KindClassification(
+        "retained", "inventory-episode completions are replayed by the "
+        "quarantine fold, never re-derived"),
+    "outcome_authority_completion": KindClassification(
+        "retained", "authority completions are replayed by the quarantine "
+        "fold, never re-derived"),
+    "outcome_axis_release": KindClassification(
+        "retained", "axis releases are replayed by the quarantine fold, "
+        "never re-derived"),
 }
 
 
@@ -472,6 +512,73 @@ def _with_close_marker(record: Mapping, marker: Mapping) -> dict:
     return corrected
 
 
+#: The non-``total_`` members of a close's money group (#1040 spec §5.2).
+_CLOSE_MONEY_EXTRA_KEYS = frozenset({
+    "_models", "_projects", "_pricing", "pricing_provenance_json",
+})
+
+
+def _close_money_keys(payload: Mapping) -> frozenset:
+    """#1040 (spec §5.2): the keys of a close payload's money group.
+
+    Every key starting with ``total_`` plus the child sets and both pricing
+    provenance fields: the partition :func:`_preserve_non_derivable_state`
+    compares the closure's non-monetary structure without.
+    """
+    return frozenset(
+        key for key in payload
+        if key in _CLOSE_MONEY_EXTRA_KEYS
+        or (isinstance(key, str) and key.startswith("total_"))
+    )
+
+
+def close_money_overlay(desired: Mapping, current: Mapping) -> dict:
+    """#1040 (spec §5.2): ``overlay(D, C)`` on whole records.
+
+    ``desired`` with ``current``'s money group: every money key of D is
+    replaced by C's, and a money key C lacks is removed.
+    """
+    desired_payload = desired.get("payload") or {}
+    current_payload = current.get("payload") or {}
+    drop = _close_money_keys(desired_payload)
+    payload = {key: value for key, value in desired_payload.items()
+               if key not in drop}
+    for key in _close_money_keys(current_payload):
+        payload[key] = current_payload[key]
+    return {**desired, "payload": payload}
+
+
+_CLOSE_POPULATION_TOTALS = (
+    "total_input_tokens", "total_output_tokens", "total_cache_create_tokens",
+    "total_cache_read_tokens",
+)
+
+
+def close_population(payload: Mapping) -> tuple:
+    """#1040 (spec §5.2): the card-independent part of a close's money group.
+
+    The four block token totals, and per ``_models`` / ``_projects`` child its
+    model or project path, account key, four token counts and entry count,
+    order-independent. Compared exactly.
+    """
+    def children(key: str, name: str) -> tuple:
+        rows = [
+            (child.get(name), child.get("account_key"),
+             *(child.get(token) for token in _BLOCK_TOKEN_KEYS),
+             child.get("entry_count"))
+            for child in payload.get(key) or ()
+            if isinstance(child, Mapping)
+        ]
+        return tuple(sorted(rows, key=lambda row: json.dumps(
+            row, sort_keys=True, default=repr)))
+
+    return (
+        tuple(payload.get(key) for key in _CLOSE_POPULATION_TOTALS),
+        children("_models", "model"),
+        children("_projects", "project_path"),
+    )
+
+
 def _preserve_non_derivable_state(
     current_record: Mapping, desired_record: Mapping, *,
     historical_marker: "Mapping | None" = None,
@@ -495,8 +602,10 @@ def _preserve_non_derivable_state(
     marker is stamped with its own basis, ``RECORDED_CLOSE_CORRECTION_BASIS``.
 
     #875: the milestones of a frozen or replaced close are decided by
-    :func:`_resolve_closed_block_milestones`, not here. This function only
-    carries a milestone's ``alerted_at`` latch.
+    :func:`_resolve_closed_block_milestones`, not here: an unchanged crossing
+    keeps its selected block cost there unless its lineage proves an earlier
+    rederive repriced it (#884). This function only carries a milestone's
+    ``alerted_at`` latch.
     """
     current_payload = current_record.get("payload") or {}
     desired_payload = desired_record.get("payload") or {}
@@ -520,6 +629,30 @@ def _preserve_non_derivable_state(
 
         if cost_structure(current_payload) == cost_structure(desired_payload):
             return current_record
+    if (
+        current_payload.get("kind") == "five_hour_block_open"
+        and desired_payload.get("kind") == "five_hour_block_open"
+        and current_record.get("at") == desired_record.get("at")
+    ):
+        # #956: the live writer stamps ``block_start_at`` in the host's zone,
+        # and a replay under another zone spells the same boundary with its
+        # own offset. An opening is immutable once written; a different
+        # spelling of the same instants is not a revision to supersede.
+        def opening_structure(payload):
+            facts = dict(payload)
+            for field in (
+                "block_start_at", "five_hour_resets_at",
+                "first_observed_at_utc", "created_at_utc",
+                "weekly_basis_captured_at_utc",
+            ):
+                instant = _iso_instant(facts.get(field))
+                if instant is not None:
+                    facts[field] = instant.isoformat()
+            return facts
+
+        if opening_structure(current_payload) == opening_structure(
+                desired_payload):
+            return current_record
     if (
         current_payload.get("kind") == "five_hour_block_close"
         and desired_payload.get("kind") == "five_hour_block_close"
@@ -533,13 +666,10 @@ def _preserve_non_derivable_state(
         # closure's non-monetary evidence first so a changed boundary or final
         # reading still reaches the normal correction path.
         def structure(payload):
+            money = _close_money_keys(payload)
             facts = {
                 key: value for key, value in payload.items()
-                if not key.startswith("total_")
-                and key not in {
-                    "_models", "_projects", "_pricing",
-                    "pricing_provenance_json",
-                }
+                if key not in money
             }
             # Live close used the display-zone offset; scratch replay writes
             # UTC. Both name one frozen boundary and must compare as an instant.
@@ -605,9 +735,9 @@ def _preserve_non_derivable_state(
                     return keep_drifted()
                 # #869 V4: record that this close was CORRECTED. The basis is
                 # provenance only: since #875 every frozen close freezes the
-                # block cost of its unchanged five-hour crossings, whatever
-                # its basis. A genuinely priced close's marker looks the same
-                # otherwise.
+                # block cost of its unchanged five-hour crossings (save a
+                # #884 history-proven restoration), whatever its basis. A
+                # genuinely priced close's marker looks the same otherwise.
                 return _with_close_marker(desired_record, {
                     **desired_pricing, "basis": RECORDED_CLOSE_CORRECTION_BASIS,
                 })
@@ -726,10 +856,967 @@ def _revived_by_this_family(selected) -> bool:
     )
 
 
+# ── #943/#956 spec 4.4: five-hour credit companions and block parents ──────
+#
+# A five-hour credit (`five_hour_credit`, `fhc`) and its exact-boundary
+# companion (`five_hour_credit_boundary`, `fhcb`) share one natural key, and
+# the companion is read only while its `credit_revision` matches the credit,
+# so a plan that acts on one without the other splits them. A five-hour
+# milestone's `block_id` is a DERIVED foreign key, resolved at fold from its
+# `(account_key, five_hour_window_key)`, so it depends on whatever
+# materializes that window's block: the opening fact (`five_hour_block_open`,
+# `fhbo`), the close fact (`five_hour_block_close`, `fhbc`), or the rebuild's
+# legacy candidate rule for an unseeded open block.
+
+_CREDIT_PAIR_KINDS = frozenset({"five_hour_credit", "five_hour_credit_boundary"})
+_BLOCK_PARENT_KINDS = frozenset({"five_hour_block_open", "five_hour_block_close"})
+_OPENING_ID_PREFIX = "fhbo:"
+
+
+def _window_of(payload: Mapping):
+    """``(account_key, int(five_hour_window_key))`` of a payload, or None."""
+    window = payload.get("five_hour_window_key")
+    if window is None or isinstance(window, bool):
+        return None
+    try:
+        return (payload.get("account_key"), int(window))
+    except (TypeError, ValueError):
+        return None
+
+
+def _credit_pair_key(payload: Mapping) -> tuple:
+    """The natural key a credit and its companion share."""
+    return (payload.get("account_key"), payload.get("five_hour_window_key"),
+            payload.get("effective_reset_at_utc"))
+
+
+def _action_payload(action, current_events: Mapping[str, Mapping]) -> Mapping:
+    """An action's payload; a tombstone's comes from its current record."""
+    if action.disposition == "tombstone":
+        return (current_events.get(action.event_id) or {}).get("payload") or {}
+    return action.payload or {}
+
+
+def _opening_window(event_id: str):
+    """The window of an `fhbo` id (``fhbo:<account_key>:<window_key>``)."""
+    if not event_id.startswith(_OPENING_ID_PREFIX):
+        return None
+    account_key, _sep, window = event_id[len(_OPENING_ID_PREFIX):].rpartition(":")
+    try:
+        return (account_key, int(window))
+    except ValueError:
+        return None
+
+
+def retired_openings_of(selection) -> frozenset:
+    """The windows whose opening fact the effective selection tombstones.
+
+    The rebuild never makes such a window a legacy open-block candidate
+    (`_cctally_journal.retired_block_openings`, spec 4.6.3)."""
+    retired = set()
+    for event_id, selected in selection.by_id.items():
+        if selected.status != "tombstone":
+            continue
+        window = _opening_window(str(event_id))
+        if window is not None:
+            retired.add(window)
+    return frozenset(retired)
+
+
+def five_hour_parent_presence(events: Mapping[str, Mapping],
+                              retired_openings=frozenset()) -> frozenset:
+    """The `(account_key, five_hour_window_key)` windows a rebuild of the
+    effective set ``events`` materializes a block for (spec 4.4, 4.6.3).
+
+    A window has a block when an opening or close fact names it, and, for
+    each account, when it is the window of the account's latest-captured
+    five-hour reading (`unixepoch(captured_at_utc) DESC, journal_id DESC`)
+    and no block of it exists and its opening was not retired: the legacy
+    candidate rule of `_cctally_five_hour._backfill_five_hour_blocks`. A
+    reading a five-hour credit's suppression names carries no five-hour
+    reading once folded (retired in place, or deleted when held), so it never
+    qualifies. A weekly suppression deletes a row that carries no five-hour
+    reading, which never qualifies, and a `record-credit` synthetic, which
+    is counted here although the fold never sees it (#943 review R-5). The
+    two differ only when that synthetic is the account's latest reading
+    and lies in another window than its next surviving reading; it copies
+    the window of the latest reading (`_resolve_prior_5h`), so that does
+    not arise in practice."""
+    present = set()
+    five_hour_suppressed = set()
+    for record in events.values():
+        payload = (record or {}).get("payload") or {}
+        kind = payload.get("kind")
+        if kind in _BLOCK_PARENT_KINDS:
+            window = _window_of(payload)
+            if window is not None:
+                present.add(window)
+        elif (kind == "five_hour_credit"
+              and payload.get("suppression_table", "weekly_usage_snapshots")
+              == "weekly_usage_snapshots"
+              and isinstance(payload.get("suppression"), list)):
+            five_hour_suppressed.update(
+                item for item in payload["suppression"]
+                if isinstance(item, str))
+    latest: dict = {}
+    for event_id, record in events.items():
+        payload = (record or {}).get("payload") or {}
+        if (payload.get("kind") != "snapshot_accept"
+                or event_id in five_hour_suppressed
+                or payload.get("five_hour_percent") is None):
+            continue
+        window = _window_of(payload)
+        instant = _iso_instant(payload.get("captured_at_utc"))
+        if window is None or instant is None:
+            continue
+        rank = (instant.timestamp() // 1, str(event_id))
+        prior = latest.get(window[0])
+        if prior is None or rank > prior[0]:
+            latest[window[0]] = (rank, window)
+    retired = frozenset(retired_openings or ())
+    for _rank, window in latest.values():
+        if window not in retired:
+            present.add(window)
+    return frozenset(present)
+
+
+def _post_plan_state(current: Mapping[str, Mapping], actions,
+                     retired_openings) -> tuple[dict, frozenset]:
+    """The effective set and the retired openings after ``actions``."""
+    after = dict(current)
+    retired = set(retired_openings or ())
+    for action in actions:
+        window = _opening_window(action.event_id)
+        if action.disposition == "tombstone":
+            after.pop(action.event_id, None)
+            if window is not None:
+                retired.add(window)
+        else:
+            after[action.event_id] = {"payload": dict(action.payload or {})}
+            if window is not None:
+                retired.discard(window)
+    return after, frozenset(retired)
+
+
+def five_hour_parent_report(current: Mapping[str, Mapping], actions,
+                            retired_openings=frozenset()):
+    """Parent validation over the resulting effective graph (spec 4.4).
+
+    Returns ``(orphaned_before, lost)``: the current five-hour milestones
+    whose window resolves no block BEFORE the plan (pre-existing damage,
+    reported, never a reason to refuse), and the milestones that resolve a
+    block before the plan and survive it without one."""
+    before = five_hour_parent_presence(current, retired_openings)
+    after_events, after_retired = _post_plan_state(
+        current, actions, retired_openings)
+    after = five_hour_parent_presence(after_events, after_retired)
+    orphaned_before = set()
+    lost = []
+    for event_id, record in sorted(current.items()):
+        payload = (record or {}).get("payload") or {}
+        if payload.get("kind") != "five_hour_milestone":
+            continue
+        if _window_of(payload) not in before:
+            orphaned_before.add(event_id)
+            continue
+        survivor = after_events.get(event_id)
+        if survivor is None:
+            continue
+        if _window_of(survivor.get("payload") or {}) not in after:
+            lost.append(event_id)
+    return frozenset(orphaned_before), lost
+
+
+def _companions_follow_kept_credits(current: Mapping[str, Mapping],
+                                    desired: dict[str, Mapping]) -> None:
+    """A credit the target keeps as its CURRENT record (a reviewed hold's
+    dependency, :func:`_preserve_reviewed_hold_dependencies`) keeps its
+    current companion with it: the companion the replay derived is bound to
+    the replay's credit content, not the one kept, and a current companion
+    with no desired twin would otherwise be tombstoned beside its credit."""
+    companions = {}
+    for source in (current, desired):
+        for event_id, record in source.items():
+            payload = (record or {}).get("payload") or {}
+            if payload.get("kind") == "five_hour_credit_boundary":
+                companions.setdefault(_credit_pair_key(payload), set()).add(
+                    event_id)
+    for event_id, record in current.items():
+        payload = (record or {}).get("payload") or {}
+        if (payload.get("kind") != "five_hour_credit"
+                or desired.get(event_id) is not record):
+            continue
+        for companion_id in companions.get(_credit_pair_key(payload), ()):
+            kept = current.get(companion_id)
+            if kept is None:
+                desired.pop(companion_id, None)
+            else:
+                desired[companion_id] = kept
+
+
+# ── #884: lineage repair of five-hour milestones an earlier rederive priced ─
+#
+# #875 freezes the block cost of an unchanged crossing under a frozen close,
+# so a later card no longer reprices it. A pre-#875 rederive may already have
+# repriced one; the freeze would then keep that later card's price for good.
+# The lineage index reads each milestone's admissible journal history beside
+# its block's close history, proves which revision last legitimately set the
+# block cost (its ANCHOR), and lets the resolver restore that amount. Any
+# ambiguity keeps the current amount and is disclosed (spec §5.1–§5.7).
+
+#: §5.2: an event's own history is uncertain.
+LINEAGE_HIDDEN_REVISION = "hidden-revision"
+LINEAGE_REVISION_GAP = "revision-gap"
+LINEAGE_DIVERGENT_REVISION = "divergent-revision"
+LINEAGE_INVALID_PAYLOAD = "invalid-payload"
+LINEAGE_ORDER_INVERSION = "order-inversion"
+LINEAGE_SELECTION_MISMATCH = "selection-mismatch"
+#: §5.3/§5.4: the walk cannot prove the anchor.
+LINEAGE_CLOSE_LINEAGE_UNCERTAIN = "close-lineage-uncertain"
+LINEAGE_CLOSE_PAIRING_UNCERTAIN = "close-pairing-uncertain"
+LINEAGE_REWRITE_WITHOUT_CLOSED_BOUNDARY = "rewrite-without-closed-boundary"
+LINEAGE_UNPAIRED_CLOSE_CHANGE = "unpaired-close-change"
+
+_LINEAGE_KINDS = frozenset({"five_hour_milestone", "five_hour_block_close"})
+
+
+@dataclasses.dataclass(frozen=True)
+class LineageOccurrence:
+    """One admissible candidate of a milestone or close, summarized (§5.1).
+
+    ``available_at`` is the journal coordinate at which it became effective:
+    a rev-0 event's own sequence, or its batch's commit sequence. Milestone
+    fields are ``None`` for a close and vice versa; a tombstone carries none.
+    ``identity`` is :func:`_milestone_identity` without ``alerted_at``.
+    ``close_view`` is an active close's canonical JSON encoding of what the
+    close timeline reads (§5.2, §5.3): ``kind``, the block key, ``is_closed``
+    and ``total_cost_usd``, each type-sensitive (``1``, ``1.0`` and ``true``
+    differ); an absent key and an explicit ``null`` encode alike.
+    """
+    rev: int
+    status: str
+    content_hash: str
+    batch_id: "str | None"
+    available_at: int
+    kind: "str | None"
+    block: "tuple | None"
+    at: object = None
+    identity: "dict | None" = None
+    block_cost_usd: object = None
+    is_closed: object = None
+    total_cost_usd: object = None
+    close_view: "bytes | None" = None
+
+
+@dataclasses.dataclass(frozen=True)
+class Restoration:
+    """One unchanged crossing's lineage answer (§5.4): ``keep``,
+    ``withhold`` (fail closed) or ``restore`` to ``value``.
+
+    ``reported`` is §5.7's predicate: a withhold counts and is disclosed only
+    when the selected crossing has a repair candidate, the revisions listed in
+    ``candidate_revisions``.
+    """
+    action: str
+    value: object = None
+    reason_codes: tuple = ()
+    candidate_revisions: tuple = ()
+    reported: bool = False
+
+
+_LINEAGE_KEEP = Restoration("keep")
+
+
+def _lineage_identity(payload: Mapping) -> dict:
+    """§5.1: a milestone's non-monetary identity without its alert latch."""
+    return {
+        key: value for key, value in payload.items()
+        if key not in _FIVE_HOUR_MILESTONE_MONETARY_KEYS
+        and key != "alerted_at"
+    }
+
+
+def _divergence_key(occurrence, *, close: bool):
+    """§5.2: what two occurrences of one revision must share to agree.
+
+    A milestone's occurrences agree only on the same ``(status,
+    content_hash)``. A close's agree on what §5.3 reads: a tombstone on its
+    status alone, an active occurrence on its status and ``close_view``
+    (compared as bytes, so no value is coerced or assumed hashable). A
+    divergence confined to a close's observation fields, weekly axes,
+    tokens, children or markers changes no close state or event (finding
+    F1, the live writer's rev-0 re-emissions).
+    """
+    if not close:
+        return (occurrence.status, occurrence.content_hash)
+    if occurrence.status != "active":
+        return (occurrence.status,)
+    return (occurrence.status, occurrence.close_view)
+
+
+def _history_uncertainty(occurrences, *, hidden: bool, invalid: bool,
+                         selected, close: bool = False) -> tuple:
+    """§5.2: the sorted reason codes of one event's own uncertain history.
+
+    ``close`` marks a close id, whose same-revision occurrences are compared
+    on the fields the close timeline reads (:func:`_divergence_key`); every
+    other code, ``selection-mismatch``'s full-hash check included, is the
+    same for both kinds.
+    """
+    codes = set()
+    if hidden:
+        codes.add(LINEAGE_HIDDEN_REVISION)
+    if invalid:
+        codes.add(LINEAGE_INVALID_PAYLOAD)
+    by_rev: dict[int, list] = {}
+    for occurrence in occurrences:
+        by_rev.setdefault(occurrence.rev, []).append(occurrence)
+    top = max(by_rev)
+    upper = top if selected is None else max(top, selected[0])
+    if any(rev not in by_rev for rev in range(upper + 1)):
+        codes.add(LINEAGE_REVISION_GAP)
+    earliest = {}
+    for rev, group in by_rev.items():
+        if len({_divergence_key(item, close=close) for item in group}) > 1:
+            codes.add(LINEAGE_DIVERGENT_REVISION)
+        earliest[rev] = min(item.available_at for item in group)
+    if any(
+        rev - 1 in earliest and earliest[rev] < earliest[rev - 1]
+        for rev in earliest
+    ):
+        codes.add(LINEAGE_ORDER_INVERSION)
+    if (
+        selected is None or selected[0] != top
+        or selected[1] not in {item.content_hash for item in by_rev[top]}
+    ):
+        codes.add(LINEAGE_SELECTION_MISMATCH)
+    return tuple(sorted(codes))
+
+
+def _first_per_revision(occurrences) -> dict:
+    """``{rev: earliest occurrence}``; ``occurrences`` are sorted."""
+    chain: dict[int, LineageOccurrence] = {}
+    for occurrence in occurrences:
+        chain.setdefault(occurrence.rev, occurrence)
+    return chain
+
+
+@dataclasses.dataclass(frozen=True)
+class FiveHourLineage:
+    """§5.1: the compact lineage of every five-hour milestone and close.
+
+    Holds summaries only, never records or the fold. ``uncertain`` maps each
+    id whose own history is uncertain (§5.2) to its reason codes.
+    ``close_ids_ever_in_block`` is a candidate index; membership at a
+    coordinate is decided from the winning payload there (§5.3).
+    """
+    milestones: Mapping[str, tuple]
+    closes: Mapping[str, tuple]
+    close_ids_ever_in_block: Mapping[tuple, tuple]
+    hidden_ids: frozenset
+    selected: Mapping[str, tuple]
+    uncertain: Mapping[str, tuple]
+    _block_timelines: dict = dataclasses.field(
+        default_factory=dict, compare=False, repr=False)
+    #: #1040: memoized journal end of the summarized occurrences.
+    _coordinate_end: list = dataclasses.field(
+        default_factory=list, compare=False, repr=False)
+
+    def _block_timeline(self, block) -> tuple:
+        """§5.3: K's close events, ``(coordinates, states, changed,
+        live_writer)``.
+
+        Only called when every close id of the block has a certain history,
+        so each id's revision becomes effective at its earliest occurrence.
+        A state is ``("ambiguous",)``, ``("absent",)``, ``("open",)`` or
+        ``("closed", total)``. ``live_writer`` marks a coordinate that only
+        rev-0 ``evt`` occurrences (no correction batch) make effective
+        (§5.4 step 3's first live-writer close).
+        """
+        cached = self._block_timelines.get(block)
+        if cached is not None:
+            return cached
+        chains = {
+            event_id: _first_per_revision(self.closes[event_id])
+            for event_id in self.close_ids_ever_in_block.get(block, ())
+        }
+        coordinates = sorted({
+            occurrence.available_at
+            for event_id in chains
+            for occurrence in self.closes[event_id]
+        })
+        states = []
+        changed = []
+        live_writer = []
+        for coordinate in coordinates:
+            counted = []
+            moved = False
+            for chain in chains.values():
+                live = [rev for rev, occurrence in chain.items()
+                        if occurrence.available_at <= coordinate]
+                if not live:
+                    continue
+                winner = chain[max(live)]
+                moved = moved or winner.available_at == coordinate
+                if winner.status == "active" and winner.block == block:
+                    counted.append(winner)
+            changed.append(moved)
+            live_writer.append(all(
+                occurrence.batch_id is None and occurrence.rev == 0
+                for event_id in chains
+                for occurrence in self.closes[event_id]
+                if occurrence.available_at == coordinate
+            ))
+            if len(counted) > 1:
+                states.append(("ambiguous",))
+            elif not counted:
+                states.append(("absent",))
+            elif counted[0].is_closed != 1:
+                states.append(("open",))
+            else:
+                states.append(("closed", counted[0].total_cost_usd))
+        timeline = (tuple(coordinates), tuple(states), tuple(changed),
+                    tuple(live_writer))
+        self._block_timelines[block] = timeline
+        return timeline
+
+    @staticmethod
+    def _closed_with_money(state) -> bool:
+        return state[0] == "closed" and _usable_amount(state[1])
+
+    @classmethod
+    def _classify(cls, before, after, changed: bool) -> str:
+        """§5.3: one close event, from K's states just before and at it."""
+        if before[0] == "ambiguous" or after[0] == "ambiguous":
+            return "uncertain"
+        if not changed:
+            return "metadata"
+        if before[0] == "closed" and after[0] == "closed":
+            if not (_usable_amount(before[1]) and _usable_amount(after[1])):
+                return "uncertain"
+            if abs(after[1] - before[1]) > _CLOSE_TOTAL_TOLERANCE_USD:
+                return "monetary"
+            return "metadata"
+        if after[0] == "closed":
+            return "monetary" if _usable_amount(after[1]) else "uncertain"
+        if before[0] == "closed":
+            return "monetary" if _usable_amount(before[1]) else "uncertain"
+        if before[0] == after[0] == "absent":
+            return "metadata"
+        return "no-boundary"
+
+    def _walk(self, chain, tail: int, selected: int, block) -> tuple:
+        """§5.4 steps 1–6 over the coordinate groups from ``tail``'s
+        coordinate inclusive. Returns ``(anchor, reasons)``."""
+        coordinates, states, changed_flags, live_writer = \
+            self._block_timeline(block)
+        start = chain[tail].available_at
+        revisions_at: dict[int, list] = {}
+        for rev in range(tail + 1, selected + 1):
+            revisions_at.setdefault(chain[rev].available_at, []).append(rev)
+        events = {}
+        # §5.4 step 3: an unpaired monetary event is exempt from the pending
+        # mark only as K's FIRST live-writer close, so whether K was ever
+        # closed before it is read over the whole timeline, before t too.
+        first_live_close = {}
+        closed_before = False
+        for index, coordinate in enumerate(coordinates):
+            before = states[index - 1] if index else ("absent",)
+            if coordinate >= start:
+                events[coordinate] = self._classify(
+                    before, states[index], changed_flags[index])
+                first_live_close[coordinate] = (
+                    live_writer[index] and not closed_before
+                    and before[0] in ("absent", "open")
+                    and states[index][0] == "closed"
+                )
+            closed_before = closed_before or states[index][0] == "closed"
+        anchor = tail
+        reasons: set = set()
+        # An unpaired monetary close event since the anchor leaves A
+        # unproven for a later price-only rewrite (findings D1, R7-1).
+        marked = False
+        for coordinate in sorted(set(revisions_at) | set(events)):
+            revisions = revisions_at.get(coordinate, [])
+            changed = any(
+                chain[rev].block_cost_usd != chain[rev - 1].block_cost_usd
+                for rev in revisions
+            )
+            event = events.get(coordinate)
+            if event == "monetary":
+                if changed:
+                    anchor = max(revisions)
+                    reasons.clear()
+                    marked = False
+                else:
+                    effective = max(
+                        rev for rev in range(tail, selected + 1)
+                        if chain[rev].available_at <= coordinate
+                    )
+                    if (chain[effective].block_cost_usd
+                            != chain[anchor].block_cost_usd):
+                        reasons.add(LINEAGE_UNPAIRED_CLOSE_CHANGE)
+                    if not first_live_close[coordinate]:
+                        marked = True
+            elif event == "uncertain":
+                reasons.add(LINEAGE_CLOSE_PAIRING_UNCERTAIN)
+            elif changed:
+                if event == "no-boundary":
+                    reasons.add(LINEAGE_REWRITE_WITHOUT_CLOSED_BOUNDARY)
+                else:
+                    # A price-only rewrite (no close event, or a metadata
+                    # one) is walked past only under a retained closed close
+                    # and with no step-3 mark pending.
+                    index = bisect.bisect_left(coordinates, coordinate)
+                    before = states[index - 1] if index else ("absent",)
+                    if not self._closed_with_money(before):
+                        reasons.add(LINEAGE_REWRITE_WITHOUT_CLOSED_BOUNDARY)
+                    if marked:
+                        reasons.add(LINEAGE_UNPAIRED_CLOSE_CHANGE)
+        return anchor, reasons
+
+    def _withhold(self, event_id: str, reasons, current_cost,
+                  anchor) -> Restoration:
+        """A fail-closed answer and §5.7's report predicate."""
+        occurrences = self.milestones[event_id]
+        selected = self.selected.get(event_id)
+        target = None
+        for occurrence in occurrences:
+            if (selected is not None and occurrence.status == "active"
+                    and (occurrence.rev, occurrence.content_hash) == selected):
+                target = occurrence
+                break
+        candidates = []
+        if target is not None:
+            by_rev: dict[int, list] = {}
+            for occurrence in occurrences:
+                by_rev.setdefault(occurrence.rev, []).append(occurrence)
+            for rev in range(max(by_rev), -1, -1):
+                if anchor is not None and rev < anchor:
+                    break
+                group = by_rev.get(rev)
+                if not group:
+                    continue  # a gap is not a boundary
+                matching = [
+                    occurrence for occurrence in group
+                    if occurrence.status == "active"
+                    and occurrence.at == target.at
+                    and occurrence.identity == target.identity
+                ]
+                if not matching:
+                    break  # a proven boundary
+                if any(
+                    _usable_amount(occurrence.block_cost_usd)
+                    and occurrence.block_cost_usd != current_cost
+                    for occurrence in matching
+                ):
+                    candidates.append(rev)
+        return Restoration(
+            "withhold",
+            reason_codes=tuple(sorted(set(reasons))),
+            candidate_revisions=tuple(sorted(candidates)),
+            reported=bool(candidates),
+        )
+
+    def restoration(self, event_id: str,
+                    current_record: Mapping) -> Restoration:
+        """§5.4: the decision for one unchanged crossing in a frozen block.
+
+        ``current_record`` is the selected record; its ``block_cost_usd`` is
+        the comparison base. In order: ``keep`` without recorded history;
+        ``withhold`` when the event's own history is uncertain; ``withhold``
+        when the walk collected a reason; ``keep`` when the anchor's amount
+        equals the current one or is unusable; else ``restore`` to the
+        anchor's parsed ``block_cost_usd``, copied as is.
+        """
+        occurrences = self.milestones.get(event_id)
+        if not occurrences:
+            return _LINEAGE_KEEP
+        current_cost = (current_record.get("payload") or {}).get(
+            "block_cost_usd")
+        own = self.uncertain.get(event_id)
+        if own:
+            return self._withhold(event_id, own, current_cost, None)
+        chain = _first_per_revision(occurrences)
+        selected = max(chain)
+        if chain[selected].status != "active":
+            return _LINEAGE_KEEP
+        life_start = 0
+        for rev in range(selected, -1, -1):
+            if chain[rev].status != "active":
+                life_start = rev + 1
+                break
+        tail = life_start
+        for rev in range(life_start + 1, selected + 1):
+            if (chain[rev].at != chain[rev - 1].at
+                    or chain[rev].identity != chain[rev - 1].identity):
+                tail = rev
+        block = chain[selected].block
+        if any(close_id in self.uncertain
+               for close_id in self.close_ids_ever_in_block.get(block, ())):
+            # §5.3: no close event of K can prove anything; A stays at t.
+            return self._withhold(
+                event_id, {LINEAGE_CLOSE_LINEAGE_UNCERTAIN}, current_cost,
+                tail)
+        anchor, reasons = self._walk(chain, tail, selected, block)
+        if reasons:
+            return self._withhold(event_id, reasons, current_cost, anchor)
+        value = chain[anchor].block_cost_usd
+        if not _usable_amount(value) or value == current_cost:
+            return _LINEAGE_KEEP
+        return Restoration("restore", value=value)
+
+    def extended(self, *, batch_id: "str | None" = None,
+                 batch_actions: Sequence[Mapping] = (),
+                 plain: Sequence[Mapping] = ()) -> "FiveHourLineage":
+        """#1040 (spec §5.4): the lineage as it reads after ``batch_actions``
+        (one completed correction batch, completion's action form) and then
+        ``plain`` (revision-0 events) are appended at the journal's end.
+
+        Read-only: a new instance with an empty timeline cache. The batch
+        becomes effective at one coordinate after every existing one, each
+        plain event at the following coordinates in order. Every candidate
+        is built and hashed by the selector's own constructors, so each
+        touched id's occurrences, selected pair (its highest revision; a tie
+        keeps the earlier occurrence) and history uncertainty are what
+        :func:`build_five_hour_lineage` reads over a journal that really
+        holds the records: a revision written above an admission-hidden id
+        stays ``hidden-revision``, one above an inert revision leaves a
+        ``revision-gap``. The close index gains every block a touched close
+        id's new occurrence names.
+        """
+        if not self._coordinate_end:
+            self._coordinate_end.append(max(
+                (occurrence.available_at
+                 for table in (self.milestones, self.closes)
+                 for items in table.values() for occurrence in items),
+                default=-1,
+            ))
+        coordinate = self._coordinate_end[0] + 1
+        added: dict[str, list] = {}
+        if batch_actions:
+            name = batch_id or "lineage-extended"
+            records = _lib_journal.make_correction_batch(
+                batch_id=name, family="lineage-extended", at="extended",
+                actions=[dict(action) for action in batch_actions])
+            for record in records[1:-1]:
+                candidate = _lib_journal._candidate_from_correction(
+                    record, coordinate)
+                added.setdefault(candidate.event_id, []).append(candidate)
+            coordinate += 1
+        for record in plain:
+            candidate = _lib_journal._candidate_from_evt(record, coordinate)
+            added.setdefault(candidate.event_id, []).append(candidate)
+            coordinate += 1
+        if not added:
+            return dataclasses.replace(
+                self, _block_timelines={}, _coordinate_end=[])
+        milestones = dict(self.milestones)
+        closes = dict(self.closes)
+        selected = dict(self.selected)
+        uncertain = dict(self.uncertain)
+        ever = {block: set(ids)
+                for block, ids in self.close_ids_ever_in_block.items()}
+        for event_id, candidates in added.items():
+            existing = list(self.closes.get(event_id)
+                            or self.milestones.get(event_id) or ())
+            identities: dict = {}
+            for occurrence in existing:
+                if occurrence.identity is not None:
+                    identities["identity"] = occurrence.identity
+            fresh = []
+            for candidate in candidates:
+                occurrence, _kind, _unhashable = _lineage_occurrence(
+                    candidate.record, rev=candidate.rev,
+                    status=candidate.status,
+                    content_hash=candidate.content_hash,
+                    batch_id=candidate.batch_id,
+                    available_at=candidate.sequence, identities=identities)
+                fresh.append(occurrence)
+            items = existing + fresh
+            kinds = {occurrence.kind for occurrence in items
+                     if occurrence.status == "active"}
+            if not existing and not (kinds & _LINEAGE_KINDS):
+                continue  # not a five-hour milestone or close
+            pair = selected.get(event_id)
+            for candidate in candidates:
+                if pair is None or candidate.rev > pair[0]:
+                    pair = (candidate.rev, candidate.content_hash)
+            selected[event_id] = pair
+            unhashable = any(
+                occurrence.status == "active"
+                and occurrence.kind == "five_hour_block_close"
+                and occurrence.block is None
+                for occurrence in items)
+            items, codes = _finalize_lineage_id(
+                event_id, items, kinds=kinds, unhashable=unhashable,
+                selected=pair, hidden=event_id in self.hidden_ids)
+            if codes:
+                uncertain[event_id] = codes
+            else:
+                uncertain.pop(event_id, None)
+            if "five_hour_block_close" in kinds:
+                closes[event_id] = items
+                for occurrence in items:
+                    if (occurrence.kind == "five_hour_block_close"
+                            and occurrence.block is not None):
+                        ever.setdefault(occurrence.block, set()).add(event_id)
+            if "five_hour_milestone" in kinds:
+                milestones[event_id] = items
+        return FiveHourLineage(
+            milestones=milestones,
+            closes=closes,
+            close_ids_ever_in_block={
+                block: tuple(sorted(ids)) for block, ids in ever.items()},
+            hidden_ids=self.hidden_ids,
+            selected=selected,
+            uncertain=uncertain,
+        )
+
+
+def _lineage_occurrence(record, *, rev: int, status: str, content_hash: str,
+                        batch_id, available_at: int, identities: dict):
+    """§5.1: one admissible candidate summarized as a :class:`LineageOccurrence`.
+
+    Returns ``(occurrence, kind, unhashable)``: ``kind`` is the active
+    payload's kind (``None`` for a tombstone or a non-object payload) and
+    ``unhashable`` marks a close whose block key indexes no block (§5.2,
+    finding D6). ``identities`` shares one identity object per run of equal
+    milestone identities of an id.
+    """
+    fields: dict = {}
+    kind = None
+    unhashable = False
+    if status == "active":
+        payload = (record or {}).get("payload")
+        kind = payload.get("kind") if isinstance(payload, dict) else None
+        if kind == "five_hour_milestone":
+            identity = _lineage_identity(payload)
+            prior = identities.get("identity")
+            if prior is not None and prior == identity:
+                identity = prior  # one shared object per run of equals
+            identities["identity"] = identity
+            fields = dict(
+                block=_five_hour_block(payload),
+                at=record.get("at"), identity=identity,
+                block_cost_usd=payload.get("block_cost_usd"),
+            )
+        elif kind == "five_hour_block_close":
+            block = _five_hour_block(payload)
+            try:
+                hash(block)
+            except TypeError:
+                # §5.2 (finding D6): a block key that indexes no block
+                # makes the id ``invalid-payload``; the plan goes on.
+                unhashable = True
+                block = None
+            fields = dict(
+                block=block,
+                is_closed=payload.get("is_closed"),
+                total_cost_usd=payload.get("total_cost_usd"),
+                close_view=_canonical_bytes([
+                    kind, payload.get("account_key"),
+                    payload.get("five_hour_window_key"),
+                    payload.get("is_closed"),
+                    payload.get("total_cost_usd"),
+                ]),
+            )
+    fields.setdefault("block", None)
+    return LineageOccurrence(
+        rev=rev, status=status, content_hash=content_hash, batch_id=batch_id,
+        available_at=available_at, kind=kind, **fields,
+    ), kind, unhashable
+
+
+def _finalize_lineage_id(event_id: str, items: list, *, kinds, unhashable: bool,
+                         selected, hidden: bool) -> tuple:
+    """§5.1/§5.2: one id's occurrences in canonical order and its own
+    history uncertainty. Sorts ``items`` in place; returns
+    ``(tuple(items), codes)``."""
+    items.sort(key=lambda item: (
+        item.rev, item.available_at, item.status, item.content_hash,
+        item.batch_id or "",
+    ))
+    codes = _history_uncertainty(
+        items, hidden=hidden,
+        invalid=len(kinds) != 1 or unhashable,
+        selected=selected,
+        close=set(kinds) == {"five_hour_block_close"},
+    )
+    return tuple(items), codes
+
+
+def build_five_hour_lineage(fold, *, selection,
+                            physical_revisions) -> FiveHourLineage:
+    """§5.1: one pass over the selector fold's admissible candidates.
+
+    ``fold`` is the :class:`SelectorFold` ``resolve_effective_events`` built
+    (its ``candidates`` hold every rev-0 event and every action of each
+    completed, untainted batch); ``physical_revisions`` maps an id to its
+    highest admission-hidden revision. Every candidate of an id some active
+    candidate places in a five-hour milestone or close is kept, identical
+    duplicates in different batches included.
+    """
+    wanted = set()
+    for candidate in fold.candidates:
+        if candidate.status == "active" and candidate.record is not None:
+            payload = candidate.record.get("payload")
+            if isinstance(payload, dict) and payload.get("kind") in \
+                    _LINEAGE_KINDS:
+                wanted.add(candidate.event_id)
+    commits: dict[str, int] = {}
+    kinds: dict[str, set] = {}
+    occurrences: dict[str, list] = {}
+    identities: dict[str, dict] = {}
+    unhashable_ids: set = set()
+    for candidate in fold.candidates:
+        event_id = candidate.event_id
+        if event_id not in wanted:
+            continue
+        if candidate.batch_id is None:
+            available_at = candidate.sequence
+        else:
+            available_at = commits.get(candidate.batch_id)
+            if available_at is None:
+                available_at = fold.markers[candidate.batch_id]["commit"][3]
+                commits[candidate.batch_id] = available_at
+        occurrence, kind, unhashable = _lineage_occurrence(
+            candidate.record, rev=candidate.rev, status=candidate.status,
+            content_hash=candidate.content_hash, batch_id=candidate.batch_id,
+            available_at=available_at,
+            identities=identities.setdefault(event_id, {}),
+        )
+        if candidate.status == "active":
+            kinds.setdefault(event_id, set()).add(kind)
+        if unhashable:
+            unhashable_ids.add(event_id)
+        occurrences.setdefault(event_id, []).append(occurrence)
+    hidden_ids = frozenset(physical_revisions or ())
+    milestones: dict[str, tuple] = {}
+    closes: dict[str, tuple] = {}
+    close_ids_ever_in_block: dict[tuple, set] = {}
+    selected: dict[str, tuple] = {}
+    uncertain: dict[str, tuple] = {}
+    for event_id, items in occurrences.items():
+        event_kinds = kinds.get(event_id, set())
+        winner = selection.by_id.get(event_id)
+        if winner is not None:
+            selected[event_id] = (winner.rev, winner.content_hash)
+        items, codes = _finalize_lineage_id(
+            event_id, items, kinds=event_kinds,
+            unhashable=event_id in unhashable_ids,
+            selected=selected.get(event_id),
+            hidden=event_id in hidden_ids,
+        )
+        if codes:
+            uncertain[event_id] = codes
+        if "five_hour_block_close" in event_kinds:
+            closes[event_id] = items
+            for item in items:
+                if (item.kind == "five_hour_block_close"
+                        and item.block is not None):
+                    close_ids_ever_in_block.setdefault(
+                        item.block, set()).add(event_id)
+        if "five_hour_milestone" in event_kinds:
+            milestones[event_id] = items
+    return FiveHourLineage(
+        milestones=milestones,
+        closes=closes,
+        close_ids_ever_in_block={
+            block: tuple(sorted(ids))
+            for block, ids in close_ids_ever_in_block.items()
+        },
+        hidden_ids=hidden_ids,
+        selected=selected,
+        uncertain=uncertain,
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class WithheldMilestone:
+    """One reported fail-closed milestone of a withheld block (§5.7)."""
+    event_id: str
+    current_revision: int
+    candidate_revisions: tuple
+    reason_codes: tuple
+
+
+@dataclasses.dataclass(frozen=True)
+class WithheldBlock:
+    """One five-hour block whose milestone repair was withheld (§5.7)."""
+    account_key: object
+    five_hour_window_key: object
+    close_event_ids: tuple
+    milestones: tuple
+
+    def to_dict(self) -> dict:
+        return {
+            "accountKey": self.account_key,
+            "fiveHourWindowKey": self.five_hour_window_key,
+            "closeEventIds": list(self.close_event_ids),
+            "milestones": [
+                {
+                    "eventId": milestone.event_id,
+                    "currentRevision": milestone.current_revision,
+                    "candidateRevisions": list(milestone.candidate_revisions),
+                    "reasonCodes": list(milestone.reason_codes),
+                }
+                for milestone in self.milestones
+            ],
+        }
+
+
+def _withheld_blocks(withheld: Mapping, current: Mapping[str, Mapping],
+                     actions, selection) -> tuple:
+    """§5.7: group reported withholds by block, sorted, with the block's
+    close ids in the plan's final state (retained, acted-on or preserved
+    records; a revival is an acted-on record)."""
+    if not withheld:
+        return ()
+    final = dict(current)
+    for action in actions:
+        if action.disposition == "tombstone":
+            final.pop(action.event_id, None)
+        else:
+            final[action.event_id] = {"payload": action.payload or {}}
+    close_ids: dict[tuple, set] = {}
+    for event_id, record in final.items():
+        payload = (record or {}).get("payload") or {}
+        if payload.get("kind") == "five_hour_block_close":
+            close_ids.setdefault(_five_hour_block(payload), set()).add(
+                event_id)
+    grouped: dict[tuple, list] = {}
+    for event_id, decision in withheld.items():
+        payload = (current.get(event_id) or {}).get("payload") or {}
+        winner = selection.by_id.get(event_id)
+        grouped.setdefault(_five_hour_block(payload), []).append(
+            WithheldMilestone(
+                event_id=event_id,
+                current_revision=None if winner is None else int(winner.rev),
+                candidate_revisions=tuple(sorted(
+                    decision.candidate_revisions)),
+                reason_codes=tuple(sorted(set(decision.reason_codes))),
+            ))
+    blocks = [
+        WithheldBlock(
+            account_key=block[0], five_hour_window_key=block[1],
+            close_event_ids=tuple(sorted(close_ids.get(block, ()))),
+            milestones=tuple(sorted(items, key=lambda item: item.event_id)),
+        )
+        for block, items in grouped.items()
+    ]
+    blocks.sort(key=lambda item: (
+        "" if item.account_key is None else str(item.account_key),
+        str(item.five_hour_window_key),
+    ))
+    return tuple(blocks)
+
+
 def _resolve_closed_block_milestones(
     current: Mapping[str, Mapping], desired: Mapping[str, Mapping],
     preserved: Mapping[str, Mapping], frozen_blocks, replaced_blocks, *,
-    selection,
+    selection, lineage: "FiveHourLineage | None" = None,
+    withheld: "dict | None" = None,
 ) -> dict[str, dict]:
     """#875: target records of the five-hour milestones of closed blocks.
 
@@ -743,6 +1830,13 @@ def _resolve_closed_block_milestones(
     and non-monetary identity are both unchanged keeps its current
     ``block_cost_usd`` across any card edit, and a crossing whose ``at`` or
     identity differs is a corrected crossing that takes replay's block cost.
+
+    #884 (spec §5.5): with ``lineage``, such an unchanged crossing instead
+    takes its history-proven anchor amount when an earlier rederive repriced
+    it (:meth:`FiveHourLineage.restoration`). When its history is ambiguous
+    it keeps the current amount, and a reported withhold is recorded in
+    ``withheld`` as ``{event_id: Restoration}``. No other role is restored,
+    and restoration never changes a block's frozen or replaced class.
     A REPLACED close is one this plan adds, or corrects so that it writes the
     close's money (it closes an open block, or its totals are unusable or
     differ by more), and every matched milestone under it is a corrected
@@ -765,13 +1859,15 @@ def _resolve_closed_block_milestones(
     crossing: replay never reproduces preserved ``b:`` predecessors, and a
     reviewed hold can remove a desired predecessor before the diff. It comes
     from the desired record for a corrected crossing or an addition. A
-    candidate keeps its whole chosen monetary pair (the current pair for an
-    unchanged crossing, the desired pair otherwise) rather than inventing a
-    value when it has no usable predecessor, or when its own threshold or
-    block cost is unusable. Only an ``int`` threshold occupies a position,
-    and only a finite amount is usable. A row whose threshold is usable but
-    whose block cost is not still occupies its threshold, so a successor
-    right above it fails closed and never skips to a lower row.
+    candidate keeps its chosen marginal (the current one for an unchanged
+    crossing, the desired one otherwise) rather than inventing a value when
+    it has no usable predecessor, or when its own threshold or block cost is
+    unusable. Its block cost is already settled and is never reset there, so
+    a restored amount survives (#884 spec §5.6). Only an ``int`` threshold
+    occupies a position, and only a finite amount is usable. A row whose
+    threshold is usable but whose block cost is not still occupies its
+    threshold, so a successor right above it fails closed and never skips to
+    a lower row.
 
     A second plan is a no-op for a block whose close it takes no action on.
     That close is frozen in the next plan, kept or preserved, whatever role
@@ -833,6 +1929,16 @@ def _resolve_closed_block_milestones(
                 payload["block_cost_usd"] = current_payload.get(
                     "block_cost_usd")
                 roles[event_id] = "unchanged"
+                if lineage is not None:
+                    # #884 (spec §5.5): a proven historical amount replaces
+                    # one an earlier rederive repriced; an ambiguous history
+                    # keeps the current amount and is disclosed.
+                    decision = lineage.restoration(event_id, current_record)
+                    if decision.action == "restore":
+                        payload["block_cost_usd"] = decision.value
+                    elif (decision.action == "withhold" and decision.reported
+                          and withheld is not None):
+                        withheld[event_id] = decision
             else:
                 roles[event_id] = "corrected"
             record = {**carried, "payload": payload}
@@ -891,7 +1997,8 @@ def _resolve_closed_block_milestones(
         ):
             prior = predecessor_cost(payload)
         if prior is None:
-            payload["block_cost_usd"] = chosen.get("block_cost_usd")
+            # #884 (spec §5.6): only the marginal falls back. The block cost
+            # is already the chosen record's, or a restored amount.
             payload["marginal_cost_usd"] = chosen.get("marginal_cost_usd")
             continue
         value = float(payload["block_cost_usd"]) - float(prior)
@@ -907,6 +2014,769 @@ def _resolve_closed_block_milestones(
     return resolved
 
 
+# ── #1040: derivation completion keeps closed five-hour money frozen ───────
+#
+# Derivation completion journals, for every id the gap acts on (its with-gap
+# and without-gap candidates differ), the with-gap candidate. For a closed
+# five-hour block that candidate carries the money the scratch replay
+# computed at the binary's CURRENT card, so a metadata-only gap repriced the
+# frozen block (spec §1–§3). The rules below decide what completion appends
+# for the closes and milestones of every touched block instead (spec §5).
+
+COMPLETION_FROZEN = "FROZEN"
+COMPLETION_REPLACED = "REPLACED"
+COMPLETION_ADDED = "ADDED"
+COMPLETION_OPEN = "OPEN"
+
+
+@dataclasses.dataclass(frozen=True)
+class CompletionClose:
+    """#1040 (spec §5.2): one close's proposed target and class.
+
+    ``target`` is T (``None`` keeps nothing to append, or a tombstone on the
+    OPEN path); ``frozen_form`` is T₀, defined for a close whose retained and
+    with-gap records are both closed, else ``None``.
+    """
+    block_class: str
+    target: "Mapping | None"
+    frozen_form: "Mapping | None" = None
+
+
+def _closed_record(record: "Mapping | None") -> bool:
+    return (record is not None
+            and (record.get("payload") or {}).get("is_closed") == 1)
+
+
+def _total_moves(before: "Mapping", after: "Mapping") -> bool:
+    """Both totals usable and more than 1e-9 USD apart."""
+    left = (before.get("payload") or {}).get("total_cost_usd")
+    right = (after.get("payload") or {}).get("total_cost_usd")
+    return (_usable_amount(left) and _usable_amount(right)
+            and abs(right - left) > _CLOSE_TOTAL_TOLERANCE_USD)
+
+
+def _is_missing_card_correction(preserved, current, desired) -> bool:
+    """§5.2: a preserved result that is neither D nor C and moves C's total.
+
+    ``_with_close_marker`` builds a #869 missing-card correction as a new
+    record under the same structure, so identity tells it apart from a kept
+    (``current``) or structurally different (``desired``) result.
+    """
+    return (preserved is not current and preserved is not desired
+            and _total_moves(current, preserved))
+
+
+def classify_completion_close(
+    current: "Mapping | None", desired: "Mapping | None",
+    reference: "Mapping | None", *, acted: bool, has_physical: bool,
+    several_close_ids: bool,
+) -> CompletionClose:
+    """#1040 (spec §5.2): the proposed close target T and the block class.
+
+    ``current`` is C (the selected active close, or ``None``), ``desired`` D
+    and ``reference`` R. The rules apply in order:
+
+    1. not acted on: T = C, FROZEN when C is closed, else OPEN;
+    2. D absent or not closed, or C present and not closed: OPEN (today's
+       path; no closed money exists to keep). OPEN is this close's class:
+       the block is OPEN only when every close of it is (spec §5.2 rule 2,
+       "no closed close in the final state");
+    3. D closed, no C: ADDED (plain revision 0) without a physical revision,
+       else a REPLACED revival;
+    4. C and D closed: T₀ first (``overlay(D, C)`` when preservation returns
+       D, else C), then 4.1 a gap-caused population change, 4.2 a #869
+       missing-card correction P, 4.3 the same-round P₂ = preserve(T₀, D),
+       4.4 FROZEN with T = T₀.
+
+    A block naming several close ids is never REPLACED: rules 4.1–4.3 yield
+    T₀ and FROZEN, and a revival proposes D under FROZEN, whose lineage check
+    decides whether it can land.
+    """
+    if not acted:
+        return CompletionClose(
+            COMPLETION_FROZEN if _closed_record(current) else COMPLETION_OPEN,
+            current)
+    if not _closed_record(desired) or (
+            current is not None and not _closed_record(current)):
+        return CompletionClose(COMPLETION_OPEN, desired)
+    if current is None:
+        if not has_physical:
+            return CompletionClose(COMPLETION_ADDED, desired)
+        if several_close_ids:
+            return CompletionClose(COMPLETION_FROZEN, desired)
+        return CompletionClose(COMPLETION_REPLACED, desired)
+    preserved = _preserve_non_derivable_state(current, desired)
+    frozen = (close_money_overlay(desired, current)
+              if preserved is desired else current)
+    if several_close_ids:
+        return CompletionClose(COMPLETION_FROZEN, frozen, frozen)
+    current_payload = current.get("payload") or {}
+    desired_payload = desired.get("payload") or {}
+    if (
+        _closed_record(reference)
+        and _usable_amount(current_payload.get("total_cost_usd"))
+        and _usable_amount(desired_payload.get("total_cost_usd"))
+        and close_population(current_payload)
+        == close_population(reference.get("payload") or {})
+        and close_population(desired_payload)
+        != close_population(current_payload)
+        and _total_moves(current, desired)
+    ):
+        return CompletionClose(COMPLETION_REPLACED, desired, frozen)
+    if _is_missing_card_correction(preserved, current, desired):
+        return CompletionClose(COMPLETION_REPLACED, preserved, frozen)
+    if _semantic_event(frozen) != _semantic_event(current):
+        second = _preserve_non_derivable_state(frozen, desired)
+        if _is_missing_card_correction(second, frozen, desired):
+            return CompletionClose(COMPLETION_REPLACED, second, frozen)
+    return CompletionClose(COMPLETION_FROZEN, frozen, frozen)
+
+#: The milestone fields a FROZEN or ADDED block's acted crossing keeps from
+#: its retained record (spec §5.3): its money and the block tokens it was
+#: priced from.
+_COMPLETION_MILESTONE_KEPT_KEYS = (
+    "block_cost_usd", "marginal_cost_usd",
+    *(f"block_{key}" for key in _BLOCK_TOKEN_KEYS),
+)
+
+COMPLETION_TREATMENTS = ("frozen", "replaced", "marginal", "none", "main")
+
+
+def _milestone_overlay(desired: Mapping, current: Mapping) -> dict:
+    """D with C's money and block tokens (a key C lacks is removed)."""
+    payload = dict(desired.get("payload") or {})
+    current_payload = current.get("payload") or {}
+    for key in _COMPLETION_MILESTONE_KEPT_KEYS:
+        if key in current_payload:
+            payload[key] = current_payload[key]
+        else:
+            payload.pop(key, None)
+    return {**desired, "payload": payload}
+
+
+def completion_block_milestones(
+    *, treatment: str, block_class: str, current: Mapping[str, Mapping],
+    with_gap: Mapping[str, Mapping], acted: frozenset, retired: frozenset,
+    lineage: FiveHourLineage, selection,
+    fixed: "Mapping[str, Mapping] | None" = None,
+) -> dict[str, dict]:
+    """#1040 (spec §5.3, §5.4): one block's milestone targets.
+
+    ``current`` holds the block's selected active milestones (the whole
+    journal's, so predecessors before a trusted frontier are included) and
+    ``with_gap`` the block's with-gap milestone candidates. ``retired`` are
+    the acted milestones with a retained record and no with-gap one: today's
+    path tombstones them, so they are no predecessor in any final chain.
+    ``fixed`` are records of ids the planner does not own that today's path
+    leaves in this block: they stand in the final chain as given and are
+    never returned. Returns every resolved record that differs semantically
+    from its retained record or has none.
+
+    A **required addition** is an acted with-gap id absent from
+    ``selection.by_id`` (spec §5.4): no admitted decision, active or
+    tombstoned, answers it. An acted with-gap id without C that the
+    selection does know (a tombstoned milestone, revived) is an optional
+    rewrite. ``treatment``:
+
+    * ``"frozen"``: an acted crossing with C takes D with C's money and
+      block tokens; when that is a corrected crossing (its ``at`` or
+      identity differs) its block cost is the lineage's restoration value
+      when :meth:`FiveHourLineage.restoration` says ``restore``. An acted id
+      without C takes D (required or revived), every other id C.
+    * ``"replaced"`` (REPLACED blocks only): an id the with-gap replay
+      carries takes D, acted or not; a current id it does not carry takes C.
+    * ``"marginal"``: every existing id keeps C; required additions take D;
+      only the marginals are resolved over the final chain.
+    * ``"none"``: the required additions alone, their marginals resolved
+      over the chain whose existing ids are C.
+    * ``"main"``: each acted id's record as today's completion path appends
+      it (``_preserve_non_derivable_state(C, D)``, or D), nothing else and
+      no marginal resolution.
+
+    The kernel is :func:`_resolve_closed_block_milestones` with the block
+    FROZEN (``replaced`` treatment: REPLACED) and no lineage.
+    """
+    if treatment not in COMPLETION_TREATMENTS:
+        raise ValueError(f"unknown milestone treatment {treatment!r}")
+    if treatment == "replaced" and block_class != COMPLETION_REPLACED:
+        raise ValueError("the replaced treatment needs a REPLACED block")
+    fixed = dict(fixed or {})
+    if treatment == "main":
+        out = {}
+        for event_id in sorted(acted & set(with_gap)):
+            desired = with_gap[event_id]
+            existing = current.get(event_id)
+            record = (desired if existing is None
+                      else _preserve_non_derivable_state(existing, desired))
+            if existing is None or (_semantic_event(record)
+                                    != _semantic_event(existing)):
+                out[event_id] = dict(record)
+        return out
+    desired: dict[str, Mapping] = {}
+    for event_id, existing in current.items():
+        if event_id in retired:
+            continue
+        candidate = with_gap.get(event_id)
+        if treatment == "replaced" and candidate is not None:
+            desired[event_id] = candidate
+        elif (treatment == "frozen" and candidate is not None
+              and event_id in acted):
+            record = _milestone_overlay(candidate, existing)
+            existing_payload = existing.get("payload") or {}
+            if (record.get("at") != existing.get("at")
+                    or _lineage_identity(record["payload"])
+                    != _lineage_identity(existing_payload)):
+                decision = lineage.restoration(event_id, existing)
+                if decision.action == "restore":
+                    record["payload"]["block_cost_usd"] = decision.value
+            desired[event_id] = record
+        else:
+            desired[event_id] = existing
+    required = set()
+    for event_id, candidate in with_gap.items():
+        if event_id in current or event_id not in acted:
+            continue
+        if event_id not in selection.by_id:
+            required.add(event_id)
+        elif treatment in ("marginal", "none"):
+            continue  # an optional revival: only F, K and R rewrite
+        desired[event_id] = candidate
+    desired.update(fixed)
+    if not desired:
+        return {}
+    block = _five_hour_block(
+        (next(iter(desired.values())).get("payload") or {}))
+    replaced = treatment == "replaced"
+    resolved = _resolve_closed_block_milestones(
+        # A fixed record is today's: it stands in the chain at its own money.
+        {event_id: record for event_id, record in current.items()
+         if event_id not in fixed},
+        desired, {},
+        frozenset() if replaced else frozenset({block}),
+        frozenset({block}) if replaced else frozenset(),
+        selection=selection, lineage=None,
+    )
+    out = {}
+    for event_id in sorted(resolved):
+        if event_id in fixed:
+            continue
+        if treatment == "none" and event_id not in required:
+            continue
+        existing = current.get(event_id)
+        record = resolved[event_id]
+        if existing is None or (_semantic_event(record)
+                                != _semantic_event(existing)):
+            out[event_id] = record
+    return out
+
+@dataclasses.dataclass(frozen=True)
+class BlockDecision:
+    """#1040 (spec §5.4): one touched block's lineage-checked decision.
+
+    ``landed`` names the candidate whose records land (``"class"``, ``"F"``,
+    ``"P"``, ``"K"``, ``"M"`` or ``"A"``); ``violations`` maps every
+    candidate the decision simulated to its violation keys.
+    """
+    block: tuple
+    block_class: str
+    component: tuple
+    landed: str
+    violations: Mapping[str, frozenset]
+
+
+@dataclasses.dataclass(frozen=True)
+class CompletionFiveHourPlan:
+    """#1040: what derivation completion appends for touched blocks.
+
+    ``targets`` maps an id to the record to append (each differs from its
+    retained record or has none); ``handled`` are the five-hour ids whose
+    every record lies in a decided block, retirements and the acted closes
+    left to today's path excluded, which today's per-id path must not append
+    again (``targets`` is a subset); ``decisions`` are sorted by block.
+    """
+    targets: Mapping[str, Mapping]
+    handled: frozenset
+    decisions: tuple
+
+
+#: §5.4: the candidates of each block class, in decision order.
+_COMPLETION_CANDIDATE_ORDER = {
+    COMPLETION_FROZEN: ("class", "K", "M", "A"),
+    COMPLETION_REPLACED: ("class", "F", "K", "M", "A"),
+    COMPLETION_ADDED: ("class", "P", "M", "A"),
+}
+#: §5.4: each later candidate's milestone treatment.
+_COMPLETION_CANDIDATE_TREATMENT = {
+    "F": "frozen", "P": "main", "K": "frozen", "M": "marginal", "A": "none",
+}
+_RESTORATION_RANK = {"keep": 0, "restore": 1, "withhold": 2}
+
+
+def _selected_milestone_view(lineage: FiveHourLineage, event_id: str) -> dict:
+    """The selected active occurrence's block cost, as the record
+    :meth:`FiveHourLineage.restoration` reads (``{}`` when there is none)."""
+    pair = lineage.selected.get(event_id)
+    for occurrence in lineage.milestones.get(event_id, ()):
+        if (pair is not None and occurrence.status == "active"
+                and (occurrence.rev, occurrence.content_hash) == pair):
+            return {"payload": {"block_cost_usd": occurrence.block_cost_usd}}
+    return {"payload": {}}
+
+
+def _violation_keys(before: FiveHourLineage, after: FiveHourLineage,
+                    milestone_ids, records: Mapping[str, Mapping]) -> frozenset:
+    """#1040 (spec §5.4): how a candidate makes #884 decisions worse.
+
+    For each milestone, its decision in ``after`` against its decision in
+    ``before``; a milestone ``before`` does not know counts as ``keep`` with
+    no reason. ``records`` are the candidate's records by id; a milestone it
+    does not name, and every ``before`` decision, reads the lineage's
+    selected occurrence. Keys: ``(id, "action", a)`` when the action rises
+    to ``a`` (``keep`` < ``restore`` < ``withhold``), ``(id, "reason",
+    code)`` per gained reason code, and ``(id, "moved")`` when both are
+    ``restore`` to different values.
+    """
+    keys = set()
+    for event_id in sorted(milestone_ids):
+        old = before.restoration(
+            event_id, _selected_milestone_view(before, event_id))
+        record = records.get(event_id)
+        new = after.restoration(
+            event_id, record if record is not None
+            else _selected_milestone_view(after, event_id))
+        if _RESTORATION_RANK[new.action] > _RESTORATION_RANK[old.action]:
+            keys.add((event_id, "action", new.action))
+        for code in set(new.reason_codes) - set(old.reason_codes):
+            keys.add((event_id, "reason", code))
+        if (old.action == new.action == "restore"
+                and old.value != new.value):
+            keys.add((event_id, "moved"))
+    return frozenset(keys)
+
+
+def _hashable_block(payload: Mapping):
+    block = _five_hour_block(payload)
+    try:
+        hash(block)
+    except TypeError:
+        return None
+    return block
+
+
+def plan_completion_five_hour(
+    *, current: Mapping[str, Mapping], with_gap: Mapping[str, Mapping],
+    without_gap: Mapping[str, Mapping], acted: frozenset,
+    physical: Mapping[str, int], selection, lineage: FiveHourLineage,
+    retirements: Sequence[Mapping],
+) -> CompletionFiveHourPlan:
+    """#1040 (spec §5.1–§5.5): completion's five-hour targets, pure.
+
+    ``current`` holds the selected active five-hour records of the whole
+    journal; ``with_gap`` / ``without_gap`` are the round's candidates by
+    id (any kind) and ``acted`` the ids whose two candidates differ;
+    ``physical`` maps an id to its highest physical revision (selected,
+    admission-excluded or inert); ``retirements`` are the tombstone actions
+    today's path appends, which land whatever is chosen and so ride along in
+    every simulation.
+
+    A block is touched when an acted close or milestone names it. Each
+    touched block's closes are classified (:func:`classify_completion_close`).
+    A block is OPEN, and keeps today's path, when no close it decides is
+    closed in the final state; in a block that stays decided an acted close
+    of rule 2 still keeps today's path. The planner owns an id only when
+    every block its retained, with-gap and without-gap records name is
+    decided (``handled``); it never targets another id, and every
+    simulation carries today's record of each acted id it leaves to that
+    path, like the retirements. Every decided block builds its whole
+    close-and-milestone candidates, each carrying the block's required
+    additions (records whose id the selection does not know), and the
+    candidates of a component of blocks that share a close or milestone id
+    are simulated through :meth:`FiveHourLineage.extended` with the append
+    policy's coordinates. A component with one touched block lands the
+    first candidate whose violations are contained in its additions' alone
+    and strictly exceed no other candidate's; a class proposal without
+    violations lands at once. Several touched blocks choose likewise with
+    each other's additions carried, and their union lands only when it adds
+    nothing beyond all their additions together; otherwise each lands its
+    additions alone.
+    """
+    def payload_of(record):
+        return (record or {}).get("payload") or {}
+
+    def five_hour(record):
+        return (record is not None
+                and payload_of(record).get("kind") in _LINEAGE_KINDS)
+
+    def by_block(records):
+        out: dict = {}
+        for event_id, record in records.items():
+            if five_hour(record):
+                block = _hashable_block(payload_of(record))
+                if block is not None:
+                    out.setdefault(block, {})[event_id] = record
+        return out
+
+    current_by_block = by_block(current)
+    with_by_block = by_block(with_gap)
+    without_by_block = by_block(without_gap)
+    touched = set()
+    for event_id in acted:
+        for record in (with_gap.get(event_id), current.get(event_id)):
+            if five_hour(record):
+                block = _hashable_block(payload_of(record))
+                if block is not None:
+                    touched.add(block)
+
+    # Every block an id's retained, with-gap or without-gap record names
+    # (an unusable block key stands for a block nothing decides).
+    unusable_block = object()
+    blocks_of_id: dict = {}
+    for table in (current, with_gap, without_gap):
+        for event_id, record in table.items():
+            if five_hour(record):
+                block = _hashable_block(payload_of(record))
+                blocks_of_id.setdefault(event_id, set()).add(
+                    unusable_block if block is None else block)
+
+    def todays_record(event_id):
+        """The record today's per-id path leaves active for ``event_id``."""
+        existing = current.get(event_id)
+        if event_id not in acted:
+            return existing
+        desired = with_gap.get(event_id)
+        if desired is None:
+            return None  # a retirement tombstone, or nothing
+        if existing is None:
+            return desired
+        return _preserve_non_derivable_state(existing, desired)
+
+    def classify_blocks(not_owned):
+        """§5.2 per touched block: its class and the closes the planner
+        decides. A block is OPEN only when no close it decides is closed in
+        the final state; an acted close of rule 2 (and an acted close the
+        planner does not own) keeps today's path."""
+        classes, owned_closes, todays_closes = {}, {}, set()
+        for block in sorted(touched, key=repr):
+            close_ids = sorted({
+                event_id for records in (
+                    current_by_block.get(block, {}),
+                    with_by_block.get(block, {}),
+                    without_by_block.get(block, {}))
+                for event_id, record in records.items()
+                if payload_of(record).get("kind") == "five_hour_block_close"
+            })
+            several = len(close_ids) > 1
+            closes = {}
+            for close_id in close_ids:
+                close = classify_completion_close(
+                    current.get(close_id), with_gap.get(close_id),
+                    without_gap.get(close_id), acted=close_id in acted,
+                    has_physical=close_id in physical,
+                    several_close_ids=several)
+                if close_id in acted and (
+                        close.block_class == COMPLETION_OPEN
+                        or close_id in not_owned):
+                    todays_closes.add(close_id)
+                elif close.block_class != COMPLETION_OPEN:
+                    closes[close_id] = close
+            if not closes:
+                classes[block] = COMPLETION_OPEN
+                continue
+            kinds = {close.block_class for close in closes.values()}
+            if len(closes) == 1:
+                classes[block] = next(iter(kinds))
+            elif kinds == {COMPLETION_ADDED}:
+                classes[block] = COMPLETION_ADDED
+            else:
+                classes[block] = COMPLETION_FROZEN
+            owned_closes[block] = closes
+        return classes, owned_closes, todays_closes
+
+    # An id whose records reach a block the planner does not decide stays
+    # on today's path (the planner never writes it); deciding fewer blocks
+    # only adds such ids, so this settles.
+    not_owned: set = set()
+    while True:
+        classes, owned_closes, todays_closes = classify_blocks(not_owned)
+        decided_blocks = set(owned_closes)
+        reaching = {
+            event_id for event_id, blocks in blocks_of_id.items()
+            if blocks & decided_blocks and not blocks <= decided_blocks}
+        if reaching <= not_owned:
+            break
+        not_owned |= reaching
+    not_owned |= todays_closes
+
+    candidates: dict = {}
+    retired_ids: set = set()
+    for block in sorted(owned_closes, key=repr):
+        closes = owned_closes[block]
+        block_class = classes[block]
+        cur = current_by_block.get(block, {})
+        wg = with_by_block.get(block, {})
+        milestones_current = {
+            event_id: record for event_id, record in cur.items()
+            if payload_of(record).get("kind") == "five_hour_milestone"}
+        milestones_with = {
+            event_id: record for event_id, record in wg.items()
+            if payload_of(record).get("kind") == "five_hour_milestone"
+            and event_id not in not_owned}
+        retired = frozenset(
+            event_id for event_id in milestones_current
+            if event_id in acted and with_gap.get(event_id) is None)
+        retired_ids.update(retired)
+        # Milestones of this block the planner does not own: today's record
+        # stands in the chain when it stays here, else it leaves the chain.
+        fixed: dict = {}
+        leaving = set()
+        for event_id in sorted(not_owned):
+            if block not in blocks_of_id.get(event_id, ()):
+                continue
+            record = todays_record(event_id)
+            if (record is not None and payload_of(record).get("kind")
+                    == "five_hour_milestone"
+                    and _hashable_block(payload_of(record)) == block):
+                fixed[event_id] = record
+            elif event_id in milestones_current:
+                leaving.add(event_id)
+        retired_chain = retired | frozenset(leaving)
+
+        def candidate(name, *, closes=closes, block_class=block_class,
+                      milestones_current=milestones_current,
+                      milestones_with=milestones_with,
+                      retired_chain=retired_chain, fixed=fixed):
+            records: dict = {}
+            for close_id, close in closes.items():
+                existing = current.get(close_id)
+                desired = with_gap.get(close_id)
+                if name == "class":
+                    target = close.target
+                elif name == "F":
+                    target = (close.frozen_form if existing is not None
+                              else desired if close_id in acted else None)
+                elif name == "P":
+                    target = desired if close_id in acted else None
+                else:
+                    target = None
+                if (close_id in acted and desired is not None
+                        and close_id not in selection.by_id):
+                    target = desired  # a required addition
+                if target is not None and (
+                        existing is None
+                        or _semantic_event(target) != _semantic_event(existing)):
+                    records[close_id] = dict(target)
+            treatment = (
+                ("replaced" if block_class == COMPLETION_REPLACED
+                 else "frozen")
+                if name == "class" else _COMPLETION_CANDIDATE_TREATMENT[name])
+            records.update(completion_block_milestones(
+                treatment=treatment, block_class=block_class,
+                current=milestones_current, with_gap=milestones_with,
+                acted=acted, retired=retired_chain, lineage=lineage,
+                selection=selection, fixed=fixed))
+            return records
+
+        candidates[block] = {
+            name: candidate(name)
+            for name in _COMPLETION_CANDIDATE_ORDER[block_class]}
+
+    decided = sorted(candidates, key=repr)
+    # The planner owns an id only when every block its records name is
+    # decided; today's path keeps every other id (spec §5.1).
+    handled = {
+        event_id for event_id, blocks in blocks_of_id.items()
+        if blocks <= decided_blocks and event_id not in not_owned
+        and event_id not in retired_ids}
+    if not decided:
+        return CompletionFiveHourPlan(
+            targets={}, handled=frozenset(handled), decisions=())
+    # Today's records of the acted ids the planner leaves to that path in a
+    # decided block's reach: they land whatever is chosen, so every
+    # candidate's simulation carries them (like the retirements).
+    todays_records: dict = {}
+    for event_id in sorted(not_owned & acted):
+        if not blocks_of_id.get(event_id, set()) & decided_blocks:
+            continue
+        record = todays_record(event_id)
+        existing = current.get(event_id)
+        if record is not None and (
+                existing is None
+                or _semantic_event(record) != _semantic_event(existing)):
+            todays_records[event_id] = dict(record)
+
+    # §5.4 components: blocks sharing a close or milestone id, over the
+    # lineage's occurrences and every candidate's records.
+    id_blocks: dict = {}
+    block_ids: dict = {}
+
+    def link(event_id, block):
+        if block is None:
+            return
+        id_blocks.setdefault(event_id, set()).add(block)
+        block_ids.setdefault(block, set()).add(event_id)
+
+    for table in (lineage.milestones, lineage.closes):
+        for event_id, items in table.items():
+            for occurrence in items:
+                if occurrence.status == "active" and occurrence.block is not None:
+                    try:
+                        hash(occurrence.block)
+                    except TypeError:
+                        continue
+                    link(event_id, occurrence.block)
+    for block in decided:
+        for records in candidates[block].values():
+            for event_id, record in records.items():
+                link(event_id, _hashable_block(payload_of(record)))
+    for event_id, record in todays_records.items():
+        link(event_id, _hashable_block(payload_of(record)))
+    components: dict = {}
+    for start in decided:
+        if start in components:
+            continue
+        component: set = set()
+        frontier = [start]
+        while frontier:
+            block = frontier.pop()
+            if block in component:
+                continue
+            component.add(block)
+            for event_id in block_ids.get(block, ()):
+                frontier.extend(id_blocks.get(event_id, ()) - component)
+        frozen_component = tuple(sorted(component, key=repr))
+        for block in component:
+            components[block] = frozen_component
+
+    order_index = {event_id: index for index, event_id in enumerate(with_gap)}
+    retirement_blocks = []
+    for action in retirements:
+        record = current.get(action.get("id"))
+        retirement_blocks.append(
+            (action, _hashable_block(payload_of(record))
+             if five_hour(record) else None))
+
+    def landed_records(choices):
+        out: dict = {}
+        for block, name in choices.items():
+            out.update(candidates[block][name])
+        return out
+
+    targets: dict = {}
+    decisions: list = []
+    done: set = set()
+    for start in decided:
+        component = components[start]
+        if start in done:
+            continue
+        members = set(component)
+        touched_here = [block for block in component if block in candidates]
+        done.update(touched_here)
+        milestone_ids = {
+            event_id for block in component
+            for event_id in block_ids.get(block, ())
+            if event_id in lineage.milestones
+            or any(payload_of(records.get(event_id)).get("kind")
+                   == "five_hour_milestone"
+                   for records in candidates.get(block, {}).values())
+        }
+        retired_actions = [dict(action) for action, block in retirement_blocks
+                           if block in members]
+        todays_here = {
+            event_id: record for event_id, record in todays_records.items()
+            if blocks_of_id.get(event_id, set()) & members
+            or _hashable_block(payload_of(record)) in members}
+        milestone_ids |= {
+            event_id for event_id, record in todays_here.items()
+            if payload_of(record).get("kind") == "five_hour_milestone"}
+        cache: dict = {}
+
+        def violations(records, *, retired_actions=retired_actions,
+                       milestone_ids=milestone_ids, cache=cache,
+                       todays_here=todays_here):
+            records = {**todays_here, **records}
+            key = _canonical_bytes([
+                [event_id, _semantic_event(records[event_id])]
+                for event_id in sorted(records)])
+            if key in cache:
+                return cache[key]
+            actions, plain = [], []
+            for event_id in sorted(records):
+                record = records[event_id]
+                existing = current.get(event_id)
+                if existing is not None and (_semantic_event(existing)
+                                             == _semantic_event(record)):
+                    continue
+                if event_id in physical:
+                    actions.append({
+                        "action": "replace", "id": event_id,
+                        "rev": physical[event_id] + 1,
+                        "at": str(record.get("at")),
+                        "payload": dict(record.get("payload") or {}),
+                    })
+                else:
+                    plain.append(record)
+            actions.extend(retired_actions)
+            if not actions and not plain:
+                # Nothing would be appended: every decision stays as it is.
+                cache[key] = frozenset()
+                return cache[key]
+            actions.sort(key=lambda action: action["id"])
+            plain.sort(key=lambda record: order_index.get(
+                record.get("id"), len(order_index)))
+            after = lineage.extended(batch_actions=actions, plain=plain)
+            result = _violation_keys(lineage, after, milestone_ids, records)
+            cache[key] = result
+            return result
+
+        def choose(block, carried):
+            order = _COMPLETION_CANDIDATE_ORDER[classes[block]]
+            own = candidates[block]
+            found = {"class": violations({**carried, **own["class"]})}
+            if not found["class"]:
+                return "class", found
+            for name in order[1:]:
+                found[name] = violations({**carried, **own[name]})
+            ceiling = found["A"]
+            for name in order:
+                if found[name] <= ceiling and not any(
+                        found[other] < found[name] for other in order):
+                    return name, found
+            return "A", found  # unreachable: A always qualifies
+
+        if len(touched_here) == 1:
+            [block] = touched_here
+            name, found = choose(block, {})
+            choices = {block: name}
+            found_by_block = {block: found}
+        else:
+            choices, found_by_block = {}, {}
+            for block in touched_here:
+                carried: dict = {}
+                for other in touched_here:
+                    if other != block:
+                        carried.update(candidates[other]["A"])
+                choices[block], found_by_block[block] = choose(block, carried)
+            alone = landed_records({block: "A" for block in touched_here})
+            if not violations(landed_records(choices)) <= violations(alone):
+                choices = {block: "A" for block in touched_here}
+        targets.update(landed_records(choices))
+        for block in touched_here:
+            decisions.append(BlockDecision(
+                block=block, block_class=classes[block], component=component,
+                landed=choices[block],
+                violations=dict(found_by_block[block])))
+    decisions.sort(key=lambda decision: repr(decision.block))
+    if not set(targets) <= handled:
+        # Both the planner and today's path would write these ids.
+        raise RuntimeError(
+            "#1040 planner targets outside the ids it owns: "
+            f"{sorted(set(targets) - handled)}")
+    return CompletionFiveHourPlan(
+        targets={event_id: targets[event_id] for event_id in sorted(targets)},
+        handled=frozenset(handled),
+        decisions=tuple(decisions),
+    )
+
 _SNAPSHOT_IDENTITY_FIELDS = (
     "account_key", "week_start_date", "week_start_at", "week_end_at",
     "weekly_percent", "five_hour_percent", "five_hour_window_key",
@@ -1876,6 +3746,19 @@ class RederivePlan:
     #: (`_retraction_scope`). Not part of the plan body: the retractions are
     #: already in the config fingerprint through the decision op's payload.
     retraction_event_ids: frozenset = frozenset()
+    #: #956 spec 4.6.3: the windows whose opening fact the selection this plan
+    #: was built over tombstones. Not part of the plan body: it is a property
+    #: of the journal prefix the plan already names. A filtered plan
+    #: (:func:`causal_delta_plan`) evaluates parent presence with it.
+    retired_openings: frozenset = frozenset()
+    #: #943/#956 spec 4.4: the current five-hour milestones whose window
+    #: resolves no block before the plan (pre-existing damage). Reported,
+    #: never a reason to refuse, and not part of the plan body.
+    orphaned_milestone_ids: frozenset = frozenset()
+    #: #884 spec §5.7: the five-hour blocks whose milestone repair the
+    #: lineage withheld (:class:`WithheldBlock`). A diagnostic, outside the
+    #: plan body; its count reaches ``uncertain_cost_fact_count``.
+    withheld_milestone_repairs: tuple = ()
 
     def _body(self) -> dict:
         body = {
@@ -1940,6 +3823,7 @@ def build_claude_usage_plan(*, selection, desired_events: Iterable[Mapping],
                             uncertain_cost_fact_ids=(),
                             historical_close_markers=None,
                             physical_revisions=None,
+                            milestone_lineage=None,
                             enforce_guard=True) -> RederivePlan:
     """Diff current effective events against one scratch-derived desired set.
 
@@ -1972,7 +3856,15 @@ def build_claude_usage_plan(*, selection, desired_events: Iterable[Mapping],
     preserved history retained or revived, or corrected without moving its
     money) or replaced (added, or corrected in a way that writes its money)
     are decided by :func:`_resolve_closed_block_milestones` before the diff,
-    the same way closes are decided before milestones."""
+    the same way closes are decided before milestones.
+
+    #884: ``milestone_lineage`` (:func:`build_five_hour_lineage`, built from
+    the same selection's fold) lets an unchanged crossing of a frozen block
+    regain the amount its history proves an earlier rederive repriced, and
+    fails closed otherwise: each reported withheld block counts once in
+    ``uncertain_cost_fact_count`` and is listed in
+    ``withheld_milestone_repairs``. ``None`` reproduces #875's plan exactly;
+    a missing lineage is a compatibility default, never evidence."""
     conflicted_event_ids = frozenset(conflicted_event_ids or ())
     historical_close_markers = dict(historical_close_markers or {})
     # #825/#832 fix round A (Codex fix-round-1 Q2): the highest revision of
@@ -2009,6 +3901,8 @@ def build_claude_usage_plan(*, selection, desired_events: Iterable[Mapping],
         current, desired, reviewed_weekly_hold_ids, historical_close_markers,
         unsupported_resets=unsupported_resets,
     )
+    # #943 spec 4.4: an `fhcb` follows its `fhc` by natural key.
+    _companions_follow_kept_credits(current, desired)
     retained_event_count = sum(
         1 for selected in selection.by_id.values()
         if selected.status == "active"
@@ -2091,9 +3985,11 @@ def build_claude_usage_plan(*, selection, desired_events: Iterable[Mapping],
     # and a replaced one is frozen. The causal block closure applies the same
     # rule (:func:`_replaced_block_closure`).
     replaced_close_blocks -= frozen_close_blocks
+    withheld: dict = {}
     milestone_decisions = _resolve_closed_block_milestones(
         current, desired, preserved, frozen_close_blocks,
         replaced_close_blocks, selection=selection,
+        lineage=milestone_lineage, withheld=withheld,
     )
 
     for event_id in sorted(set(current) | set(desired) | set(preserved)):
@@ -2186,6 +4082,19 @@ def build_claude_usage_plan(*, selection, desired_events: Iterable[Mapping],
             kind=kind,
         ))
 
+    # #943/#956 spec 4.4: parent validation over the resulting effective
+    # graph. Every five-hour milestone that resolves a block before the plan
+    # must still resolve one after it. The diff above already tombstones a
+    # current milestone the desired replay lacks, so a survivor without its
+    # parent is one the replay itself keeps (or preserved history): refuse
+    # rather than leave it parentless.
+    retired_openings = retired_openings_of(selection)
+    orphaned_before, lost = five_hour_parent_report(
+        current, actions, retired_openings)
+    if lost:
+        raise RederiveConflict(
+            "a five-hour block removal would orphan a retained milestone: "
+            + ", ".join(lost[:10]))
     # #869 F7/Q9: a close counts only while its cost stays unprovable in the
     # state this plan leaves behind — not a provably priced close, not one this
     # plan corrects, and not one an earlier correction already proved.
@@ -2207,6 +4116,18 @@ def build_claude_usage_plan(*, selection, desired_events: Iterable[Mapping],
         set(uncertain_cost_fact_ids or ()) | uncertain_closes
         | drifted_close_ids
     )
+    # #884 spec §5.7: a withheld block counts once, by its smallest close id,
+    # and never beside a close of its own that already counts.
+    withheld_blocks = _withheld_blocks(withheld, current, actions, selection)
+    for block in withheld_blocks:
+        if any(close_id in uncertain_ids for close_id in block.close_event_ids):
+            continue
+        # The synthetic key is defensive only: a frozen block always has a
+        # close in the plan's final state, so it is unreachable.
+        uncertain_ids.add(
+            min(block.close_event_ids) if block.close_event_ids
+            else ("withheld-block", block.account_key,
+                  block.five_hour_window_key))
     plan = RederivePlan(
         family=FAMILY,
         journal_high_water=journal_high_water,
@@ -2219,6 +4140,9 @@ def build_claude_usage_plan(*, selection, desired_events: Iterable[Mapping],
         uncertain_cost_fact_count=len(uncertain_ids),
         action_counts_by_event_kind=counts_by_kind,
         retraction_event_ids=retraction_event_ids,
+        retired_openings=retired_openings,
+        orphaned_milestone_ids=orphaned_before,
+        withheld_milestone_repairs=withheld_blocks,
     )
     if enforce_guard:
         enforce_week_reset_add_burst_guard(plan)
@@ -2502,6 +4426,89 @@ def _retained_reference_closure(actions, reviewed_by_id, current_events):
     return actions
 
 
+def _five_hour_parent_closure(included: list, reviewed_actions,
+                              current_events: Mapping[str, Mapping],
+                              retired_openings=frozenset()) -> list:
+    """#943/#956 spec 4.4: the reviewed actions an included action needs.
+
+    * Derived-FK parent closure: an included five-hour milestone add or
+      supersede resolves its `block_id` from its window at fold, so when the
+      graph the included actions leave behind materializes no block for
+      that window, it keeps the reviewed plan's parent-materializing action
+      for the window (an opening or close add or supersede), even when that
+      action is common to the baseline. A window whose block the resulting
+      graph already materializes (a current close or opening the plan keeps)
+      needs no action: pulling a baseline-common close correction in there
+      would rewrite a close the #875 frozen-block rule keeps as it stands.
+    * A credit and its boundary companion travel together: an included
+      action on either brings the reviewed action on the other.
+    * A seed never outlives a removed block: an included close tombstone
+      brings the reviewed opening tombstone of its window (the reviewed plan
+      tombstones the opening only when its replay has no block there).
+
+    Only reviewed actions are ever added, each once."""
+    parents: dict = {}
+    opening_tombstones: dict = {}
+    pairs: dict = {}
+    for action in reviewed_actions:
+        payload = _action_payload(action, current_events)
+        if action.kind in _BLOCK_PARENT_KINDS:
+            window = _window_of(payload)
+            if action.disposition in {"add", "supersede"}:
+                parents.setdefault(window, []).append(action)
+            elif action.kind == "five_hour_block_open":
+                opening_tombstones.setdefault(window, []).append(action)
+        elif action.kind in _CREDIT_PAIR_KINDS:
+            pairs.setdefault(_credit_pair_key(payload), []).append(action)
+    expanded = list(included)
+    included_ids = {action.event_id for action in included}
+    present = None
+    for action in included:
+        payload = _action_payload(action, current_events)
+        needed = []
+        if (action.kind == "five_hour_milestone"
+                and action.disposition != "tombstone"):
+            if present is None:
+                after_events, after_retired = _post_plan_state(
+                    current_events, included, retired_openings)
+                present = five_hour_parent_presence(
+                    after_events, after_retired)
+            if _window_of(payload) not in present:
+                needed = parents.get(_window_of(payload), [])
+        elif action.kind in _CREDIT_PAIR_KINDS:
+            needed = pairs.get(_credit_pair_key(payload), [])
+        elif (action.kind == "five_hour_block_close"
+              and action.disposition == "tombstone"):
+            needed = opening_tombstones.get(_window_of(payload), [])
+        for dependency in needed:
+            if dependency.event_id not in included_ids:
+                expanded.append(dependency)
+                included_ids.add(dependency.event_id)
+    return expanded
+
+
+def _parent_validation_completion(included: list, reviewed_by_id,
+                                  current_events: Mapping[str, Mapping],
+                                  retired_openings) -> list:
+    """#943/#956 spec 4.4: a filtered plan whose block removal would orphan
+    an unchanged, retained milestone takes that milestone's reviewed
+    tombstone (the desired replay lacks it). A survivor with no reviewed
+    tombstone is left for the final validation, which refuses."""
+    _orphaned_before, lost = five_hour_parent_report(
+        current_events, included, retired_openings)
+    if not lost:
+        return included
+    expanded = list(included)
+    included_ids = {action.event_id for action in included}
+    for event_id in lost:
+        reviewed = reviewed_by_id.get(event_id)
+        if (reviewed is not None and reviewed.disposition == "tombstone"
+                and event_id not in included_ids):
+            expanded.append(reviewed)
+            included_ids.add(event_id)
+    return expanded
+
+
 def causal_delta_plan(
     baseline: RederivePlan, reviewed: RederivePlan, *,
     current_events: Mapping[str, Mapping],
@@ -2568,8 +4575,23 @@ def causal_delta_plan(
         if retraction_scope:
             actions = _retained_reference_closure(
                 actions, reviewed_by_id, current_events)
+        # #943/#956 spec 4.4: over the final filtered set, so a parent or a
+        # companion the B/R filter dropped as baseline-common returns.
+        actions = _five_hour_parent_closure(
+            actions, reviewed.actions, current_events,
+            reviewed.retired_openings)
+        actions = _parent_validation_completion(
+            actions, reviewed_by_id, current_events,
+            reviewed.retired_openings)
         if {action.event_id for action in actions} == previous_ids:
             break
+    # Parent validation over the resulting effective graph (spec 4.4).
+    orphaned_before, lost = five_hour_parent_report(
+        current_events, actions, reviewed.retired_openings)
+    if lost:
+        raise RederiveConflict(
+            "a five-hour block removal would orphan a retained milestone: "
+            + ", ".join(lost[:10]))
     included_ids = {action.event_id for action in actions}
     actions = tuple(
         action for action in reviewed.actions
@@ -2599,6 +4621,9 @@ def causal_delta_plan(
         uncertain_cost_fact_count=reviewed.uncertain_cost_fact_count,
         action_counts_by_event_kind=counts_by_kind,
         retraction_event_ids=reviewed.retraction_event_ids,
+        retired_openings=reviewed.retired_openings,
+        orphaned_milestone_ids=orphaned_before,
+        withheld_milestone_repairs=reviewed.withheld_milestone_repairs,
     )