cctally 1.108.0 → 1.110.0

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 (85) hide show
  1. package/CHANGELOG.md +147 -0
  2. package/README.md +6 -6
  3. package/bin/_cctally_account.py +4 -0
  4. package/bin/_cctally_alerts.py +6 -2
  5. package/bin/_cctally_cache.py +1652 -166
  6. package/bin/_cctally_config.py +3 -2
  7. package/bin/_cctally_core.py +594 -33
  8. package/bin/_cctally_dashboard.py +1585 -201
  9. package/bin/_cctally_dashboard_conversation.py +494 -48
  10. package/bin/_cctally_dashboard_envelope.py +167 -11
  11. package/bin/_cctally_dashboard_share.py +154 -36
  12. package/bin/_cctally_dashboard_sources.py +2615 -422
  13. package/bin/_cctally_db.py +678 -5
  14. package/bin/_cctally_diagnosis_sources.py +238 -26
  15. package/bin/_cctally_doctor.py +99 -18
  16. package/bin/_cctally_five_hour.py +1295 -40
  17. package/bin/_cctally_forecast.py +124 -28
  18. package/bin/_cctally_journal.py +408 -38
  19. package/bin/_cctally_milestone_history.py +150 -14
  20. package/bin/_cctally_parser.py +5 -0
  21. package/bin/_cctally_percent_breakdown.py +6 -1
  22. package/bin/_cctally_project.py +48 -76
  23. package/bin/_cctally_quota.py +39 -7
  24. package/bin/_cctally_quota_model.py +17 -2
  25. package/bin/_cctally_record.py +1647 -443
  26. package/bin/_cctally_rederive.py +899 -30
  27. package/bin/_cctally_refresh.py +2 -1
  28. package/bin/_cctally_share.py +24 -5
  29. package/bin/_cctally_source_analytics.py +1035 -78
  30. package/bin/_cctally_statusline.py +83 -19
  31. package/bin/_cctally_store.py +61 -4
  32. package/bin/_cctally_transcript.py +27 -2
  33. package/bin/_cctally_tui.py +264 -76
  34. package/bin/_cctally_weekrefs.py +28 -5
  35. package/bin/_lib_blocks.py +127 -20
  36. package/bin/_lib_cache_report.py +20 -5
  37. package/bin/_lib_codex_conversation_query.py +297 -64
  38. package/bin/_lib_codex_hooks.py +102 -0
  39. package/bin/_lib_codex_metadata.py +207 -0
  40. package/bin/_lib_conversation.py +119 -0
  41. package/bin/_lib_conversation_dispatch.py +31 -1
  42. package/bin/_lib_conversation_query.py +315 -51
  43. package/bin/_lib_conversation_retention.py +413 -25
  44. package/bin/_lib_dashboard_sources.py +267 -7
  45. package/bin/_lib_diagnosis.py +10 -0
  46. package/bin/_lib_diff_kernel.py +12 -1
  47. package/bin/_lib_doctor.py +230 -8
  48. package/bin/_lib_ingest_frontier.py +1366 -49
  49. package/bin/_lib_journal.py +19 -2
  50. package/bin/_lib_merge_gate.py +307 -0
  51. package/bin/_lib_pricing.py +588 -29
  52. package/bin/_lib_record.py +130 -12
  53. package/bin/_lib_rederive.py +903 -2
  54. package/bin/_lib_render.py +9 -3
  55. package/bin/_lib_retained_size.py +27 -2
  56. package/bin/_lib_segment_summary.py +66 -8
  57. package/bin/_lib_share_templates.py +28 -18
  58. package/bin/_lib_snapshot_cache.py +115 -1
  59. package/bin/_lib_source_retry.py +320 -0
  60. package/bin/_lib_statusline_candidates.py +400 -36
  61. package/bin/_lib_tick_stats.py +119 -0
  62. package/bin/_lib_view_models.py +256 -76
  63. package/bin/cctally +69 -0
  64. package/dashboard/static/assets/ConversationsView-BB9vUiL6.js +72 -0
  65. package/dashboard/static/assets/{DoctorModal-CWn3U4Wl.js → DoctorModal-DFY2iPDf.js} +1 -1
  66. package/dashboard/static/assets/ModalRoot-DvRKHbQE.js +1 -0
  67. package/dashboard/static/assets/ProjectsDrillPanel-DAv39uSo.js +1 -0
  68. package/dashboard/static/assets/SourceDetailModal-DSAWo2Fp.js +1 -0
  69. package/dashboard/static/assets/{UpdateModal-D3m8GG6V.js → UpdateModal-R_9dOVnh.js} +3 -3
  70. package/dashboard/static/assets/dashboardStream.shared-worker-DbG6Ef0T.js +1 -0
  71. package/dashboard/static/assets/index-COhxe3vU.css +1 -0
  72. package/dashboard/static/assets/index-DdU62sov.js +13 -0
  73. package/dashboard/static/assets/outlineNavigation-BOCLcRa6.js +9 -0
  74. package/dashboard/static/assets/useKeymap-CW7Up0Ay.js +1 -0
  75. package/dashboard/static/dashboard.html +3 -3
  76. package/package.json +4 -1
  77. package/dashboard/static/assets/ConversationsView-BOSaBRtu.js +0 -72
  78. package/dashboard/static/assets/ModalRoot-SR070V6c.js +0 -1
  79. package/dashboard/static/assets/ProjectsDrillPanel-QLI9i5mZ.js +0 -1
  80. package/dashboard/static/assets/SourceDetailModal-pv0wlFxl.js +0 -1
  81. package/dashboard/static/assets/dashboardStream.shared-worker-1XTMV3nr.js +0 -1
  82. package/dashboard/static/assets/index-BHu4mxd8.css +0 -1
  83. package/dashboard/static/assets/index-CIWsbux3.js +0 -13
  84. package/dashboard/static/assets/outlineNavigation-CJvKqmLV.js +0 -9
  85. package/dashboard/static/assets/useKeymap-ffqsS5G0.js +0 -1
@@ -34,6 +34,10 @@ from _cctally_quota import assert_projection_readable, codex_quota_breakdown
34
34
  from _lib_accounts import UNATTRIBUTED
35
35
  from _lib_codex_pools import is_model_scoped_codex_quota
36
36
  from _lib_dashboard_sources import dashboard_resource_key
37
+ from _cctally_percent_breakdown import (
38
+ OBSERVATION_GAP_CAUSE,
39
+ classify_observation_gaps,
40
+ )
37
41
  from _lib_display_tz import _resolve_display_tz_obj, format_display_dt
38
42
  from _lib_json_envelope import _iso_z
39
43
  from _lib_quota import QuotaWindowIdentity
@@ -316,7 +320,42 @@ def _claude_cycle_rows(conn: sqlite3.Connection, ref) -> list:
316
320
  ).fetchall()
317
321
 
318
322
 
319
- def _index_entry(conn, ref, current_cycle_key, tz) -> dict:
323
+ def _five_hour_detail_revision(conn, start_iso, end_iso) -> tuple[int, ...]:
324
+ """Append-only 5h child revision for one cycle's intersecting blocks.
325
+
326
+ The detail cache uses the index stamp. Weekly crossing counts do not move
327
+ when another account records a 5h credit or crossing in an existing block.
328
+ These child tables insert new ids for those events; count and max id also
329
+ notice deletions and replacement rows without hashing an unbounded ledger.
330
+ """
331
+ if not start_iso or not end_iso:
332
+ return (0, 0, 0, 0, 0, 0)
333
+ interval = (
334
+ "unixepoch(b.block_start_at) < unixepoch(?) "
335
+ "AND unixepoch(b.five_hour_resets_at) > unixepoch(?)"
336
+ )
337
+ bounds = (end_iso, start_iso)
338
+ blocks = conn.execute(
339
+ "SELECT COUNT(*), MAX(b.id) FROM five_hour_blocks b "
340
+ f"WHERE {interval}", bounds,
341
+ ).fetchone()
342
+ milestones = conn.execute(
343
+ "SELECT COUNT(*), MAX(m.id) FROM five_hour_blocks b "
344
+ "JOIN five_hour_milestones m ON m.block_id = b.id "
345
+ f"WHERE {interval}", bounds,
346
+ ).fetchone()
347
+ credits = conn.execute(
348
+ "SELECT COUNT(*), MAX(e.id) FROM five_hour_blocks b "
349
+ "JOIN five_hour_reset_events e "
350
+ "ON e.account_key = b.account_key "
351
+ "AND e.five_hour_window_key = b.five_hour_window_key "
352
+ f"WHERE {interval}", bounds,
353
+ ).fetchone()
354
+ return tuple(int(value or 0) for row in (blocks, milestones, credits)
355
+ for value in row)
356
+
357
+
358
+ def _index_entry(conn, ref, current_cycle_key, tz, *, decorated=False) -> dict:
320
359
  rows = _claude_cycle_rows(conn, ref)
321
360
  milestone_count = len(rows)
322
361
  segment_count = 1 if rows else 0
@@ -325,6 +364,26 @@ def _index_entry(conn, ref, current_cycle_key, tz) -> dict:
325
364
  end_z = _to_iso_z(ref.week_end_at)
326
365
  block_count = _count_blocks(conn, start_z, end_z)
327
366
  key = _claude_cycle_key(ref)
367
+ # R8: leave the <=1-real-account stamp byte-identical. On a decorated
368
+ # provider the fetched block list contains multiple account-owned rows,
369
+ # so its cache identity also needs their child-ledger revision.
370
+ block_revision = (
371
+ _five_hour_detail_revision(conn, start_z, end_z) if decorated else ())
372
+
373
+ # #750 S4 §5.3. A CURRENT single-segment cycle neither fetches its detail
374
+ # nor uses one that arrives, so a gap in the LIVE cycle would stay
375
+ # invisible: the disclosure travels on the week-detail payload. This hint
376
+ # is what gives the client a reason to fetch, and a reason to render what
377
+ # comes back. It was written only after the failing test §5.3 requires
378
+ # demonstrated the need — the probe is
379
+ # `renders the disclosure for a CURRENT single-segment cycle` in
380
+ # `dashboard/web/src/modals/currentWeekHistory.test.tsx`, and it failed.
381
+ #
382
+ # Additive and cheap: the rows are already loaded, and the classifier is
383
+ # the same pure kernel the detail route uses, so the index and the detail
384
+ # cannot disagree about whether a cycle has a gap.
385
+ has_gap = bool(
386
+ classify_observation_gaps(rows).runs) if rows else False
328
387
 
329
388
  return {
330
389
  "key": key,
@@ -335,8 +394,10 @@ def _index_entry(conn, ref, current_cycle_key, tz) -> dict:
335
394
  "milestone_count": milestone_count,
336
395
  "block_count": block_count,
337
396
  "segment_count": segment_count,
397
+ "has_observation_gap": has_gap,
338
398
  "detail_stamp": _mh.compute_detail_stamp(
339
- key, milestone_count, block_count, segment_count, max_captured
399
+ key, milestone_count, block_count, segment_count, max_captured,
400
+ *block_revision,
340
401
  ),
341
402
  }
342
403
 
@@ -357,7 +418,12 @@ def build_claude_week_index(conn: sqlite3.Connection) -> list:
357
418
  )
358
419
  current_cycle_key = _claude_cycle_key(current_ref) if current_ref else None
359
420
  tz = _resolve_display_tz()
360
- entries = [_index_entry(conn, ref, current_cycle_key, tz) for ref in refs]
421
+ import _cctally_account
422
+ decorated = _cctally_account.provider_is_decorated(conn, "claude")
423
+ entries = [
424
+ _index_entry(conn, ref, current_cycle_key, tz, decorated=decorated)
425
+ for ref in refs
426
+ ]
361
427
  entries.sort(key=lambda e: e["start_at_utc"] or "", reverse=True)
362
428
  return entries
363
429
 
@@ -365,29 +431,75 @@ def build_claude_week_index(conn: sqlite3.Connection) -> list:
365
431
  # ── Claude week detail (spec §1b) ──────────────────────────────────────
366
432
 
367
433
 
368
- def _shape_weekly_milestone(row) -> dict:
434
+ def _shape_weekly_milestone(row, *, withheld: bool = False) -> dict:
369
435
  """Reshape a ``percent_milestones`` row to the envelope
370
436
  ``current_week.milestones`` wire shape (byte-parallel with
371
- ``_cctally_dashboard_envelope.snapshot_to_envelope``)."""
437
+ ``_cctally_dashboard_envelope.snapshot_to_envelope``).
438
+
439
+ ``withheld`` (#750 S4 §5.1) says the classifier identified this row's null
440
+ marginal as an observation gap rather than an absent one. The shaper
441
+ emitted five fields and dropped the cause, so the modal rendered a bare em
442
+ dash for a figure the CLI names. The key is snake_case to match its
443
+ neighbours on this wire shape, which is one of the frozen legacy snake
444
+ surfaces `docs/cli-contract.md` describes; the CLI's own JSON keeps its
445
+ camelCase `marginalCostWithheldCause`.
446
+
447
+ The field appears ONLY on a withheld row, so every existing payload byte
448
+ is unchanged.
449
+ """
372
450
  marginal = row["marginal_cost_usd"]
373
451
  fh = row["five_hour_percent_at_crossing"]
374
- return {
452
+ shaped = {
375
453
  "percent": int(row["percent_threshold"]),
376
454
  "crossed_at_utc": _to_iso_z(row["captured_at_utc"]),
377
455
  "cumulative_usd": round(float(row["cumulative_cost_usd"]), 4),
378
456
  "marginal_usd": None if marginal is None else round(float(marginal), 4),
379
457
  "five_hour_pct_at_cross": None if fh is None else float(fh),
380
458
  }
459
+ if withheld and marginal is None:
460
+ shaped["marginal_usd_withheld_cause"] = OBSERVATION_GAP_CAUSE
461
+ return shaped
462
+
463
+
464
+ def _shape_observation_gap_runs(disclosure, rows) -> list:
465
+ """The classified runs, as the additive week-detail wire member.
466
+
467
+ #750 S4 §5.2. The per-row cause alone cannot state a run's first threshold
468
+ or the instant of the previous crossing, which are what the note above the
469
+ table is about, so the runs travel as structured data and the CLIENT
470
+ composes the sentence through `lib/fmt.ts`. Shipping a pre-rendered
471
+ sentence would put a presentation decision inside a data contract and
472
+ bypass the browser's display-timezone chokepoint, so the viewer's zone
473
+ would come from the server's idea of it.
474
+
475
+ Ordered ascending by first threshold. Absent or empty means no gap.
476
+ """
477
+ out: list = []
478
+ for run in sorted(disclosure.runs, key=lambda r: r.first_threshold):
479
+ out.append({
480
+ "first_percent": int(run.first_threshold),
481
+ "last_percent": int(run.last_threshold),
482
+ "observed_at_utc": _to_iso_z(run.captured_at_utc),
483
+ # None when the run opens the ladder and has no predecessor.
484
+ "previous_crossed_at_utc": (
485
+ _to_iso_z(run.previous_captured_at_utc)
486
+ if run.previous_captured_at_utc else None
487
+ ),
488
+ })
489
+ return out
381
490
 
382
491
 
383
- def _load_block_credits(conn: sqlite3.Connection, window_key: int) -> list:
492
+ def _load_block_credits(
493
+ conn: sqlite3.Connection, window_key: int, account_key: str,
494
+ ) -> list:
384
495
  """5h in-place credit rows for a block, ascending by effective time —
385
496
  same wire shape as the envelope's ``five_hour_block.credits``."""
386
497
  rows = conn.execute(
387
498
  "SELECT effective_reset_at_utc, prior_percent, post_percent "
388
- "FROM five_hour_reset_events WHERE five_hour_window_key = ? "
499
+ "FROM five_hour_reset_events "
500
+ "WHERE five_hour_window_key = ? AND account_key = ? "
389
501
  "ORDER BY effective_reset_at_utc ASC",
390
- (int(window_key),),
502
+ (int(window_key), account_key),
391
503
  ).fetchall()
392
504
  return [
393
505
  {
@@ -407,14 +519,22 @@ def _build_blocks(conn: sqlite3.Connection, start_iso, end_iso) -> list:
407
519
  if not start_iso or not end_iso:
408
520
  return []
409
521
  c = _cctally()
522
+ import _cctally_account
523
+ decorated = _cctally_account.provider_is_decorated(conn, "claude")
524
+ # #834 S1 (#836): `id` is selected so each block's milestones are loaded by
525
+ # the PRECISE selector. This route used to select blocks account-blind and
526
+ # then pass a bare `five_hour_window_key` to the milestone read, while block
527
+ # uniqueness is `(account_key, five_hour_window_key)` — so one physical
528
+ # window's per-account blocks each rendered EVERY account's milestones. `id`
529
+ # stays internal: it is not added to the published `blocks[]` shape.
410
530
  rows = conn.execute(
411
- "SELECT five_hour_window_key, block_start_at, five_hour_resets_at, "
531
+ "SELECT id, account_key, five_hour_window_key, block_start_at, five_hour_resets_at, "
412
532
  " final_five_hour_percent, total_cost_usd, "
413
533
  " crossed_seven_day_reset, is_closed "
414
534
  "FROM five_hour_blocks "
415
535
  "WHERE unixepoch(block_start_at) < unixepoch(?) "
416
536
  " AND unixepoch(five_hour_resets_at) > unixepoch(?) "
417
- "ORDER BY unixepoch(block_start_at) ASC, five_hour_window_key ASC",
537
+ "ORDER BY unixepoch(block_start_at) ASC, five_hour_window_key ASC, id ASC",
418
538
  (end_iso, start_iso),
419
539
  ).fetchall()
420
540
  out: list = []
@@ -431,8 +551,14 @@ def _build_blocks(conn: sqlite3.Connection, start_iso, end_iso) -> list:
431
551
  "total_cost_usd": None if cost is None else float(cost),
432
552
  "crossed_seven_day_reset": bool(b["crossed_seven_day_reset"]),
433
553
  "is_closed": bool(b["is_closed"]),
434
- "milestones": c._tui_build_five_hour_milestones(conn, wk),
435
- "credits": _load_block_credits(conn, wk),
554
+ "milestones": c._tui_build_five_hour_milestones(
555
+ conn, wk, block_id=int(b["id"])),
556
+ "credits": _load_block_credits(conn, wk, b["account_key"]),
557
+ **({
558
+ "account_key": b["account_key"],
559
+ "account_label": _cctally_account.display_account_label(
560
+ conn, b["account_key"]),
561
+ } if decorated else {}),
436
562
  }
437
563
  )
438
564
  return out
@@ -452,9 +578,17 @@ def build_claude_week_detail(conn: sqlite3.Connection, key: str) -> "dict | None
452
578
  "milestone_segment", "claude", ref.key,
453
579
  ref.week_start_at or None, ref.week_end_at or None,
454
580
  )
581
+ # #750 S4 §5.1: classify BEFORE shaping, through the existing pure kernel,
582
+ # so the shaper can name a null marginal's cause instead of dropping it.
583
+ disclosure = classify_observation_gaps(rows)
455
584
  segments = ([{"key": segment_key,
456
- "milestones": [_shape_weekly_milestone(r) for r in rows]}]
585
+ "milestones": [
586
+ _shape_weekly_milestone(
587
+ r, withheld=i in disclosure.withheld_indexes)
588
+ for i, r in enumerate(rows)
589
+ ]}]
457
590
  if rows else [])
591
+ gap_runs = _shape_observation_gap_runs(disclosure, rows) if rows else []
458
592
  blocks = _build_blocks(conn, entry["start_at_utc"], entry["end_at_utc"])
459
593
 
460
594
  return {
@@ -466,6 +600,8 @@ def build_claude_week_detail(conn: sqlite3.Connection, key: str) -> "dict | None
466
600
  "is_current": entry["is_current"],
467
601
  "detail_stamp": entry["detail_stamp"],
468
602
  "segments": segments,
603
+ # #750 S4 §5.2: additive and nullable. Absent or empty means no gap.
604
+ "observation_gap_runs": gap_runs,
469
605
  "dividers": [],
470
606
  "blocks": blocks,
471
607
  }
@@ -3175,6 +3175,11 @@ def _build_db_parser(subparsers, name, *, help_text, xref=None):
3175
3175
  action="store_true",
3176
3176
  help="Append the correction batch and rebuild stats.db (default: preview)",
3177
3177
  )
3178
+ db_rederive.add_argument(
3179
+ "--reviewed-weekly-decisions",
3180
+ metavar="PATH",
3181
+ help="Review exact Claude weekly observations from a pinned manifest",
3182
+ )
3178
3183
  db_rederive.add_argument(
3179
3184
  "--json",
3180
3185
  action="store_true",
@@ -384,7 +384,12 @@ def cmd_percent_breakdown(args: argparse.Namespace) -> int:
384
384
  # uses) so the display header shows the effective window — e.g.
385
385
  # a post-reset short week shows "2026-04-23..2026-04-25" rather
386
386
  # than the backdated API-derived "2026-04-18..2026-04-25".
387
- canon_start, canon_end = c._get_canonical_boundary_for_date(conn, week_start_date)
387
+ # SCOPED to the requesting account (#834 S2, #837): every other read
388
+ # in this command already carries `_acct_pred`, and a merged boundary
389
+ # read renders another account's window over this account's
390
+ # milestones.
391
+ canon_start, canon_end = c._get_canonical_boundary_for_date(
392
+ conn, week_start_date, account_key=acct_key)
388
393
  display_start_iso = canon_start
389
394
  display_end_iso = canon_end
390
395
  if canon_start and canon_end:
@@ -29,8 +29,8 @@ import sys
29
29
 
30
30
  from _cctally_core import (
31
31
  _command_as_of,
32
- _floored_week_max,
33
32
  eprint,
33
+ latest_usage_by_segment,
34
34
  open_db,
35
35
  parse_iso_datetime,
36
36
  )
@@ -327,7 +327,7 @@ def render_attribution_footer(totals, *, basis, cause) -> "list[str]":
327
327
  "Modelled quota: withheld \u2014 "
328
328
  f"{_cause_copy(cause)}. Used % is a cost share.")
329
329
  else:
330
- parts = [f"{modelled:,.2f} points across the modelled weeks"]
330
+ parts = [f"{modelled:,.2f} points across the modelled cycles"]
331
331
  if visible is not None:
332
332
  parts.append(f"{visible:,.2f} in the rows listed")
333
333
  if unmodelled is not None:
@@ -378,84 +378,45 @@ def observed_minus_modelled(*, observed, modelled):
378
378
 
379
379
 
380
380
  def _load_week_snapshots(
381
- since: dt.datetime, until: dt.datetime, *,
382
- account_key: "str | None" = None,
381
+ subweeks, *, account_key: "str | None" = None,
383
382
  ) -> dict[dt.datetime, float]:
384
- """Return {week_start_utc -> max(weekly_percent)} for weeks intersecting
385
- the [since, until] range.
386
-
387
- Reads the `weekly_percent` column of `weekly_usage_snapshots` (authoritative
388
- column name — NOT `used_7d_percent`). A week's "used %" is the maximum
389
- snapshot captured within that week (the monotonic-within-window invariant:
390
- weekly_percent only increases across the life of a week). Skips rows
391
- whose `week_start_at` or `week_end_at` are NULL (pre-migration legacy
392
- rows that only carried date granularity).
393
-
394
- MAX is computed in Python keyed on the parsed UTC datetime so that rows
395
- holding different string spellings of the same instant (e.g. `+00:00` vs
396
- `+03:00` from pre-UTC-cast canonicalizer history) coalesce into one
397
- bucket instead of splitting and silently dropping the higher value.
398
-
399
- Reset-aware (record-credit M2, #209): each week's MAX is restricted to
400
- snapshots captured at-or-after that week's latest in-place clamp floor
401
- (`_reset_aware_floor`, the union of `week_reset_events` +
402
- `weekly_credit_floors`). Without this, a credited week's per-project Used %
403
- would read the stale pre-credit peak (e.g. 46) instead of the post-credit
404
- value (e.g. 31) — the same floor the statusline / write-clamp / `--from`
405
- helper apply (spec §4a, test S15). The floor compare uses `unixepoch()` on
406
- both sides (mixed `Z` / `+00:00` offset spellings).
407
-
408
- ``account_key`` (#620 S1): scopes the read to one account's snapshots.
409
- ``None`` — the default and every unfiltered invocation — is the merged
410
- all-accounts read, byte-identical to before. A real key is required under
411
- ``--account``: two accounts hold independent weekly quotas, so summing
412
- another account's percentage into an account-filtered total reports a
413
- figure that describes neither account. Percentages across accounts are
414
- never summed for the same reason the dashboard never sums them.
415
-
416
- Returns an empty dict if the stats DB has no relevant rows.
383
+ """Return ``{segment start (UTC) -> that cycle's weekly_percent}``.
384
+
385
+ #750 S4 §2.1. This used to return ``{week_start_utc -> max(weekly_percent)}``
386
+ keyed on `weekly_usage_snapshots.week_start_at`, while `cmd_project` looked
387
+ each week up with a `SubWeek.start_ts` instant. On a credited week those are
388
+ different quantities: the post-credit segment matched nothing and landed in
389
+ `weeks_missing_snapshot`, and the pre-credit segment received the
390
+ POST-credit reading. That is #731.
391
+
392
+ It is now a thin wrapper over `latest_usage_by_segment`, the shared reducer
393
+ the dashboard projects panel also calls, so the CLI and the panel resolve a
394
+ cycle's percentage through one implementation instead of two. The keys are
395
+ parsed back to datetimes because that is `cmd_project`'s bucket identity,
396
+ and a segment with no observation inside its own interval is ABSENT rather
397
+ than carrying a neighbour's reading — which is what lets
398
+ `weeks_missing_snapshot` report one missing cycle per cut.
399
+
400
+ This wrapper is the leg that opens its own connection; the reducer takes
401
+ the caller's, because the dashboard already holds a transaction.
417
402
  """
418
- acct_pred = "" if account_key is None else " AND account_key = ?"
419
- acct_params: tuple = () if account_key is None else (account_key,)
420
403
  conn = open_db()
421
404
  try:
422
- try:
423
- cur = conn.execute(
424
- "SELECT week_start_date, week_start_at, week_end_at, "
425
- " captured_at_utc, weekly_percent "
426
- "FROM weekly_usage_snapshots "
427
- "WHERE week_start_at IS NOT NULL "
428
- "AND week_end_at IS NOT NULL "
429
- "AND datetime(week_start_at) < datetime(?) "
430
- "AND datetime(week_end_at) > datetime(?)"
431
- f"{acct_pred}",
432
- (until.isoformat(), since.isoformat(), *acct_params),
433
- )
434
- except sqlite3.OperationalError:
435
- # A stats.db predating the `account_key` column — an install
436
- # whose migrations have not run, or a dev binary that refused
437
- # the prod forward-migration (#142). `_projects_week_grid`
438
- # carries the same guard for the same predicate.
439
- #
440
- # Withholding is the degradation, not dropping the predicate:
441
- # retrying unscoped would sum another account's weekly
442
- # percentage into an account-filtered total, which is the
443
- # figure describing neither account that #620 S1 removed.
444
- return {}
445
- rows_in = []
446
- for wsd, ws_iso, we_iso, cap_iso, pct in cur.fetchall():
447
- if ws_iso is None or pct is None:
448
- continue
449
- ws = dt.datetime.fromisoformat(str(ws_iso).replace("Z", "+00:00"))
450
- key = ws.astimezone(dt.timezone.utc)
451
- rows_in.append((key, wsd, ws_iso, we_iso, cap_iso, pct))
452
- # Reset-aware per-week max (#290): the shared reducer resolves each
453
- # week's clamp floor once (keyed on week_start_date) and drops stale
454
- # pre-credit captures before taking the per-week maximum. The query
455
- # above already filters NULL bounds, so canonical bounds are present.
456
- return _floored_week_max(conn, rows_in)
405
+ by_segment = latest_usage_by_segment(
406
+ conn, subweeks, account_key=account_key)
457
407
  finally:
458
408
  conn.close()
409
+ out: dict[dt.datetime, float] = {}
410
+ for segment_key, pct in by_segment.items():
411
+ if pct is None:
412
+ continue
413
+ try:
414
+ out[parse_iso_datetime(
415
+ segment_key, "subweek.segment_key",
416
+ ).astimezone(dt.timezone.utc)] = float(pct)
417
+ except (TypeError, ValueError):
418
+ continue
419
+ return out
459
420
 
460
421
 
461
422
  def _sum_cost_by_project(
@@ -1143,8 +1104,13 @@ def cmd_project(args: argparse.Namespace) -> int:
1143
1104
  # intersects [since_dt, until_dt]. Missing snapshots are tracked so we
1144
1105
  # can surface `weeksMissingSnapshot` in the output — those weeks can't
1145
1106
  # contribute to attributed %.
1107
+ # One value per SEGMENT, resolved inside that cycle's own half-open
1108
+ # interval (#750 S4 §2.1 / #731). The emitted `SubWeek`s are handed over
1109
+ # rather than a date range, because the segment IS the identity
1110
+ # `cmd_project` buckets by and a date is what the two cycles of a
1111
+ # credited week share.
1146
1112
  week_snapshots: dict[dt.datetime, float] = _load_week_snapshots(
1147
- since_dt, until_dt, account_key=acct_key,
1113
+ subweeks, account_key=acct_key,
1148
1114
  )
1149
1115
 
1150
1116
  # Set of every week the user asked about (from the computed SubWeek
@@ -1158,11 +1124,17 @@ def cmd_project(args: argparse.Namespace) -> int:
1158
1124
  # #661 S2 §5.1: one decision per subscription week, over that week's WHOLE
1159
1125
  # account population. A week with an unsupported or out-of-regime segment
1160
1126
  # falls back for the whole week; partial-week mixtures are not produced.
1127
+ # The segment's REAL emitted end, never `ws + 7d` (#750 S4 §2.5). Once
1128
+ # `ws` is a credit cut that synthetic end is not the cycle's end, and a
1129
+ # bounded regime can then classify a short segment as crossing a boundary
1130
+ # it never reaches.
1131
+ _end_by_start = {s_dt: e_dt for s_dt, e_dt in parsed_bounds}
1161
1132
  week_attribution: dict = {}
1162
1133
  for ws in sorted(set(week_starts) | set(week_records)):
1163
1134
  week_attribution[ws] = resolve_week_attribution(
1164
1135
  attribution_regime, week_records.get(ws, ()),
1165
- week_start=ws, week_end=ws + dt.timedelta(days=7))
1136
+ week_start=ws,
1137
+ week_end=_end_by_start.get(ws, ws + dt.timedelta(days=7)))
1166
1138
  modelled_weeks = sorted(
1167
1139
  ws for ws, attr in week_attribution.items()
1168
1140
  if attr.basis == "modelled")
@@ -322,8 +322,31 @@ PROJECTION_DYNAMIC_READ_SITES: "dict[str, int]" = {
322
322
  # the hole `PROJECTION_DYNAMIC_READ_SITES` exists to close. `{table}` there
323
323
  # iterates a hardcoded conversation-table tuple, so none of them reaches a
324
324
  # projection family and none needs an entry below.
325
- "_cctally_cache.py": 3,
326
- "_cctally_core.py": 2,
325
+ #
326
+ # Seven, not three, since #769 S3. The four new reads all name the browse
327
+ # rollup or its staging twin — `_recompute_conversation_sessions`' two
328
+ # `SELECT … FROM {target}` derivations plus
329
+ # `_fill_conversation_sessions_filter_columns`' `PRAGMA table_info({target})`
330
+ # and its session-id scan — so a rebuild can derive its replacement
331
+ # generation into `conversation_sessions_staging` without touching what
332
+ # readers are reading (#752). `{target}` substitutes one of exactly two
333
+ # names chosen inside `_cctally_cache`, neither of which is a projection
334
+ # table, so none of them needs an entry below either.
335
+ #
336
+ # Nine, not seven, since #769 S3 tranche 3. `conversation_legacy_bridge_pending`
337
+ # adds `SELECT 1 FROM main.{table}` and `SELECT 1 FROM cache_db.{table}`,
338
+ # which are `_import_legacy_conversation_rows`' own condition read back as
339
+ # a pure predicate so the read-only reader can DETECT that the bridge still
340
+ # has work without performing it (#780). `{table}` iterates the same
341
+ # hardcoded `_LEGACY_BRIDGE_TABLES` tuple as the three reads above, so
342
+ # neither reaches a projection family and neither needs an entry below.
343
+ "_cctally_cache.py": 9,
344
+ # One, not two, since #750 S4: `_get_latest_row_for_week` composed
345
+ # its `WHERE` clauses instead of branching on `as_of_utc`, so its
346
+ # two near-identical `FROM {table_name}` reads became one. The
347
+ # target is still `weekly_usage_snapshots` or
348
+ # `weekly_cost_snapshots`; neither is a projection table.
349
+ "_cctally_core.py": 1,
327
350
  "_cctally_dashboard.py": 3,
328
351
  "_cctally_dashboard_envelope.py": 5,
329
352
  # Six, not seven: `cctally: rebuilt stats.db from {} journal segment(s)` is
@@ -347,12 +370,21 @@ PROJECTION_DYNAMIC_READ_SITES: "dict[str, int]" = {
347
370
  "_lib_codex_conversation_query.py": 1,
348
371
  "_lib_conversation_query.py": 1,
349
372
  "_lib_conversation_retention.py": 2,
350
- # Three: `_target_has_cursor_gap` selects one of the two accounting source
351
- # tables, while `_conversation_source_paths` and `_conversation_target_risk`
352
- # select one of the two transcript source tables. Every choice is hardcoded;
353
- # none is a quota projection table, so no
373
+ # Five: `_target_has_cursor_gap` selects one of the two accounting source
374
+ # tables, `_conversation_source_paths` and `_conversation_target_risk`
375
+ # select one of the two transcript source tables, and #769 S6's
376
+ # `select_recently_active_codex_paths` reads whichever Codex cursor table
377
+ # its caller owns — twice, once for the recency predicate and once for the
378
+ # ticket-named paths that predicate missed. That choice is confined to
379
+ # `_CODEX_CURSOR_TABLES` and validated against it before the query is
380
+ # built. Six, not five, since #769 S6 T2a's `32b8eaa0a`: `_source_paths`
381
+ # now reads `f"SELECT path FROM {table}"`, where `_ingest_source_table`
382
+ # returns `session_files` or `codex_session_files` in place of the literal
383
+ # pair the planner used to spell at its own call site. That function is
384
+ # total over those two names and raises on anything else. Every choice here
385
+ # is hardcoded; none is a quota projection table, so no
354
386
  # `PROJECTION_DYNAMIC_READ_ACTIONS` classification applies.
355
- "_lib_ingest_frontier.py": 3,
387
+ "_lib_ingest_frontier.py": 6,
356
388
  "_lib_snapshot_cache.py": 1,
357
389
  "_lib_subscription_weeks.py": 1,
358
390
  }
@@ -236,11 +236,16 @@ def _read_stats_component(conn, account_key, start):
236
236
  excluded at the query as a closed committed set; an unrecognized source is
237
237
  retained and counted.
238
238
  """
239
+ # `weekly_observation_held = 0` (#769 S11, #824): these rows ARE the meter
240
+ # readings the coefficients are fitted against. A held row repeats the
241
+ # latest genuine reading under a later capture instant, so admitting one
242
+ # would feed the fit a flat interval that no upstream meter reported —
243
+ # a fabricated observation rather than a missing one.
239
244
  placeholders = ",".join("?" for _ in SYNTHETIC_SNAPSHOT_SOURCES)
240
245
  sql = (
241
246
  "SELECT id, captured_at_utc, week_start_at, week_start_date,"
242
247
  " weekly_percent, source FROM weekly_usage_snapshots"
243
- f" WHERE source NOT IN ({placeholders})"
248
+ f" WHERE weekly_observation_held = 0 AND source NOT IN ({placeholders})"
244
249
  )
245
250
  params: list = list(SYNTHETIC_SNAPSHOT_SOURCES)
246
251
  if start is not None:
@@ -345,10 +350,15 @@ def _retained_snapshot_span(conn, account_key):
345
350
  rows, so it needs the span the floor hides. An empty store returns
346
351
  `(None, None)` and says nothing.
347
352
  """
353
+ # Same population as `_read_stats_component` (#769 S11, #824). The finding
354
+ # this span qualifies is a statement about the readings the model used, so
355
+ # the two must count the same rows; a span computed over a wider set would
356
+ # report an era the fit never saw.
348
357
  placeholders = ",".join("?" for _ in SYNTHETIC_SNAPSHOT_SOURCES)
349
358
  sql = ("SELECT MIN(captured_at_utc), MAX(captured_at_utc)"
350
359
  " FROM weekly_usage_snapshots"
351
- f" WHERE source NOT IN ({placeholders})")
360
+ " WHERE weekly_observation_held = 0"
361
+ f" AND source NOT IN ({placeholders})")
352
362
  params: list = list(SYNTHETIC_SNAPSHOT_SOURCES)
353
363
  clause, extra = _account_clause("account_key", account_key)
354
364
  sql += clause
@@ -509,6 +519,11 @@ def _unattributed_bucket_has_rows() -> bool:
509
519
  return False
510
520
  try:
511
521
  placeholders = ",".join("?" for _ in SYNTHETIC_SNAPSHOT_SOURCES)
522
+ # HELD-INCLUSIVE, decided rather than overlooked (#769 S11, #824).
523
+ # This asks whether the bucket contains any real observation at all,
524
+ # not what its weekly value is, and a held row is a real write by a
525
+ # real tick. The answer cannot differ in practice either way, because a
526
+ # held row implies a non-held basis in the same bucket.
512
527
  row = conn.execute(
513
528
  "SELECT 1 FROM weekly_usage_snapshots WHERE source NOT IN "
514
529
  f"({placeholders}) AND (account_key IS NULL OR account_key = ?)"