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
@@ -28,6 +28,19 @@ decision. (The schema-3 `retract` projects each retraction as an ordinary
28
28
  Rows are retained: nothing in this work prunes the table. The read is exact-
29
29
  window (spec D9) and an unavailable projection raises
30
30
  :class:`ProjectionUnavailable` rather than answering "no sample".
31
+
32
+ #1015 (spec 5.1) adds the lineage facts beside them, on the same paths:
33
+
34
+ * `claude_weekly_observation_index`, one row per admitted Claude usage
35
+ observation carrying a weekly reading (:func:`project_observation` live and
36
+ scratch; :class:`RebuildProjector` in the rebuild, which stages a record the
37
+ legacy normalization would stamp in `rebuild_weekly_observation_unstamped`
38
+ until :func:`attribute_staged_observations` knows the cutover account);
39
+ * `claude_weekly_correction_history`, every decision of every reviewed op with
40
+ its decoded disposition, written by the same op applier;
41
+ * `claude_weekly_correction_ops`, the op's journal coordinate, written by
42
+ :func:`record_correction_op` on the published paths only (live ingest and
43
+ the rebuild). A scratch replay never writes it.
31
44
  """
32
45
  from __future__ import annotations
33
46
 
@@ -63,7 +76,7 @@ _READ_WEEKLY = (
63
76
  " AND NOT EXISTS (SELECT 1 FROM claude_weekly_observation_decisions AS d"
64
77
  " WHERE d.observation_id = s.observation_id"
65
78
  " AND d.disposition = 'hold')"
66
- " ORDER BY s.requested_at_utc, s.observation_id"
79
+ " ORDER BY s.requested_at_utc"
67
80
  )
68
81
  _READ_FIVE_HOUR = (
69
82
  f"SELECT {_COLUMNS} FROM claude_oauth_samples AS s"
@@ -71,8 +84,38 @@ _READ_FIVE_HOUR = (
71
84
  " AND s.requested_at_utc > ? AND s.five_hour_percent IS NOT NULL"
72
85
  " AND unixepoch(s.captured_at_utc)"
73
86
  " < MIN(unixepoch(s.five_hour_resets_at_utc), s.five_hour_window_key)"
74
- " ORDER BY s.requested_at_utc, s.observation_id"
87
+ " ORDER BY s.requested_at_utc"
88
+ )
89
+ _INSERT_OBSERVATION = (
90
+ "INSERT OR IGNORE INTO claude_weekly_observation_index (observation_id,"
91
+ " account_key, captured_at_utc) VALUES (?, ?, ?)"
92
+ )
93
+ #: The rebuild's staging table for observations whose account is the cutover
94
+ #: op's (known only after the read pass). Scratch-index only; dropped by
95
+ #: :func:`attribute_staged_observations` before the inventory check.
96
+ STAGING_TABLE = "rebuild_weekly_observation_unstamped"
97
+ _CREATE_STAGING = (
98
+ "CREATE TABLE IF NOT EXISTS rebuild_weekly_observation_unstamped ("
99
+ " observation_id TEXT PRIMARY KEY, captured_at_utc TEXT NOT NULL)"
100
+ )
101
+ _INSERT_STAGED = (
102
+ "INSERT OR IGNORE INTO rebuild_weekly_observation_unstamped"
103
+ " (observation_id, captured_at_utc) VALUES (?, ?)"
75
104
  )
105
+ _INSERT_HISTORY = (
106
+ "INSERT OR IGNORE INTO claude_weekly_correction_history (decision_op_id,"
107
+ " observation_id, disposition) VALUES (?, ?, ?)"
108
+ )
109
+ _INSERT_OP = (
110
+ "INSERT OR IGNORE INTO claude_weekly_correction_ops (decision_op_id,"
111
+ " op_segment, op_offset) VALUES (?, ?, ?)"
112
+ )
113
+ #: The reviewed weekly decision op kinds whose journal coordinate lineage
114
+ #: records.
115
+ DECISION_OP_KINDS = frozenset((
116
+ "claude_weekly_observation_decision",
117
+ "claude_weekly_observation_decision_v2",
118
+ ))
76
119
  _UPSERT_DECISION = (
77
120
  "INSERT INTO claude_weekly_observation_decisions (observation_id,"
78
121
  " disposition, decision_op_id) VALUES (?, ?, ?)"
@@ -132,6 +175,86 @@ def project_record(conn, rec) -> None:
132
175
  project_sample(conn, sample)
133
176
 
134
177
 
178
+ def _weekly_observation_key(rec) -> "tuple[str, str] | None":
179
+ """``(observation_id, captured_at_utc)`` of one Claude usage observation
180
+ carrying a weekly reading — exactly the records
181
+ `_cctally_record._pipeline_claude_usage` derives — or None. The capture
182
+ instant is the recording path's fallback (`payload.captured_at`, else the
183
+ record's `at`) in canonical full-precision UTC; a record whose instants
184
+ are both unparsable projects nothing."""
185
+ if not isinstance(rec, dict) or rec.get("t") != "obs":
186
+ return None
187
+ if rec.get("provider") != "claude":
188
+ return None
189
+ payload = rec.get("payload")
190
+ if (not isinstance(payload, dict)
191
+ or "resets_at" not in payload or "weekly_percent" not in payload):
192
+ return None
193
+ import _cctally_record
194
+ if rec.get("src") not in _cctally_record._CLAUDE_OBS_SRCS:
195
+ return None
196
+ observation_id = rec.get("id")
197
+ if not isinstance(observation_id, str) or not observation_id:
198
+ return None
199
+ for value in (payload.get("captured_at"), rec.get("at")):
200
+ if not value:
201
+ continue
202
+ try:
203
+ return observation_id, _lib_oauth_samples.canonical_instant(value)
204
+ except (TypeError, ValueError):
205
+ continue
206
+ return None
207
+
208
+
209
+ def project_observation(conn, rec, *, cutover_account=None) -> None:
210
+ """#1015 spec 5.1: project ``rec`` into `claude_weekly_observation_index`
211
+ on live ingest and the scratch replays, under the one attribution rule:
212
+ the stamp, else `unattributed` — except a record the legacy normalization
213
+ would stamp, which takes the cutover op's Claude account.
214
+
215
+ The scratch replays normalize before their hooks, so they never reach
216
+ that branch. Live ingest does NOT normalize an observation before the
217
+ pipeline, so it passes ``cutover_account`` (a zero-argument callable,
218
+ resolved at most once per cycle) and the index still agrees with the
219
+ rebuild's staged attribution. Idempotent under the primary key."""
220
+ key = _weekly_observation_key(rec)
221
+ if key is None:
222
+ return
223
+ import _cctally_journal
224
+ import _lib_accounts
225
+ account = rec.get("account") or _lib_accounts.UNATTRIBUTED
226
+ if (cutover_account is not None
227
+ and _cctally_journal.needs_cutover_attribution(rec)):
228
+ account = cutover_account()
229
+ conn.execute(_INSERT_OBSERVATION, (key[0], account, key[1]))
230
+
231
+
232
+ def attribute_staged_observations(conn, claude_account: str) -> int:
233
+ """Move the rebuild's staged observations into the index under the
234
+ cutover op's Claude account (``claude_account``, `unattributed` when the
235
+ journal has none), then drop the staging table. One transaction; a no-op
236
+ when nothing was staged. Returns the number of rows moved."""
237
+ present = conn.execute(
238
+ "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?",
239
+ (STAGING_TABLE,)).fetchone()
240
+ if present is None:
241
+ return 0
242
+ conn.execute("BEGIN IMMEDIATE")
243
+ try:
244
+ moved = conn.execute(
245
+ "INSERT OR IGNORE INTO claude_weekly_observation_index"
246
+ " (observation_id, account_key, captured_at_utc)"
247
+ " SELECT observation_id, ?, captured_at_utc"
248
+ " FROM rebuild_weekly_observation_unstamped",
249
+ (claude_account,)).rowcount
250
+ conn.execute("DROP TABLE rebuild_weekly_observation_unstamped")
251
+ conn.commit()
252
+ except BaseException:
253
+ conn.rollback()
254
+ raise
255
+ return moved
256
+
257
+
135
258
  class RebuildProjector:
136
259
  """The apply-only rebuild's leg of the projection: its single read pass
137
260
  offers every admitted record, and samples are projected into the scratch
@@ -143,30 +266,54 @@ class RebuildProjector:
143
266
  def __init__(self, conn) -> None:
144
267
  self._conn = conn
145
268
  self._pending: list = []
269
+ # #1015: observation-index rows, ``(statement, params)``, flushed in
270
+ # the same bounded batches.
271
+ self._observations: list = []
272
+ self._staging_created = False
146
273
  self.projected = 0
147
274
 
148
275
  def offer(self, rec) -> None:
149
276
  sample = sample_from_record(rec)
150
- if sample is None:
151
- return
152
- self._pending.append(sample)
153
- if len(self._pending) >= self.BATCH:
277
+ if sample is not None:
278
+ self._pending.append(sample)
279
+ key = _weekly_observation_key(rec)
280
+ if key is not None:
281
+ # The record is not yet normalized: a record the legacy
282
+ # normalization would stamp takes the cutover account, which only
283
+ # the end of the pass knows, so it is staged; every other record
284
+ # keeps its stamp or `unattributed` (spec 5.1's three cases).
285
+ import _cctally_journal
286
+ if _cctally_journal.needs_cutover_attribution(rec):
287
+ self._observations.append((_INSERT_STAGED, key))
288
+ else:
289
+ import _lib_accounts
290
+ self._observations.append(
291
+ (_INSERT_OBSERVATION,
292
+ (key[0], rec.get("account") or _lib_accounts.UNATTRIBUTED,
293
+ key[1])))
294
+ if len(self._pending) + len(self._observations) >= self.BATCH:
154
295
  self.flush()
155
296
 
156
297
  def flush(self) -> None:
157
- if not self._pending:
298
+ if not self._pending and not self._observations:
158
299
  return
159
300
  conn = self._conn
160
301
  conn.execute("BEGIN IMMEDIATE")
161
302
  try:
162
303
  for sample in self._pending:
163
304
  project_sample(conn, sample)
305
+ for statement, params in self._observations:
306
+ if statement is _INSERT_STAGED and not self._staging_created:
307
+ conn.execute(_CREATE_STAGING)
308
+ self._staging_created = True
309
+ conn.execute(statement, params)
164
310
  conn.commit()
165
311
  except BaseException:
166
312
  conn.rollback()
167
313
  raise
168
314
  self.projected += len(self._pending)
169
315
  self._pending = []
316
+ self._observations = []
170
317
 
171
318
 
172
319
  def apply_weekly_observation_decision_op(conn, record) -> None:
@@ -186,6 +333,11 @@ def apply_weekly_observation_decision_op(conn, record) -> None:
186
333
  op_id = record.get("id")
187
334
  if not isinstance(op_id, str):
188
335
  return
336
+ # #1015 spec 5.1: the history carries the DECODED disposition, so a
337
+ # schema-3 retraction (projected as an ordinary `hold`) is `retract`.
338
+ retractions = payload.get("weekly_axis_retractions") if version == 3 else None
339
+ retracted = (frozenset(r for r in retractions if isinstance(r, str))
340
+ if isinstance(retractions, list) else frozenset())
189
341
  for item in decisions:
190
342
  if not isinstance(item, dict):
191
343
  continue
@@ -195,6 +347,28 @@ def apply_weekly_observation_decision_op(conn, record) -> None:
195
347
  and disposition in _DISPOSITIONS):
196
348
  conn.execute(_UPSERT_DECISION,
197
349
  (observation_id, disposition, op_id))
350
+ conn.execute(_INSERT_HISTORY, (
351
+ op_id, observation_id,
352
+ "retract" if (disposition == "hold"
353
+ and observation_id in retracted)
354
+ else disposition))
355
+
356
+
357
+ def record_correction_op(conn, record, coordinate) -> None:
358
+ """#1015 spec 5.1: record where a reviewed weekly decision op sits in the
359
+ journal — ``coordinate`` is the END ``(segment, offset)`` of its line, as
360
+ the published path read it. Live ingest and the rebuild call this; a
361
+ scratch replay has no coordinate and never does. Idempotent."""
362
+ if coordinate is None or not isinstance(record, dict):
363
+ return
364
+ payload = record.get("payload")
365
+ if (not isinstance(payload, dict)
366
+ or payload.get("kind") not in DECISION_OP_KINDS):
367
+ return
368
+ op_id = record.get("id")
369
+ if not isinstance(op_id, str) or not op_id:
370
+ return
371
+ conn.execute(_INSERT_OP, (op_id, str(coordinate[0]), int(coordinate[1])))
198
372
 
199
373
 
200
374
  def read_samples(conn, *, account_key: str,
@@ -232,6 +406,10 @@ def read_samples(conn, *, account_key: str,
232
406
  rows = conn.execute(sql, (account_key, key, after)).fetchall()
233
407
  except sqlite3.OperationalError as exc:
234
408
  raise ProjectionUnavailable(str(exc)) from exc
409
+ # #1019: the window's index serves the `q` order; equal-`q` ties are
410
+ # ordered here, because an `observation_id` term in the SQL ORDER BY needs
411
+ # a temporary B-tree, which the render path's plan policy refuses (#902).
412
+ rows.sort(key=lambda row: (row[2], row[1]))
235
413
  return tuple(_lib_oauth_samples.OAuthSample(*row) for row in rows)
236
414
 
237
415
 
@@ -3872,6 +3872,42 @@ def _build_codex_prune_drain_parser(subparsers, name, *, help_text, xref=None):
3872
3872
  )
3873
3873
  pd.set_defaults(func=c.cmd_codex_prune_drain_internal)
3874
3874
 
3875
+ def _build_quota_index_rebuild_parser(subparsers, name, *, help_text, xref=None):
3876
+ """Build the `_quota-index-rebuild` parser (#977 C7)."""
3877
+ c = _cctally()
3878
+ qi = subparsers.add_parser(
3879
+ name,
3880
+ help=help_text,
3881
+ formatter_class=CLIHelpFormatter,
3882
+ description=textwrap.dedent(
3883
+ """\
3884
+ Internal subcommand: detached worker that rebuilds the
3885
+ journal's Codex quota natural-key index off the hook,
3886
+ with a bounded locked publication. Always returns 0;
3887
+ the outcome is written to hook-tick.log.
3888
+ """
3889
+ ),
3890
+ )
3891
+ qi.set_defaults(func=c.cmd_quota_index_rebuild_internal)
3892
+
3893
+ def _build_codex_inventory_bootstrap_parser(subparsers, name, *, help_text, xref=None):
3894
+ """Build the `_codex-inventory-bootstrap` parser (#927 spec §4.2 B2)."""
3895
+ c = _cctally()
3896
+ ib = subparsers.add_parser(
3897
+ name,
3898
+ help=help_text,
3899
+ formatter_class=CLIHelpFormatter,
3900
+ description=textwrap.dedent(
3901
+ """\
3902
+ Internal subcommand: detached worker that backfills the
3903
+ Codex retained-identity inventory off the hook, one
3904
+ admitted chunk at a time. Always returns 0; the outcome
3905
+ is written to hook-tick.log.
3906
+ """
3907
+ ),
3908
+ )
3909
+ ib.set_defaults(func=c.cmd_codex_inventory_bootstrap_internal)
3910
+
3875
3911
  def _build_repair_symlinks_parser(subparsers, name, *, help_text, xref=None):
3876
3912
  """Build the `repair-symlinks` parser (registered via _REGISTRATION; #279 S6 W3).
3877
3913
 
@@ -3962,6 +3998,8 @@ _REGISTRATION = (
3962
3998
  _Reg('_artifact-retention', _build_artifact_retention_parser, argparse.SUPPRESS, None, None),
3963
3999
  _Reg('_codex-replay-drain', _build_codex_replay_drain_parser, argparse.SUPPRESS, None, None),
3964
4000
  _Reg('_codex-prune-drain', _build_codex_prune_drain_parser, argparse.SUPPRESS, None, None),
4001
+ _Reg('_quota-index-rebuild', _build_quota_index_rebuild_parser, argparse.SUPPRESS, None, None),
4002
+ _Reg('_codex-inventory-bootstrap', _build_codex_inventory_bootstrap_parser, argparse.SUPPRESS, None, None),
3965
4003
  _Reg('repair-symlinks', _build_repair_symlinks_parser, argparse.SUPPRESS, None, None),
3966
4004
  )
3967
4005
 
@@ -62,7 +62,8 @@ def _cctally():
62
62
  #: outside the stored regime's coefficient era (#978 spec 4.6).
63
63
  ATTRIBUTION_CAUSES = ("account-not-resolved", "calibration-absent",
64
64
  "regime-boundary", "unsupported-composition",
65
- "no-local-history", "unvalidated-coefficient-era")
65
+ "no-local-history", "unvalidated-coefficient-era",
66
+ "recalibration-needed")
66
67
 
67
68
  #: The three bases a row or a run can carry.
68
69
  ATTRIBUTION_BASES = ("modelled", "cost-share", "withheld")
@@ -198,7 +199,8 @@ def resolve_attribution_account_gate(*, account_key, decorated):
198
199
  return None, None
199
200
 
200
201
 
201
- def resolve_week_attribution(regime, records, *, week_start, week_end):
202
+ def resolve_week_attribution(regime, records, *, week_start, week_end,
203
+ absent_cause="calibration-absent"):
202
204
  """Whether one subscription week can be modelled, and at what rate.
203
205
 
204
206
  A week whose entries do not all fall inside the regime's half-open
@@ -214,7 +216,10 @@ def resolve_week_attribution(regime, records, *, week_start, week_end):
214
216
  not this one.
215
217
  """
216
218
  if regime is None:
217
- return WeekAttribution("cost-share", "calibration-absent", None)
219
+ # #1015: a calibration that exists and was refused keeps its own
220
+ # cause (`recalibration-needed`, or its attempt's status) rather than
221
+ # reading as absent.
222
+ return WeekAttribution("cost-share", absent_cause, None)
218
223
  if week_start < regime.effective_from:
219
224
  return WeekAttribution("cost-share", "regime-boundary", None)
220
225
  if regime.effective_until is not None \
@@ -288,6 +293,9 @@ _ATTRIBUTION_CAUSE_COPY: dict = {
288
293
  "unvalidated-coefficient-era":
289
294
  "the week is not inside the coefficient era the calibration's token "
290
295
  "weights are validated for",
296
+ "recalibration-needed":
297
+ "the stored calibration was fitted before a correction to its "
298
+ "inputs; run cctally quota to recalibrate",
291
299
  RESIDUAL_MISALIGNED:
292
300
  "the account, the window or the population does not align",
293
301
  RESIDUAL_OBSERVED_ABSENT:
@@ -301,7 +309,14 @@ _ATTRIBUTION_CAUSE_COPY: dict = {
301
309
  def _cause_copy(cause) -> str:
302
310
  if cause is None:
303
311
  return "no cause stated"
304
- return _ATTRIBUTION_CAUSE_COPY.get(cause, str(cause))
312
+ copy = _ATTRIBUTION_CAUSE_COPY.get(cause)
313
+ if copy is None:
314
+ # #1015: a refused calibration may state its recalibration attempt's
315
+ # status, a member of the quota kernel's cause vocabulary, whose
316
+ # sentence the shared copy table owns.
317
+ copy = _cctally()._load_sibling("_lib_quota_copy")._LONG_FORM.get(
318
+ str(cause))
319
+ return copy if copy is not None else str(cause)
305
320
 
306
321
 
307
322
  def render_attribution_footer(totals, *, basis, cause) -> "list[str]":
@@ -977,11 +992,21 @@ def cmd_project(args: argparse.Namespace) -> int:
977
992
  account_key=acct_key, decorated=_decorated,
978
993
  )
979
994
  attribution_regime = None
995
+ # #1015 spec 5.4: the WHOLE read is kept, so a refused calibration states
996
+ # its cause rather than `calibration-absent`.
997
+ absent_cause = "calibration-absent"
980
998
  if run_basis is None:
981
999
  try:
982
1000
  qcg = c._load_sibling("_cctally_quota_calibration")
983
- attribution_regime = qcg.read_calibration_file(
984
- account_key=acct_key).regime
1001
+ attribution_read = qcg.read_calibration_file(
1002
+ account_key=acct_key, stats_conn=conn)
1003
+ attribution_regime = attribution_read.regime
1004
+ if attribution_read.rejection is \
1005
+ qcg.RegimeRejection.RECALIBRATION_NEEDED:
1006
+ qm = c._load_sibling("_lib_quota_model")
1007
+ stored = attribution_read.regime_status
1008
+ absent_cause = (stored if stored in qm.EVIDENCE_CODES
1009
+ else qm.RECALIBRATION_NEEDED)
985
1010
  except Exception: # noqa: BLE001
986
1011
  attribution_regime = None
987
1012
  # Per-week weighted units, and the records the whole-week support test
@@ -1140,7 +1165,8 @@ def cmd_project(args: argparse.Namespace) -> int:
1140
1165
  week_attribution[ws] = resolve_week_attribution(
1141
1166
  attribution_regime, week_records.get(ws, ()),
1142
1167
  week_start=ws,
1143
- week_end=_end_by_start.get(ws, ws + dt.timedelta(days=7)))
1168
+ week_end=_end_by_start.get(ws, ws + dt.timedelta(days=7)),
1169
+ absent_cause=absent_cause)
1144
1170
  modelled_weeks = sorted(
1145
1171
  ws for ws, attr in week_attribution.items()
1146
1172
  if attr.basis == "modelled")
@@ -1161,7 +1187,7 @@ def cmd_project(args: argparse.Namespace) -> int:
1161
1187
  attribution_basis = "cost-share"
1162
1188
  attribution_cause = (
1163
1189
  week_attribution[fallback_weeks[0]].cause if fallback_weeks
1164
- else "calibration-absent")
1190
+ else absent_cause)
1165
1191
 
1166
1192
  # Collapse (project_key, week) buckets into one row per project, summing
1167
1193
  # tokens / cost / sessions / first_seen / last_seen / models across the