cctally 1.116.1 → 1.117.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/README.md +4 -6
  3. package/bin/_cctally_account.py +57 -3
  4. package/bin/_cctally_cache.py +5720 -885
  5. package/bin/_cctally_claude_attribution.py +997 -0
  6. package/bin/_cctally_completion.py +101 -28
  7. package/bin/_cctally_core.py +235 -12
  8. package/bin/_cctally_dashboard.py +263 -17
  9. package/bin/_cctally_dashboard_conversation.py +107 -21
  10. package/bin/_cctally_dashboard_envelope.py +44 -0
  11. package/bin/_cctally_db.py +928 -80
  12. package/bin/_cctally_diagnosis_sources.py +78 -13
  13. package/bin/_cctally_doctor.py +211 -86
  14. package/bin/_cctally_five_hour.py +446 -22
  15. package/bin/_cctally_forecast.py +302 -6
  16. package/bin/_cctally_journal.py +2418 -158
  17. package/bin/_cctally_milestone_history.py +379 -91
  18. package/bin/_cctally_oauth_samples.py +185 -7
  19. package/bin/_cctally_parser.py +38 -0
  20. package/bin/_cctally_project.py +34 -8
  21. package/bin/_cctally_quarantine.py +821 -343
  22. package/bin/_cctally_quota.py +69 -4
  23. package/bin/_cctally_quota_calibration.py +677 -3
  24. package/bin/_cctally_quota_model.py +927 -127
  25. package/bin/_cctally_record.py +922 -445
  26. package/bin/_cctally_rederive.py +119 -15
  27. package/bin/_cctally_statusline.py +1048 -176
  28. package/bin/_cctally_store.py +544 -110
  29. package/bin/_cctally_tui.py +455 -42
  30. package/bin/_cctally_update.py +77 -14
  31. package/bin/_lib_account_protocol.py +227 -19
  32. package/bin/_lib_claude_attribution.py +421 -0
  33. package/bin/_lib_clone_copy.py +30 -0
  34. package/bin/_lib_codex_conversation_query.py +45 -9
  35. package/bin/_lib_codex_conversation_watch.py +72 -13
  36. package/bin/_lib_codex_rollout_container.py +234 -19
  37. package/bin/_lib_codex_worker_lifecycle.py +374 -0
  38. package/bin/_lib_credit.py +22 -13
  39. package/bin/_lib_dashboard_sources.py +257 -18
  40. package/bin/_lib_detector_access_registry.py +1335 -166
  41. package/bin/_lib_doctor.py +276 -92
  42. package/bin/_lib_ingest_frontier.py +269 -36
  43. package/bin/_lib_journal.py +273 -22
  44. package/bin/_lib_jsonl.py +12 -0
  45. package/bin/_lib_meter_rate_change.py +72 -0
  46. package/bin/_lib_outcome_quarantine.py +917 -554
  47. package/bin/_lib_provider_activity.py +24 -6
  48. package/bin/_lib_quota_calibration.py +57 -3
  49. package/bin/_lib_quota_copy.py +7 -2
  50. package/bin/_lib_quota_lineage.py +613 -0
  51. package/bin/_lib_quota_model.py +464 -33
  52. package/bin/_lib_rate_change_delivery.py +16 -0
  53. package/bin/_lib_reclaim_planner.py +6 -4
  54. package/bin/_lib_rederive.py +2046 -21
  55. package/bin/_lib_selector_state.py +131 -3
  56. package/bin/_lib_snapshot_cache.py +8 -0
  57. package/bin/_lib_stale_proof.py +113 -4
  58. package/bin/_lib_statusline.py +72 -3
  59. package/bin/_lib_statusline_candidates.py +246 -42
  60. package/bin/_lib_tick_stats.py +10 -5
  61. package/bin/_lib_write_io.py +419 -6
  62. package/bin/cctally +28 -11
  63. package/dashboard/static/assets/{ConversationsView-Dflb_myA.js → ConversationsView-oqNsWzWV.js} +1 -1
  64. package/dashboard/static/assets/{DoctorModal-DFX5CfIs.js → DoctorModal-B0DnU9d9.js} +1 -1
  65. package/dashboard/static/assets/ModalRoot-CYua2wP_.js +1 -0
  66. package/dashboard/static/assets/{ProjectsDrillPanel-C3PJy1xx.js → ProjectsDrillPanel-DSxXQSa-.js} +1 -1
  67. package/dashboard/static/assets/{SourceDetailModal-BczsWKhD.js → SourceDetailModal-BleDpQqG.js} +1 -1
  68. package/dashboard/static/assets/{UpdateModal-Os-Lo5cs.js → UpdateModal-CMqaAkSK.js} +1 -1
  69. package/dashboard/static/assets/{index-CYZ3NLqF.js → index-BjQV-0-D.js} +3 -3
  70. package/dashboard/static/assets/index-D34eYhAc.css +1 -0
  71. package/dashboard/static/assets/{outlineNavigation-k-zIif6W.js → outlineNavigation-CO-VWBm7.js} +1 -1
  72. package/dashboard/static/assets/{useKeymap-CW7Up0Ay.js → useKeymap-CUgEnnua.js} +1 -1
  73. package/dashboard/static/dashboard.html +3 -3
  74. package/package.json +5 -1
  75. package/dashboard/static/assets/ModalRoot-HlxoagIa.js +0 -1
  76. package/dashboard/static/assets/index-BKITk1CT.css +0 -1
@@ -539,6 +539,25 @@ def _hook_tick_make_mock_refresh(*args, **kwargs):
539
539
  # manual replay with stale 5h flags doesn't fail-close on a
540
540
  # documented recovery path.
541
541
  _RECORD_USAGE_WEEK_PAST_SLACK_S = 30 * 86400
542
+
543
+
544
+ def _weekly_resets_rejection_notice(resets_at: int, now_dt) -> str:
545
+ """The stderr notice of a weekly reset outside the plausibility band.
546
+ Shared with the authoritative OAuth writer, which checks the band before
547
+ any fence (#948 spec 6.4), so the user sees the same rejection."""
548
+ return (f"[record-usage] rejecting --resets-at={resets_at}: outside "
549
+ f"plausibility band [now-30d, now+8d]; "
550
+ f"now={int(now_dt.timestamp())} ({now_dt.isoformat()}). "
551
+ f"No row written.")
552
+
553
+
554
+ def _five_hour_resets_drop_notice(resets_at: int, now_dt) -> str:
555
+ """The stderr notice of a five-hour reset outside its band (dropped;
556
+ the weekly reading is still written). Shared like the weekly notice."""
557
+ return (f"[record-usage] dropping --five-hour-resets-at={resets_at}: "
558
+ f"outside plausibility band [now-10m, now+6h]; "
559
+ f"now={int(now_dt.timestamp())} ({now_dt.isoformat()}). "
560
+ f"Weekly snapshot still written; 5h fields will be NULL.")
542
561
  _RECORD_USAGE_WEEK_FUTURE_BAND_S = 8 * 86400
543
562
  _RECORD_USAGE_5H_PAST_SLACK_S = 600 # 10 min; matches _FIVE_HOUR_JITTER_FLOOR_SECONDS
544
563
  _RECORD_USAGE_5H_FUTURE_BAND_S = 6 * 3600
@@ -583,13 +602,24 @@ class FiveHourResetEvent:
583
602
  never from the SQLite rowid. ``row_id`` is the materialized foreign-key
584
603
  target inside ONE materialization (milestone ``reset_event_id``); it is
585
604
  excluded from equality and must never enter retry identity, because a
586
- rebuild renumbers it."""
605
+ rebuild renumbers it.
606
+
607
+ #943 spec 4.2.2/4.2.4: ``effective_reset_at_utc`` / ``floor_epoch`` are
608
+ the credit's floored ten-minute SLOT, its identity (the ``fhc`` id, the
609
+ UNIQUE, milestones' ``reset_event_ref``, the credit revision).
610
+ ``boundary_at_utc`` / ``boundary_epoch`` are its exact post-credit
611
+ BOUNDARY: the ``five_hour_credit_boundaries`` companion's arming capture
612
+ second when a companion with the same natural key and a matching
613
+ ``credit_revision`` exists, otherwise the slot. Every post-credit read
614
+ compares with ``>=`` against the boundary."""
587
615
 
588
616
  account_key: str
589
617
  canonical_window_key: int
590
618
  effective_reset_at_utc: str
591
619
  floor_epoch: int
592
620
  logical_generation: str
621
+ boundary_at_utc: str
622
+ boundary_epoch: int
593
623
  row_id: int = field(default=0, compare=False)
594
624
 
595
625
 
@@ -617,22 +647,30 @@ def resolve_five_hour_reset_event(
617
647
  rebuild that renumbers rows cannot change which event is active. A database
618
648
  or query error PROPAGATES: it is not evidence that no reset happened.
619
649
  ``NoFiveHourResetEvent`` is returned only when the exact lookup finds no
620
- row."""
650
+ row.
651
+
652
+ The event's boundary (#943 spec 4.2.2/4.2.4) is resolved here, once, for
653
+ every post-credit reader: the companion row of the same natural key whose
654
+ ``credit_revision`` equals the selected credit row's
655
+ `_five_hour_credit_revision`, else the slot. A companion with no credit,
656
+ or with a mismatched revision, is inert. A store without the companion
657
+ table has no companion."""
621
658
  if not isinstance(account_key, str) or not account_key:
622
659
  raise ValueError("five-hour reset resolution requires an exact account")
623
660
  import _lib_journal
624
661
 
625
662
  key = int(canonical_window_key)
626
663
  rows = conn.execute(
627
- "SELECT detected_at_utc, effective_reset_at_utc, id "
664
+ "SELECT detected_at_utc, effective_reset_at_utc, id, "
665
+ " prior_percent, post_percent "
628
666
  "FROM five_hour_reset_events "
629
667
  "WHERE five_hour_window_key = ? AND account_key = ?",
630
668
  (key, account_key),
631
669
  ).fetchall()
632
670
  best = None
633
671
  for row in rows:
634
- effective = str(row["effective_reset_at_utc"])
635
- detected = str(row["detected_at_utc"])
672
+ effective = str(row[1])
673
+ detected = str(row[0])
636
674
  identity = _lib_journal.evt_id("fhc", account_key, key, effective)
637
675
  order = (
638
676
  int(parse_iso_datetime(effective, "five_hour_reset_events.effective").timestamp()),
@@ -644,16 +682,48 @@ def resolve_five_hour_reset_event(
644
682
  if best is None:
645
683
  return NoFiveHourResetEvent(account_key, key)
646
684
  order, row, effective, detected, identity = best
685
+ boundary_at, boundary_epoch = effective, order[0]
686
+ companion = _five_hour_credit_companion(
687
+ conn, account_key=account_key, canonical_window_key=key,
688
+ effective_reset_at_utc=effective)
689
+ if companion is not None and str(companion[1]) == _five_hour_credit_revision(
690
+ (detected, row[3], row[4], effective)):
691
+ boundary_at = str(companion[0])
692
+ boundary_epoch = int(parse_iso_datetime(
693
+ boundary_at, "five_hour_credit_boundaries.boundary").timestamp())
647
694
  return FiveHourResetEvent(
648
695
  account_key=account_key,
649
696
  canonical_window_key=key,
650
697
  effective_reset_at_utc=effective,
651
698
  floor_epoch=order[0],
652
699
  logical_generation=f"{effective}|{detected}|{identity}",
653
- row_id=int(row["id"]),
700
+ boundary_at_utc=boundary_at,
701
+ boundary_epoch=boundary_epoch,
702
+ row_id=int(row[2]),
654
703
  )
655
704
 
656
705
 
706
+ def _five_hour_credit_companion(conn, *, account_key, canonical_window_key,
707
+ effective_reset_at_utc):
708
+ """``(boundary_at_utc, credit_revision)`` of the boundary companion with
709
+ the credit's natural key, or None (#943 spec 4.2.2). A store that
710
+ predates the companion table has none; any other database error
711
+ propagates."""
712
+ try:
713
+ return conn.execute(
714
+ "SELECT boundary_at_utc, credit_revision "
715
+ "FROM five_hour_credit_boundaries "
716
+ "WHERE account_key = ? AND five_hour_window_key = ? "
717
+ " AND effective_reset_at_utc = ?",
718
+ (account_key, int(canonical_window_key),
719
+ str(effective_reset_at_utc)),
720
+ ).fetchone()
721
+ except sqlite3.OperationalError as exc:
722
+ if "no such table" in str(exc):
723
+ return None
724
+ raise
725
+
726
+
657
727
  def _resolve_active_five_hour_reset_event_id(
658
728
  conn: "sqlite3.Connection",
659
729
  five_hour_window_key: int,
@@ -1271,6 +1341,20 @@ def _record_budget_milestone_for_vendor(
1271
1341
  eprint(f"[budget-milestone:{vendor}] account attribution unavailable; "
1272
1342
  f"skipping the {account_key} ladder this tick ({exc})")
1273
1343
  return 0
1344
+ except _cctally_cache.CodexReadDeferred as exc:
1345
+ # #981 A5: under the hook's read policy a Codex read that cannot prove
1346
+ # a complete snapshot defers. Like the attribution skip above, this
1347
+ # ladder is skipped this tick — nothing armed (the spend leg precedes
1348
+ # every crossing, so `pending_alerts` is empty), never re-raised — and
1349
+ # recorded on the policy so the hook leaves its lifecycle markers due
1350
+ # and the next due hook retries. Only the Codex vendor reads under the
1351
+ # policy; a Claude ladder can never raise it.
1352
+ if vendor != "codex":
1353
+ raise
1354
+ policy = _cctally_cache._active_hook_codex_read_policy()
1355
+ if policy is not None:
1356
+ policy.record_deferral(f"codex_budget:{account_key}", exc.reason)
1357
+ return 0
1274
1358
  except Exception as exc:
1275
1359
  # Exception discipline (6c-gate P1): passed-conn (ingest) path re-raises
1276
1360
  # so a failure ABORTS the cycle (invariant ii); this covers both budget
@@ -1704,7 +1788,8 @@ def maybe_record_codex_budget_milestone(
1704
1788
 
1705
1789
 
1706
1790
  def _forecast_calibrated_projection(
1707
- now_utc, week_start_at, week_end_at, *, account_key=None):
1791
+ now_utc, week_start_at, week_end_at, *, account_key=None,
1792
+ stats_conn=None):
1708
1793
  """Return the model-backed projection the forecast would publish here.
1709
1794
 
1710
1795
  `apply_regime` re-tests support against THIS week's population, so a
@@ -1744,7 +1829,8 @@ def _forecast_calibrated_projection(
1744
1829
  try:
1745
1830
  value, _code = _cctally()._load_sibling(
1746
1831
  "_cctally_forecast")._calibrated_projection(
1747
- now_utc, week_start_at, week_end_at, account_key=account_key)
1832
+ now_utc, week_start_at, week_end_at, account_key=account_key,
1833
+ stats_conn=stats_conn)
1748
1834
  return value
1749
1835
  except Exception:
1750
1836
  return None
@@ -1837,8 +1923,10 @@ def _weekly_pct_week_avg_projection(conn, now_utc, *, account_key=None):
1837
1923
  has_sample_ge_24h=any(s[0] <= target_24h for s in samples),
1838
1924
  )
1839
1925
 
1926
+ # #1015: the lineage assessment reads this cycle's own stats connection.
1840
1927
  calibrated = _forecast_calibrated_projection(
1841
- now_utc, week_start_at, week_end_at, account_key=account_key)
1928
+ now_utc, week_start_at, week_end_at, account_key=account_key,
1929
+ stats_conn=conn)
1842
1930
  if calibrated is not None:
1843
1931
  return (calibrated, confidence == "low")
1844
1932
 
@@ -2088,11 +2176,24 @@ def maybe_record_projected_alert(
2088
2176
  # skip_sync=True leg could read a cold cache and under-count.
2089
2177
  # The pre-probe above already gated this, so a sync only runs
2090
2178
  # when a cross is genuinely owed; it's a near-no-op when warm.
2091
- c_inputs = _build_vendor_budget_inputs(
2092
- vendor="codex", period=c_period, target_usd=c_target,
2093
- alert_thresholds=c_thresholds, now_utc=now_utc,
2094
- config=cfg, tz=config_tz, skip_sync=False,
2095
- )
2179
+ import _cctally_cache
2180
+ try:
2181
+ c_inputs = _build_vendor_budget_inputs(
2182
+ vendor="codex", period=c_period,
2183
+ target_usd=c_target,
2184
+ alert_thresholds=c_thresholds, now_utc=now_utc,
2185
+ config=cfg, tz=config_tz, skip_sync=False,
2186
+ )
2187
+ except _cctally_cache.CodexReadDeferred as exc:
2188
+ # #981 A5: the Codex axis only is skipped this tick
2189
+ # and recorded on the hook's read policy; the weekly
2190
+ # and Claude budget legs above already evaluated.
2191
+ c_inputs = None
2192
+ policy = (
2193
+ _cctally_cache._active_hook_codex_read_policy())
2194
+ if policy is not None:
2195
+ policy.record_deferral(
2196
+ "codex_projected", exc.reason)
2096
2197
  if c_inputs is not None:
2097
2198
  c_status = compute_budget_status(c_inputs)
2098
2199
  if not c_status.low_confidence:
@@ -2537,10 +2638,155 @@ def _flag_blocks_spanning_week_resets(conn, account_key: str) -> None:
2537
2638
  )
2538
2639
 
2539
2640
 
2641
+ def _refresh_open_five_hour_block(conn, journal_ctx, account_key: str,
2642
+ five_hour_window_key: int, *,
2643
+ as_of: str) -> int:
2644
+ """Project one OPEN block of ``(account_key, five_hour_window_key)``
2645
+ through the shared capture-order pair (#956 class 1, spec 4.5.1). The
2646
+ ownership context is every block window of the account whose interval
2647
+ reaches the block's load range (`_five_hour_ownership_windows`, the same
2648
+ interval-overlap set the live totals use, so no window outside it can own
2649
+ an entry the projection loads). Returns 1 when a block was refreshed."""
2650
+ import _cctally_five_hour as _fh
2651
+
2652
+ block = conn.execute(
2653
+ "SELECT id, block_start_at, five_hour_resets_at, last_observed_at_utc "
2654
+ " FROM five_hour_blocks "
2655
+ " WHERE account_key = ? AND five_hour_window_key = ? AND is_closed = 0",
2656
+ (account_key, int(five_hour_window_key)),
2657
+ ).fetchone()
2658
+ if block is None:
2659
+ return 0
2660
+ end = _fh.select_open_block_end(
2661
+ conn, account_key=account_key,
2662
+ five_hour_window_key=int(five_hour_window_key))
2663
+ try:
2664
+ start = parse_iso_datetime(
2665
+ block["block_start_at"], "five_hour_blocks.block_start_at")
2666
+ reset = parse_iso_datetime(
2667
+ block["five_hour_resets_at"],
2668
+ "five_hour_blocks.five_hour_resets_at")
2669
+ cutoff = parse_iso_datetime(
2670
+ end.captured_at_utc if end is not None
2671
+ else block["last_observed_at_utc"],
2672
+ "five_hour_blocks.last_observed_at_utc")
2673
+ except ValueError as exc:
2674
+ eprint(f"[5h-block] bad stored block bounds, not refreshed: {exc}")
2675
+ return 0
2676
+ ownership = _five_hour_ownership_windows(
2677
+ conn,
2678
+ account_key=account_key,
2679
+ target_key=int(five_hour_window_key),
2680
+ target_start=start.astimezone(dt.timezone.utc),
2681
+ target_reset=reset.astimezone(dt.timezone.utc),
2682
+ load_start=start,
2683
+ load_end=cutoff,
2684
+ )
2685
+ _fh.project_open_block_end(
2686
+ conn, block, end, ownership=ownership, journal_ctx=journal_ctx,
2687
+ as_of=as_of)
2688
+ return 1
2689
+
2690
+
2691
+ def _insert_five_hour_block_opening(
2692
+ conn, *, account_key: str, five_hour_window_key: int,
2693
+ five_hour_resets_at: str, block_start_at: str,
2694
+ first_observed_at_utc: str, created_at_utc: str,
2695
+ opening_record_id: str, creation_kind: str, five_hour_percent: float,
2696
+ seven_day_pct_at_block_start, weekly_observation_held: bool,
2697
+ weekly_basis_captured_at_utc,
2698
+ ) -> None:
2699
+ """Insert one block's opening fact (#956 spec 4.6.1/4.6.2), within the
2700
+ caller's transaction. Rows are immutable: the live writer only inserts,
2701
+ and a window that already has one keeps it. `journal_id` stays NULL
2702
+ until harvest journals the row as `five_hour_block_open`."""
2703
+ conn.execute(
2704
+ """
2705
+ INSERT OR IGNORE INTO five_hour_block_openings (
2706
+ account_key, five_hour_window_key, five_hour_resets_at,
2707
+ block_start_at, first_observed_at_utc, created_at_utc,
2708
+ opening_record_id, creation_kind, five_hour_percent,
2709
+ seven_day_pct_at_block_start, weekly_observation_held,
2710
+ weekly_basis_captured_at_utc
2711
+ )
2712
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
2713
+ """,
2714
+ (
2715
+ account_key, int(five_hour_window_key), five_hour_resets_at,
2716
+ block_start_at, first_observed_at_utc, created_at_utc,
2717
+ opening_record_id, creation_kind, float(five_hour_percent),
2718
+ seven_day_pct_at_block_start,
2719
+ 1 if weekly_observation_held else 0,
2720
+ weekly_basis_captured_at_utc if weekly_observation_held else None,
2721
+ ),
2722
+ )
2723
+
2724
+
2725
+ def mark_five_hour_window_dirty(journal_ctx, account_key: str,
2726
+ five_hour_window_key: int, *, conn=None,
2727
+ as_of: "str | None" = None) -> None:
2728
+ """Record that ``(account_key, five_hour_window_key)``'s open block may
2729
+ no longer equal its capture-order projection (#956 class 1, spec 4.5.2).
2730
+
2731
+ On the ingest path the key joins the cycle's
2732
+ ``journal_ctx.five_hour_dirty_windows`` and is refreshed at the next
2733
+ flush point. A direct caller (``journal_ctx`` None, or a context without
2734
+ the set) passes ``conn`` and has the open block refreshed immediately, so
2735
+ it must mark AFTER the mutation it reports; the keys themselves are
2736
+ collected before any row is cleared or deleted."""
2737
+ if account_key is None or five_hour_window_key is None:
2738
+ return
2739
+ dirty = getattr(journal_ctx, "five_hour_dirty_windows", None)
2740
+ if dirty is not None:
2741
+ dirty.add((account_key, int(five_hour_window_key)))
2742
+ return
2743
+ if conn is not None:
2744
+ _refresh_open_five_hour_block(
2745
+ conn, journal_ctx, account_key, int(five_hour_window_key),
2746
+ as_of=as_of or now_utc_iso())
2747
+
2748
+
2749
+ def mark_account_open_blocks_dirty(conn, journal_ctx, account_key: str, *,
2750
+ as_of: "str | None" = None) -> None:
2751
+ """Mark every OPEN block of ``account_key`` dirty (#956 class 1). A
2752
+ block creation changes the window set ownership is resolved over, so a
2753
+ late-created predecessor takes overlap entries from its open successor;
2754
+ a mutation whose affected windows are not named also uses this, since
2755
+ only open blocks are ever refreshed."""
2756
+ for row in conn.execute(
2757
+ "SELECT five_hour_window_key FROM five_hour_blocks "
2758
+ " WHERE account_key = ? AND is_closed = 0",
2759
+ (account_key,),
2760
+ ).fetchall():
2761
+ mark_five_hour_window_dirty(
2762
+ journal_ctx, account_key, int(row["five_hour_window_key"]),
2763
+ conn=conn, as_of=as_of)
2764
+
2765
+
2766
+ def flush_five_hour_dirty_windows(conn, journal_ctx, *, as_of: str,
2767
+ only: "set | None" = None) -> int:
2768
+ """Refresh the cycle's dirty OPEN blocks through the capture-order
2769
+ projection (#956 class 1, spec 4.5.2 flush points (a)-(d)) and clear
2770
+ them from the set. ``only`` restricts the flush to those keys (flush
2771
+ (c): the blocks about to close), leaving the rest dirty. A closed block
2772
+ is never refreshed. Returns the number of blocks refreshed."""
2773
+ dirty = getattr(journal_ctx, "five_hour_dirty_windows", None)
2774
+ if not dirty:
2775
+ return 0
2776
+ keys = sorted(dirty if only is None else dirty & set(only))
2777
+ dirty.difference_update(keys)
2778
+ refreshed = 0
2779
+ for account_key, window_key in keys:
2780
+ refreshed += _refresh_open_five_hour_block(
2781
+ conn, journal_ctx, account_key, window_key, as_of=as_of)
2782
+ return refreshed
2783
+
2784
+
2540
2785
  def maybe_update_five_hour_block(
2541
2786
  saved: dict[str, Any], *, conn=None, as_of: "str | None" = None,
2542
2787
  alert_sink: "list | None" = None, account_key: str = _lib_accounts.UNATTRIBUTED,
2543
- journal_ctx=None,
2788
+ journal_ctx=None, opening_record_id: "str | None" = None,
2789
+ creation_kind: str = "snapshot",
2544
2790
  ) -> None:
2545
2791
  """Upsert the current 5h block in five_hour_blocks; close strictly
2546
2792
  older open blocks; sweep naturally-expired blocks; flag blocks
@@ -2567,7 +2813,34 @@ def maybe_update_five_hour_block(
2567
2813
  ``journal_ctx`` makes a close durable at the transition itself. The complete
2568
2814
  parent + model/project child sets are frozen before the transaction can
2569
2815
  commit; an already-stamped closed block is immutable to later observations
2570
- and mutable cache growth."""
2816
+ and mutable cache growth.
2817
+
2818
+ #956 class 1 (spec 4.5): the block's END columns, totals, child sets,
2819
+ pricing provenance and cross flag are not this observation's. They are
2820
+ the capture-order projection of the window's surviving readings
2821
+ (`_cctally_five_hour.select_open_block_end` / `project_open_block_end`),
2822
+ the one the rebuild and derivation completion run too. This function
2823
+ marks its window dirty (and, on a creation, every open block of the
2824
+ account) and refreshes the dirty open blocks at two of the four flush
2825
+ points: (c) immediately before a close, for the blocks about to close, so
2826
+ the frozen close payload equals the projection; and (a) after the
2827
+ creation and close-older steps, so the code that follows reads projected
2828
+ values. The upsert's ``DO UPDATE`` no longer writes end columns or
2829
+ totals. Milestone money is unchanged: a crossing's cumulative and
2830
+ marginal cost are the totals computed to the crossing observation's own
2831
+ capture, not the block's projected end.
2832
+
2833
+ #956 class 2 (spec 4.6.2): when its upsert CREATES the block (no row
2834
+ existed for the window and the INSERT took), the same transaction
2835
+ inserts the block's opening fact (`five_hour_block_openings`, harvested
2836
+ as `five_hour_block_open`) from the values the upsert wrote, naming
2837
+ ``opening_record_id`` (the creating obs or op) and ``creation_kind``
2838
+ (``"heal"`` from the pipeline's step 4' rollover heal, else
2839
+ ``"snapshot"``), and re-links the window's five-hour milestones still at
2840
+ `block_id = 0` to the new block (spec 4.6.5). Only the step-4b pipeline
2841
+ passes ``opening_record_id``, so a seed is never created by step 4a's
2842
+ replay or its flush, and every seed falls inside harvest's change-counted
2843
+ window."""
2571
2844
  five_hour_percent = saved.get("fiveHourPercent")
2572
2845
  five_hour_resets_at = saved.get("fiveHourResetsAt")
2573
2846
  five_hour_window_key = saved.get("fiveHourWindowKey")
@@ -2672,12 +2945,6 @@ def maybe_update_five_hour_block(
2672
2945
  except ValueError as exc:
2673
2946
  eprint(f"[5h-block] bad stored resets_at, skipping: {exc}")
2674
2947
  return
2675
- current_is_frozen = (
2676
- prior is not None
2677
- and int(prior["is_closed"]) == 1
2678
- and prior["journal_id"] is not None
2679
- )
2680
-
2681
2948
  # Step 6 (totals) — done outside the transaction so the
2682
2949
  # cache.db read doesn't hold the stats.db write lock open.
2683
2950
  captured_at_dt = parse_iso_datetime(captured_at, "capturedAt")
@@ -2691,27 +2958,18 @@ def maybe_update_five_hour_block(
2691
2958
  load_end=captured_at_dt,
2692
2959
  )
2693
2960
  pricing_evidence = {}
2694
- # `db rederive`'s scratch replay alone supplies this sink (#869), keyed
2695
- # by the blocks whose historical close it must prove. It keeps the
2696
- # exact entries behind the totals this tick applies, so the planner
2697
- # proves a missing card from the very population that produced the
2698
- # replayed children. A frozen close's upsert applies nothing, so its
2699
- # later recomputations are not kept.
2700
- source_sink = getattr(journal_ctx, "block_source_evidence", None)
2701
- source_key = (account_key, int(five_hour_window_key))
2702
- owned_entries = (
2703
- [] if source_sink is not None and source_key in source_sink
2704
- and not current_is_frozen else None
2705
- )
2961
+ # The totals to THIS observation's capture: a new block's initial
2962
+ # values and the five-hour milestone money below (spec 4.5.1). The
2963
+ # block's stored end totals and children are the projection's
2964
+ # (`project_open_block_end`), which also feeds `db rederive`'s
2965
+ # `block_source_evidence` sink (#869) from the population behind the
2966
+ # totals it applies.
2706
2967
  totals = _compute_block_totals(
2707
2968
  block_start_dt, captured_at_dt,
2708
2969
  owner_key=int(five_hour_window_key),
2709
2970
  windows=ownership_windows,
2710
2971
  pricing_evidence=pricing_evidence,
2711
- owned_entries=owned_entries,
2712
2972
  )
2713
- if owned_entries is not None:
2714
- source_sink[source_key] = tuple(owned_entries)
2715
2973
  pricing_provenance_json = _block_pricing_provenance_json(
2716
2974
  pricing_evidence)
2717
2975
 
@@ -2766,16 +3024,14 @@ def maybe_update_five_hour_block(
2766
3024
  # never ingest/retry wall time.
2767
3025
  # Read into sets without a history-sized SQL sort; each emission
2768
3026
  # set is sorted below before frozen closure events are emitted.
2769
- closing_ids = {
2770
- int(row["id"])
2771
- for row in conn.execute(
2772
- "SELECT id FROM five_hour_blocks "
2773
- "WHERE is_closed = 0 AND account_key = ? "
2774
- "AND (five_hour_window_key < ? "
2775
- " OR unixepoch(five_hour_resets_at) < unixepoch(?))",
2776
- (account_key, int(five_hour_window_key), now_iso),
2777
- ).fetchall()
2778
- }
3027
+ closing_rows = conn.execute(
3028
+ "SELECT id, five_hour_window_key FROM five_hour_blocks "
3029
+ "WHERE is_closed = 0 AND account_key = ? "
3030
+ "AND (five_hour_window_key < ? "
3031
+ " OR unixepoch(five_hour_resets_at) < unixepoch(?))",
3032
+ (account_key, int(five_hour_window_key), now_iso),
3033
+ ).fetchall()
3034
+ closing_ids = {int(row["id"]) for row in closing_rows}
2779
3035
  # A lost-commit retry replays the frozen event before reprocessing
2780
3036
  # its trigger observation. Re-emit that exact duplicate only when
2781
3037
  # this retained trigger clock matches the frozen closure clock;
@@ -2797,6 +3053,15 @@ def maybe_update_five_hour_block(
2797
3053
  ).fetchall()
2798
3054
  }
2799
3055
 
3056
+ # Flush point (c), #956 class 1: a dirty block about to close is
3057
+ # projected first, so the `five_hour_block_close` payload frozen
3058
+ # below equals the projection. Only those blocks: the rest stay
3059
+ # dirty for flush (a).
3060
+ flush_five_hour_dirty_windows(
3061
+ conn, journal_ctx, as_of=now_iso,
3062
+ only={(account_key, int(row["five_hour_window_key"]))
3063
+ for row in closing_rows})
3064
+
2800
3065
  # Step 5: close any STRICTLY OLDER open block. `<` not `!=`
2801
3066
  # — record-usage runs in parallel via background hook-tick &
2802
3067
  # detach + status-line ticks; an older invocation completing
@@ -2836,15 +3101,19 @@ def maybe_update_five_hour_block(
2836
3101
  # insert-vs-update branches and is race-safe: when two
2837
3102
  # record-usage invocations both observe `prior is None`
2838
3103
  # for a brand-new window (the SELECT at line 8636 happens
2839
- # before BEGIN), the loser's INSERT lands as DO UPDATE
3104
+ # before BEGIN), the loser's INSERT lands as DO NOTHING
2840
3105
  # rather than raising IntegrityError on the
2841
3106
  # UNIQUE(five_hour_window_key) constraint and dropping the
2842
3107
  # tick. Immutable columns (block_start_at,
2843
3108
  # first_observed_at_utc, five_hour_resets_at,
2844
- # seven_day_pct_at_block_start, created_at_utc) are
2845
- # deliberately omitted from DO UPDATE — first writer
2846
- # owns them.
2847
- conn.execute(
3109
+ # seven_day_pct_at_block_start, created_at_utc) belong to
3110
+ # the first writer. The end columns, totals and provenance
3111
+ # the INSERT writes are a new block's initial values only:
3112
+ # an existing block's are the capture-order projection
3113
+ # (#956 class 1), refreshed at flush (a) below, never this
3114
+ # observation's, so an earlier capture appended later cannot
3115
+ # move the end backward and a closed block is never touched.
3116
+ created = conn.execute(
2848
3117
  """
2849
3118
  INSERT INTO five_hour_blocks (
2850
3119
  five_hour_window_key,
@@ -2868,19 +3137,7 @@ def maybe_update_five_hour_block(
2868
3137
  account_key
2869
3138
  )
2870
3139
  VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?)
2871
- ON CONFLICT(account_key, five_hour_window_key) DO UPDATE SET
2872
- last_observed_at_utc = excluded.last_observed_at_utc,
2873
- final_five_hour_percent = excluded.final_five_hour_percent,
2874
- seven_day_pct_at_block_end = excluded.seven_day_pct_at_block_end,
2875
- total_input_tokens = excluded.total_input_tokens,
2876
- total_output_tokens = excluded.total_output_tokens,
2877
- total_cache_create_tokens = excluded.total_cache_create_tokens,
2878
- total_cache_read_tokens = excluded.total_cache_read_tokens,
2879
- total_cost_usd = excluded.total_cost_usd,
2880
- pricing_provenance_json = excluded.pricing_provenance_json,
2881
- last_updated_at_utc = excluded.last_updated_at_utc
2882
- WHERE five_hour_blocks.is_closed = 0
2883
- OR five_hour_blocks.journal_id IS NULL
3140
+ ON CONFLICT(account_key, five_hour_window_key) DO NOTHING
2884
3141
  """,
2885
3142
  (
2886
3143
  int(five_hour_window_key),
@@ -2915,6 +3172,50 @@ def maybe_update_five_hour_block(
2915
3172
  (int(five_hour_window_key), account_key),
2916
3173
  ).fetchone()
2917
3174
  block_id = int(block_id_row["id"])
3175
+ created = prior is None and (created.rowcount or 0) == 1
3176
+ if created and opening_record_id is not None:
3177
+ _insert_five_hour_block_opening(
3178
+ conn, account_key=account_key,
3179
+ five_hour_window_key=int(five_hour_window_key),
3180
+ five_hour_resets_at=str(five_hour_resets_at),
3181
+ block_start_at=block_start_at,
3182
+ first_observed_at_utc=captured_at,
3183
+ created_at_utc=now_iso,
3184
+ opening_record_id=opening_record_id,
3185
+ creation_kind=creation_kind,
3186
+ five_hour_percent=float(five_hour_percent),
3187
+ seven_day_pct_at_block_start=block_weekly_percent,
3188
+ weekly_observation_held=bool(
3189
+ saved.get("blockWeeklyHeld",
3190
+ saved.get("weeklyObservationHeld"))),
3191
+ weekly_basis_captured_at_utc=saved.get(
3192
+ "blockWeeklyBasisCapturedAt"),
3193
+ )
3194
+ if created:
3195
+ # Spec 4.6.5: the rebuild's derived-FK fold gives these
3196
+ # milestones this block (its seed folds at 35, before them
3197
+ # at 60), so live re-links them on creation too.
3198
+ conn.execute(
3199
+ "UPDATE five_hour_milestones SET block_id = ? "
3200
+ " WHERE account_key = ? AND five_hour_window_key = ? "
3201
+ " AND block_id = 0",
3202
+ (block_id, account_key, int(five_hour_window_key)),
3203
+ )
3204
+
3205
+ # Flush point (a), #956 class 1: this window is dirty (its reading
3206
+ # was just accepted, converged or re-derived), and a creation
3207
+ # changes the window set ownership is resolved over, so it dirties
3208
+ # every open block of the account (a late-created predecessor takes
3209
+ # overlap entries from its successor). Every dirty open block is
3210
+ # projected before anything below reads it.
3211
+ if prior is None:
3212
+ mark_account_open_blocks_dirty(
3213
+ conn, journal_ctx, account_key, as_of=now_iso)
3214
+ else:
3215
+ mark_five_hour_window_dirty(
3216
+ journal_ctx, account_key, int(five_hour_window_key),
3217
+ conn=conn, as_of=now_iso)
3218
+ flush_five_hour_dirty_windows(conn, journal_ctx, as_of=now_iso)
2918
3219
 
2919
3220
  # Close the just-upserted FIRST block if its window already expired at
2920
3221
  # capture time — replicating the (journal-model-dead)
@@ -2933,77 +3234,8 @@ def maybe_update_five_hour_block(
2933
3234
  (now_iso, int(five_hour_window_key), account_key, now_iso),
2934
3235
  )
2935
3236
 
2936
- # ── Replace-all per-tick: per-(block, model) and per-(block, project_path)
2937
- # rollup-children. DELETE keyed on five_hour_window_key (NOT block_id) so
2938
- # orphan child rows from a prior parent rebuild are cleaned up automatically.
2939
- # Same transaction as the parent upsert; if these raise, the whole tick
2940
- # rolls back and the next tick recomputes from scratch.
2941
- if not current_is_frozen:
2942
- conn.execute(
2943
- "DELETE FROM five_hour_block_models "
2944
- "WHERE five_hour_window_key = ? AND account_key = ?",
2945
- (int(five_hour_window_key), account_key),
2946
- )
2947
- if totals.get("by_model"):
2948
- conn.executemany(
2949
- """
2950
- INSERT INTO five_hour_block_models (
2951
- block_id, five_hour_window_key, model,
2952
- input_tokens, output_tokens,
2953
- cache_create_tokens, cache_read_tokens,
2954
- cost_usd, entry_count, account_key
2955
- )
2956
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
2957
- """,
2958
- [
2959
- (
2960
- block_id,
2961
- int(five_hour_window_key),
2962
- model,
2963
- b["input_tokens"],
2964
- b["output_tokens"],
2965
- b["cache_create_tokens"],
2966
- b["cache_read_tokens"],
2967
- b["cost_usd"],
2968
- b["entry_count"],
2969
- account_key,
2970
- )
2971
- for model, b in totals["by_model"].items()
2972
- ],
2973
- )
2974
-
2975
- conn.execute(
2976
- "DELETE FROM five_hour_block_projects "
2977
- "WHERE five_hour_window_key = ? AND account_key = ?",
2978
- (int(five_hour_window_key), account_key),
2979
- )
2980
- if totals.get("by_project"):
2981
- conn.executemany(
2982
- """
2983
- INSERT INTO five_hour_block_projects (
2984
- block_id, five_hour_window_key, project_path,
2985
- input_tokens, output_tokens,
2986
- cache_create_tokens, cache_read_tokens,
2987
- cost_usd, entry_count, account_key
2988
- )
2989
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
2990
- """,
2991
- [
2992
- (
2993
- block_id,
2994
- int(five_hour_window_key),
2995
- project_path,
2996
- b["input_tokens"],
2997
- b["output_tokens"],
2998
- b["cache_create_tokens"],
2999
- b["cache_read_tokens"],
3000
- b["cost_usd"],
3001
- b["entry_count"],
3002
- account_key,
3003
- )
3004
- for project_path, b in totals["by_project"].items()
3005
- ],
3006
- )
3237
+ # The per-(block, model) and per-(block, project_path) child sets
3238
+ # are the projection's (flush (a) above), never this observation's.
3007
3239
 
3008
3240
  # The first historical block is inserted after the sweep above, so
3009
3241
  # include it explicitly when this observation closes it.
@@ -3429,8 +3661,10 @@ def _read_five_hour_source_state(conn, account_key, five_hour_window_key,
3429
3661
 
3430
3662
  The tuple is ``(baseline_pct, pending_low_pct, pending_at_utc,
3431
3663
  pending_observation_id, baseline_observation_id, baseline_generation,
3432
- pending_generation, pending_position)``; ``pending_low_pct is not None``
3433
- is the armed predicate. The last four are the v2 detector's causal facts
3664
+ pending_generation, pending_position, pending_captured_at_utc)``;
3665
+ ``pending_low_pct is not None`` is the armed predicate. The last is the
3666
+ arming observation's capture second (#943 spec 4.2.1), recorded by BOTH
3667
+ detectors and read only as the credit's exact boundary. The last four are the v2 detector's causal facts
3434
3668
  (#797/#823/#840 spec 4.9): the observation that established the baseline,
3435
3669
  the credit generation the baseline and the pending descent were
3436
3670
  established under, and the arming observation's capture instant. Each is
@@ -3474,7 +3708,7 @@ def _read_five_hour_source_state(conn, account_key, five_hour_window_key,
3474
3708
  "SELECT baseline_pct, pending_low_pct, pending_at_utc, "
3475
3709
  " pending_observation_id, baseline_observation_id, "
3476
3710
  " baseline_generation, pending_generation, "
3477
- " pending_position "
3711
+ " pending_position, pending_captured_at_utc "
3478
3712
  " FROM five_hour_credit_confirmation_state "
3479
3713
  " WHERE account_key = ? AND five_hour_window_key = ? "
3480
3714
  " AND source = ?",
@@ -3493,6 +3727,7 @@ def _read_five_hour_source_state(conn, account_key, five_hour_window_key,
3493
3727
  row[5],
3494
3728
  row[6],
3495
3729
  row[7],
3730
+ row[8],
3496
3731
  )
3497
3732
 
3498
3733
 
@@ -3503,7 +3738,8 @@ def _write_five_hour_source_state(conn, account_key, five_hour_window_key,
3503
3738
  baseline_observation_id=None,
3504
3739
  baseline_generation=None,
3505
3740
  pending_generation=None,
3506
- pending_position=None):
3741
+ pending_position=None,
3742
+ pending_captured_at_utc=None):
3507
3743
  """Upsert one contributor's state for one window, then retire that
3508
3744
  contributor's rows for earlier windows.
3509
3745
 
@@ -3513,7 +3749,9 @@ def _write_five_hour_source_state(conn, account_key, five_hour_window_key,
3513
3749
  for the v2 causal facts (``baseline_observation_id``,
3514
3750
  ``baseline_generation``, ``pending_generation``, ``pending_position``):
3515
3751
  every write states all of them, so the historical detector's write
3516
- leaves none behind.
3752
+ leaves none behind. ``pending_captured_at_utc`` (#943 spec 4.2.1) has the
3753
+ lifecycle of ``pending_at_utc``: set with a pending descent, NULL
3754
+ without one.
3517
3755
 
3518
3756
  ``pending_at_utc`` is the arming tick's DETECTION clock, which is what the
3519
3757
  five-hour path has always stamped into `effective_reset_at_utc`
@@ -3533,8 +3771,8 @@ def _write_five_hour_source_state(conn, account_key, five_hour_window_key,
3533
3771
  "(account_key, five_hour_window_key, source, baseline_pct, "
3534
3772
  " pending_low_pct, pending_at_utc, pending_observation_id, "
3535
3773
  " baseline_observation_id, baseline_generation, pending_generation, "
3536
- " pending_position) "
3537
- "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
3774
+ " pending_position, pending_captured_at_utc) "
3775
+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
3538
3776
  "ON CONFLICT(account_key, five_hour_window_key, source) DO UPDATE SET "
3539
3777
  " baseline_pct = excluded.baseline_pct, "
3540
3778
  " pending_low_pct = excluded.pending_low_pct, "
@@ -3543,11 +3781,13 @@ def _write_five_hour_source_state(conn, account_key, five_hour_window_key,
3543
3781
  " baseline_observation_id = excluded.baseline_observation_id, "
3544
3782
  " baseline_generation = excluded.baseline_generation, "
3545
3783
  " pending_generation = excluded.pending_generation, "
3546
- " pending_position = excluded.pending_position",
3784
+ " pending_position = excluded.pending_position, "
3785
+ " pending_captured_at_utc = excluded.pending_captured_at_utc",
3547
3786
  (account_key, int(five_hour_window_key), source, float(baseline_pct),
3548
3787
  None if pending_low_pct is None else float(pending_low_pct),
3549
3788
  pending_at_utc, pending_observation_id, baseline_observation_id,
3550
- baseline_generation, pending_generation, pending_position),
3789
+ baseline_generation, pending_generation, pending_position,
3790
+ pending_captured_at_utc),
3551
3791
  )
3552
3792
  conn.execute(
3553
3793
  "DELETE FROM five_hour_credit_confirmation_state "
@@ -3580,6 +3820,10 @@ def _step_five_hour_source_state(conn, account_key, five_hour_window_key,
3580
3820
  baseline's observation and generation, and an arming observation's
3581
3821
  generation and causal position (its capture instant, ``capture_at``). The
3582
3822
  historical detector passes None and records none of these.
3823
+
3824
+ #943 spec 4.2.1: an arming observation's capture second (``capture_at``)
3825
+ is recorded for BOTH detectors in ``pending_captured_at_utc``, the
3826
+ credit's exact boundary; ``pending_position`` keeps its v2-only meaning.
3583
3827
  """
3584
3828
  prior_state = _read_five_hour_source_state(
3585
3829
  conn, account_key, five_hour_window_key, source)
@@ -3613,6 +3857,7 @@ def _step_five_hour_source_state(conn, account_key, five_hour_window_key,
3613
3857
  baseline_generation=generation,
3614
3858
  pending_generation=generation,
3615
3859
  pending_position=capture_at if v2 else None,
3860
+ pending_captured_at_utc=capture_at,
3616
3861
  )
3617
3862
  elif decision.action in (FIVE_HOUR_SET_BASELINE, FIVE_HOUR_CANCEL):
3618
3863
  # Establish, raise, or cancel. All three write the baseline with the
@@ -3714,7 +3959,8 @@ def _rebase_five_hour_sources(conn, account_key, five_hour_window_key,
3714
3959
  rows = conn.execute(
3715
3960
  "SELECT source, baseline_pct, pending_low_pct, pending_at_utc, "
3716
3961
  " pending_observation_id, baseline_observation_id, "
3717
- " baseline_generation, pending_generation, pending_position "
3962
+ " baseline_generation, pending_generation, pending_position, "
3963
+ " pending_captured_at_utc "
3718
3964
  " FROM five_hour_credit_confirmation_state "
3719
3965
  " WHERE account_key = ? AND five_hour_window_key = ?",
3720
3966
  (account_key, int(five_hour_window_key)),
@@ -3747,6 +3993,7 @@ def _rebase_five_hour_sources(conn, account_key, five_hour_window_key,
3747
3993
  pending_generation=(
3748
3994
  None if row[2] is None else row[7] or old_generation),
3749
3995
  pending_position=row[8],
3996
+ pending_captured_at_utc=row[9],
3750
3997
  )
3751
3998
 
3752
3999
 
@@ -3790,6 +4037,8 @@ def _record_five_hour_credit_facts(conn, account_key, five_hour_window_key,
3790
4037
  baseline_generation=old_generation,
3791
4038
  pending_generation=new_generation,
3792
4039
  pending_position=None if armed_state is None else armed_state[7],
4040
+ pending_captured_at_utc=(
4041
+ None if armed_state is None else armed_state[8]),
3793
4042
  )
3794
4043
 
3795
4044
 
@@ -4275,6 +4524,11 @@ def _fire_in_place_credit(conn, week_start_date, cur_end_canon, weekly_percent,
4275
4524
  except sqlite3.DatabaseError as exc:
4276
4525
  eprint(f"[record-usage] post-credit cleanup failed: {exc}")
4277
4526
  return
4527
+ # #956 class 1: the weekly retirement and its K16b held conversion can
4528
+ # move an open block's end reading. The band is week-scoped, not window-
4529
+ # scoped, so every open block of the account is marked (only open blocks
4530
+ # are ever refreshed); marking reads blocks, never the retired rows.
4531
+ mark_account_open_blocks_dirty(conn, ctx, account_key, as_of=as_of)
4278
4532
  # Deliberately OUTSIDE the handler above. Swallowing a failure here would
4279
4533
  # leave the DELETE standing as an inline-only effect, which is the exact
4280
4534
  # degradation this event exists to prevent, and the caller would be told
@@ -4335,7 +4589,8 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4335
4589
  ctx=None, account_key=_lib_accounts.UNATTRIBUTED,
4336
4590
  origin_observation_id=None, capture_at=None,
4337
4591
  source=None, hold_weekly_axis=False,
4338
- outcomes_allowed=True, fold_policy=0,
4592
+ weekly_outcomes_allowed=True,
4593
+ five_hour_outcomes_allowed=True, fold_policy=0,
4339
4594
  detector_policy="historical"):
4340
4595
  """Detect + record weekly and 5h reset/credit artifacts for one usage
4341
4596
  observation (extracted from ``cmd_record_usage``; DB journal redesign
@@ -4404,11 +4659,13 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4404
4659
  reviewed observation hold. It bypasses weekly reset/credit detection
4405
4660
  while still running the independent five-hour detector below. Live
4406
4661
  callers retain the default.
4407
- - ``outcomes_allowed`` (#825/#832 spec 5.6 item 2, default ``True``): the
4408
- outcome-quarantine gate, decided by the ingest fold BEFORE this call and
4409
- before any durable append. ``False`` withholds every automatic outcome —
4410
- the moved week-end transition, the >=25 pp fire, the reset-to-zero
4411
- confirmation and the five-hour credit — together with its event, its
4662
+ - ``weekly_outcomes_allowed`` / ``five_hour_outcomes_allowed`` (#825/#832
4663
+ spec 5.6 item 2; #948 spec 6.8 split them per axis, default ``True``):
4664
+ the outcome-quarantine gate of each axis, decided by the ingest fold
4665
+ BEFORE this call and before any durable append. ``False`` withholds that
4666
+ axis's automatic outcomes — weekly: the moved week-end transition, the
4667
+ >=25 pp fire and the reset-to-zero confirmation; five-hour: the
4668
+ five-hour credit — together with its event, its
4412
4669
  stale-replica deletions, its floor and HWM changes and its state
4413
4670
  replacement: the detector takes its no-outcome branch. Detector state
4414
4671
  that is not an outcome (arming, a cleared transient zero, a five-hour
@@ -4465,12 +4722,24 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4465
4722
  # copy's correctness NOT load-bearing, so a row whose boundary diverged
4466
4723
  # — hand-written, or produced by an older shape — cannot reclassify a
4467
4724
  # later reset as an in-place credit (review finding 7).
4725
+ # #943, the weekly twin of the five-hour self-row exclusion below: the
4726
+ # PREVIOUS accepted row, never this observation's own. A crashed cycle
4727
+ # that appended this observation's `snapshot_accept` evt but not its
4728
+ # `wr` credit leaves that evt orphaned, and step 4a of the next ingest
4729
+ # folds it before this detector re-runs; reading it back here compared
4730
+ # the post-credit reading with itself and the credit was lost, live
4731
+ # and after a rebuild. Live, the row does not exist yet, so nothing is
4732
+ # excluded. A record without an id (legacy) excludes nothing.
4733
+ weekly_self_ref = (
4734
+ None if origin_observation_id is None
4735
+ else f"sa:{origin_observation_id}")
4468
4736
  prior = conn.execute(
4469
4737
  "SELECT week_end_at, weekly_percent FROM weekly_usage_snapshots "
4470
4738
  "WHERE week_end_at IS NOT NULL AND account_key = ? "
4471
4739
  " AND weekly_observation_held = 0 "
4740
+ " AND (? IS NULL OR journal_id IS NOT ?) "
4472
4741
  "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
4473
- (account_key,),
4742
+ (account_key, weekly_self_ref, weekly_self_ref),
4474
4743
  ).fetchone()
4475
4744
  if not hold_weekly_axis and prior and prior["week_end_at"] and cur_end_canon:
4476
4745
  prior_end_canon = _canonicalize_optional_iso(
@@ -4491,7 +4760,7 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4491
4760
  # or more (filters out API flaps / transient boundary
4492
4761
  # jitter where usage stays roughly the same).
4493
4762
  if (
4494
- outcomes_allowed
4763
+ weekly_outcomes_allowed
4495
4764
  and prior_end_dt > now_utc
4496
4765
  and prior_pct is not None
4497
4766
  and c._is_reset_drop(prior_pct, weekly_percent)
@@ -4566,7 +4835,7 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4566
4835
  marker_armed=armed,
4567
4836
  marker_baseline=(state[2] if armed else None),
4568
4837
  ).action
4569
- if (not outcomes_allowed
4838
+ if (not weekly_outcomes_allowed
4570
4839
  and decision in (FIRE_IMMEDIATE, CONFIRM_RESET)):
4571
4840
  # Quarantined (spec 5.6 item 2): the no-outcome
4572
4841
  # branch. The armed state, if any, is left exactly
@@ -4668,6 +4937,18 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4668
4937
  five_hour_window_key is not None
4669
4938
  and five_hour_percent is not None
4670
4939
  ):
4940
+ # #943 spec 4.2.3 crash analysis: the PREVIOUS accepted row,
4941
+ # never this observation's own. A crashed cycle that appended
4942
+ # this observation's `snapshot_accept` evt but not its credit
4943
+ # leaves that evt orphaned, and step 4a of the next ingest
4944
+ # folds it before this detector re-runs; reading it back here
4945
+ # made the re-run's stale-replica band centre this reading's
4946
+ # own post-credit level, so the replayed suppression named the
4947
+ # wrong row. Live, the row does not exist yet, so nothing is
4948
+ # excluded. A record without an id (legacy) excludes nothing.
4949
+ self_snapshot_ref = (
4950
+ None if origin_observation_id is None
4951
+ else f"sa:{origin_observation_id}")
4671
4952
  prior_5h_row = conn.execute(
4672
4953
  "SELECT five_hour_window_key, five_hour_percent, "
4673
4954
  " five_hour_resets_at "
@@ -4675,8 +4956,9 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4675
4956
  " WHERE five_hour_window_key IS NOT NULL "
4676
4957
  " AND five_hour_percent IS NOT NULL "
4677
4958
  " AND account_key = ? "
4959
+ " AND (? IS NULL OR journal_id IS NOT ?) "
4678
4960
  " ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
4679
- (account_key,),
4961
+ (account_key, self_snapshot_ref, self_snapshot_ref),
4680
4962
  ).fetchone()
4681
4963
  # The prior snapshot answers two WINDOW-level questions, and
4682
4964
  # only those: whether the previous accepted reading belongs to
@@ -4736,11 +5018,29 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4736
5018
  generation=generation,
4737
5019
  capture_at=capture_dt.isoformat(timespec="seconds"),
4738
5020
  )
4739
- if src_decision.action == FIVE_HOUR_CONFIRM and not outcomes_allowed:
5021
+ if (src_decision.action == FIVE_HOUR_CONFIRM
5022
+ and not five_hour_outcomes_allowed):
4740
5023
  # Quarantined (spec 5.6 item 2): no event, no stale-replica
4741
5024
  # deletion, no HWM force-write and no state replacement.
4742
5025
  # The source state stays armed, as on a mid-fire raise.
4743
5026
  pass
5027
+ elif (src_decision.action == FIVE_HOUR_CONFIRM
5028
+ and (src_state is None or src_state[8] is None)):
5029
+ # #943 spec 4.2.1: a pending descent with no recorded
5030
+ # arming capture second is never confirmed with a guessed
5031
+ # boundary. It is treated as no pending descent: this
5032
+ # reading re-establishes the baseline and nothing is
5033
+ # emitted. Unreachable after the 1021 epoch rebuild (the
5034
+ # table starts empty and every ARM records the column);
5035
+ # the guard makes it explicit.
5036
+ _write_five_hour_source_state(
5037
+ conn, account_key, five_hour_window_key,
5038
+ five_hour_source,
5039
+ baseline_pct=float(five_hour_percent),
5040
+ baseline_observation_id=(
5041
+ origin_observation_id if v2_detector else None),
5042
+ baseline_generation=generation,
5043
+ )
4744
5044
  elif src_decision.action == FIVE_HOUR_CONFIRM:
4745
5045
  _note_deletion_outcome(ctx, account_key)
4746
5046
  # The two ends of the credit, both taken from the ARMING
@@ -4832,33 +5132,31 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4832
5132
  )
4833
5133
  # 10-min floor (spec §2.3 — bounded
4834
5134
  # stacked-credit resolution; one event per
4835
- # 10-min slot per block). Resolved BEFORE
4836
- # the ``if not is_dup`` branch so it's in
4837
- # scope for the pivots below (per memory
4838
- # ``project_dedup_must_not_gate_side_effects.md``:
4839
- # the recovery-tick path must still force
4840
- # HWM + DELETE even when the INSERT is
4841
- # absorbed by the pre-check or by
4842
- # UNIQUE — see comment below for the
4843
- # crash scenario). ``_floor_to_ten_minutes``
5135
+ # 10-min slot per block). ``_floor_to_ten_minutes``
4844
5136
  # is a cctally module attribute; the
4845
5137
  # ``c.X`` accessor resolves at call time
4846
5138
  # so test ``monkeypatch.setitem(ns,
4847
5139
  # "_floor_to_ten_minutes", …)``
4848
5140
  # propagates.
4849
5141
  #
4850
- # #769 S2 §3: floored from the ARMING tick, not from
4851
- # this confirming one. The credit happened when the
4852
- # drop was observed, and the weekly CONFIRM leg anchors
4853
- # on its first-zero instant for the same reason. It is
4854
- # also what makes the stale-replica DELETE below reach
4855
- # the arming observation's own row: the write clamp
4856
- # raised that reading back to the pre-credit baseline,
4857
- # so it is a stale replica by that DELETE's own
4858
- # predicate, and both the DELETE and the reset-aware
4859
- # MAX bound on `>= effective_iso`. Falls back to the
4860
- # confirming tick when the armed row carries no instant
4861
- # (a state row written before this field existed).
5142
+ # #769 S2 §3: floored from the ARMING tick's detection
5143
+ # clock, not from this confirming one: the credit
5144
+ # happened when the drop was observed, and the weekly
5145
+ # CONFIRM leg anchors on its first-zero instant for the
5146
+ # same reason. Falls back to the confirming tick when the
5147
+ # armed row carries no instant (a state row written
5148
+ # before this field existed).
5149
+ #
5150
+ # #943 spec 4.2.2: this floored instant is the credit's
5151
+ # SLOT — its identity (the `fhc` id, the UNIQUE, R-5HC3,
5152
+ # milestones' `reset_event_ref`, the credit revision) —
5153
+ # and no longer its boundary. The boundary is the arming
5154
+ # observation's exact capture second
5155
+ # (`pending_captured_at_utc`, guaranteed present by the
5156
+ # guard above): the stale-replica band and every
5157
+ # post-credit read start there, so a genuine reading
5158
+ # captured inside the slot but before the arming
5159
+ # observation is kept.
4862
5160
  armed_at_iso = (
4863
5161
  src_state[2] if src_state is not None else None)
4864
5162
  effective_dt = c._floor_to_ten_minutes(
@@ -4870,6 +5168,30 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4870
5168
  effective_iso = effective_dt.isoformat(
4871
5169
  timespec="seconds"
4872
5170
  )
5171
+ boundary_iso = parse_iso_datetime(
5172
+ src_state[8], "five_hour_state.pending_captured_at"
5173
+ ).astimezone(dt.timezone.utc).isoformat(
5174
+ timespec="seconds")
5175
+ detected_iso = as_of or now_utc_iso()
5176
+ # A derivation-completion scratch replay of an input a
5177
+ # previous release decided materializes only that
5178
+ # release's decisions, and they carry no boundary
5179
+ # companion: the credit stays a floored-slot credit, so
5180
+ # its cleanup bands from the slot, exactly as every reader
5181
+ # will resolve it (#943 spec 4.2.2), and no companion is
5182
+ # written for the harvest to discard.
5183
+ retention = (
5184
+ None if ctx is None
5185
+ else getattr(ctx, "scratch_retention", None))
5186
+ import _lib_journal
5187
+ companion_withheld = (
5188
+ retention is not None
5189
+ and retention.withholds(_lib_journal.evt_id(
5190
+ "fhcb", account_key, int(five_hour_window_key),
5191
+ effective_iso)))
5192
+ if companion_withheld:
5193
+ boundary_iso = effective_iso
5194
+ credit_inserted = False
4873
5195
  if not is_dup:
4874
5196
  ins_fhc = conn.execute(
4875
5197
  "INSERT OR IGNORE INTO five_hour_reset_events "
@@ -4878,7 +5200,7 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4878
5200
  " effective_reset_at_utc, account_key) "
4879
5201
  "VALUES (?, ?, ?, ?, ?, ?)",
4880
5202
  (
4881
- (as_of or now_utc_iso()),
5203
+ detected_iso,
4882
5204
  int(five_hour_window_key),
4883
5205
  prior_5h_pct,
4884
5206
  post_5h_pct,
@@ -4886,19 +5208,54 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4886
5208
  account_key,
4887
5209
  ),
4888
5210
  )
5211
+ credit_inserted = ins_fhc.rowcount == 1
5212
+ # #943 spec 4.2.3: every destructive effect of the credit
5213
+ # is gated on THIS insert having taken effect. A
5214
+ # same-slot collision (UNIQUE absorbed the insert) or a
5215
+ # historical pair-check duplicate writes no new credit,
5216
+ # so no evt is harvested for it, and a cleanup run here
5217
+ # would be a live-only mutation no replay reproduces.
5218
+ # The crash cases the earlier unconditional hoist served
5219
+ # (an event row committed before its cleanup) cannot
5220
+ # occur: the credit, its companion and its cleanup commit
5221
+ # in one transaction, and a crashed cycle's journaled
5222
+ # `fhcb`/`fhc` evts are folded with their suppression by
5223
+ # step 4a of the next ingest.
5224
+ if credit_inserted:
5225
+ # The boundary companion, bound to the credit's
5226
+ # content revision (spec 4.2.2). Harvested as `fhcb`
5227
+ # (order 29) before the credit's `fhc` (30).
5228
+ if not companion_withheld:
5229
+ conn.execute(
5230
+ "INSERT OR IGNORE INTO "
5231
+ "five_hour_credit_boundaries "
5232
+ "(account_key, five_hour_window_key, "
5233
+ " effective_reset_at_utc, boundary_at_utc, "
5234
+ " arming_observation_id, credit_revision, "
5235
+ " detected_at_utc) "
5236
+ "VALUES (?, ?, ?, ?, ?, ?, ?)",
5237
+ (
5238
+ account_key,
5239
+ int(five_hour_window_key),
5240
+ effective_iso,
5241
+ boundary_iso,
5242
+ str(src_state[3] or ""),
5243
+ _five_hour_credit_revision((
5244
+ detected_iso, prior_5h_pct,
5245
+ post_5h_pct, effective_iso)),
5246
+ detected_iso,
5247
+ ),
5248
+ )
4889
5249
  # Design B (§5.3 event+effects): on the ingest path,
4890
5250
  # capture the doomed stale-replica snapshots'
4891
- # journal_ids BEFORE the unconditional DELETE below,
4892
- # using the SAME predicate as that DELETE, and stash
4893
- # them in ctx.suppression_map keyed on the fhc
4894
- # harvest natural key (window_key, effective_iso).
5251
+ # journal_ids BEFORE the cleanup below, using the
5252
+ # SAME exact-boundary band, and stash them in
5253
+ # ctx.suppression_map keyed on the fhc harvest
5254
+ # natural key (account, window_key, effective_iso).
4895
5255
  # _build_harvest_evt attaches them to the fhc evt so
4896
5256
  # the destructive effect replays deterministically.
4897
- # Gated on the genuine-new-reset winner
4898
- # (rowcount == 1) so a crash-replayed reset never
4899
- # re-suppresses with a divergent list; ctx=None
4900
- # (legacy) captures nothing.
4901
- if ctx is not None and ins_fhc.rowcount == 1:
5257
+ # ctx=None (legacy) captures nothing.
5258
+ if ctx is not None:
4902
5259
  doomed = conn.execute(
4903
5260
  "SELECT journal_id "
4904
5261
  "FROM weekly_usage_snapshots "
@@ -4911,7 +5268,7 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4911
5268
  (
4912
5269
  int(five_hour_window_key),
4913
5270
  account_key,
4914
- effective_iso,
5271
+ boundary_iso,
4915
5272
  stale_replica_pct,
4916
5273
  ),
4917
5274
  ).fetchall()
@@ -4923,41 +5280,12 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4923
5280
  ] = [r[0] for r in doomed]
4924
5281
  # (inline commit removed — one end-of-function commit
4925
5282
  # on legacy; the ingest cycle owns the commit.)
4926
- # Pivots fire UNCONDITIONALLY whenever a
4927
- # credit is detected — NOT gated on
4928
- # ``not is_dup`` and NOT on
4929
- # ``rowcount == 1``. Memory
4930
- # ``project_dedup_must_not_gate_side_effects.md``:
4931
- # "Skipping a no-op INSERT must NOT skip
4932
- # milestones/rollups/alerts; prior run may
4933
- # have died mid-flight." Crash scenario A:
4934
- # tick N committed the event row, then died
4935
- # before HWM + DELETE. Tick N+1's
4936
- # INSERT OR IGNORE returns rowcount == 0
4937
- # (UNIQUE absorbs) but the system is still
4938
- # wedged on the pre-credit HWM + stale-
4939
- # replica rows. Crash scenario B (the
4940
- # Codex r4 finding): a recovery tick where
4941
- # ``(prior, post)`` pair-matches the
4942
- # already-stored event row also takes the
4943
- # ``is_dup`` branch; without the hoist the
4944
- # pivots would be skipped and the system
4945
- # would stay wedged. The pivots are
4946
- # individually idempotent (file overwrite
4947
- # + DELETE on a stable predicate), so
4948
- # re-running them on the recovery tick is
4949
- # always safe. Mirrors the weekly hoist at
4950
- # ``_cctally_record.py`` after the
4951
- # ``if already is None`` block (grep
4952
- # ``Force-write hwm-7d``).
4953
- #
4954
- # Force-write hwm-5h: bypasses the
4955
- # monotonic guard at the normal hwm-5h
4956
- # writer below. Lands AFTER
4957
- # ``conn.commit()`` so a concurrent reader
4958
- # doesn't see the new HWM before the
4959
- # event row is durable. File format
4960
- # matches the canonical writer:
5283
+ # Force-write hwm-5h: bypasses the monotonic guard at the
5284
+ # normal hwm-5h writer below. It is a re-derivable
5285
+ # projection of the CURRENT meter level, not a credit
5286
+ # effect, so it stays unconditional on every detection
5287
+ # entry (a recovery or duplicate tick rewrites the same
5288
+ # level). File format matches the canonical writer:
4961
5289
  # ``<key> <percent>\n``.
4962
5290
  #
4963
5291
  # #769 S2 §3 F1: this stays bound to the
@@ -4980,81 +5308,92 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
4980
5308
  )
4981
5309
  except OSError:
4982
5310
  pass
4983
- # Stale-replica DELETE (spec §4.3).
4984
- # Defends against claude-statusline
4985
- # replaying the pre-credit
4986
- # ``--five-hour-percent`` value past the
4987
- # credit moment from its own in-memory
4988
- # HWM cache. 1.0pp tolerance band (issue
4989
- # #48 — symmetric follow-up to weekly #45)
4990
- # around the observed pre-credit baseline
4991
- # absorbs any rounding drift between
4992
- # cctally's OAuth read and statusline's
4993
- # ``--five-hour-percent`` payload (today
4994
- # they match byte-identically, but the
4995
- # band future-proofs against Anthropic or
4996
- # statusline changing 5h rounding). The
4997
- # band stays well below the 5.0pp 5h
4998
- # in-place credit detection threshold
4999
- # (``_FIVE_HOUR_RESET_PCT_DROP_THRESHOLD``)
5000
- # — 4pp safety margin — so legitimate
5001
- # post-credit values are never caught. That
5002
- # margin holds against ``stale_replica_pct``
5003
- # and not only against the event's
5004
- # ``prior_percent``: arming requires the
5005
- # full 5.0pp drop from this source's own
5006
- # baseline, and the clamped maximum is at or
5007
- # above that baseline, so the credited low
5008
- # is at least 5.0pp below the band centre.
5009
- # ``unixepoch()`` on both sides for offset
5010
- # robustness (Z vs +00:00). Bind is
5011
- # ``stale_replica_pct`` — the clamped level
5012
- # these rows actually carry — NOT the
5013
- # event's ``prior_percent``; see the two
5014
- # values' definitions above.
5015
- try:
5016
- # #825/#832 spec 4.7 revision 6 (fix round K15): the
5017
- # cleanup retires FIVE-HOUR effects only, for every
5018
- # fold policy. An unheld stale replica carries
5019
- # accepted weekly evidence, so it is retired in
5020
- # place (its five-hour percent, reset and window key
5021
- # become NULL together) and keeps its weekly value,
5022
- # boundary, capture and held provenance. The DELETE
5023
- # below then reaches only the held rows (a retired
5024
- # row has left the band), whose weekly value is a
5025
- # copy of an older basis. `_apply_reset_with_
5026
- # suppression` replays the event's one suppression
5027
- # list the same way. A store that predates the held
5028
- # column holds no held row, so there every band row
5029
- # is retired (two literal statements, so each
5030
- # keeps its own detector-access contract).
5031
- retire_params = (
5032
- int(five_hour_window_key),
5033
- account_key,
5034
- effective_iso,
5035
- stale_replica_pct,
5036
- )
5037
- if _cctally_core.weekly_held_exclusion(conn):
5038
- conn.execute(
5039
- "UPDATE weekly_usage_snapshots "
5040
- " SET five_hour_percent = NULL, "
5041
- " five_hour_resets_at = NULL, "
5042
- " five_hour_window_key = NULL "
5043
- " WHERE five_hour_window_key = ? "
5044
- " AND account_key = ? "
5045
- " AND unixepoch(captured_at_utc) "
5046
- " >= unixepoch(?) "
5047
- " AND ABS(five_hour_percent - ?) "
5048
- " < 1.0 "
5049
- " AND weekly_observation_held = 0",
5050
- retire_params,
5311
+ # Stale-replica cleanup (spec §4.3), gated on the credit
5312
+ # insert above (#943 spec 4.2.3). Defends against
5313
+ # claude-statusline replaying the pre-credit
5314
+ # ``--five-hour-percent`` value past the credit moment
5315
+ # from its own in-memory HWM cache. 1.0pp tolerance band
5316
+ # (issue #48 — symmetric follow-up to weekly #45) around
5317
+ # the observed pre-credit level absorbs rounding drift
5318
+ # between cctally's OAuth read and statusline's payload.
5319
+ # The band stays well below the 5.0pp 5h in-place credit
5320
+ # detection threshold
5321
+ # (``_FIVE_HOUR_RESET_PCT_DROP_THRESHOLD``) — 4pp safety
5322
+ # margin — so legitimate post-credit values are never
5323
+ # caught. That margin holds against ``stale_replica_pct``
5324
+ # and not only against the event's ``prior_percent``:
5325
+ # arming requires the full 5.0pp drop from this source's
5326
+ # own baseline, and the clamped maximum is at or above
5327
+ # that baseline, so the credited low is at least 5.0pp
5328
+ # below the band centre. ``unixepoch()`` on both sides for
5329
+ # offset robustness (Z vs +00:00). Bind is
5330
+ # ``stale_replica_pct`` — the clamped level these rows
5331
+ # actually carry — NOT the event's ``prior_percent``.
5332
+ #
5333
+ # #943 spec 4.2.3: the band starts at the exact boundary
5334
+ # (the arming capture second), never at the floored slot:
5335
+ # a genuine reading captured before the arming
5336
+ # observation is not a replica of anything.
5337
+ # #956 class 1: the band's rows all lie in the credit's
5338
+ # own window, so that key is the one the retirement can
5339
+ # move; it is collected here, before any row is cleared
5340
+ # (a key read afterwards finds nothing), and marked after.
5341
+ credit_dirty_key = (account_key, int(five_hour_window_key))
5342
+ if credit_inserted:
5343
+ try:
5344
+ # #825/#832 spec 4.7 revision 6 (fix round K15):
5345
+ # the cleanup retires FIVE-HOUR effects only, for
5346
+ # every fold policy. An unheld stale replica
5347
+ # carries accepted weekly evidence, so it is
5348
+ # retired in place (its five-hour percent, reset
5349
+ # and window key become NULL together) and keeps
5350
+ # its weekly value, boundary, capture and held
5351
+ # provenance. The DELETE below then reaches only
5352
+ # the held rows (a retired row has left the band),
5353
+ # whose weekly value is a copy of an older basis.
5354
+ # `_apply_reset_with_suppression` replays the
5355
+ # event's one suppression list the same way. A
5356
+ # store that predates the held column holds no
5357
+ # held row, so there every band row is retired
5358
+ # (two literal statements, so each keeps its own
5359
+ # detector-access contract).
5360
+ retire_params = (
5361
+ int(five_hour_window_key),
5362
+ account_key,
5363
+ boundary_iso,
5364
+ stale_replica_pct,
5051
5365
  )
5052
- else:
5366
+ if _cctally_core.weekly_held_exclusion(conn):
5367
+ conn.execute(
5368
+ "UPDATE weekly_usage_snapshots "
5369
+ " SET five_hour_percent = NULL, "
5370
+ " five_hour_resets_at = NULL, "
5371
+ " five_hour_window_key = NULL "
5372
+ " WHERE five_hour_window_key = ? "
5373
+ " AND account_key = ? "
5374
+ " AND unixepoch(captured_at_utc) "
5375
+ " >= unixepoch(?) "
5376
+ " AND ABS(five_hour_percent - ?) "
5377
+ " < 1.0 "
5378
+ " AND weekly_observation_held = 0",
5379
+ retire_params,
5380
+ )
5381
+ else:
5382
+ conn.execute(
5383
+ "UPDATE weekly_usage_snapshots "
5384
+ " SET five_hour_percent = NULL, "
5385
+ " five_hour_resets_at = NULL, "
5386
+ " five_hour_window_key = NULL "
5387
+ " WHERE five_hour_window_key = ? "
5388
+ " AND account_key = ? "
5389
+ " AND unixepoch(captured_at_utc) "
5390
+ " >= unixepoch(?) "
5391
+ " AND ABS(five_hour_percent - ?) "
5392
+ " < 1.0",
5393
+ retire_params,
5394
+ )
5053
5395
  conn.execute(
5054
- "UPDATE weekly_usage_snapshots "
5055
- " SET five_hour_percent = NULL, "
5056
- " five_hour_resets_at = NULL, "
5057
- " five_hour_window_key = NULL "
5396
+ "DELETE FROM weekly_usage_snapshots "
5058
5397
  " WHERE five_hour_window_key = ? "
5059
5398
  " AND account_key = ? "
5060
5399
  " AND unixepoch(captured_at_utc) "
@@ -5063,28 +5402,16 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
5063
5402
  " < 1.0",
5064
5403
  retire_params,
5065
5404
  )
5066
- conn.execute(
5067
- "DELETE FROM weekly_usage_snapshots "
5068
- " WHERE five_hour_window_key = ? "
5069
- " AND account_key = ? "
5070
- " AND unixepoch(captured_at_utc) "
5071
- " >= unixepoch(?) "
5072
- " AND ABS(five_hour_percent - ?) "
5073
- " < 1.0",
5074
- (
5075
- int(five_hour_window_key),
5076
- account_key,
5077
- effective_iso,
5078
- stale_replica_pct,
5079
- ),
5080
- )
5081
- # (inline commit removed — end-of-function commit on
5082
- # legacy; the ingest cycle owns the commit.)
5083
- except sqlite3.DatabaseError as exc:
5084
- eprint(
5085
- "[record-usage] 5h post-credit "
5086
- f"cleanup failed: {exc}"
5087
- )
5405
+ # (inline commit removed — end-of-function commit
5406
+ # on legacy; the ingest cycle owns the commit.)
5407
+ except sqlite3.DatabaseError as exc:
5408
+ eprint(
5409
+ "[record-usage] 5h post-credit "
5410
+ f"cleanup failed: {exc}"
5411
+ )
5412
+ mark_five_hour_window_dirty(
5413
+ ctx, *credit_dirty_key, conn=conn,
5414
+ as_of=as_of or now_utc_iso())
5088
5415
  # Retire the pending descent and restart this source's
5089
5416
  # baseline at the credited level. Written only AFTER
5090
5417
  # the pivots complete, mirroring the weekly CONFIRM
@@ -5342,12 +5669,12 @@ def _apply_credit(conn, plan, *, five_hour=(None, None, None), as_of=None,
5342
5669
  the synthetic snapshot is re-INSERTed only after a ``--force`` re-record's
5343
5670
  destructive clear or on the completion path where none exists yet).
5344
5671
 
5345
- `plan.effective_iso` is `floor_to_hour(at)`. parse_iso_datetime returns a
5672
+ `plan.effective_iso` is the exact `--at` second (#943 O1). parse_iso_datetime returns a
5346
5673
  host-local-offset aware datetime; convert to UTC so `effective_at_utc`
5347
5674
  persists with a +00:00 spelling, not a host offset, in the `*_utc` column.
5348
5675
  On the completion / --force re-apply path the CALLER passes a `plan` whose
5349
5676
  `effective_iso` is the EXISTING floor row's `effective_at_utc` (NOT a fresh
5350
- floor_to_hour(now)) — spec §4a completion-effective reuse."""
5677
+ `--at`) — spec §4a completion-effective reuse."""
5351
5678
  c = _cctally()
5352
5679
  effective_dt = parse_iso_datetime(plan.effective_iso, "effective").astimezone(dt.timezone.utc)
5353
5680
  effective_iso = effective_dt.isoformat(timespec="seconds")
@@ -5412,6 +5739,13 @@ def _apply_credit(conn, plan, *, five_hour=(None, None, None), as_of=None,
5412
5739
  # 4d. INSERT the synthetic post-credit snapshot at plan.to_pct.
5413
5740
  c._insert_credit_snapshot(conn, plan, five_hour=five_hour, commit=commit,
5414
5741
  account_key=account_key)
5742
+ # #956 class 1: the removal and the synthetic can each move an open
5743
+ # block's end reading; a direct caller refreshes every open block of
5744
+ # the account now. (The ingest path marks through `emit_model_a`,
5745
+ # which collects the named rows' windows before applying the evt.)
5746
+ mark_account_open_blocks_dirty(conn, None, account_key, as_of=as_of)
5747
+ if commit:
5748
+ conn.commit()
5415
5749
  else:
5416
5750
  # ── Ingest path (Design B, §5.3 event+effects) ─────────────────────
5417
5751
  # Journal the destructive effects + synthetic instead of running them
@@ -5614,12 +5948,18 @@ def _credit_preview_text(plan, *, stale_replays, dry_run, account_label=None):
5614
5948
  ]
5615
5949
  if account_label is not None:
5616
5950
  lines.append(f" account: {account_label}")
5951
+ # #943 (O1): a fresh plan's effective IS the `--at` second, so the
5952
+ # "floored from" note appears only when the two differ — a completion
5953
+ # reusing an older floor row's instant.
5954
+ effective_line = f" effective: {eff_dt.strftime('%Y-%m-%d %H:%M:%S')} UTC"
5955
+ if eff_dt != cap_dt:
5956
+ effective_line += (
5957
+ f" (floored from {cap_dt.strftime('%Y-%m-%d %H:%M:%S')})")
5617
5958
  lines += [
5618
5959
  f" week: {plan.week_start_date} -> "
5619
5960
  f"{we_dt.strftime('%Y-%m-%d %H:%M')} UTC",
5620
5961
  f" from -> to: {plan.from_pct:g}% -> {plan.to_pct:g}% (from: {src})",
5621
- f" effective: {eff_dt.strftime('%Y-%m-%d %H:%M')} UTC "
5622
- f"(floored from {cap_dt.strftime('%Y-%m-%d %H:%M')})",
5962
+ effective_line,
5623
5963
  " writes:",
5624
5964
  f" + weekly_credit_floors (effective={plan.effective_iso}, "
5625
5965
  f"pre_credit={plan.from_pct:g})",
@@ -5886,7 +6226,7 @@ def cmd_record_credit(args) -> int:
5886
6226
  # - half-applied (floor row present, NO command-owned snapshot
5887
6227
  # at/after its effective): a crash between 4a and 4d. A plain
5888
6228
  # rerun FINISHES it, reusing the existing effective_at_utc (NOT
5889
- # a fresh floor_to_hour(now)) so no stale [old,new) replay leaks
6229
+ # a fresh `--at`) so no stale [old,new) replay leaks
5890
6230
  # into the floored MAX (spec §4a completion-effective reuse).
5891
6231
  # - fully applied (floor row + command-owned snapshot): refuse by
5892
6232
  # default; --force clears + re-records at a fresh effective.
@@ -5900,8 +6240,9 @@ def cmd_record_credit(args) -> int:
5900
6240
  is_completion = owned is None
5901
6241
 
5902
6242
  # The effective the plan should carry: a half-applied completion reuses
5903
- # the EXISTING floor row's effective; a first credit / --force re-apply
5904
- # uses floor_to_hour(at) (computed inside _build_credit_plan).
6243
+ # the EXISTING floor row's effective verbatim (a historical hour floor
6244
+ # included); a first credit / --force re-apply uses the exact `--at`
6245
+ # second (#943 O1, computed inside _build_credit_plan).
5905
6246
  reuse_effective = existing[1] if is_completion else None
5906
6247
 
5907
6248
  # 3. Validate + build plan.
@@ -6196,6 +6537,7 @@ def cmd_record_usage(
6196
6537
  publication: "dict | None" = None,
6197
6538
  appended: "list | None" = None,
6198
6539
  expected_high_water: "tuple | None" = None,
6540
+ selected_state_locked: bool = False,
6199
6541
  ) -> int:
6200
6542
  """The CLI adapter over `record_usage_bound` (#825/#832 spec 4.7).
6201
6543
 
@@ -6217,7 +6559,8 @@ def cmd_record_usage(
6217
6559
  args, binding=binding, ingest_mode=ingest_mode, writer=writer,
6218
6560
  nudge_dashboard=nudge_dashboard, nudge_sink=nudge_sink,
6219
6561
  publication=publication, appended=appended,
6220
- expected_high_water=expected_high_water)
6562
+ expected_high_water=expected_high_water,
6563
+ selected_state_locked=selected_state_locked)
6221
6564
 
6222
6565
 
6223
6566
  def record_usage_bound(
@@ -6230,8 +6573,48 @@ def record_usage_bound(
6230
6573
  publication: "dict | None" = None,
6231
6574
  appended: "list | None" = None,
6232
6575
  expected_high_water: "tuple | None" = None,
6576
+ selected_state_locked: bool = False,
6577
+ ) -> int:
6578
+ """Record one bound Claude observation (#948 spec 6.7): every path that
6579
+ appends a Claude observation runs the outcome quarantine's release
6580
+ protocol in the selected-state critical section. A caller that already
6581
+ holds the lock (the statusline reducer, the authoritative OAuth
6582
+ publication) passes ``selected_state_locked=True`` and runs inside its
6583
+ own section; otherwise — the direct `record-usage` route — the lock is
6584
+ taken here around exactly the release steps and the append, in the
6585
+ existing lock order (selected-state lock outside the journal append), and
6586
+ released before the ingest and any dashboard nudge, so a concurrent
6587
+ render never waits on this process's ingest."""
6588
+ import contextlib
6589
+ import _cctally_statusline
6590
+
6591
+ if selected_state_locked or _cctally_statusline._SELECTED_DEPTH.get() > 0:
6592
+ critical = contextlib.nullcontext
6593
+ else:
6594
+ critical = _cctally_statusline._selected_state_lock
6595
+ return _record_usage_bound_locked(
6596
+ args, binding=binding, ingest_mode=ingest_mode, writer=writer,
6597
+ nudge_dashboard=nudge_dashboard, nudge_sink=nudge_sink,
6598
+ publication=publication, appended=appended,
6599
+ expected_high_water=expected_high_water, critical=critical)
6600
+
6601
+
6602
+ def _record_usage_bound_locked(
6603
+ args: argparse.Namespace, *,
6604
+ binding,
6605
+ ingest_mode: str = "authoritative",
6606
+ writer: str = "record-usage",
6607
+ nudge_dashboard: bool = True,
6608
+ nudge_sink=None,
6609
+ publication: "dict | None" = None,
6610
+ appended: "list | None" = None,
6611
+ expected_high_water: "tuple | None" = None,
6612
+ critical=None,
6233
6613
  ) -> int:
6234
- """The bound recording kernel (#825/#832 spec 4.7).
6614
+ """The bound recording kernel (#825/#832 spec 4.7). ``critical`` is the
6615
+ selected-state critical section around the release steps and the append
6616
+ (`record_usage_bound`; a no-op context when the caller already holds
6617
+ the lock).
6235
6618
 
6236
6619
  ``binding`` is required and is the ONLY source of the observation's
6237
6620
  account: this kernel never resolves the active identity. The account
@@ -6312,11 +6695,7 @@ def record_usage_bound(
6312
6695
  past_slack_s=_RECORD_USAGE_WEEK_PAST_SLACK_S,
6313
6696
  future_band_s=_RECORD_USAGE_WEEK_FUTURE_BAND_S,
6314
6697
  ):
6315
- eprint(
6316
- f"[record-usage] rejecting --resets-at={resets_at}: outside "
6317
- f"plausibility band [now-30d, now+8d]; "
6318
- f"now={now_epoch} ({now_dt.isoformat()}). No row written."
6319
- )
6698
+ eprint(_weekly_resets_rejection_notice(resets_at, now_dt))
6320
6699
  return 2
6321
6700
 
6322
6701
  five_hour_percent: float | None = None
@@ -6345,13 +6724,8 @@ def record_usage_bound(
6345
6724
  past_slack_s=_RECORD_USAGE_5H_PAST_SLACK_S,
6346
6725
  future_band_s=_RECORD_USAGE_5H_FUTURE_BAND_S,
6347
6726
  ):
6348
- eprint(
6349
- f"[record-usage] dropping --five-hour-resets-at="
6350
- f"{five_hour_resets_at_epoch}: outside plausibility band "
6351
- f"[now-10m, now+6h]; now={now_epoch} "
6352
- f"({now_dt.isoformat()}). Weekly snapshot still written; "
6353
- f"5h fields will be NULL."
6354
- )
6727
+ eprint(_five_hour_resets_drop_notice(
6728
+ five_hour_resets_at_epoch, now_dt))
6355
6729
  five_hour_percent = None
6356
6730
  five_hour_resets_at_epoch = None
6357
6731
  else:
@@ -6455,19 +6829,39 @@ def record_usage_bound(
6455
6829
  obs = _lj.prepare_record(_lj.make_obs(
6456
6830
  at=obs_at, src=writer, provider="claude", payload=raw,
6457
6831
  account=obs_account))
6458
- if expected_high_water is None:
6459
- _jr.append_record(obs)
6460
- else:
6461
- _jr.append_records(
6462
- [obs] if observe is None else [observe, obs],
6463
- expected_high_water=(str(expected_high_water[0]),
6464
- int(expected_high_water[1])))
6465
- if observe is not None:
6466
- _mark_account_observed(binding)
6467
- if appended is not None:
6468
- # #825/#832 spec 5.6 item 7: the authoritative OAuth writer records
6469
- # this observation's identity as its control commit.
6470
- appended.append(obs["id"])
6832
+ # #948 spec 6.7 *Resume after a crash*: a qualifying witness of this
6833
+ # account still awaiting its release is released BEFORE this observation
6834
+ # is appended, so it is never forfeited by the very next record. Free of
6835
+ # any write without a quarantine trigger.
6836
+ import contextlib
6837
+ import _cctally_quarantine
6838
+ with (critical or contextlib.nullcontext)():
6839
+ decided = _cctally_quarantine.run_release_step(account_key)
6840
+ if expected_high_water is None:
6841
+ _jr.append_record(obs)
6842
+ else:
6843
+ _jr.append_records(
6844
+ [obs] if observe is None else [observe, obs],
6845
+ expected_high_water=(str(expected_high_water[0]),
6846
+ int(expected_high_water[1])))
6847
+ if observe is not None:
6848
+ _mark_account_observed(binding)
6849
+ if appended is not None:
6850
+ # #825/#832 spec 5.6 item 7: the authoritative OAuth writer
6851
+ # records this observation's identity as its control commit.
6852
+ appended.append(obs["id"])
6853
+ # #948 spec 6.7 *Live path*: still in the selected-state critical
6854
+ # section, release every axis this observation witnesses. With a
6855
+ # trigger, a lagging index is caught up by one authoritative ingest
6856
+ # first, so the fold judges the witness against its whole prefix, and
6857
+ # on any failure nothing is written. Skipped when the resume step
6858
+ # decided nothing (review finding F13): with no trigger the append
6859
+ # opens the index once, and the observation just appended cannot
6860
+ # witness a trigger appended after that check (its generation has
6861
+ # no coverage yet); a step skipped on failure is the next append's
6862
+ # resume step.
6863
+ if decided is not None:
6864
+ _cctally_quarantine.run_release_step(account_key)
6471
6865
  # authoritative observes its own write synchronously; opportunistic skips a
6472
6866
  # busy ingest lock and lets the current holder consume the appended line.
6473
6867
  result = _jr.run_stats_ingest(mode=ingest_mode)
@@ -6955,7 +7349,8 @@ def _codex_lifecycle_log_line(
6955
7349
  *, source_root_key: str, event: str, sync: str, result: str,
6956
7350
  blocks: int, milestones: int, alert_eligible_roots: int,
6957
7351
  quota_alerts: int, budget_alerts: int, dur_ms: int, backlog: int = 0,
6958
- error: str = "", drain_request: str = "",
7352
+ error: str = "", drain_request: str = "", reason: str = "",
7353
+ projection: str = "",
6959
7354
  ) -> str:
6960
7355
  """Render one privacy-safe root-qualified Codex lifecycle outcome.
6961
7356
 
@@ -6983,7 +7378,17 @@ def _codex_lifecycle_log_line(
6983
7378
  safe_event = "".join(
6984
7379
  char for char in str(event)[:40] if char.isalnum() or char in "-_"
6985
7380
  ) or "unknown"
6986
- suffix = f" drain_request={drain_request}" if drain_request else ""
7381
+ # `reason` is a fixed token naming why a tick deferred (#977:
7382
+ # `quota_index_pending`), never free text.
7383
+ safe_reason = "".join(
7384
+ char for char in str(reason)[:40] if char.isalnum() or char in "-_")
7385
+ suffix = f" reason={safe_reason}" if safe_reason else ""
7386
+ # #980 D6: the fixed token `deferred` when the quota projection refused to
7387
+ # publish over an unresolved model; absent otherwise.
7388
+ if projection == "deferred":
7389
+ suffix += " projection=deferred"
7390
+ if drain_request:
7391
+ suffix += f" drain_request={drain_request}"
6987
7392
  if error:
6988
7393
  collapsed = _hook_log_safe_free_text(error)
6989
7394
  if collapsed:
@@ -7046,10 +7451,14 @@ def _cmd_hook_tick_codex(
7046
7451
  def log_outcome(
7047
7452
  *, sync: str, result: str, projection=None, budget_alerts: int = 0,
7048
7453
  backlog: int = 0, error: str = "", drain_request: str = "",
7454
+ reason: str = "",
7049
7455
  ) -> None:
7050
7456
  blocks = int(getattr(projection, "blocks_upserted", 0) or 0)
7051
7457
  milestones = int(getattr(projection, "milestones_upserted", 0) or 0)
7052
7458
  quota_alerts = int(getattr(projection, "alerts_dispatched", 0) or 0)
7459
+ projection_state = (
7460
+ "deferred"
7461
+ if getattr(projection, "status", None) == "deferred_model" else "")
7053
7462
  dur_ms = int((time.monotonic() - started_at) * 1000)
7054
7463
  for lock in locks:
7055
7464
  _hook_tick_log_line(_codex_lifecycle_log_line(
@@ -7066,6 +7475,8 @@ def _cmd_hook_tick_codex(
7066
7475
  dur_ms=dur_ms,
7067
7476
  error=error,
7068
7477
  drain_request=drain_request,
7478
+ reason=reason,
7479
+ projection=projection_state,
7069
7480
  ))
7070
7481
  _hook_tick_log_rotate_if_needed()
7071
7482
 
@@ -7091,94 +7502,122 @@ def _cmd_hook_tick_codex(
7091
7502
  # ingest diagnostics remain available to explicit CLI operations.
7092
7503
  with open(os.devnull, "w", encoding="utf-8") as quiet, \
7093
7504
  contextlib.redirect_stdout(quiet), contextlib.redirect_stderr(quiet):
7094
- cache = c.open_cache_db()
7095
- try:
7096
- cache_mod = c._load_sibling("_cctally_cache")
7097
- # public #5 spec §4: the hook's ingest leg is BUDGETED and
7098
- # resumable, and it ingests the active rollout first so live
7099
- # numbers stay correct while history lags. Only this caller
7100
- # passes a budget — an explicit `cctally cache-sync` still runs
7101
- # to completion.
7102
- import _cctally_config as _cfg_codex
7103
- budget_seconds = _cfg_codex.resolve_codex_hook_ingest_budget(
7104
- c.load_config())
7105
- stats, cache = cache_mod._run_cache_operation_with_recovery(
7106
- cache,
7107
- lambda active_conn: c.sync_codex_cache(
7108
- active_conn, lock_timeout=0,
7109
- budget_seconds=budget_seconds,
7110
- active_transcript_path=transcript_path or None,
7111
- # public #5 spec §4: ONE reconcile per tick. The
7112
- # explicit alert-eligible reconcile below can never
7113
- # take the certificate short-circuit (it is guarded by
7114
- # `not alert_eligible_roots`), so the sync-internal one
7115
- # was pure duplicated cost.
7116
- quota_reconcile="defer",
7117
- ),
7118
- origin="hook.codex_quota.sync",
7119
- )
7120
- finally:
7121
- cache.close()
7122
- if stats.lock_contended:
7123
- # #968 spec 5.7: publish this hook's own waiting request so
7124
- # drain workers yield once their admitted work commits. The
7125
- # hook never waits and never touches the drain gate.
7126
- import _lib_codex_drain_admission as _drain_adm
7127
- request_id = _drain_adm.publish_waiting_request(
7128
- _cctally_core.APP_DIR, root_keys=all_root_keys)
7129
- log_outcome(
7130
- sync="contended", result="noop",
7131
- drain_request="published" if request_id else "failed")
7132
- return 0
7133
- projection = c.reconcile_codex_quota_projection(
7134
- source_root_keys=all_root_keys,
7135
- alert_eligible_root_keys=due_root_keys,
7136
- now=dt.datetime.now(dt.timezone.utc),
7137
- # public #5 spec §2/§4: the hook path NEVER runs a
7138
- # whole-history quota pass inline — not the once-a-day
7139
- # verification, and not a rebuilt stats index, an interpretation
7140
- # bump, a missing reverse map, a reset ledger or a dirty-unit
7141
- # burst either. On a hook-only install no dashboard tick or
7142
- # `codex quota` invocation reaches any of them first, so each
7143
- # would land here as a ~14-30s reconcile on a blocking path
7144
- # against Codex's 30-second timeout. `defer` hands every one of
7145
- # them to the detached `_codex-quota-verify` worker; the bounded
7146
- # ingest above stays foreground, so fresh observations still
7147
- # precede the turn.
7148
- full_pass="defer",
7149
- )
7150
- # Vendor-scoped spend is intentionally evaluated once per
7151
- # successful due-set tick, not once per root. Task 7 Item 4: the
7152
- # on-demand Codex budget firing routes through the single-flight
7153
- # ingest cycle (the `codex_apply` seam) instead of opening its own
7154
- # stats connection — so its `budget_milestones` (vendor=codex)
7155
- # crossings are journaled by the budget harvest and its alerts
7156
- # dispatch post-commit (set-then-dispatch). AUTHORITATIVE so a failure
7157
- # propagates to this leg's try/except (raise_errors=True preserved).
7158
- import _cctally_journal as _jr_codex
7159
- _budget_holder = {"n": 0}
7160
-
7161
- def _codex_budget_leg(ictx):
7162
- _budget_holder["n"] = int(c.maybe_record_codex_budget_milestone(
7163
- {}, conn=ictx.conn, alert_sink=ictx.pending_alerts,
7164
- journal_ctx=ictx,
7165
- raise_errors=True) or 0)
7166
-
7167
- budget_ingest = _jr_codex.run_stats_ingest(
7168
- mode="authoritative", codex_apply=_codex_budget_leg)
7169
- if not budget_ingest.ran:
7170
- # A detached quota-verification worker can own the ingest lock
7171
- # while applying its projection. Authoritative ingest reports
7172
- # that bounded timeout as `ran=False`; acknowledging the root
7173
- # here would throttle away the skipped budget evaluation. Keep
7174
- # the lifecycle markers due so the first uncontended tick
7175
- # retries the forward-only budget crossing.
7176
- log_outcome(
7177
- sync="contended", result="noop", projection=projection,
7178
- backlog=int(getattr(stats, "backlog_files", 0) or 0),
7505
+ cache_mod = c._load_sibling("_cctally_cache")
7506
+ # #981 A6: the hook-scoped Codex read policy is entered BEFORE the
7507
+ # budgeted sync, so that sync pins its read-only snapshot while it
7508
+ # still holds both writer flocks, and stays active across the
7509
+ # projection reconcile (its journal pipeline can consume a pending
7510
+ # Claude observation and reach the dollar axes) and the budget
7511
+ # ingest. Every Codex budget read in between evaluates on that one
7512
+ # snapshot or defers; none syncs, discovers or parses rollouts.
7513
+ # The context closes the snapshot on every exit path.
7514
+ with cache_mod.hook_codex_read_policy() as read_policy:
7515
+ cache = c.open_cache_db()
7516
+ try:
7517
+ # public #5 spec §4: the hook's ingest leg is BUDGETED and
7518
+ # resumable, and it ingests the active rollout first so
7519
+ # live numbers stay correct while history lags. Only this
7520
+ # caller passes a budget — an explicit `cctally cache-sync`
7521
+ # still runs to completion.
7522
+ import _cctally_config as _cfg_codex
7523
+ budget_seconds = _cfg_codex.resolve_codex_hook_ingest_budget(
7524
+ c.load_config())
7525
+ stats, cache = cache_mod._run_cache_operation_with_recovery(
7526
+ cache,
7527
+ lambda active_conn: c.sync_codex_cache(
7528
+ active_conn, lock_timeout=0,
7529
+ budget_seconds=budget_seconds,
7530
+ active_transcript_path=transcript_path or None,
7531
+ # public #5 spec §4: ONE reconcile per tick. The
7532
+ # explicit alert-eligible reconcile below can never
7533
+ # take the certificate short-circuit (it is guarded
7534
+ # by `not alert_eligible_roots`), so the
7535
+ # sync-internal one was pure duplicated cost.
7536
+ quota_reconcile="defer",
7537
+ ),
7538
+ origin="hook.codex_quota.sync",
7539
+ )
7540
+ finally:
7541
+ cache.close()
7542
+ if stats.lock_contended:
7543
+ # #968 spec 5.7: publish this hook's own waiting request so
7544
+ # drain workers yield once their admitted work commits. The
7545
+ # hook never waits and never touches the drain gate.
7546
+ import _lib_codex_drain_admission as _drain_adm
7547
+ request_id = _drain_adm.publish_waiting_request(
7548
+ _cctally_core.APP_DIR, root_keys=all_root_keys)
7549
+ log_outcome(
7550
+ sync="contended", result="noop",
7551
+ drain_request="published" if request_id else "failed")
7552
+ return 0
7553
+ walk_deferral = getattr(stats, "deferred_reason", None)
7554
+ if walk_deferral in ("quota_index_pending", "inventory_pending"):
7555
+ # #977 C5 / #927 B4: the walk stopped before ingesting
7556
+ # (the quota natural-key index or the retained-identity
7557
+ # inventory is being rebuilt off the hook; the sync
7558
+ # requested the worker after releasing its flocks). Like a
7559
+ # contended tick this is neither success nor error: no root
7560
+ # is acknowledged, so the next Codex turn retries at once,
7561
+ # and no budget is evaluated on a walk that never ran.
7562
+ log_outcome(
7563
+ sync="deferred", result="noop",
7564
+ reason=walk_deferral,
7565
+ backlog=int(getattr(stats, "backlog_files", 0) or 0))
7566
+ return 0
7567
+ projection = c.reconcile_codex_quota_projection(
7568
+ source_root_keys=all_root_keys,
7569
+ alert_eligible_root_keys=due_root_keys,
7570
+ now=dt.datetime.now(dt.timezone.utc),
7571
+ # public #5 spec §2/§4: the hook path NEVER runs a
7572
+ # whole-history quota pass inline — not the once-a-day
7573
+ # verification, and not a rebuilt stats index, an
7574
+ # interpretation bump, a missing reverse map, a reset
7575
+ # ledger or a dirty-unit burst either. On a hook-only
7576
+ # install no dashboard tick or `codex quota` invocation
7577
+ # reaches any of them first, so each would land here as a
7578
+ # ~14-30s reconcile on a blocking path against Codex's
7579
+ # 30-second timeout. `defer` hands every one of them to the
7580
+ # detached `_codex-quota-verify` worker; the bounded ingest
7581
+ # above stays foreground, so fresh observations still
7582
+ # precede the turn.
7583
+ full_pass="defer",
7179
7584
  )
7180
- return 0
7181
- budget_alerts = _budget_holder["n"]
7585
+ # Vendor-scoped spend is intentionally evaluated once per
7586
+ # successful due-set tick, not once per root. Task 7 Item 4:
7587
+ # the on-demand Codex budget firing routes through the
7588
+ # single-flight ingest cycle (the `codex_apply` seam) instead
7589
+ # of opening its own stats connection — so its
7590
+ # `budget_milestones` (vendor=codex) crossings are journaled by
7591
+ # the budget harvest and its alerts dispatch post-commit
7592
+ # (set-then-dispatch). AUTHORITATIVE so a failure propagates to
7593
+ # this leg's try/except (raise_errors=True preserved).
7594
+ import _cctally_journal as _jr_codex
7595
+ _budget_holder = {"n": 0}
7596
+
7597
+ def _codex_budget_leg(ictx):
7598
+ _budget_holder["n"] = int(
7599
+ c.maybe_record_codex_budget_milestone(
7600
+ {}, conn=ictx.conn, alert_sink=ictx.pending_alerts,
7601
+ journal_ctx=ictx,
7602
+ raise_errors=True) or 0)
7603
+
7604
+ budget_ingest = _jr_codex.run_stats_ingest(
7605
+ mode="authoritative", codex_apply=_codex_budget_leg)
7606
+ if not budget_ingest.ran:
7607
+ # A detached quota-verification worker can own the ingest
7608
+ # lock while applying its projection. Authoritative ingest
7609
+ # reports that bounded timeout as `ran=False`;
7610
+ # acknowledging the root here would throttle away the
7611
+ # skipped budget evaluation. Keep the lifecycle markers
7612
+ # due so the first uncontended tick retries the
7613
+ # forward-only budget crossing.
7614
+ log_outcome(
7615
+ sync="contended", result="noop", projection=projection,
7616
+ backlog=int(getattr(stats, "backlog_files", 0) or 0),
7617
+ )
7618
+ return 0
7619
+ budget_alerts = _budget_holder["n"]
7620
+ budget_deferral = read_policy.first_deferral_reason()
7182
7621
  if getattr(stats, "deferred_reason", None) == "replay_pending":
7183
7622
  # public #5: the budgeted tick declined a byte-zero replay, and on
7184
7623
  # a hook-only install nothing else would ever perform one — no
@@ -7189,6 +7628,19 @@ def _cmd_hook_tick_codex(
7189
7628
  # before returning) and after the connection closed, so the worker
7190
7629
  # is not racing this tick for the writer lock.
7191
7630
  cache_mod._defer_codex_replay_drain()
7631
+ if budget_deferral is not None:
7632
+ # #981 A6 / P4: a Codex budget read could not prove a complete
7633
+ # snapshot, so its ladder was skipped rather than evaluated on a
7634
+ # partial total. Neither success nor error, exactly like a
7635
+ # contended tick: no root is acknowledged, so every following due
7636
+ # hook retries, and doctor reads a growing last-success age.
7637
+ log_outcome(
7638
+ sync="deferred", result="noop", projection=projection,
7639
+ budget_alerts=budget_alerts,
7640
+ backlog=int(getattr(stats, "backlog_files", 0) or 0),
7641
+ reason=f"budget_{budget_deferral}",
7642
+ )
7643
+ return 0
7192
7644
  mark_lifecycle_success(locks)
7193
7645
  log_outcome(
7194
7646
  # A byte-zero Codex replay is not sliceable, so a budgeted tick
@@ -8056,6 +8508,8 @@ def _five_hour_saved_from_fold(fold, *, snapshot_id, capture_at,
8056
8508
  future caller has to remember. On a tick whose weekly axis is OBSERVED the
8057
8509
  two collapse to one number, which is why every pre-#824 caller was correct.
8058
8510
  """
8511
+ import _cctally_journal as jr
8512
+ held = fold.weekly.disposition == jr.WEEKLY_HELD_CLAMP
8059
8513
  return {
8060
8514
  "id": snapshot_id,
8061
8515
  "capturedAt": capture_at,
@@ -8064,6 +8518,12 @@ def _five_hour_saved_from_fold(fold, *, snapshot_id, capture_at,
8064
8518
  "fiveHourPercent": fold.five_hour.effective_pct,
8065
8519
  "fiveHourResetsAt": five_hour_resets_at,
8066
8520
  "fiveHourWindowKey": fold.five_hour.window_key,
8521
+ # #956 spec 4.6.1: the held provenance of the block's weekly value,
8522
+ # which a block's opening fact retains (value-only).
8523
+ "blockWeeklyHeld": held,
8524
+ "blockWeeklyBasisCapturedAt": (
8525
+ fold.weekly.basis.captured_at_utc
8526
+ if held and fold.weekly.basis is not None else None),
8067
8527
  }
8068
8528
 
8069
8529
 
@@ -8195,6 +8655,12 @@ def _pipeline_claude_usage(ctx, rec):
8195
8655
  # rebuild offers its read pass to the same projection.
8196
8656
  import _cctally_oauth_samples
8197
8657
  _cctally_oauth_samples.project_record(conn, rec)
8658
+ # #1015 spec 5.1: the observation index, from the same normalized record
8659
+ # at the same site, on live ingest and both scratch replays.
8660
+ import _cctally_journal
8661
+ _cctally_oauth_samples.project_observation(
8662
+ conn, rec,
8663
+ cutover_account=lambda: _cctally_journal.cycle_cutover_claude(ctx))
8198
8664
 
8199
8665
  # Week boundaries from resets_at (cmd_record_usage canonicalization).
8200
8666
  # Normalize before deriving the date keys as well as the ISO overrides:
@@ -8262,7 +8728,11 @@ def _pipeline_claude_usage(ctx, rec):
8262
8728
  # append). Withheld outcomes take the detector's no-outcome branch;
8263
8729
  # ordinary recording below continues (C3).
8264
8730
  import _cctally_quarantine
8731
+ import _lib_outcome_quarantine
8265
8732
  gate = _cctally_quarantine.quarantine_gate(ctx, account_key)
8733
+ if hasattr(gate, "allowed"):
8734
+ # One decision for both axes (a caller-installed or substituted gate).
8735
+ gate = _lib_outcome_quarantine.all_axes(gate)
8266
8736
  # #797/#823/#840 spec 4.9 (D6, D12): the detector revision this raw
8267
8737
  # observation recorded, and which of its axes are readings of its source.
8268
8738
  # An unsupported or malformed revision, or a v2 publication whose
@@ -8292,7 +8762,12 @@ def _pipeline_claude_usage(ctx, rec):
8292
8762
  # #769 S2 §3: the contributor discriminator for five-hour credit
8293
8763
  # confirmation. `payload.source`, never `rec["src"]`.
8294
8764
  source=source,
8295
- hold_weekly_axis=hold_weekly_axis, outcomes_allowed=gate.allowed,
8765
+ hold_weekly_axis=hold_weekly_axis,
8766
+ # #948 spec 6.8: each axis's gate independently — a released
8767
+ # five-hour axis publishes its outcomes while the weekly axis
8768
+ # of the same account stays paused, and vice versa.
8769
+ weekly_outcomes_allowed=gate["sevenDay"].allowed,
8770
+ five_hour_outcomes_allowed=gate["fiveHour"].allowed,
8296
8771
  fold_policy=fold_policy)
8297
8772
 
8298
8773
  # 2. Accept/skip DECISION (clamp + dedup), made ONCE and journaled via the
@@ -8511,7 +8986,8 @@ def _pipeline_claude_usage(ctx, rec):
8511
8986
  five_hour_resets_at=five_hour_resets_at_str,
8512
8987
  ) if wrote_row else five_hour_saved,
8513
8988
  conn=conn, as_of=capture_at, alert_sink=ctx.pending_alerts,
8514
- account_key=account_key, journal_ctx=ctx)
8989
+ account_key=account_key, journal_ctx=ctx,
8990
+ opening_record_id=rec["id"], creation_kind="snapshot")
8515
8991
  # The dollar-decoupled axes resolve a CURRENT budget/period WINDOW from
8516
8992
  # "now" and must see the record's DETECTION clock (`as_of` = rec["at"] =
8517
8993
  # `_command_as_of()`), NOT the wall-clock capture stamp: legacy
@@ -8563,7 +9039,8 @@ def _pipeline_claude_usage(ctx, rec):
8563
9039
  five_hour_resets_at=five_hour_resets_at_str,
8564
9040
  ),
8565
9041
  conn=conn, as_of=capture_at, alert_sink=ctx.pending_alerts,
8566
- account_key=account_key, journal_ctx=ctx)
9042
+ account_key=account_key, journal_ctx=ctx,
9043
+ opening_record_id=rec["id"], creation_kind="heal")
8567
9044
 
8568
9045
  # 5. hwm-7d / hwm-5h projection files — WRITE paths only (the monotonic
8569
9046
  # writer; a no-change tick's percent is already <= the stored HWM).