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
@@ -111,6 +111,122 @@ def plan_five_hour_credit(
111
111
  return prior_resets_in_future and (prior_pct - new_pct) >= drop_threshold
112
112
 
113
113
 
114
+ # ── Fragment 3b: 5h source-local confirmation state machine (#769 S2 §3) ───
115
+ FIVE_HOUR_HOLD = "hold"
116
+ FIVE_HOUR_SET_BASELINE = "set_baseline"
117
+ FIVE_HOUR_ARM = "arm"
118
+ FIVE_HOUR_CONFIRM = "confirm"
119
+ FIVE_HOUR_CANCEL = "cancel"
120
+
121
+
122
+ @dataclass(frozen=True)
123
+ class FiveHourSourceDecision:
124
+ """What one contributor's observation does to that contributor's own
125
+ five-hour credit state.
126
+
127
+ ``action`` is one of the FIVE_HOUR_* constants above. ``baseline_pct`` is
128
+ the baseline to persist afterwards, and is ``None`` exactly when the action
129
+ writes no baseline (FIVE_HOUR_HOLD).
130
+
131
+ ``credit_prior_pct`` and ``credit_post_pct`` are set only on
132
+ FIVE_HOUR_CONFIRM and are the two ends of the credit this decision found:
133
+ the pre-drop baseline and the armed low that dropped away from it. They are
134
+ what the credit event records as ``prior_percent`` and ``post_percent``.
135
+ Both belong to the ARMING observation, because that is the observation that
136
+ saw the drop; the confirming observation only establishes that the drop was
137
+ not a single stale reading, and its own percent is not one end of the
138
+ credit. Binding ``post_percent`` to the confirming percent instead records
139
+ a drop that can be arbitrarily smaller than the eligibility threshold the
140
+ arming leg required — down to nothing at all, since confirmation asks only
141
+ for a reading below the baseline — which is what `R-5HC1` in
142
+ ``bin/cctally-reconcile-test`` forbids.
143
+ """
144
+ action: str
145
+ baseline_pct: float | None = None
146
+ credit_prior_pct: float | None = None
147
+ credit_post_pct: float | None = None
148
+
149
+
150
+ def plan_five_hour_source_local_credit(
151
+ *, baseline_pct, pending_low_pct, pending_observation_id,
152
+ new_pct, observation_id, drop_threshold, window_live,
153
+ ):
154
+ """Classify one observation against ONE contributor's own five-hour state
155
+ (glue call site: ``detect_reset_and_credit``'s 5h branch).
156
+
157
+ The rule this implements (#769 S2 §3, issue #751): a credit needs a
158
+ same-source observed descent followed by a distinct same-source
159
+ confirmation that is still below that source's own pre-drop baseline,
160
+ inside one physical window. Detection used to compare an incoming reading
161
+ against the latest accepted snapshot whatever contributor produced it, so a
162
+ single stale ``source=statusline`` sample below an ``source=api`` baseline
163
+ fabricated a credit with no confirmation from any source.
164
+
165
+ All inputs are that ONE source's own state; the caller selects the row by
166
+ ``(account_key, five_hour_window_key, source)`` and therefore cannot pass
167
+ another contributor's evidence in. ``baseline_pct is None`` means the
168
+ source has no state for this window — a fresh window, or state a rebuild
169
+ dropped.
170
+
171
+ ``drop_threshold`` stays ELIGIBILITY only. It decides whether a decrease is
172
+ large enough to be worth arming; it is not evidence of freshness, and there
173
+ is deliberately no maximum gap, no maximum climb and no confirmation-value
174
+ band, because observations arrive at an unbounded interval and every finite
175
+ threshold on the change between two of them has a legitimate crossing.
176
+ """
177
+ new_pct = float(new_pct)
178
+
179
+ if baseline_pct is None:
180
+ # No state for this source in this window. Establish the baseline and
181
+ # emit nothing: a first reading is not a descent, whatever any other
182
+ # contributor has already reported.
183
+ return FiveHourSourceDecision(FIVE_HOUR_SET_BASELINE, new_pct)
184
+
185
+ baseline_pct = float(baseline_pct)
186
+
187
+ if pending_low_pct is not None:
188
+ # An armed descent from this source.
189
+ if (
190
+ observation_id is not None
191
+ and pending_observation_id is not None
192
+ and observation_id == pending_observation_id
193
+ ):
194
+ # The arming observation replayed. It cannot confirm itself, so
195
+ # leave the state armed and write nothing — the same rule the
196
+ # weekly debounce applies at `first_zero_observation_id`.
197
+ return FiveHourSourceDecision(FIVE_HOUR_HOLD)
198
+ if window_live and new_pct < baseline_pct:
199
+ # A distinct same-source observation, still below the pre-drop
200
+ # baseline, inside the live window. This is the confirmation. The
201
+ # baseline to persist afterwards is this observation's own percent
202
+ # — the source's current level — while the credit itself is the
203
+ # arming observation's descent from `baseline_pct` to
204
+ # `pending_low_pct`.
205
+ return FiveHourSourceDecision(
206
+ FIVE_HOUR_CONFIRM, new_pct, baseline_pct,
207
+ float(pending_low_pct))
208
+ # Back at or above the baseline (or the window is no longer live):
209
+ # the descent was not sustained, so the candidate is cancelled.
210
+ return FiveHourSourceDecision(
211
+ FIVE_HOUR_CANCEL, max(baseline_pct, new_pct))
212
+
213
+ if plan_five_hour_credit(
214
+ baseline_pct, new_pct,
215
+ drop_threshold=drop_threshold, prior_resets_in_future=window_live,
216
+ ):
217
+ return FiveHourSourceDecision(FIVE_HOUR_ARM, baseline_pct)
218
+
219
+ if new_pct > baseline_pct:
220
+ return FiveHourSourceDecision(FIVE_HOUR_SET_BASELINE, new_pct)
221
+
222
+ # Equal, or a decrease too small to be eligible. The baseline is this
223
+ # source's running maximum inside the window, which is what the write-time
224
+ # MAX clamp already makes the accepted snapshots behave like, so a
225
+ # sub-threshold dip does not lower it and a later cumulative drop past the
226
+ # threshold still arms.
227
+ return FiveHourSourceDecision(FIVE_HOUR_HOLD)
228
+
229
+
114
230
  # ── Fragment 4: reset-aware HWM clamp comparison ───────────────────────────
115
231
  def hwm_clamp_applies(incoming_pct: float, recorded_max_pct) -> bool:
116
232
  """Return True when ``incoming_pct`` is below the reset-aware recorded MAX
@@ -181,19 +297,21 @@ def projected_crossings(value: float, levels) -> list:
181
297
 
182
298
 
183
299
  # ── Fragment 8: usage-snapshot fold outcome classification ─────────────────
184
- #: The three outcomes of ``_cctally_journal._usage_snapshot_fold_decision``.
185
- #: ACCEPT journals a ``snapshot_accept`` evt. The two SKIPs both suppress that
186
- #: insert, but they mean OPPOSITE things about the incoming observation and the
187
- #: stored row, so the glue must be able to tell them apart:
300
+ #: RETAINED LEGACY SPELLINGS with no live consumer (#769 S11, #824).
301
+ #:
302
+ #: These were the three outcomes of ``_usage_snapshot_fold_decision`` while it
303
+ #: returned a positional ``(skip, adjusted, reason)`` tuple. It now returns
304
+ #: ``UsageSnapshotFoldResult``, which states the weekly and five-hour axes
305
+ #: separately, and the weekly milestone gate reads that result's held flag
306
+ #: rather than comparing a reason string. Nothing outside this module and its
307
+ #: own test reads these names today.
188
308
  #:
189
- #: * ``SNAPSHOT_SKIP_DEDUP`` — the incoming observation AGREES with the latest
190
- #: stored row (both percents unchanged). Re-running the derivation
191
- #: chokepoints against that row is correct; it is what heals a tick killed
192
- #: between the snapshot insert and the milestone insert.
193
- #: * ``SNAPSHOT_SKIP_CLAMP`` — the incoming 7d percent is strictly BELOW the
194
- #: reset-aware in-window maximum, so the observation CONTRADICTS the stored
195
- #: row. Deriving a weekly milestone from the higher stored value would
196
- #: record a crossing the meter says did not happen.
309
+ #: They are kept rather than deleted because an out-of-tree reader could still
310
+ #: import them, and because the distinction they encode is still true of the
311
+ #: system: a dedup outcome means the incoming observation AGREES with the stored
312
+ #: row, while a clamp outcome means it CONTRADICTS it, and only the second must
313
+ #: suppress a weekly milestone. Deleting them is a behaviour-neutral cleanup,
314
+ #: not part of this change.
197
315
  SNAPSHOT_ACCEPT = "accept"
198
316
  SNAPSHOT_SKIP_CLAMP = "clamp"
199
317
  SNAPSHOT_SKIP_DEDUP = "dedup"