cctally 1.108.0 → 1.110.0

package/bin/_lib_render.py

@@ -2890,9 +2890,15 @@ def _render_project_table(
             return ("\u2014", _gray)  # em-dash for unknown
         base = f"{ap:.1f}%"
         if weeks_in_range > 1:
-            # Count weeks the user asked about; surface via `(Nwk)` suffix
-            # (spec §3). Keep the suffix short so column width stays sane.
-            base = f"{base} ({weeks_in_range}wk)"
+            # The count of BILLING CYCLES the window covers, surfaced as an
+            # `(Ncy)` suffix. It was `(Nwk)`, and a credited week contributes
+            # two cycles, so the abbreviation named the wrong unit — the same
+            # inconsistency #750 S4 D2 removes from every other surface. `cy`
+            # rather than the spelled-out word because the suffix is exactly as
+            # wide as before: the cell already truncates to `80.0% (…` at
+            # ordinary terminal widths, and a longer token would truncate more
+            # often. The summary line below the table spells `cycles` out.
+            base = f"{base} ({weeks_in_range}cy)"
         return (base, _used_pct_color(ap))
 
     def _cost_per_pct_cell(cpp: float | None) -> tuple[str, Any]:

package/bin/_lib_retained_size.py

@@ -110,6 +110,8 @@ def retained_size_bytes(
     *,
     stop_after: int | None = None,
     cancelled: Callable[[], bool] | None = None,
+    borrowed: Callable[[object], bool] | None = None,
+    opaque: Callable[[object], bool] | None = None,
     _object_id: Callable[[object], int] = id,
 ) -> int:
     """Return owned reachable bytes, or ``stop_after + 1`` once over budget.
@@ -120,6 +122,25 @@ def retained_size_bytes(
     charged for their object shell and, when present, ``__dict__``/``__slots__``.
     Modules, functions and classes therefore do not cause an unbounded walk of
     interpreter-global state.
+
+    ``borrowed`` is the ownership-graph seam (#769 S6 T2a, #716 Task B). It
+    answers, for one referent, "does some OTHER declared owner carry this
+    payload's charge?".  A borrowed referent is charged nothing AND is not
+    descended into, so a cache that merely repeats a payload another cache
+    retains pays for its own containers and references and for nothing else.
+    That is what makes a sum of per-owner charges comparable with one walk of
+    the whole retained graph instead of double counting every repeat.  The
+    predicate is never applied to ``value`` itself: a caller asking for the
+    size of an object it declares borrowed is asking a contradictory question,
+    and answering zero would silently drop the owner's own charge.
+
+    ``opaque`` is the same seam for a CONTAINER of borrowed payloads.  The
+    container's own shell is the owner's charge — a tuple of 200,000 borrowed
+    rows costs eight bytes a slot and somebody has to pay for them — but
+    descending into it to ask ``borrowed`` about each slot would make the
+    charge proportional to a population the owner does not own.  An opaque
+    referent is therefore charged its ``sys.getsizeof`` and not descended into.
+    Like ``borrowed`` it is never applied to ``value`` itself.
     """
     if stop_after is not None and stop_after < 0:
         raise ValueError("stop_after must be non-negative or None")
@@ -146,12 +167,16 @@ def retained_size_bytes(
             )
         )
 
-    def walk(obj) -> bool:
+    def walk(obj, root: bool = False) -> bool:
         object_id = _object_id(obj)
         if object_id in seen:
             return False
+        if not root and borrowed is not None and borrowed(obj):
+            return False
         if add(obj, object_id):
             return True
+        if not root and opaque is not None and opaque(obj):
+            return False
         if isinstance(obj, _ATOMIC):
             return False
         if isinstance(obj, (types.ModuleType, type)) or callable(obj):
@@ -183,5 +208,5 @@ def retained_size_bytes(
                 return True
         return False
 
-    exceeded = walk(value)
+    exceeded = walk(value, root=True)
     return sentinel if exceeded and sentinel is not None else total

package/bin/_lib_segment_summary.py

@@ -52,9 +52,12 @@ the raw `st_size`, and elision requires all three to be equal.
 This module performs no I/O beyond the sidecar itself and imports nothing from
 `_cctally_journal`, so it is unit-testable without a journal on disk — the same
 rule `bin/_lib_journal_router.py` and `bin/_lib_cache_coverage.py` follow. The
-two modules it does import, `_lib_journal_router` and `_cctally_core`, are
-themselves leaf modules; they are imported for the two constants
-`summary_version` is derived from, not for behaviour.
+three modules it does import — `_lib_journal_router`, `_cctally_core` and
+`_lib_ingest_frontier` — are themselves leaf modules; the first two supply the
+two constants `summary_version` is derived from, and the third supplies
+`source_identity_replaced`, the repository's single point of truth for "does a
+different file now occupy this pathname". The prefix proof the identity check
+may require is supplied BY THE CALLER as a callable, so the no-I/O rule holds.
 """
 from __future__ import annotations
 
@@ -66,6 +69,7 @@ import tempfile
 from dataclasses import dataclass, field, replace
 
 import _cctally_core
+import _lib_ingest_frontier
 import _lib_journal_router
 
 
@@ -80,7 +84,7 @@ SIDECAR_NAME = ".segment-summaries"
 #: Bumped by hand when a summary's FIELD SET or the meaning of one of its
 #: numbers changes. It is only one of the three inputs to `summary_version`; the
 #: other two are derived, for the reason that function's docstring gives.
-SUMMARY_SHAPE_VERSION = 2
+SUMMARY_SHAPE_VERSION = 3
 
 #: The refusal reasons `summary_is_elidable` returns. They are stable, because
 #: the rebuild record reports them (spec section 6.3, "recorded, not silent").
@@ -121,6 +125,14 @@ class SegmentSummary:
     #: retained records plus placeholders, and never a malformed line. `None`
     #: means the summary predates the field and cannot be elided against.
     decoded_entry_count: "int | None" = 0
+    #: Hex `sha256` of the segment's bytes in `[0, complete_line_covered_offset)`
+    #: — the COMPLETE prefix this summary describes. #834 S2 (#827): it exists
+    #: so a device-only identity change can be settled by content rather than
+    #: refused. Inode numbers are unique only within a device, and no other
+    #: field separates two files sharing device-independent identity, size and
+    #: pinned extent. `None` means the summary predates the field, and no proof
+    #: is possible against it, so such a summary refuses a device-only change.
+    complete_prefix_sha256: "str | None" = None
     #: The segment's partial `LastSeenAccumulator` state.
     last_seen_stamped: dict = field(default_factory=dict)
     last_seen_legacy_claude_at: "str | None" = None
@@ -129,7 +141,7 @@ class SegmentSummary:
 
 def summary_is_elidable(
     summary, *, pinned_raw_extent, is_last, certificate_covers,
-    resolution_seen, stat_identity=None,
+    resolution_seen, stat_identity=None, prefix_proof=None,
 ) -> "tuple[bool, str]":
     """``(verdict, reason)`` for one segment against spec section 5.5.
 
@@ -138,6 +150,13 @@ def summary_is_elidable(
     and a unit test asserting one of the other conditions does not; when it is
     absent the identity condition is the caller's to have checked.
 
+    ``prefix_proof`` is a callable returning the hex ``sha256`` of the segment's
+    CURRENT bytes in ``[0, complete_line_covered_offset)``. It is evaluated ONLY
+    on a device-only identity change, because evaluating it on the common path
+    would read every segment elision exists to skip. ``None`` means the caller
+    can supply no proof, which refuses that change rather than reusing
+    optimistically.
+
     The order is deliberate, and two parts of it change behaviour rather than
     only wording. `resolution_seen` comes first because it is a property of the
     PASS rather than of the segment, so reporting a segment-shaped reason for it
@@ -149,15 +168,47 @@ def summary_is_elidable(
     segment the summary's own extent already disqualifies, and a test asserting
     the refusal REASON is what distinguishes the two mechanisms. Reordering
     these two is therefore a behaviour change, not a cleanup.
+
+    #834 S2 (#827): THE INODE DECIDES; THE DEVICE CORROBORATES. This used to
+    compare ``(st_dev, st_ino)`` as a pair, so an ordinary remount of a journal
+    on an external or network volume refused every summary for files that had
+    not changed at all — `st_dev` is assigned when a volume is mounted rather
+    than when a file is created. The verdict now goes through
+    `_lib_ingest_frontier.source_identity_replaced`, which both Codex walks and
+    `classify_recent_active_path` already use, because three copies of one
+    comparison is the shape in which one of them silently stops matching the
+    others.
+
+    A device-only change additionally requires the byte-identity proof, because
+    inode numbers are unique only WITHIN a device and no other field separates
+    two files sharing device-independent identity, size and pinned extent. The
+    collision is narrow — size and pinned extent must also match — but the
+    failure it produces is a silent omission of retained data rather than a
+    recomputation, so it is refused rather than argued about. A summary written
+    before the digest field carries ``None`` and refuses the same way.
     """
     if resolution_seen:
         return False, REASON_RESOLUTION
     if is_last:
         return False, REASON_LAST
     if stat_identity is not None:
-        if (int(summary.st_dev), int(summary.st_ino)) != (
-                int(stat_identity[0]), int(stat_identity[1])):
+        observed_dev, observed_ino = int(stat_identity[0]), int(stat_identity[1])
+        if _lib_ingest_frontier.source_identity_replaced(
+                int(summary.st_dev), int(summary.st_ino),
+                observed_dev, observed_ino):
             return False, REASON_IDENTITY
+        if int(summary.st_dev) != observed_dev:
+            digest = summary.complete_prefix_sha256
+            if not digest or prefix_proof is None:
+                return False, REASON_IDENTITY
+            try:
+                observed_digest = prefix_proof()
+            except OSError:
+                # An unreadable prefix is not a proof. Refusing costs a re-read
+                # of one segment; accepting would skip retained data.
+                return False, REASON_IDENTITY
+            if observed_digest != digest:
+                return False, REASON_IDENTITY
     # ONE equality over three operands, not two comparisons: see the module
     # docstring for why the raw size and the newline boundary are independent.
     if not (int(summary.complete_line_covered_offset)
@@ -176,7 +227,8 @@ def summary_is_elidable(
 _FIELDS = (
     "segment_name", "st_dev", "st_ino", "summarized_size",
     "complete_line_covered_offset", "lines", "bytes", "decodes", "malformed",
-    "quota_only", "decoded_entry_count", "last_seen_stamped",
+    "quota_only", "decoded_entry_count", "complete_prefix_sha256",
+    "last_seen_stamped",
     "last_seen_legacy_claude_at", "last_seen_legacy_codex_at",
 )
 
@@ -236,6 +288,9 @@ def to_wire(summary) -> dict:
         "decoded_entry_count": (
             None if summary.decoded_entry_count is None
             else int(summary.decoded_entry_count)),
+        "complete_prefix_sha256": (
+            None if summary.complete_prefix_sha256 is None
+            else str(summary.complete_prefix_sha256)),
         "last_seen_stamped": {
             str(key): str(value)
             for key, value in dict(summary.last_seen_stamped).items()
@@ -272,6 +327,9 @@ def from_wire(item) -> SegmentSummary:
         malformed=int(item["malformed"]),
         quota_only=bool(item["quota_only"]),
         decoded_entry_count=None if count is None else int(count),
+        complete_prefix_sha256=(
+            None if item["complete_prefix_sha256"] is None
+            else str(item["complete_prefix_sha256"])),
         last_seen_stamped={
             str(key): str(value) for key, value in stamped.items()},
         last_seen_legacy_claude_at=(

package/bin/_lib_share_templates.py

@@ -750,12 +750,16 @@ def _build_trend_recap(*, panel_data, options):
     delta = panel_data.get("delta_3_weeks") or {}
     return _LS.ShareSnapshot(
         cmd="report",
-        title="$/% trend — last 8 weeks",
+        title="$/% trend — last 8 cycles",
         subtitle=None,
-        period=_civil_period(start, end, label="Last 8 weeks",
+        period=_civil_period(start, end, label="Last 8 cycles",
                               display_tz=_display_tz(options)),
         columns=(
-            _LS.ColumnSpec(key="week",  label="Week",   align="left"),
+            # The KEY stays `week` — it is a frozen wire name. Only the
+            # human label changes: a Claude trend row is a billing CYCLE,
+            # and `report` split a credited week into two long before this
+            # epic (#750 S4 D2 / §4.5).
+            _LS.ColumnSpec(key="week",  label="Cycle",  align="left"),
             _LS.ColumnSpec(key="cost",  label="$",      align="right", emphasis=True),
             _LS.ColumnSpec(key="pct",   label="% used", align="right"),
             _LS.ColumnSpec(key="dpp",   label="$/%",    align="right"),
@@ -776,8 +780,8 @@ def _build_trend_recap(*, panel_data, options):
             reference_lines=(),
         ) if weeks else None,
         totals=_kpi_strip(
-            ("Δ $/% (3wk)", _optional_signed_pct(delta.get('dpp_change_pct'))),
-            ("Δ $ (3wk)",   _optional_signed_money(delta.get('cost_change_usd'))),
+            ("Δ $/% (3cy)", _optional_signed_pct(delta.get('dpp_change_pct'))),
+            ("Δ $ (3cy)",   _optional_signed_money(delta.get('cost_change_usd'))),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -1261,9 +1265,9 @@ def _build_trend_visual(*, panel_data, options):
     delta = panel_data.get("delta_3_weeks") or {}
     return _LS.ShareSnapshot(
         cmd="report",
-        title="$/% trend visual — last 8 weeks",
+        title="$/% trend visual — last 8 cycles",
         subtitle=None,
-        period=_civil_period(start, end, label="Last 8 weeks",
+        period=_civil_period(start, end, label="Last 8 cycles",
                               display_tz=_display_tz(options)),
         columns=(),
         rows=(),
@@ -1274,8 +1278,8 @@ def _build_trend_visual(*, panel_data, options):
             reference_lines=(),
         ) if weeks else None,
         totals=_kpi_strip(
-            ("Δ $/% (3wk)", _optional_signed_pct(delta.get('dpp_change_pct'))),
-            ("Δ $ (3wk)",   _optional_signed_money(delta.get('cost_change_usd'))),
+            ("Δ $/% (3cy)", _optional_signed_pct(delta.get('dpp_change_pct'))),
+            ("Δ $ (3cy)",   _optional_signed_money(delta.get('cost_change_usd'))),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -1292,12 +1296,16 @@ def _build_trend_detail(*, panel_data, options):
     delta = panel_data.get("delta_3_weeks") or {}
     return _LS.ShareSnapshot(
         cmd="report",
-        title="$/% trend detail — last 8 weeks",
+        title="$/% trend detail — last 8 cycles",
         subtitle=None,
-        period=_civil_period(start, end, label="Last 8 weeks",
+        period=_civil_period(start, end, label="Last 8 cycles",
                               display_tz=_display_tz(options)),
         columns=(
-            _LS.ColumnSpec(key="week",  label="Week",   align="left"),
+            # The KEY stays `week` — it is a frozen wire name. Only the
+            # human label changes: a Claude trend row is a billing CYCLE,
+            # and `report` split a credited week into two long before this
+            # epic (#750 S4 D2 / §4.5).
+            _LS.ColumnSpec(key="week",  label="Cycle",  align="left"),
             _LS.ColumnSpec(key="cost",  label="$",      align="right", emphasis=True),
             _LS.ColumnSpec(key="pct",   label="% used", align="right"),
             _LS.ColumnSpec(key="dpp",   label="$/%",    align="right"),
@@ -1318,8 +1326,8 @@ def _build_trend_detail(*, panel_data, options):
             reference_lines=(),
         ) if weeks else None,
         totals=_kpi_strip(
-            ("Δ $/% (3wk)", _optional_signed_pct(delta.get('dpp_change_pct'))),
-            ("Δ $ (3wk)",   _optional_signed_money(delta.get('cost_change_usd'))),
+            ("Δ $/% (3cy)", _optional_signed_pct(delta.get('dpp_change_pct'))),
+            ("Δ $ (3cy)",   _optional_signed_money(delta.get('cost_change_usd'))),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -1929,8 +1937,10 @@ def _projects_chart_for_template(rows: list[dict], cap: int):
 def _projects_period(panel_data: dict, options: dict):
     start = panel_data["period_start"]
     end = panel_data["period_end"]
+    # `window_weeks` stays the frozen wire name; the rendered noun does not.
+    # The Projects window is a set of billing-cycle buckets (#750 S4 D2/D6).
     weeks = int(panel_data.get("window_weeks", 1) or 1)
-    label = "This week" if weeks == 1 else f"Last {weeks} weeks"
+    label = "This cycle" if weeks == 1 else f"Last {weeks} cycles"
     return _period(start, end, label=label,
                    display_tz=_display_tz(options))
 
@@ -2048,11 +2058,11 @@ _RECAP = (
                   default_options={"top_n": 5, "show_chart": True, "show_table": True},
                   builder=_build_weekly_recap),
     ShareTemplate(id="current-week-recap", panel="current-week", label="Recap",
-                  description="Week-to-date KPIs + line + top-3 projects",
+                  description="Cycle-to-date KPIs + line + top-3 projects",
                   default_options={"top_n": 3, "show_chart": True, "show_table": True},
                   builder=_build_current_week_recap),
     ShareTemplate(id="trend-recap", panel="trend", label="Recap",
-                  description="$/% trend over 8 weeks + 3-week delta",
+                  description="$/% trend over 8 cycles + 3-cycle delta",
                   default_options={"top_n": 3, "show_chart": True, "show_table": True},
                   builder=_build_trend_recap),
     ShareTemplate(id="daily-recap", panel="daily", label="Recap",
@@ -2093,7 +2103,7 @@ _VISUAL = (
                   default_options={"top_n": 8, "show_chart": True, "show_table": False},
                   builder=_build_weekly_visual),
     ShareTemplate(id="current-week-visual", panel="current-week", label="Visual",
-                  description="Week-to-date line with KPI overlay",
+                  description="Cycle-to-date line with KPI overlay",
                   default_options={"top_n": 8, "show_chart": True, "show_table": False},
                   builder=_build_current_week_visual),
     ShareTemplate(id="trend-visual", panel="trend", label="Visual",

package/bin/_lib_snapshot_cache.py

@@ -1079,6 +1079,14 @@ def reset_session_cache_state() -> None:
 # === #582 — persistent Codex accounting rows by dirty physical path =========
 
 
+#: Bumped when anything about how this population or the labels derived from
+#: it is COMPUTED changes, rather than when the data changes. A consumer
+#: comparing the signature is therefore invalidated by an algorithm change as
+#: well as by a mutation, which is what lets the project label cache retain
+#: derived labels across ticks at all.
+CODEX_POPULATION_SIGNATURE_VERSION = "codex-accounting-population-v1"
+
+
 @dataclass(frozen=True)
 class CodexAccountingCacheResult:
     """One cold or incrementally refreshed accounting population."""
@@ -1089,6 +1097,12 @@ class CodexAccountingCacheResult:
     cold: bool
     changed_old: tuple[object, ...] = ()
     changed_new: tuple[object, ...] = ()
+    #: The exact identity of the population in `entries` (#769 S6 T2a, #716
+    #: Task B). A consumer that compares this instead of scanning the rows
+    #: cannot serve a stale population, and a clean comparison visits no row at
+    #: all. `None` means "cannot establish an identity", which every consumer
+    #: must treat as a cold read rather than as a hit.
+    population_signature: tuple | None = None
 
 
 _CODEX_ACCOUNTING_CACHE_STATE: dict[str, object] = _ObservedSnapshotDict()
@@ -1135,6 +1149,64 @@ def _codex_accounting_mutation_seq(conn: sqlite3.Connection) -> int | None:
         return None
 
 
+def _codex_window_attribution_revision(conn: sqlite3.Connection) -> str | None:
+    """`codex_window_attributions`' revision — a LEADING attribution signal.
+
+    An earlier version of this docstring said that window-scoped spend adoption
+    rewrites `account_key` on existing rows and bumps this revision in the same
+    transaction. Both halves were wrong, and the leg is worth keeping for a
+    different reason.
+
+    The restamp does not need this leg. `account_key` is a member of
+    `_CODEX_ACCOUNTING_SEMANTIC_COLUMNS` (`bin/_cctally_db.py`), so an UPDATE to
+    it fires `trg_codex_accounting_upd`, advances `codex_accounting_mutation_seq`
+    and marks the path dirty — the ledger DDL's own docstring calls this "the
+    ordinary account-adoption case", and the sequence leg above already carries
+    it. And `apply_codex_window_spend_adoption` (`bin/_cctally_cache.py`) does
+    not call `bump_codex_window_attribution_revision` at all; the three callers
+    are in `bin/_cctally_journal.py` and belong to the `codex_window_attributions`
+    overlay, a different table outside the accounting population.
+
+    What this leg actually covers is the GAP BETWEEN the two. The revision
+    advances in the same transaction as the overlay's own rows, during journal
+    replay. The restamp those rows imply is performed later, by
+    `reconcile_codex_window_attribution_spend` at the end of the next Codex
+    sync. Between the two the accounting ledger head has not moved, so a memo
+    keyed on the ledger alone would keep serving a population built before the
+    operator's attribution landed. Carrying the revision turns that window into
+    an unnecessary miss, which is the direction this signature is written in.
+    """
+    try:
+        row = conn.execute(
+            "SELECT value FROM cache_meta "
+            "WHERE key='codex_window_attribution_revision'"
+        ).fetchone()
+    except sqlite3.Error:
+        return None
+    return None if row is None or row[0] is None else str(row[0])
+
+
+def _codex_main_database_path(conn: sqlite3.Connection) -> str | None:
+    try:
+        return next(
+            str(row[2]) for row in conn.execute("PRAGMA database_list")
+            if str(row[1]) == "main"
+        )
+    except (sqlite3.Error, StopIteration):
+        return None
+
+
+def current_codex_population_signature() -> tuple | None:
+    """The signature of the population the process cache currently holds.
+
+    Read by the project and label caches, which are built from that population
+    but are not handed the `CodexAccountingCacheResult` that produced it.
+    """
+    _assert_owner()
+    signature = _CODEX_ACCOUNTING_CACHE_STATE.get("population_signature")
+    return signature if isinstance(signature, tuple) else None
+
+
 def codex_accounting_cache_pending(conn: sqlite3.Connection) -> bool:
     """Whether the process cache has not consumed the durable ledger head."""
     _assert_owner()
@@ -1174,8 +1246,35 @@ def build_cached_codex_accounting(
     ):
         raise ValueError("Codex accounting cache range must be aware and ordered")
     current_seq = _codex_accounting_mutation_seq(cache_conn)
+    database_path = _codex_main_database_path(cache_conn)
+    attribution_revision = _codex_window_attribution_revision(cache_conn)
     state = _CODEX_ACCOUNTING_CACHE_STATE
     prior_cached_entries = tuple(state.get("entries", ())) if state else ()
+
+    def signature(generation: int) -> tuple | None:
+        """The exact identity of the population this call is returning.
+
+        `range_end` is deliberately NOT a leg. It advances on every tick, so a
+        signature carrying it would move every tick and no consumer could ever
+        reuse anything — which is the same trap `_cached_projects_wire` already
+        records for its own key. An upper bound that actually reveals a row
+        dirties that row's path, and the generation below moves with it; an
+        upper bound that reveals nothing leaves the population identical, and
+        saying so is correct rather than optimistic.
+        """
+        if current_seq is None or database_path is None:
+            # No ledger is not an idle ledger. Refusing to name an identity is
+            # what makes every consumer take a cold read.
+            return None
+        return (
+            CODEX_POPULATION_SIGNATURE_VERSION,
+            database_path,
+            int(current_seq),
+            int(generation),
+            range_start,
+            extra_signature,
+            attribution_revision,
+        )
     cold = (
         current_seq is None
         or not state
@@ -1240,6 +1339,8 @@ def build_cached_codex_accounting(
             str(account_of(entry))
             for entry in (*prior_cached_entries, *entries)
         }))
+        generation = int(state.get("generation", 0)) + 1
+        population_signature = signature(generation)
         _CODEX_ACCOUNTING_CACHE_STATE.clear()
         _CODEX_ACCOUNTING_CACHE_STATE.update({
             "entries": entries,
@@ -1247,16 +1348,24 @@ def build_cached_codex_accounting(
             "start": range_start,
             "end": range_end,
             "extra": extra_signature,
+            "generation": generation,
+            "population_signature": population_signature,
         })
         return CodexAccountingCacheResult(
             entries, (), accounts, True, prior_cached_entries, entries,
+            population_signature=population_signature,
         )
 
     prior_entries = tuple(state["entries"])
     if not dirty:
+        population_signature = signature(int(state.get("generation", 0)))
         state["seq"] = current_seq
         state["end"] = range_end
-        return CodexAccountingCacheResult(prior_entries, (), (), False)
+        state["population_signature"] = population_signature
+        return CodexAccountingCacheResult(
+            prior_entries, (), (), False,
+            population_signature=population_signature,
+        )
 
     dirty_paths = tuple(sorted(dirty))
     prior_dirty = tuple(
@@ -1294,11 +1403,16 @@ def build_cached_codex_accounting(
     # while keeping the tuple's shallow shape. Mark this semantic replacement
     # explicitly; the routine ``seq``/``end`` watermark updates below do not.
     _mark_snapshot_accelerators_dirty()
+    generation = int(state.get("generation", 0)) + 1
+    population_signature = signature(generation)
     state["entries"] = entries
     state["seq"] = current_seq
     state["end"] = range_end
+    state["generation"] = generation
+    state["population_signature"] = population_signature
     return CodexAccountingCacheResult(
         entries, dirty_paths, dirty_accounts, False, changed_old, changed_new,
+        population_signature=population_signature,
     )