cctally 1.114.0 → 1.115.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 (64) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/bin/_cctally_account.py +32 -8
  3. package/bin/_cctally_cache.py +4394 -279
  4. package/bin/_cctally_completion.py +1287 -0
  5. package/bin/_cctally_config.py +37 -0
  6. package/bin/_cctally_core.py +178 -2
  7. package/bin/_cctally_dashboard.py +2 -2
  8. package/bin/_cctally_dashboard_conversation.py +292 -23
  9. package/bin/_cctally_dashboard_envelope.py +16 -3
  10. package/bin/_cctally_dashboard_sources.py +18 -9
  11. package/bin/_cctally_db.py +316 -5
  12. package/bin/_cctally_doctor.py +436 -27
  13. package/bin/_cctally_five_hour.py +82 -31
  14. package/bin/_cctally_forecast.py +81 -9
  15. package/bin/_cctally_journal.py +3884 -112
  16. package/bin/_cctally_journal_repair.py +101 -12
  17. package/bin/_cctally_parser.py +42 -0
  18. package/bin/_cctally_project.py +8 -2
  19. package/bin/_cctally_quarantine.py +652 -0
  20. package/bin/_cctally_quota.py +26 -4
  21. package/bin/_cctally_quota_model.py +360 -83
  22. package/bin/_cctally_record.py +677 -149
  23. package/bin/_cctally_rederive.py +297 -32
  24. package/bin/_cctally_refresh.py +84 -13
  25. package/bin/_cctally_source_analytics.py +23 -2
  26. package/bin/_cctally_statusline.py +6137 -517
  27. package/bin/_cctally_store.py +287 -48
  28. package/bin/_cctally_transcript.py +8 -7
  29. package/bin/_cctally_tui.py +57 -53
  30. package/bin/_lib_account_binding.py +152 -0
  31. package/bin/_lib_account_protocol.py +386 -0
  32. package/bin/_lib_aggregators.py +4 -0
  33. package/bin/_lib_cache_coverage.py +13 -1
  34. package/bin/_lib_cache_writer_lock.py +19 -3
  35. package/bin/_lib_clone_copy.py +142 -0
  36. package/bin/_lib_codex_conversation_query.py +133 -19
  37. package/bin/_lib_codex_conversation_watch.py +59 -14
  38. package/bin/_lib_codex_drain_admission.py +214 -0
  39. package/bin/_lib_codex_metadata.py +18 -1
  40. package/bin/_lib_codex_publication_barrier.py +277 -0
  41. package/bin/_lib_codex_rollout_container.py +502 -0
  42. package/bin/_lib_conversation_dispatch.py +3 -0
  43. package/bin/_lib_conversation_query.py +11 -3
  44. package/bin/_lib_detector_access_registry.py +3817 -0
  45. package/bin/_lib_doctor.py +452 -1
  46. package/bin/_lib_five_hour.py +126 -0
  47. package/bin/_lib_ingest_frontier.py +414 -20
  48. package/bin/_lib_journal.py +141 -10
  49. package/bin/_lib_jsonl.py +5 -4
  50. package/bin/_lib_legacy_spool.py +126 -0
  51. package/bin/_lib_legacy_writer_evidence.py +136 -0
  52. package/bin/_lib_merge_gate.py +29 -302
  53. package/bin/_lib_meter_rate_change.py +10 -0
  54. package/bin/_lib_outcome_quarantine.py +690 -0
  55. package/bin/_lib_pricing.py +7 -2
  56. package/bin/_lib_quarantine.py +154 -0
  57. package/bin/_lib_quota_calibration.py +53 -8
  58. package/bin/_lib_quota_copy.py +2 -1
  59. package/bin/_lib_quota_model.py +288 -46
  60. package/bin/_lib_rederive.py +94 -5
  61. package/bin/_lib_segment_summary.py +35 -2
  62. package/bin/_lib_statusline_candidates.py +292 -23
  63. package/bin/cctally +23 -1
  64. package/package.json +14 -1
@@ -11,6 +11,11 @@ drift independently; the regression `bin/cctally-5h-canonical-test`
11
11
  pins the cross-shape equivalence (epoch-int → datetime → epoch round-trip
12
12
  matches the modulo floor on 600-aligned base epochs).
13
13
 
14
+ `latest_five_hour_reading` is the one read-only selection of an account's
15
+ newest five-hour reading (#825/#832 spec 4.7 revision 7): it takes the
16
+ caller's connection and runs one bounded statement, so the module stays free
17
+ of I/O at import time and of sibling imports.
18
+
14
19
  `bin/cctally` re-exports every symbol below so internal call sites and
15
20
  SourceFileLoader-based tests/fixtures (`tests/test_blocks_recorded_anchor`,
16
21
  `tests/test_five_hour_block_selector`, `tests/test_five_hour_blocks_json`,
@@ -24,6 +29,7 @@ from __future__ import annotations
24
29
 
25
30
  import datetime as dt
26
31
  import math
32
+ from dataclasses import dataclass
27
33
 
28
34
 
29
35
  _FIVE_HOUR_JITTER_FLOOR_SECONDS = 600 # 10 minutes; tolerance band for resets_at jitter
@@ -141,3 +147,123 @@ def _canonical_5h_window_key(
141
147
  ):
142
148
  return prior_key
143
149
  return resets_at_epoch - (resets_at_epoch % _FIVE_HOUR_JITTER_FLOOR_SECONDS)
150
+
151
+
152
+ @dataclass(frozen=True)
153
+ class FiveHourReading:
154
+ """One five-hour reading, every field taken from ONE snapshot row.
155
+
156
+ ``resets_at`` is the row's stored ``five_hour_resets_at`` text (``None`` on
157
+ a hand-built or legacy row that stores only the canonical key) and
158
+ ``window_key`` its canonical window: the stored key, or the
159
+ ``_canonical_5h_window_key`` floor of the stored reset for a row that
160
+ predates the key. ``snapshot_id`` / ``captured_at_utc`` / ``account_key`` identify the
161
+ row, and ``weekly_observation_held`` says whether its WEEKLY axis was
162
+ carried forward — its five-hour fields are the writing tick's own either
163
+ way.
164
+ """
165
+
166
+ percent: float
167
+ resets_at: "str | None"
168
+ window_key: int
169
+ captured_at_utc: str
170
+ snapshot_id: int
171
+ account_key: str
172
+ weekly_observation_held: bool
173
+
174
+
175
+ def latest_five_hour_reading(
176
+ conn,
177
+ *,
178
+ account_key: "str | None" = None,
179
+ as_of_utc: "str | None" = None,
180
+ captured_at_or_after_utc: "str | None" = None,
181
+ week_start_date: "str | None" = None,
182
+ week_start_at_in: "tuple[str, ...] | list[str] | None" = None,
183
+ ) -> "FiveHourReading | None":
184
+ """The newest ``weekly_usage_snapshots`` row carrying a five-hour reading
185
+ (#825/#832 spec 4.7 revision 7 *Latest five-hour reading*).
186
+
187
+ The ONE shared, read-only selection every reader of the newest five-hour
188
+ value uses. A five-hour credit retires a stale replica in place (its three
189
+ five-hour columns NULL, its weekly evidence kept), and an ordinary
190
+ weekly-only reading has the same shape, so either can be the newest row
191
+ while saying nothing about the five-hour axis. Eligible rows carry a
192
+ finite, non-negative percent and a resolvable canonical window (the stored
193
+ ``five_hour_window_key``, else ``_canonical_5h_window_key`` of a parseable
194
+ ``five_hour_resets_at``; the recorder always writes all three together),
195
+ held rows included (a held row's five-hour fields are the writing tick's
196
+ own). Zero is a valid percent. Weekly evidence is NOT selected here: callers select it
197
+ independently, with their own freshness and held-row rules.
198
+
199
+ Every restriction is the CALLER's, applied unchanged:
200
+
201
+ - ``account_key``: ``None`` adds no account predicate (the caller's own
202
+ account-blind contract); a key, including ``unattributed``, scopes the
203
+ selection to that account, so one account never borrows another's
204
+ reading.
205
+ - ``as_of_utc`` / ``captured_at_or_after_utc``: an inclusive capture
206
+ window, compared as instants.
207
+ - ``week_start_date`` alone: one week date key. With ``week_start_at_in``:
208
+ the week whose ``week_start_at`` is one of those texts, or a
209
+ ``week_start_at``-less row of that date (the current-week reader's
210
+ scope).
211
+
212
+ The selection is one ``LIMIT 1`` statement, so no history-sized sort is
213
+ materialized. ``None`` means no eligible row.
214
+ """
215
+ clauses = [
216
+ "five_hour_percent IS NOT NULL",
217
+ "five_hour_percent >= 0",
218
+ "five_hour_percent <= 1e308",
219
+ "(five_hour_window_key IS NOT NULL "
220
+ " OR unixepoch(five_hour_resets_at) IS NOT NULL)",
221
+ ]
222
+ params: list = []
223
+ if account_key is not None:
224
+ clauses.append("account_key = ?")
225
+ params.append(account_key)
226
+ if as_of_utc is not None:
227
+ clauses.append("unixepoch(captured_at_utc) <= unixepoch(?)")
228
+ params.append(as_of_utc)
229
+ if captured_at_or_after_utc is not None:
230
+ clauses.append("unixepoch(captured_at_utc) >= unixepoch(?)")
231
+ params.append(captured_at_or_after_utc)
232
+ if week_start_at_in is not None:
233
+ texts = tuple(week_start_at_in)
234
+ if not texts:
235
+ clauses.append("(week_start_at IS NULL AND week_start_date = ?)")
236
+ else:
237
+ clauses.append(
238
+ "(week_start_at IN (" + ",".join("?" * len(texts)) + ") "
239
+ "OR (week_start_at IS NULL AND week_start_date = ?))")
240
+ params.extend(texts)
241
+ params.append(week_start_date)
242
+ elif week_start_date is not None:
243
+ clauses.append("week_start_date = ?")
244
+ params.append(week_start_date)
245
+ row = conn.execute(
246
+ "SELECT id, account_key, captured_at_utc, five_hour_percent, "
247
+ " five_hour_resets_at, five_hour_window_key, "
248
+ " unixepoch(five_hour_resets_at), weekly_observation_held "
249
+ "FROM weekly_usage_snapshots WHERE " + " AND ".join(clauses) +
250
+ " ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
251
+ tuple(params),
252
+ ).fetchone()
253
+ if row is None:
254
+ return None
255
+ percent = float(row[3])
256
+ if not math.isfinite(percent) or percent < 0:
257
+ return None
258
+ window_key = (
259
+ int(row[5]) if row[5] is not None
260
+ else _canonical_5h_window_key(int(row[6])))
261
+ return FiveHourReading(
262
+ percent=percent,
263
+ resets_at=row[4],
264
+ window_key=window_key,
265
+ captured_at_utc=row[2],
266
+ snapshot_id=int(row[0]),
267
+ account_key=row[1],
268
+ weekly_observation_held=bool(row[7]),
269
+ )