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
@@ -127,8 +127,36 @@ def _resolve_forecast_now(as_of: str | None) -> dt.datetime:
127
127
  return _command_as_of()
128
128
 
129
129
 
130
+ def _shape_week_samples(rows, *, include_held: bool,
131
+ include_account: bool = False) -> list:
132
+ """Turn snapshot rows into the sample tuples `_fetch_current_week_snapshots`
133
+ returns. Both of that function's row-fetch legs go through here so the two
134
+ cannot drift on the tuple width.
135
+
136
+ `rows` are `(captured_at_utc, weekly_percent, five_hour_percent,
137
+ weekly_observation_held[, account_key])`. The held flag is appended only
138
+ for a held-inclusive read, and the account only for an explicit identity
139
+ read. Existing consumers keep the historical three- or four-field shape.
140
+ """
141
+ out = []
142
+ for row in rows:
143
+ sample = (
144
+ parse_iso_datetime(row[0], "captured_at_utc"),
145
+ float(row[1]),
146
+ float(row[2]) if row[2] is not None else None,
147
+ )
148
+ if include_held:
149
+ sample = sample + (int(row[3] or 0),)
150
+ if include_account:
151
+ sample = sample + (row[4],)
152
+ out.append(sample)
153
+ return out
154
+
155
+
130
156
  def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime,
131
- *, account_key: "str | None" = None):
157
+ *, account_key: "str | None" = None,
158
+ include_held: bool = False,
159
+ include_account: bool = False):
132
160
  """Return (week_start_at, week_end_at, list[(captured_at, percent, five_hr)])
133
161
  for the subscription week containing `now_utc`, or None if no snapshot
134
162
  exists for the current week.
@@ -157,16 +185,46 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
157
185
  Samples are filtered to `captured_at <= now_utc` so that `--as-of <past>`
158
186
  is deterministic (no leak of future snapshots into samples[-1] / p_now /
159
187
  snapshot_count / latest_snapshot_at).
188
+
189
+ ``include_held`` (#769 S11, #824) selects the AXIS. A
190
+ `weekly_observation_held` row carries the writing tick's capture time,
191
+ source and five-hour reading while its weekly value and boundary are
192
+ copied forward from the latest genuinely observed row, so:
193
+
194
+ * ``False`` (the default, and every weekly caller) excludes those rows.
195
+ This function IS the weekly sample series — the weekly projection, the
196
+ weekly freshness stamp and `snapshot_count` are all derived from it —
197
+ and a held row would contribute a repeat of an older reading under a
198
+ newer instant, inflating the sample count and stamping stale weekly
199
+ evidence as fresh.
200
+ * ``True`` retains them and appends a fourth element, the held flag, to
201
+ every sample. One query then serves both axes: a caller reading the
202
+ five-hour axis takes the newest sample, a caller reading the weekly
203
+ axis takes the newest sample whose flag is 0, and neither can mistake
204
+ a carried-forward weekly value for an observed one.
205
+
206
+ ``include_account`` appends the physical account key after the held flag
207
+ for the multi-account Current Week card only. The default wire-independent
208
+ sample shape and merged forecast/cost reads remain unchanged.
160
209
  """
161
210
  # #341: optional account scoping — same predicate on every leg so the whole
162
211
  # window resolution stays consistent (a real key or the `unattributed`
163
212
  # sentinel both match `account_key = ?`; `None` omits the predicate = merged).
164
213
  _acct_pred = "" if account_key is None else " AND account_key = ?"
165
214
  _acct_p: tuple = () if account_key is None else (account_key,)
215
+ # Applied to the WINDOW-RESOLUTION legs as well as the row fetches, so
216
+ # `include_held=True` is a pure superset of the default read rather than a
217
+ # read that can also resolve a different week.
218
+ _held_pred = "" if include_held else " AND weekly_observation_held = 0"
219
+ # The TUI's multi-account card needs the physical owner of the sample it
220
+ # actually displays. Keep the historical sample shape for every other read.
221
+ _owner_column = ", account_key" if include_account else ""
222
+ _sample_order = " ASC, id ASC" if include_account else " ASC"
166
223
  candidates = conn.execute(
167
224
  "SELECT week_start_at, week_end_at, week_start_date, MAX(captured_at_utc) AS latest_cap "
168
225
  "FROM weekly_usage_snapshots "
169
- "WHERE week_start_at IS NOT NULL AND week_end_at IS NOT NULL" + _acct_pred +
226
+ "WHERE week_start_at IS NOT NULL AND week_end_at IS NOT NULL"
227
+ + _acct_pred + _held_pred +
170
228
  " GROUP BY week_start_at, week_end_at, week_start_date",
171
229
  _acct_p,
172
230
  ).fetchall()
@@ -192,7 +250,8 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
192
250
  drow = conn.execute(
193
251
  "SELECT week_start_date, week_end_date "
194
252
  "FROM weekly_usage_snapshots "
195
- "WHERE week_start_date <= ? AND week_end_date >= ?" + _acct_pred +
253
+ "WHERE week_start_date <= ? AND week_end_date >= ?"
254
+ + _acct_pred + _held_pred +
196
255
  " GROUP BY week_start_date, week_end_date "
197
256
  "ORDER BY MAX(captured_at_utc) DESC LIMIT 1",
198
257
  (today_local_str, today_local_str) + _acct_p,
@@ -206,17 +265,15 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
206
265
  week_start_at = dt.datetime.combine(ws_date, dt.time(0, 0), local_tz).astimezone(dt.timezone.utc)
207
266
  week_end_at = dt.datetime.combine(we_date + dt.timedelta(days=1), dt.time(0, 0), local_tz).astimezone(dt.timezone.utc)
208
267
  rows = conn.execute(
209
- "SELECT captured_at_utc, weekly_percent, five_hour_percent "
268
+ "SELECT captured_at_utc, weekly_percent, five_hour_percent, "
269
+ " weekly_observation_held" + _owner_column + " "
210
270
  "FROM weekly_usage_snapshots "
211
- "WHERE week_start_date = ?" + _acct_pred +
212
- " ORDER BY captured_at_utc ASC",
271
+ "WHERE week_start_date = ?" + _acct_pred + _held_pred +
272
+ " ORDER BY captured_at_utc" + _sample_order,
213
273
  (drow[0],) + _acct_p,
214
274
  ).fetchall()
215
- samples = [
216
- (parse_iso_datetime(r[0], "captured_at_utc"), float(r[1]),
217
- float(r[2]) if r[2] is not None else None)
218
- for r in rows
219
- ]
275
+ samples = _shape_week_samples(rows, include_held=include_held,
276
+ include_account=include_account)
220
277
  samples = [s for s in samples if s[0] <= now_utc]
221
278
  return week_start_at, week_end_at, samples
222
279
  row = chosen
@@ -237,18 +294,17 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
237
294
  chosen_date = chosen[2]
238
295
  placeholders = ",".join("?" * len(matching_texts))
239
296
  rows = conn.execute(
240
- f"SELECT captured_at_utc, weekly_percent, five_hour_percent "
297
+ f"SELECT captured_at_utc, weekly_percent, five_hour_percent, "
298
+ f" weekly_observation_held{_owner_column} "
241
299
  f"FROM weekly_usage_snapshots "
242
300
  f"WHERE (week_start_at IN ({placeholders}) "
243
- f" OR (week_start_at IS NULL AND week_start_date = ?)){_acct_pred} "
244
- f"ORDER BY captured_at_utc ASC",
301
+ f" OR (week_start_at IS NULL AND week_start_date = ?))"
302
+ f"{_acct_pred}{_held_pred} "
303
+ f"ORDER BY captured_at_utc{_sample_order}",
245
304
  tuple(matching_texts) + (chosen_date,) + _acct_p,
246
305
  ).fetchall()
247
- samples = [
248
- (parse_iso_datetime(r[0], "captured_at_utc"), float(r[1]),
249
- float(r[2]) if r[2] is not None else None)
250
- for r in rows
251
- ]
306
+ samples = _shape_week_samples(rows, include_held=include_held,
307
+ include_account=include_account)
252
308
  samples = [s for s in samples if s[0] <= now_utc]
253
309
  return week_start_at, week_end_at, samples
254
310
 
@@ -854,12 +910,30 @@ def _select_dollars_per_percent(
854
910
  source_col = ("source" if "source" in present else "NULL")
855
911
  payload_col = ("payload_json" if "payload_json" in present
856
912
  else "NULL")
913
+ # Held rows are excluded: `_realized_week_movement` sums POSITIVE
914
+ # DELTAS between consecutive readings, which is a weekly-axis question
915
+ # (#769 S11, #824).
916
+ #
917
+ # Inside one account a held row repeats the immediately preceding
918
+ # genuine reading and contributes a delta of exactly zero, so this
919
+ # predicate changes nothing there. It matters on the MERGED read, where
920
+ # `account_key` is None: `_realized_week_movement` orders the merged
921
+ # readings by capture instant alone, so account A's held row can follow
922
+ # account B's lower reading and contribute a large spurious positive
923
+ # delta. Review finding F2 — the earlier held-inclusive justification
924
+ # was stated unqualified but is true only per account.
925
+ #
926
+ # Guarded on `_snapshot_columns`, because this query already reads a
927
+ # store that may predate the column.
928
+ held_pred = (" AND weekly_observation_held = 0"
929
+ if "weekly_observation_held" in present else "")
857
930
  snap = conn.execute(
858
931
  "SELECT week_start_date, week_start_at, week_end_at, "
859
932
  " captured_at_utc, weekly_percent, "
860
933
  f" {source_col}, {payload_col} "
861
934
  "FROM weekly_usage_snapshots "
862
- "WHERE week_start_at IN (" + placeholders + ")" + _acct_pred,
935
+ "WHERE week_start_at IN (" + placeholders + ")"
936
+ + held_pred + _acct_pred,
863
937
  ws_iso_list + list(_acct_p),
864
938
  ).fetchall()
865
939
  for wsd, ws_iso, we_iso, cap_iso, pct, source, payload in snap:
@@ -1070,7 +1144,10 @@ def _assess_forecast_confidence(
1070
1144
 
1071
1145
 
1072
1146
  def _pick_p_24h_ago(
1073
- samples: list[tuple[dt.datetime, float, float | None]],
1147
+ # Three members when `_fetch_current_week_snapshots` ran with
1148
+ # `include_held=False`, four when the held flag is appended. Only the first
1149
+ # two are read here, so both shapes are accepted deliberately.
1150
+ samples: list[tuple],
1074
1151
  now_utc: dt.datetime,
1075
1152
  ) -> tuple[float | None, float | None]:
1076
1153
  """Return (p_24h_ago, t_24h_actual_hours). Closest to (now_utc - 24h)
@@ -1292,25 +1369,39 @@ def _load_forecast_inputs(
1292
1369
  account (``forecast --account``).
1293
1370
  """
1294
1371
  c = _cctally()
1295
- fetched = _fetch_current_week_snapshots(conn, now_utc, account_key=account_key)
1372
+ # #769 S11 (#824): ONE read, held-inclusive, split per axis below.
1373
+ fetched = _fetch_current_week_snapshots(
1374
+ conn, now_utc, account_key=account_key, include_held=True)
1296
1375
  if fetched is None:
1297
1376
  return None
1298
- week_start_at, week_end_at, samples = fetched
1299
- if not samples:
1377
+ week_start_at, week_end_at, observations = fetched
1378
+ if not observations:
1300
1379
  return None
1301
1380
 
1302
1381
  # Mid-week reset override: shift week_start_at to the effective
1303
1382
  # reset moment and drop pre-reset samples so elapsed/remaining math
1304
1383
  # and spent_usd reflect the post-reset window only.
1305
- week_start_at, samples = _apply_midweek_reset_override(
1306
- conn, week_start_at, week_end_at, samples, now_utc=now_utc
1384
+ week_start_at, observations = _apply_midweek_reset_override(
1385
+ conn, week_start_at, week_end_at, observations, now_utc=now_utc
1307
1386
  )
1308
1387
 
1388
+ if not observations:
1389
+ return None
1390
+ # The weekly axis. A `weekly_observation_held` row repeats an older weekly
1391
+ # reading under a newer capture instant, so every weekly quantity derived
1392
+ # below — `p_now`, the 24-hour anchor, `snapshot_count` and
1393
+ # `latest_snapshot_at` — is taken from genuinely observed rows alone.
1394
+ # Counting a held row would both stamp stale weekly evidence as fresh and
1395
+ # raise the confidence assessment on a sample that observed nothing.
1396
+ samples = [s for s in observations if not s[3]]
1309
1397
  if not samples:
1310
1398
  return None
1311
1399
  latest = samples[-1]
1312
1400
  p_now = latest[1]
1313
- five_hr = latest[2]
1401
+ # The five-hour axis, which is why the read is held-inclusive: a held row
1402
+ # exists precisely because its five-hour reading GREW, so the newest
1403
+ # observation of either kind is the current five-hour percentage.
1404
+ five_hr = observations[-1][2]
1314
1405
 
1315
1406
  elapsed_hours = (now_utc - week_start_at).total_seconds() / 3600.0
1316
1407
  total_hours = (week_end_at - week_start_at).total_seconds() / 3600.0
@@ -2111,7 +2202,12 @@ def cmd_report(args: argparse.Namespace) -> int:
2111
2202
  ).fetchone()
2112
2203
  if latest_usage is not None:
2113
2204
  date_str = latest_usage["week_start_date"]
2114
- canon_start, canon_end = c._get_canonical_boundary_for_date(conn, date_str)
2205
+ # SCOPED to the requesting account (#834 S2, #837). The latest
2206
+ # usage row above is already account-scoped, so resolving its
2207
+ # boundary account-blind handed the current week the window the
2208
+ # EARLIEST-capturing account established.
2209
+ canon_start, canon_end = c._get_canonical_boundary_for_date(
2210
+ conn, date_str, account_key=acct_key)
2115
2211
  current_ref = make_week_ref(
2116
2212
  week_start_date=date_str,
2117
2213
  week_end_date=latest_usage["week_end_date"],