cctally 1.92.1 → 1.92.3

package/bin/_cctally_journal_repair.py

@@ -10,13 +10,31 @@ import pathlib
 import signal
 import sqlite3
 import sys
+import typing
 
 import _cctally_core
 import _cctally_journal as _journal
+import _lib_accounts
 import _lib_journal
+import _lib_journal_router
 from _lib_json_envelope import stamp_schema_version
 
 
+class _PrefixSnapshot(typing.NamedTuple):
+    """One pinned prefix, read exactly once (#496 S5 §4).
+
+    `audit_ends` maps each `journal_protocol_resolution` op id to the end
+    coordinate of its line. The already-resolved recovery branch needs those
+    coordinates and used to re-read the whole prefix through `_audit_high_water`
+    to find them, even though this pass had them in hand.
+    """
+
+    high_water: "tuple[str, int] | None"
+    prefix_hash: "str | None"
+    selection: object
+    audit_ends: dict
+
+
 def _read_only_high_water() -> "tuple[str, int] | None":
     """Capture the append-only prefix without creating a lock or sidecar."""
     segments = _journal.list_segments()
@@ -27,37 +45,99 @@ def _read_only_high_water() -> "tuple[str, int] | None":
 
 
 def _read_prefix(high_water):
+    """Stream the pinned prefix once, producing everything derived from it.
+
+    Returns `(records, evidence, prefix_hash, audit_ends)`. The prefix hash
+    comes from a `PrefixHashAccumulator` fed by the same bytes this pass reads,
+    the protocol evidence is captured from that accumulator rather than by
+    re-reading the prefix per resolution op, and the cutover account is captured
+    inline exactly as `rebuild_stats_index` captures it. Before this, those were
+    four separate whole-prefix traversals on top of this one (#496 S5 §4).
+
+    Every record stays decoded. Unlike the rebuild, the selector here feeds an
+    acknowledgement the repair command may then mint, and unlike the rebuild's
+    filtered retention there is no placeholder scheme to keep the `enumerate`
+    numbering identical — so the list is unfiltered, exactly as before.
+    """
     if high_water is None:
-        return [], ()
+        return [], (), None, {}
+    segments = _journal.list_segments()
+    if high_water[0] not in segments:
+        raise OSError(
+            f"journal high-water segment is unavailable: {high_water[0]}"
+        )
     records = []
     evidence = []
+    audit_ends: dict = {}
     malformed = 0
     prior_high_water = None
-    for segment, offset, raw in _journal._read_range(None, high_water):
+    cutover_captured = _journal._CUTOVER_UNSEEN
+    hasher = _lib_journal_router.PrefixHashAccumulator()
+    for segment, offset, raw in _journal._iter_range_with_segments(
+        None,
+        high_water,
+        segments,
+        on_segment=lambda name: hasher.begin_segment(name, prior_high_water),
+        on_bytes=hasher.extend,
+    ):
         record = _lib_journal.decode_line(raw)
         if record is None:
             malformed += 1
             prior_high_water = (segment, offset + len(raw) + 1)
             continue
-        _journal._capture_protocol_prefix_evidence(
-            record,
-            prior_high_water,
-            evidence,
-        )
+        record_end = (segment, offset + len(raw) + 1)
+        if record.get("t") == "op":
+            _journal._capture_protocol_prefix_evidence(
+                record,
+                prior_high_water,
+                evidence,
+                hasher=hasher,
+            )
+            payload = record.get("payload")
+            if (
+                isinstance(payload, dict)
+                and payload.get("kind")
+                == _lib_journal._PROTOCOL_RESOLUTION_KIND
+            ):
+                audit_ends[record.get("id")] = record_end
+        # First cutover op wins, exactly as `find_accounts_cutover_op` scans.
+        if (
+            cutover_captured is _journal._CUTOVER_UNSEEN
+            and record.get("id") == _journal.CUTOVER_OP_ID
+        ):
+            cutover_captured = _journal._cutover_value_of(record)
         records.append(record)
-        prior_high_water = (segment, offset + len(raw) + 1)
+        prior_high_water = record_end
+    prefix_hash = hasher.digest_at(high_water)
+    # The accumulator buffers the segment it is reading — 410 MB on the
+    # maintainer's journal — so it is dropped the moment its pass ends, before
+    # the normalization loop below, exactly as `rebuild_stats_index` drops it.
+    # It is dropped before the raise too, so a malformed prefix does not pin the
+    # buffer on the traceback while the exception unwinds.
+    hasher = None
     if malformed:
         raise _lib_journal.JournalProtocolError(
             f"journal prefix contains {malformed} malformed line(s)"
         )
-    cutover_claude = _journal.resolve_cutover_claude_account()
+    # No suffix fallback, deliberately. `_read_only_high_water` pins the
+    # canonically-last segment at its full size, so this prefix IS the whole
+    # journal and an op the prefix does not contain is not in the journal at
+    # all — which is exactly what `resolve_cutover_claude_account` used to
+    # answer by re-reading every segment. An op appended in the window between
+    # that pin and this loop is therefore NOT seen, where the whole-journal scan
+    # would have found it; that divergence is accepted, because the account then
+    # matches the prefix the fingerprints are computed over and `_apply`'s
+    # conflict check catches a preview that has gone stale. The rebuild's
+    # `_resolve_cutover_for_rebuild` cannot be reused here: its fallback calls
+    # `journal_high_water`, which takes the leaf lock and so CREATES
+    # `journal.lock`, and the preview must leave no sidecar behind.
+    if cutover_captured is _journal._CUTOVER_UNSEEN or cutover_captured is None:
+        cutover_claude = _lib_accounts.UNATTRIBUTED
+    else:
+        cutover_claude = cutover_captured
     for record in records:
         _journal._normalize_legacy_account_stamp(record, cutover_claude)
-    return records, tuple(evidence)
-
-
-def _prefix_hash(high_water) -> "str | None":
-    return _journal.journal_prefix_hash(high_water)
+    return records, tuple(evidence), prefix_hash, audit_ends
 
 
 def _high_water_dict(high_water):
@@ -66,18 +146,21 @@ def _high_water_dict(high_water):
     return {"segment": high_water[0], "offset": high_water[1]}
 
 
-def _selection_snapshot():
+def _selection_snapshot() -> _PrefixSnapshot:
     high_water = _read_only_high_water()
-    records, evidence = _read_prefix(high_water)
+    records, evidence, prefix_hash, audit_ends = _read_prefix(high_water)
     selection = _lib_journal.resolve_effective_events(
         records,
         protocol_prefix_evidence=evidence,
     )
-    return high_water, _prefix_hash(high_water), selection
+    return _PrefixSnapshot(high_water, prefix_hash, selection, audit_ends)
 
 
 def _preview_payload(requested=()):
-    high_water, prefix_hash, selection = _selection_snapshot()
+    snapshot = _selection_snapshot()
+    high_water = snapshot.high_water
+    prefix_hash = snapshot.prefix_hash
+    selection = snapshot.selection
     unacknowledged = {
         violation.fingerprint: violation
         for violation in selection.protocol_violations
@@ -115,7 +198,7 @@ def _preview_payload(requested=()):
         "rebuild": None,
         "errors": errors,
     }
-    return stamp_schema_version(body, version=1), selection
+    return stamp_schema_version(body, version=1), snapshot
 
 
 def _rebuild_dict(result):
@@ -230,7 +313,7 @@ def _repair_failure_guidance(exc: Exception) -> str:
 
 def _post_audit_failure(requested, audit_ids, exc):
     """Report durable acknowledgement truth when index publication declined."""
-    payload, _selection = _preview_payload(requested)
+    payload, _snapshot = _preview_payload(requested)
     payload["status"] = "failed"
     payload["errors"] = [_repair_failure_guidance(exc)]
     if len(audit_ids) == 1:
@@ -261,12 +344,19 @@ def _stats_has_acknowledgements(fingerprints) -> bool:
         return False
 
 
-def _audit_high_water(audit_ids, high_water):
-    found = {}
-    for segment, offset, raw in _journal._read_range(None, high_water):
-        record = _lib_journal.decode_line(raw)
-        if record is not None and record.get("id") in audit_ids:
-            found[record["id"]] = (segment, offset + len(raw) + 1)
+def _recovery_high_water(audit_ids, audit_ends):
+    """The last acknowledged audit record's end coordinate.
+
+    `audit_ends` is produced by the same streaming pass that produced the
+    selection, so an already-resolved recovery no longer re-reads the whole
+    prefix to find coordinates that pass already held (#496 S5 §4.1). The
+    ordering rule is the pre-change one: canonical segment order, then offset.
+    """
+    found = {
+        audit_id: audit_ends[audit_id]
+        for audit_id in audit_ids
+        if audit_id in audit_ends
+    }
     if set(found) != set(audit_ids):
         raise _journal.JournalError(
             "acknowledged protocol audit record is missing from the journal"
@@ -279,7 +369,8 @@ def _audit_high_water(audit_ids, high_water):
 def _apply(requested, initial_preview):
     _call_pause_hook("before-lock")
     with _repair_locks():
-        preview, selection = _preview_payload(requested)
+        preview, snapshot = _preview_payload(requested)
+        selection = snapshot.selection
         if preview["errors"]:
             preview["status"] = "conflict"
             return preview, 2
@@ -347,7 +438,7 @@ def _apply(requested, initial_preview):
                     {audit["id"]},
                     exc,
                 )
-            final_payload, _final_selection = _preview_payload(requested)
+            final_payload, _final_snapshot = _preview_payload(requested)
             final_payload["status"] = "applied"
             final_payload["selectedViolations"] = [
                 violation.to_dict() for violation in to_acknowledge
@@ -374,8 +465,8 @@ def _apply(requested, initial_preview):
         if len(audit_ids) == 1:
             preview["auditId"] = next(iter(audit_ids))
         if not _stats_has_acknowledgements(requested):
-            recovery_high_water = _audit_high_water(
-                audit_ids, reviewed_high_water
+            recovery_high_water = _recovery_high_water(
+                audit_ids, snapshot.audit_ends
             )
             try:
                 _call_rebuild_error_hook()
@@ -395,7 +486,7 @@ def _apply(requested, initial_preview):
                     audit_ids,
                     exc,
                 )
-            final_payload, _final_selection = _preview_payload(requested)
+            final_payload, _final_snapshot = _preview_payload(requested)
             final_payload["status"] = "recovered"
             if len(audit_ids) == 1:
                 final_payload["auditId"] = next(iter(audit_ids))
@@ -408,7 +499,7 @@ def cmd_db_journal_repair(args) -> int:
     """Preview structural violations without mutating the journal or indexes."""
     try:
         requested = list(getattr(args, "violation", ()) or ())
-        payload, _selection = _preview_payload(requested)
+        payload, _snapshot = _preview_payload(requested)
     except (OSError, _lib_journal.JournalProtocolError) as exc:
         if bool(getattr(args, "json", False)):
             try:

package/bin/_cctally_rederive.py

@@ -27,6 +27,7 @@ import _cctally_core
 import _cctally_journal as _journal
 import _cctally_record as _record
 import _lib_journal
+import _lib_journal_router
 import _lib_json_envelope
 import _lib_rederive
 
@@ -441,40 +442,74 @@ def owned_conflicted_event_ids(selection) -> frozenset:
 
 def read_rederive_journal_prefix(
     high_water: "tuple[str, int] | None" = None,
-) -> tuple[list[dict], "tuple[str, int] | None", list[tuple[str, int]]]:
-    """Read and strictly decode one canonical journal prefix."""
+):
+    """Stream and strictly decode one canonical journal prefix.
+
+    Returns `(records, high_water, record_ends, protocol_prefix_evidence)`.
+    The evidence digests come from a `PrefixHashAccumulator` fed by the bytes
+    this pass is already reading. Before this, the prefix was materialized as
+    raw lines, materialized again as decoded records while the first form was
+    still referenced, walked a third time to produce the evidence, and re-read
+    from byte zero by `journal_prefix_hash` once per
+    `journal_protocol_resolution` op (#496 S5 §4).
+
+    Retention is DELIBERATELY unfiltered, unlike the rebuild's. The rebuild
+    keeps only the decision records and substitutes `None` placeholders for
+    everything else; the planner here reads every observation for cache
+    validation, desired-event derivation and preservation decisions, and walks
+    `records` in parallel with `record_ends`. Both lists stay complete and
+    aligned, so the win in this file is the removed double materialization and
+    the removed hash traversals, not reduced retention.
+    """
     if high_water is None:
         high_water = _journal.journal_high_water()
     if high_water is None:
-        return [], None, []
+        return [], None, [], ()
+    segments = _journal.list_segments()
+    if high_water[0] not in segments:
+        raise OSError(
+            f"journal high-water segment is unavailable: {high_water[0]}"
+        )
     records: list[dict] = []
     record_ends: list[tuple[str, int]] = []
+    evidence: list = []
     malformed = 0
-    for segment, offset, raw in _journal._read_range(None, high_water):
+    prior_high_water = None
+    hasher = _lib_journal_router.PrefixHashAccumulator()
+    for segment, offset, raw in _journal._iter_range_with_segments(
+        None,
+        high_water,
+        segments,
+        on_segment=lambda name: hasher.begin_segment(name, prior_high_water),
+        on_bytes=hasher.extend,
+    ):
         record = _lib_journal.decode_line(raw)
+        record_end = (segment, offset + len(raw) + 1)
         if record is None:
             malformed += 1
+            prior_high_water = record_end
             continue
+        if record.get("t") == "op":
+            _journal._capture_protocol_prefix_evidence(
+                record,
+                prior_high_water,
+                evidence,
+                hasher=hasher,
+            )
         records.append(record)
-        record_ends.append((segment, offset + len(raw) + 1))
+        record_ends.append(record_end)
+        prior_high_water = record_end
+    # Released before the raise below, so a malformed prefix does not pin the
+    # accumulator's buffered segment — 410 MB on the maintainer's journal — on
+    # the traceback while the exception unwinds. On the success path the frame
+    # dies two statements later, so this mirrors the repair reader, where the
+    # release genuinely precedes a loop over every decoded record.
+    hasher = None
     if malformed:
         raise _lib_rederive.RederiveConflict(
             f"journal prefix contains {malformed} malformed line(s)"
         )
-    return records, high_water, record_ends
-
-
-def _protocol_prefix_evidence(records, record_ends):
-    evidence = []
-    prior_high_water = None
-    for record, record_end in zip(records, record_ends):
-        _journal._capture_protocol_prefix_evidence(
-            record,
-            prior_high_water,
-            evidence,
-        )
-        prior_high_water = record_end
-    return tuple(evidence)
+    return records, high_water, record_ends, tuple(evidence)
 
 
 def _read_only_journal_high_water() -> "tuple[str, int] | None":
@@ -603,12 +638,11 @@ def _preview_from_snapshot(
     if journal_high_water is None:
         journal_high_water = _read_only_journal_high_water()
     if journal_high_water is None:
-        records, high_water, record_ends = [], None, []
+        records, high_water, record_ends, protocol_evidence = [], None, [], ()
     else:
-        records, high_water, record_ends = read_rederive_journal_prefix(
-            journal_high_water
+        records, high_water, record_ends, protocol_evidence = (
+            read_rederive_journal_prefix(journal_high_water)
         )
-    protocol_evidence = _protocol_prefix_evidence(records, record_ends)
     with _open_cache_read_view() as cache:
         plan = plan_claude_usage(
             records,

package/bin/_lib_journal.py

@@ -242,6 +242,46 @@ def bootstrap_id(table: str, rowid: int) -> str:
     return f"b:{table}:{rowid}"
 
 
+def reusable_bootstrap_name(candidate_digest, candidate_size, existing):
+    """The already-published bootstrap segment a cutover may reuse verbatim.
+
+    `existing` is `(name, byte_length_or_None, sha256_hex_or_None)` for EVERY
+    published segment the caller found. A `None` digest means the caller did not
+    read that segment, which it does only when the length already differs; a
+    `None` length means it could not stat the file at all. Neither can match, and
+    reporting the segment anyway is required — see the ordering rule below.
+
+    Reuse requires the CANONICALLY NEWEST bootstrap to be the exact match, on
+    both length and digest. A crash-after-rename retry re-exports byte-identical
+    lines, so reusing that orphan makes the retry idempotent on disk instead of
+    only idempotent on fold (#496 S5 §3), and timestamps increase monotonically,
+    so the orphan an immediately-prior attempt left IS the newest bootstrap.
+
+    Reusing an older match instead would stamp the cursor behind a bootstrap the
+    cursor does not cover, and the next ingest would fold that stale bootstrap's
+    records into stats.db. Writing a fresh segment is the pre-reuse behaviour and
+    restores the pre-reuse invariant, because a minted name always sorts last.
+
+    Returns None when the newest bootstrap does not match, which covers the
+    ordinary first-cutover path, the genuinely-differing-export path, and the
+    stale-match path alike.
+    """
+    bootstraps = [
+        (name, size, digest)
+        for name, size, digest in existing
+        if name.startswith(BOOTSTRAP_PREFIX)
+    ]
+    if not bootstraps:
+        return None
+    name, size, digest = max(
+        bootstraps, key=lambda entry: segment_sort_key(entry[0]))
+    if size is None or digest is None:
+        return None
+    if size == candidate_size and digest == candidate_digest:
+        return name
+    return None
+
+
 def evt_id(kind: str, *parts: object) -> str:
     """Natural-key id for an evt line: ``"<kind>:" + ":".join(str(p) …)``.
 

package/bin/_lib_journal_router.py

@@ -0,0 +1,234 @@
+"""Pure record-routing kernel for the stats rebuild's journal read pass (#496 S4).
+
+The rebuild used to materialize the whole journal twice: `_read_range` built a
+list of every raw line, and the decode loop built a second list of every parsed
+record while the first was still referenced. On the maintainer's install that is
+1,954,007 lines and 1.72 GB producing an 8.08 GiB peak, of which the stats fold
+consumes 99,289 records (5.08%).
+
+`bin/_cctally_doctor.py`'s conflict scan already established the shape this
+kernel generalizes: retain only what the effective selector consumes and drop
+everything else as it is decoded (#374 review, measured at 4.3 GB of peak RSS
+for an identical result).
+
+No I/O and no imports from `_cctally_journal`, so the rules here are unit
+testable without a journal on disk.
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+#: The record types the stats rebuild retains decoded. `resolve_effective_events`
+#: acts only on evt / correction / correction_batch and the protocol-resolution
+#: op; the op-fold stream takes only ops whose kind is in `FOLD_APPLIERS`.
+#: Deliberately identical to `_cctally_doctor._CONFLICT_SCAN_RECORD_TYPES` — the
+#: two must not drift, because both feed the same shared selector.
+RETAINED_RECORD_TYPES = frozenset({"evt", "correction", "correction_batch", "op"})
+
+
+class LastSeenAccumulator:
+    """Reproduce `_derive_account_last_seen`'s contribution set from a stream.
+
+    The rebuild normalizes every record and then takes `_account_of`, which
+    reads a top-level ``account`` or an ``account_observe`` op's
+    ``payload.account_key``. `_normalize_legacy_account_stamp` writes a
+    top-level ``account`` ONLY for ``t == "obs"``; a legacy evt or op instead
+    gets ``payload.account_key``, which `_account_of` does not read.
+
+    So exactly three classes contribute, and a provider-wide maximum over every
+    legacy line would over-count — advancing `last_seen_utc` from legacy events
+    and vendor-tagged budget events that contribute nothing today. The Claude
+    legacy bucket is deferred because the cutover account is not known until the
+    stream reaches it, at 92.9% of a production journal.
+    """
+
+    __slots__ = ("stamped", "legacy_claude_at", "legacy_codex_at")
+
+    def __init__(self) -> None:
+        self.stamped: dict = {}
+        self.legacy_claude_at = None
+        self.legacy_codex_at = None
+
+    def observe(self, record, provider_of_legacy) -> None:
+        """Fold one record. `provider_of_legacy` is `classify_legacy_provider`."""
+        at = record.get("at")
+        if not at:
+            return
+        account = record.get("account")
+        if isinstance(account, str) and account:
+            self._bump(account, at)
+            return
+        record_type = record.get("t")
+        if record_type == "op":
+            payload = record.get("payload") or {}
+            if payload.get("kind") == "account_observe":
+                key = payload.get("account_key")
+                if isinstance(key, str) and key:
+                    self._bump(key, at)
+            return
+        if record_type != "obs":
+            # A legacy evt normalizes into `payload.account_key`, which
+            # `_account_of` ignores. Contributing here would move last-seen.
+            return
+        provider = provider_of_legacy(record)
+        if provider == "claude":
+            if self.legacy_claude_at is None or at > self.legacy_claude_at:
+                self.legacy_claude_at = at
+        elif provider == "codex":
+            if self.legacy_codex_at is None or at > self.legacy_codex_at:
+                self.legacy_codex_at = at
+
+    def _bump(self, key: str, at: str) -> None:
+        previous = self.stamped.get(key)
+        if previous is None or at > previous:
+            self.stamped[key] = at
+
+    def resolve(self, cutover_claude: str, unattributed: str) -> dict:
+        """Apply the deferred legacy buckets and return the final MAX map."""
+        out = dict(self.stamped)
+        if self.legacy_claude_at is not None:
+            previous = out.get(cutover_claude)
+            if previous is None or self.legacy_claude_at > previous:
+                out[cutover_claude] = self.legacy_claude_at
+        if self.legacy_codex_at is not None:
+            previous = out.get(unattributed)
+            if previous is None or self.legacy_codex_at > previous:
+                out[unattributed] = self.legacy_codex_at
+        return out
+
+
+class PrefixEvidenceUnavailable(LookupError):
+    """A protocol-evidence digest was asked for a prefix the stream dropped.
+
+    Never expected: an evidence point is always the end of the line immediately
+    preceding a `journal_protocol_resolution` op, so it is either inside the
+    segment being streamed or the boundary registered at the last segment
+    transition. Raised rather than silently degraded, because the alternative is
+    a rebuild that quietly disagrees with `journal_prefix_hash`.
+    """
+
+
+class PrefixHashAccumulator:
+    """`journal_prefix_hash` computed from the bytes the rebuild already read.
+
+    `journal_prefix_hash(prior_high_water)` does `path.read_bytes()[:size]` on
+    every segment through the prefix, so one `journal_protocol_resolution` op
+    re-reads the whole journal up to its own position and builds a full-segment
+    bytes transient. This accumulator reproduces the identical durable digest
+    from the bytes the single streaming pass is reading anyway (#496 S4 §5.2).
+
+    The framing is `journal_prefix_hash`'s, verbatim: per segment, the 4-byte
+    big-endian name length, the name, the 8-byte big-endian data length, then
+    the data. Completed segments are absorbed into a running `sha256`; only the
+    segment currently being streamed is buffered, so residency is bounded by one
+    segment. At a segment transition the caller passes the boundary the next
+    record's `prior_high_water` will name, which is the ONE offset in the
+    outgoing segment that can still be asked for; its digest is precomputed
+    before the buffer is released.
+    """
+
+    # A transition can only ever register one boundary, and consecutive empty
+    # segments re-register the same one. A handful of slots is therefore already
+    # generous; the cap exists so a pathological journal cannot grow this map.
+    # Eviction is safe because a registered boundary is only ever READ
+    # IMMEDIATELY AFTER the `begin_segment` that registered it: a resolution op
+    # can name a previous segment's end only when it is the first line of the
+    # new segment, and every later position falls in the `_current_name` branch
+    # of `digest_at`. So the cap bounds a map that never needs more than the
+    # most recent entry; widening it buys nothing and narrowing it below the
+    # runs of empty segments a journal can contain would start dropping the one
+    # entry that is still live.
+    _MAX_BOUNDARIES = 16
+
+    def __init__(self) -> None:
+        self._running = hashlib.sha256()
+        self._current_name = None
+        self._current = bytearray()
+        self._boundaries: dict = {}
+        self._boundary_order: list = []
+        #: Bytes fed into an evidence digest, reported as the `protocol_evidence`
+        #: traversal pass. Zero on any journal with no resolution op.
+        self.bytes_hashed = 0
+        self.digests_computed = 0
+
+    # -- feeding ----------------------------------------------------------
+
+    def begin_segment(self, name: str, boundary=None) -> None:
+        """Start `name`, absorbing whatever segment was open before it.
+
+        `boundary` is the `(segment, offset)` the next record's evidence would
+        name — i.e. the streaming loop's current `prior_high_water`. It is
+        resolved and cached HERE because the outgoing segment's bytes are gone
+        immediately afterwards.
+        """
+        if boundary is not None:
+            self._register_boundary(boundary)
+        if self._current_name is not None:
+            # `hashlib.update` accepts the buffer directly, so the outgoing
+            # segment is framed WITHOUT a copy of itself. The maintainer's
+            # largest segment is 410 MB, and copying it here briefly doubled
+            # that at every transition.
+            with memoryview(self._current) as data:
+                self._absorb(self._current_name, data)
+        self._current_name = name
+        self._current = bytearray()
+
+    def extend(self, data: bytes) -> None:
+        """Absorb raw bytes read from the segment currently open."""
+        self._current.extend(data)
+
+    # -- reading ----------------------------------------------------------
+
+    def digest_at(self, high_water) -> "str | None":
+        """`journal_prefix_hash(high_water)`, from the streamed bytes."""
+        if high_water is None:
+            return None
+        segment, offset = high_water
+        if segment == self._current_name:
+            digest = self._running.copy()
+            with memoryview(self._current)[:offset] as data:
+                self._frame(digest, segment, data)
+                self.bytes_hashed += len(data)
+            self.digests_computed += 1
+            return "sha256:" + digest.hexdigest()
+        cached = self._boundaries.get((segment, offset))
+        if cached is None:
+            raise PrefixEvidenceUnavailable(
+                f"no streamed prefix evidence for {segment}@{offset}"
+            )
+        self.bytes_hashed += cached[1]
+        self.digests_computed += 1
+        return cached[0]
+
+    # -- internals --------------------------------------------------------
+
+    def _register_boundary(self, boundary) -> None:
+        segment, offset = boundary
+        if segment != self._current_name:
+            # Already registered at an earlier transition (a run of empty
+            # segments leaves `prior_high_water` unchanged), or never streamed.
+            return
+        key = (segment, offset)
+        if key in self._boundaries:
+            return
+        digest = self._running.copy()
+        with memoryview(self._current)[:offset] as data:
+            self._frame(digest, segment, data)
+            size = len(data)
+        self._boundaries[key] = ("sha256:" + digest.hexdigest(), size)
+        self._boundary_order.append(key)
+        while len(self._boundary_order) > self._MAX_BOUNDARIES:
+            self._boundaries.pop(self._boundary_order.pop(0), None)
+
+    def _absorb(self, name, data) -> None:
+        self._frame(self._running, name, data)
+
+    @staticmethod
+    def _frame(digest, name: str, data) -> None:
+        """`data` is any bytes-like buffer; `hashlib` consumes it in place."""
+        encoded = name.encode("utf-8")
+        digest.update(len(encoded).to_bytes(4, "big"))
+        digest.update(encoded)
+        digest.update(len(data).to_bytes(8, "big"))
+        digest.update(data)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.92.1",
+  "version": "1.92.3",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {
@@ -103,6 +103,7 @@
     "bin/_lib_fmt.py",
     "bin/_lib_forecast.py",
     "bin/_lib_journal.py",
+    "bin/_lib_journal_router.py",
     "bin/_lib_json_envelope.py",
     "bin/_lib_jsonl.py",
     "bin/_lib_log.py",