cctally 1.101.0 → 1.103.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.
@@ -20,10 +20,60 @@ from __future__ import annotations
20
20
 
21
21
  import datetime as dt
22
22
  from dataclasses import dataclass
23
+ from enum import Enum
23
24
 
24
25
  from _lib_budget import project_linear
25
26
 
26
27
 
28
+ class ForecastConfidenceCause(str, Enum):
29
+ """The closed set of reasons a forecast is low-confidence.
30
+
31
+ The four values are a wire contract `--json` consumers read, so they are
32
+ the exact strings `_assess_forecast_confidence` has always emitted.
33
+ """
34
+
35
+ ELAPSED_HOURS = "elapsed_hours<24"
36
+ PERCENT = "percent<2"
37
+ SNAPSHOTS = "snapshots<3"
38
+ NO_SAMPLE_GE_24H = "no_sample_ge_24h"
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class ForecastConfidenceAssessment:
43
+ confidence: str # "high" | "low"
44
+ reasons: tuple[str, ...]
45
+
46
+
47
+ def assess_forecast_confidence(
48
+ elapsed_hours: float,
49
+ percent: float,
50
+ snapshot_count: int,
51
+ *,
52
+ has_sample_ge_24h: bool,
53
+ ) -> ForecastConfidenceAssessment:
54
+ """The complete confidence predicate, including the fourth trigger.
55
+
56
+ `no_sample_ge_24h` used to be appended by `_load_forecast_inputs` after
57
+ it called the three-trigger predicate, which meant glue could add reasons
58
+ the predicate did not know about (#620 S2 E3, closes F19). Reason order
59
+ is `elapsed_hours<24`, `percent<2`, `snapshots<3`, `no_sample_ge_24h` —
60
+ the order the old call-plus-append produced.
61
+ """
62
+ reasons: list[str] = []
63
+ if elapsed_hours < 24:
64
+ reasons.append(ForecastConfidenceCause.ELAPSED_HOURS.value)
65
+ if percent < 2:
66
+ reasons.append(ForecastConfidenceCause.PERCENT.value)
67
+ if snapshot_count < 3:
68
+ reasons.append(ForecastConfidenceCause.SNAPSHOTS.value)
69
+ if not has_sample_ge_24h:
70
+ reasons.append(ForecastConfidenceCause.NO_SAMPLE_GE_24H.value)
71
+ return ForecastConfidenceAssessment(
72
+ confidence="low" if reasons else "high",
73
+ reasons=tuple(reasons),
74
+ )
75
+
76
+
27
77
  @dataclass
28
78
  class ForecastInputs:
29
79
  now_utc: dt.datetime
package/bin/_lib_jsonl.py CHANGED
@@ -381,6 +381,19 @@ class _CodexIterState:
381
381
  # watermark by construction, and the caller persists exactly it (replacing
382
382
  # the old reconstructed initial+Σ(per-turn) sum, which could diverge).
383
383
  total_tokens: int = 0
384
+ # #647: provider time of the last accepted accounting event. The caller
385
+ # seeds this from the retained row immediately before a delta cursor, and
386
+ # the iterator advances it on every accepted accounting record. A lower
387
+ # cumulative can start a new producer generation only when its timestamp
388
+ # advances this independent chronological watermark; copied or
389
+ # out-of-order history at a new byte offset therefore cannot lower the
390
+ # cumulative watermark and make the copied suffix count twice.
391
+ last_accounting_timestamp: dt.datetime | None = None
392
+ # A provider lifecycle record (turn_context/task_started) observed since
393
+ # the last accepted accounting row. Token-count re-emissions cannot set
394
+ # this bit themselves, so it is the producer-transition evidence required
395
+ # before a restart-shaped lower cumulative may replace the watermark.
396
+ generation_transition_pending: bool = False
384
397
  # #279 S2 F1 parse-health counters — per-iterator-call; sync_codex_cache
385
398
  # folds them into CodexIngestStats after each file drains. Reason
386
399
  # vocabulary: info-non-dict / no-last-token-usage / bad-timestamp /
@@ -869,6 +882,57 @@ def _reject_nonfinite_json_constant(value: str) -> None:
869
882
  raise ValueError(f"non-finite JSON constant: {value}")
870
883
 
871
884
 
885
+ def _codex_generation_transition_between(
886
+ path_str: str, after_offset: int, before_offset: int,
887
+ ) -> bool:
888
+ """Return whether a producer lifecycle boundary exists in this byte gap.
889
+
890
+ ``after_offset`` is the physical row of the last retained accounting
891
+ event, so that row is skipped. ``before_offset`` is a durable resume cursor
892
+ and is never consumed. This reconstructs the one bit of parser state a
893
+ metadata-only or budgeted pass can leave between the last accounting row
894
+ and the next token event without adding another cache schema column.
895
+ Malformed or unreadable evidence fails closed.
896
+ """
897
+ if after_offset < 0 or before_offset <= after_offset:
898
+ return False
899
+ try:
900
+ with open(path_str, "rb") as fh:
901
+ fh.seek(after_offset)
902
+ fh.readline() # skip the retained accounting record itself
903
+ while fh.tell() < before_offset:
904
+ line_offset = fh.tell()
905
+ line = fh.readline()
906
+ if not line or not line.endswith(b"\n"):
907
+ return False
908
+ if fh.tell() > before_offset:
909
+ return False
910
+ try:
911
+ obj = json.loads(
912
+ line.decode("utf-8"),
913
+ parse_constant=_reject_nonfinite_json_constant,
914
+ )
915
+ except (UnicodeDecodeError, json.JSONDecodeError, ValueError, TypeError):
916
+ continue
917
+ if not isinstance(obj, dict) or not _json_value_is_finite(obj):
918
+ continue
919
+ payload = (
920
+ obj.get("payload")
921
+ if isinstance(obj.get("payload"), dict)
922
+ else {}
923
+ )
924
+ if obj.get("type") == "turn_context" or (
925
+ obj.get("type") == "event_msg"
926
+ and payload.get("type") == "task_started"
927
+ ):
928
+ return True
929
+ if fh.tell() <= line_offset: # defensive progress invariant
930
+ return False
931
+ except OSError:
932
+ return False
933
+ return False
934
+
935
+
872
936
  def _seed_codex_iter_state(
873
937
  state: _CodexIterState, initial_session_id: str | None,
874
938
  initial_model: str | None, initial_total_tokens: int,
@@ -934,6 +998,11 @@ def _accounting_from_record(
934
998
  and state.thread.parent_thread_id is not None):
935
999
  return None, last_total_tokens, filename_session_id_warned
936
1000
 
1001
+ timestamp = _parse_codex_timestamp(obj.get("timestamp"))
1002
+ if timestamp is None:
1003
+ _codex_skip(state, "bad-timestamp")
1004
+ return None, last_total_tokens, filename_session_id_warned
1005
+
937
1006
  total_token_usage = info.get("total_token_usage")
938
1007
  if isinstance(total_token_usage, dict):
939
1008
  try:
@@ -941,14 +1010,33 @@ def _accounting_from_record(
941
1010
  except (TypeError, ValueError):
942
1011
  cumulative = 0
943
1012
  if cumulative <= last_total_tokens:
944
- return None, last_total_tokens, filename_session_id_warned
1013
+ # A continued Codex producer can append to the same rollout while
1014
+ # restarting its cumulative counter at zero. The first record of
1015
+ # that new generation is self-originating: its cumulative total is
1016
+ # exactly the complete provider-native last-turn total. A distinct
1017
+ # producer lifecycle record must have occurred since the last
1018
+ # accepted accounting row, and this event must also advance the
1019
+ # retained maximum timestamp. Token-count re-emissions cannot
1020
+ # manufacture the lifecycle evidence, even when they carry fresh
1021
+ # timestamps. Equal totals remain duplicates, and arbitrary or
1022
+ # non-monotonic lower totals remain noise.
1023
+ try:
1024
+ last_usage_total = int(last_token_usage.get("total_tokens") or 0)
1025
+ except (TypeError, ValueError):
1026
+ last_usage_total = 0
1027
+ starts_generation = (
1028
+ state.generation_transition_pending
1029
+ and cumulative < last_total_tokens
1030
+ and cumulative > 0
1031
+ and cumulative == last_usage_total
1032
+ and state.last_accounting_timestamp is not None
1033
+ and timestamp > state.last_accounting_timestamp
1034
+ )
1035
+ if not starts_generation:
1036
+ return None, last_total_tokens, filename_session_id_warned
945
1037
  else:
946
1038
  cumulative = None
947
1039
 
948
- timestamp = _parse_codex_timestamp(obj.get("timestamp"))
949
- if timestamp is None:
950
- _codex_skip(state, "bad-timestamp")
951
- return None, last_total_tokens, filename_session_id_warned
952
1040
  session_id = state.session_id
953
1041
  if session_id is None:
954
1042
  session_id = filename_uuid
@@ -982,6 +1070,12 @@ def _accounting_from_record(
982
1070
  if cumulative is not None:
983
1071
  state.total_tokens = cumulative
984
1072
  last_total_tokens = cumulative
1073
+ if (
1074
+ state.last_accounting_timestamp is None
1075
+ or timestamp > state.last_accounting_timestamp
1076
+ ):
1077
+ state.last_accounting_timestamp = timestamp
1078
+ state.generation_transition_pending = False
985
1079
  return entry, last_total_tokens, filename_session_id_warned
986
1080
 
987
1081
 
@@ -1076,6 +1170,9 @@ def _iter_codex_fused_records_with_offsets(
1076
1170
  model = _codex_string(payload.get("model"))
1077
1171
  if model is not None:
1078
1172
  state.model = model.strip()
1173
+ state.generation_transition_pending = True
1174
+ elif obj.get("type") == "event_msg" and payload.get("type") == "task_started":
1175
+ state.generation_transition_pending = True
1079
1176
 
1080
1177
  event = _event_from_record(
1081
1178
  obj, path_str, line_offset, source_root_key, state.thread
package/bin/_lib_perf.py CHANGED
@@ -244,6 +244,18 @@ def current_root():
244
244
  return getattr(_tls, "root", None)
245
245
 
246
246
 
247
+ def in_phase() -> bool:
248
+ """Whether a phase is currently OPEN on this thread.
249
+
250
+ `current_root()` answers a different question — it names the last root
251
+ that CLOSED — so a caller deciding whether to open a root of its own
252
+ cannot use it. A pure fold that opens child phases needs this one: with no
253
+ root open its children would be emitted into whatever phase happens to be
254
+ on the stack, or into none at all.
255
+ """
256
+ return bool(_stack())
257
+
258
+
247
259
  def reset_thread():
248
260
  """Start a fresh root scope on this thread, capturing the armed state.
249
261
 
@@ -53,7 +53,7 @@ def _chip_for_model(name: str) -> str:
53
53
  # Date the embedded pricing snapshots below were last verified against
54
54
  # vendor sources. Bump whenever CLAUDE_MODEL_PRICING / CODEX_MODEL_PRICING
55
55
  # is synced. Read by `pricing-check` + the release pre-flight staleness nudge.
56
- PRICING_SNAPSHOT_DATE = "2026-08-13"
56
+ PRICING_SNAPSHOT_DATE = "2026-08-25"
57
57
  PRICING_STALENESS_DAYS = 60 # release pre-flight WARNs past this age
58
58
 
59
59
  # Canonical machine-readable pricing source (Claude values + Codex values).
@@ -73,6 +73,22 @@ LITELLM_PRICES_URL = (
73
73
  # currently mirrors successor Mythos 5's lower $10/$50 rate onto the Preview
74
74
  # identifier. Retained Preview rows therefore keep the explicit historical
75
75
  # rate rather than being rewritten to the successor's rate.
76
+ #
77
+ # gpt-5.6-sol (#643): OpenAI's pricing page states that "GPT-5.6 Sol's
78
+ # promotional pricing is available at least through November 21, 2026" and
79
+ # publishes no post-promotional price, so LiteLLM's $4/$20 per MTok rate is
80
+ # time-boxed. This table is date-blind and roughly half the retained Sol rows
81
+ # predate the promotion, so the pre-promotional $5/$30 card is kept and the
82
+ # promotion is suppressed here. `expires` is what stops the divergence
83
+ # ossifying: `stale_allowlist_entries` only fires if LiteLLM reverts, so a
84
+ # promotion made permanent would otherwise never surface.
85
+ #
86
+ # gpt-5.6 (#643): a model-only entry, which suppresses `missing_from_us` rather
87
+ # than a value drift. OpenAI lists `gpt-5.6` as an alias of `gpt-5.6-sol`, so
88
+ # CODEX_MODEL_ALIASES resolves it instead of duplicating the rate card.
89
+ # `diff_pricing` keys on raw table membership and is deliberately NOT
90
+ # alias-aware, so the omission needs this entry. It is self-policing: it goes
91
+ # stale automatically if upstream drops `gpt-5.6` or we restore a direct card.
76
92
  PRICING_DRIFT_ALLOWLIST: list[dict] = [
77
93
  {
78
94
  "model": "claude-mythos-preview",
@@ -90,6 +106,39 @@ PRICING_DRIFT_ALLOWLIST: list[dict] = [
90
106
  "cache_creation_input_token_cost",
91
107
  "cache_read_input_token_cost",
92
108
  )
109
+ ] + [
110
+ {
111
+ "model": "gpt-5.6-sol",
112
+ "field": field,
113
+ "expires": "2026-11-21",
114
+ "reason": (
115
+ "OpenAI's pricing page guarantees GPT-5.6 Sol's promotional "
116
+ "$4/$20 per MTok rate only 'at least through November 21, 2026' "
117
+ "and publishes no post-promotional price. This table is "
118
+ "date-blind, so the pre-promotional $5/$30 card is kept rather "
119
+ "than adopting a rate that would have to be reverted by hand "
120
+ "when the promotion ends (#643)."
121
+ ),
122
+ }
123
+ for field in (
124
+ "input_cost_per_token",
125
+ "cache_read_input_token_cost",
126
+ "output_cost_per_token",
127
+ "input_cost_per_token_above_272k_tokens",
128
+ "cache_read_input_token_cost_above_272k_tokens",
129
+ "output_cost_per_token_above_272k_tokens",
130
+ )
131
+ ] + [
132
+ {
133
+ "model": "gpt-5.6",
134
+ "reason": (
135
+ "OpenAI lists gpt-5.6 as an alias of gpt-5.6-sol, so "
136
+ "CODEX_MODEL_ALIASES resolves it to Sol's card and this table "
137
+ "carries no duplicate entry. `diff_pricing` is deliberately not "
138
+ "alias-aware, so the intentional omission is suppressed here "
139
+ "(#643)."
140
+ ),
141
+ },
93
142
  ]
94
143
 
95
144
  # Anthropic API pricing snapshot:
@@ -398,10 +447,11 @@ _unknown_model_warnings: set[str] = set()
398
447
  # Codex (OpenAI) API pricing snapshot:
399
448
  # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
400
449
  # - Captured: 2026-07-19 — the last FULL Codex sync. PRICING_SNAPSHOT_DATE has
401
- # since moved for three targeted syncs (2026-07-24, the Claude-side opus-5
402
- # sync; 2026-07-31, the gpt-5.6-terra/-luna correction logged below; and
403
- # 2026-08-13, the Claude-side Sonnet/Mythos sync above). Codex values outside
404
- # the one Codex correction were NOT re-verified on those days.
450
+ # since moved for four targeted syncs (2026-07-24, the Claude-side opus-5
451
+ # sync; 2026-07-31, the gpt-5.6-terra/-luna correction logged below;
452
+ # 2026-08-13, the Claude-side Sonnet/Mythos sync above; and 2026-08-25, the
453
+ # gpt-5.6-cyber addition logged below). Codex values outside those two Codex
454
+ # corrections were NOT re-verified on those days.
405
455
  # - As of the 2026-07-19 sync this carries every openai-provider
406
456
  # gpt-5* model the LiteLLM snapshot lists, so `pricing-check`'s scope finds
407
457
  # nothing missing. Models absent from this table still fall back to `gpt-5`
@@ -425,6 +475,21 @@ _unknown_model_warnings: set[str] = set()
425
475
  # the vendor lists these as standard ongoing prices with no promotional or
426
476
  # expiring annotation, so the durable rate is the cut rate. gpt-5.6 and
427
477
  # gpt-5.6-sol were not repriced and are unchanged.
478
+ # 2026-08-25 (#643): added gpt-5.6-cyber at OpenAI's published $12.50 input /
479
+ # $1.25 cached input / $75.00 output per MTok, with LiteLLM's above-272k tier
480
+ # ($25.00 / $2.50 / $112.50 per MTok). The vendor page shows dashes in the
481
+ # long-context columns, but max_input_tokens is 400,000, so a turn above the
482
+ # 272,000 threshold is reachable and pricing it at the base rate would be
483
+ # knowingly wrong; LiteLLM's tier ratios match every other gpt-5.6 member.
484
+ # Removed the duplicated gpt-5.6 card and aliased that identifier to
485
+ # gpt-5.6-sol, which OpenAI lists it as an alias of. gpt-5.6-sol's own values
486
+ # are UNCHANGED: LiteLLM now carries OpenAI's promotional $4/$20 per MTok
487
+ # rate, which the vendor guarantees only "at least through November 21, 2026"
488
+ # and publishes no successor for. That promotion is suppressed in
489
+ # PRICING_DRIFT_ALLOWLIST with expires 2026-11-21 instead of being written
490
+ # into this date-blind table, because roughly half the retained Sol rows
491
+ # predate it. The accepted cost is that while the promotion runs, Sol
492
+ # reporting is high by 25% on input and 50% on output.
428
493
  #
429
494
  # Billing rules:
430
495
  # - reasoning_output_tokens is billed at the *output* rate (matches
@@ -518,19 +583,15 @@ CODEX_MODEL_PRICING: dict[str, dict[str, Any]] = {
518
583
  "output_cost_per_token_above_272k_tokens": 4.5e-05,
519
584
  },
520
585
  # ── gpt-5.6 family (LiteLLM openai-provider entries) ──
521
- # Exact model_prices_and_context_window.json values; each carries the
522
- # above-272k tier (max_input_tokens 1050000). gpt-5.6 and gpt-5.6-sol keep
523
- # gpt-5.5's rate card from the 2026-07-10 sync; -terra and -luna carry
524
- # OpenAI's 2026-07-30 post-cut rates (#441) and no longer track gpt-5.4's
525
- # card or any other model's.
526
- "gpt-5.6": {
527
- "input_cost_per_token": 5e-06,
528
- "cache_read_input_token_cost": 5e-07,
529
- "output_cost_per_token": 3e-05,
530
- "input_cost_per_token_above_272k_tokens": 1e-05,
531
- "cache_read_input_token_cost_above_272k_tokens": 1e-06,
532
- "output_cost_per_token_above_272k_tokens": 4.5e-05,
533
- },
586
+ # Every member carries the above-272k tier, but the context windows differ:
587
+ # -sol, -terra and -luna are max_input_tokens 922,000 and -cyber is 400,000.
588
+ # gpt-5.6-sol keeps gpt-5.5's rate card from the 2026-07-10 sync and is
589
+ # deliberately HELD there while OpenAI's promotion runs — see the
590
+ # gpt-5.6-sol block in PRICING_DRIFT_ALLOWLIST (#643). -terra and -luna
591
+ # carry OpenAI's 2026-07-30 post-cut rates (#441) and no longer track
592
+ # gpt-5.4's card or any other model's. -cyber carries its own launch rates.
593
+ # The bare `gpt-5.6` identifier is OpenAI's alias of -sol and has NO card
594
+ # here; CODEX_MODEL_ALIASES resolves it.
534
595
  "gpt-5.6-sol": {
535
596
  "input_cost_per_token": 5e-06,
536
597
  "cache_read_input_token_cost": 5e-07,
@@ -555,6 +616,16 @@ CODEX_MODEL_PRICING: dict[str, dict[str, Any]] = {
555
616
  "cache_read_input_token_cost_above_272k_tokens": 4e-08,
556
617
  "output_cost_per_token_above_272k_tokens": 1.8e-06,
557
618
  },
619
+ # No cache_creation field: the Codex cost kernel never reads one, so
620
+ # carrying LiteLLM's would only give `diff_pricing` a value to compare.
621
+ "gpt-5.6-cyber": {
622
+ "input_cost_per_token": 1.25e-05,
623
+ "cache_read_input_token_cost": 1.25e-06,
624
+ "output_cost_per_token": 7.5e-05,
625
+ "input_cost_per_token_above_272k_tokens": 2.5e-05,
626
+ "cache_read_input_token_cost_above_272k_tokens": 2.5e-06,
627
+ "output_cost_per_token_above_272k_tokens": 1.125e-04,
628
+ },
558
629
  # ── Issue #123: full gpt-5.x LiteLLM sync (2026-05-30 snapshot) ──
559
630
  # Exact model_prices_and_context_window.json values for every
560
631
  # openai-provider gpt-5* model `pricing-check`'s scope flags but the
@@ -740,11 +811,16 @@ CODEX_LEGACY_FALLBACK_MODEL = "gpt-5"
740
811
  # drift retains one source of truth per card. OpenAI's live pricing page states
741
812
  # that ``daybreak-blue-latest`` currently points to ``gpt-5.6-sol`` and inherits
742
813
  # the underlying model's pricing; Codex emits the prefixed runtime identifier
743
- # retained below. ``codex-auto-review`` is the hidden Guardian model and maps to
744
- # the model current when it appeared, covering every retained event observed
745
- # for issue #535.
814
+ # retained below. OpenAI's models page lists the bare ``gpt-5.6`` identifier as
815
+ # an alias of ``gpt-5.6-sol`` too, so it resolves here rather than duplicating
816
+ # Sol's rates (#643) — its intentional absence from CODEX_MODEL_PRICING is
817
+ # covered by a model-only PRICING_DRIFT_ALLOWLIST entry.
818
+ # ``codex-auto-review`` is the hidden Guardian model and maps to the model
819
+ # current when it appeared, covering every retained event observed for issue
820
+ # #535.
746
821
  CODEX_MODEL_ALIASES: dict[str, str] = {
747
822
  "codex-auto-review": "gpt-5.5",
823
+ "gpt-5.6": "gpt-5.6-sol",
748
824
  "gpt-daybreak-blue-latest": "gpt-5.6-sol",
749
825
  }
750
826
 
@@ -8,7 +8,9 @@ implementation:
8
8
  1. ``extract_highlights`` — pull up to N lint-clean highlight bullets from a
9
9
  specific ``## [X.Y.Z] - YYYY-MM-DD`` CHANGELOG section (exact version match,
10
10
  Added > Changed > Fixed priority, multiline flattening, terminal issue-ref
11
- stripping, fenced-code skipping).
11
+ stripping, fenced-code skipping). ``render_latest_stable_block`` keeps that
12
+ compact target-section sample honest by naming and linking the complete
13
+ previous-stable-to-target upgrade span.
12
14
  2. ``normalize_highlight`` — deterministically rewrite a bullet so it satisfies
13
15
  the copy lint by construction (em/en dashes with surrounding spaces become
14
16
  ``, ``; doubled separators collapse; leading/trailing separators trim).
@@ -297,14 +299,33 @@ def extract_highlights(
297
299
 
298
300
 
299
301
  def render_latest_stable_block(
300
- version: str, date: str, bullets: "list[str]"
302
+ version: str,
303
+ date: str,
304
+ bullets: "list[str]",
305
+ *,
306
+ previous_stable: "str | None" = None,
307
+ release_url: "str | None" = None,
301
308
  ) -> str:
302
309
  """Render the auto-maintained latest-stable block (no trailing newline
303
- after the last bullet; version+date only when *bullets* is empty)."""
310
+ after the last line; initial baselines retain the single-release shape)."""
304
311
  base = f"**Latest stable: v{version}** ({date})\n"
312
+ if previous_stable is None:
313
+ if bullets:
314
+ return base + "\n" + "\n".join(f"- {b}" for b in bullets)
315
+ return base
316
+ if release_url is None:
317
+ raise ValueError("stable-span README block requires a release URL")
318
+ blocks = [
319
+ base.rstrip("\n"),
320
+ f"Highlights from the `v{previous_stable}` to `v{version}` "
321
+ "stable upgrade:",
322
+ ]
305
323
  if bullets:
306
- return base + "\n" + "\n".join(f"- {b}" for b in bullets)
307
- return base
324
+ blocks.append("\n".join(f"- {b}" for b in bullets))
325
+ blocks.append(
326
+ f"[See every change in this stable upgrade]({release_url})"
327
+ )
328
+ return "\n\n".join(blocks)
308
329
 
309
330
 
310
331
  # --------------------------------------------------------------------------
package/bin/cctally CHANGED
@@ -93,8 +93,10 @@ def _load_sibling(name: str):
93
93
  `_lib_transcript_access.transcripts_allowed`), then self-heal once the body
94
94
  finished. `_SIBLING_LOCK` serializes the load so a concurrent caller blocks
95
95
  until the body completes; `_LOADED_SIBLINGS` gates a lock-free fast path for
96
- already-loaded siblings. Fail-closed by construction — a race waits, it never
97
- returns a partial module early.
96
+ already-loaded siblings and retains the completed object owned by this
97
+ cctally module generation. Fail-closed by construction — a race waits, it
98
+ never returns a partial module early or adopts one registered by a newer
99
+ test-loader generation.
98
100
 
99
101
  For `_cctally_*.py` siblings that back-reference `cctally`, the sibling
100
102
  module exposes a `_cctally()` accessor that reads `sys.modules['cctally']`
@@ -115,19 +117,23 @@ def _load_sibling(name: str):
115
117
  # _load_sibling closure — regardless of pytest re-imports.
116
118
  sys.modules["cctally"] = _THIS_MODULE
117
119
  # Fast path: a sibling whose body has FULLY executed is returned without
118
- # contending on the load lock. `_LOADED_SIBLINGS` is only ever added to,
119
- # after a successful exec_module (below), so its membership is a stable
120
- # "complete" signal — keeping the hot path lock-free for the ~50 sequential
121
- # sibling loads at CLI startup and every warm request-thread lazy-load.
122
- if name in _LOADED_SIBLINGS:
123
- return sys.modules[name]
120
+ # contending on the load lock. The mapping is populated only after a
121
+ # successful exec_module (below), so its value is both a stable "complete"
122
+ # signal and the exact module object this cctally generation completed.
123
+ # Tests deliberately replace sys.modules entries between load_script()
124
+ # generations while older request threads may still run; consulting the
125
+ # process-global entry here would let an old loader adopt a newer partial.
126
+ loaded = _LOADED_SIBLINGS.get(name)
127
+ if loaded is not None:
128
+ return loaded
124
129
  # Slow path — serialize the actual load (#306). Any concurrent caller blocks
125
130
  # here until the owning thread finishes exec_module and records the name
126
131
  # complete, so it can never observe the half-initialized module.
127
132
  with _SIBLING_LOCK:
128
133
  # Completed while we waited for the lock.
129
- if name in _LOADED_SIBLINGS:
130
- return sys.modules[name]
134
+ loaded = _LOADED_SIBLINGS.get(name)
135
+ if loaded is not None:
136
+ return loaded
131
137
  cached = sys.modules.get(name)
132
138
  if cached is not None:
133
139
  # Registered but not yet recorded complete. Under the lock this is
@@ -159,7 +165,7 @@ def _load_sibling(name: str):
159
165
  # broken module is never recorded complete (mirrors importlib).
160
166
  sys.modules.pop(name, None)
161
167
  raise
162
- _LOADED_SIBLINGS.add(name)
168
+ _LOADED_SIBLINGS[name] = mod
163
169
  return mod
164
170
 
165
171
 
@@ -185,12 +191,12 @@ _THIS_MODULE = sys.modules.get(__name__) or sys.modules.get("cctally")
185
191
  # conversation-path siblings are lazy-loaded on those threads. `_SIBLING_LOCK`
186
192
  # serializes the actual load so a concurrent caller can never observe a module
187
193
  # that is registered in sys.modules but whose exec_module is still mid-body (the
188
- # pre-registration window below), and `_LOADED_SIBLINGS` records the names whose
189
- # bodies have fully executed, gating a lock-free fast path. RLock (not Lock) so a
190
- # circular import that re-enters _load_sibling on the SAME thread during
191
- # exec_module cannot self-deadlock.
194
+ # pre-registration window below), and `_LOADED_SIBLINGS` records the completed
195
+ # module objects, gating a lock-free and generation-local fast path. RLock (not
196
+ # Lock) lets a circular import re-enter _load_sibling on the SAME thread during
197
+ # exec_module without self-deadlocking.
192
198
  _SIBLING_LOCK = threading.RLock()
193
- _LOADED_SIBLINGS: set[str] = set()
199
+ _LOADED_SIBLINGS: dict[str, object] = {}
194
200
 
195
201
 
196
202
  # Hook-tick non-path constants (Section 1 of onboarding spec).
@@ -204,6 +210,7 @@ SETUP_SYMLINK_NAMES = (
204
210
  "cctally-budget",
205
211
  "cctally-dashboard",
206
212
  "cctally-dollar-per-percent",
213
+ "cctally-explain",
207
214
  "cctally-five-hour-blocks",
208
215
  "cctally-five-hour-breakdown",
209
216
  "cctally-forecast",
@@ -404,6 +411,40 @@ project_linear = _lib_budget.project_linear
404
411
  calendar_month_window = _lib_budget.calendar_month_window
405
412
  calendar_week_window = _lib_budget.calendar_week_window
406
413
 
414
+ # Diagnosis kernel (#620 S2): the pure classification layer behind
415
+ # `cctally explain` and `GET /api/diagnosis`. Re-exported like the other
416
+ # _lib_* kernels; the store adapter and the renderer are separate siblings.
417
+ _lib_diagnosis = _load_sibling("_lib_diagnosis")
418
+ DIAGNOSIS_CONTRACT_VERSION = _lib_diagnosis.DIAGNOSIS_CONTRACT_VERSION
419
+ DIAGNOSIS_CONTRIBUTOR_SHARE_FLOOR = _lib_diagnosis.DIAGNOSIS_CONTRIBUTOR_SHARE_FLOOR
420
+ DIAGNOSIS_SHARE_FLOOR_EPSILON = _lib_diagnosis.DIAGNOSIS_SHARE_FLOOR_EPSILON
421
+ DIAGNOSIS_TIE_EPSILON_USD = _lib_diagnosis.DIAGNOSIS_TIE_EPSILON_USD
422
+ CONTRIBUTOR_REGISTRY = _lib_diagnosis.CONTRIBUTOR_REGISTRY
423
+ ContributorSpec = _lib_diagnosis.ContributorSpec
424
+ ContributorRow = _lib_diagnosis.ContributorRow
425
+ ClassResult = _lib_diagnosis.ClassResult
426
+ DiagnosisReport = _lib_diagnosis.DiagnosisReport
427
+ DiagnosisWindow = _lib_diagnosis.DiagnosisWindow
428
+ Denominator = _lib_diagnosis.Denominator
429
+ EvidenceField = _lib_diagnosis.EvidenceField
430
+ PopulationCoverage = _lib_diagnosis.PopulationCoverage
431
+ SubjectFacts = _lib_diagnosis.SubjectFacts
432
+ ProviderResult = _lib_diagnosis.ProviderResult
433
+ EstablishmentError = _lib_diagnosis.EstablishmentError
434
+ EstablishmentFailure = _lib_diagnosis.EstablishmentFailure
435
+ WithheldCause = _lib_diagnosis.WithheldCause
436
+ BaselineOutcome = _lib_diagnosis.BaselineOutcome
437
+ VerdictState = _lib_diagnosis.VerdictState
438
+ OverallVerdict = _lib_diagnosis.OverallVerdict
439
+ assess_confidence = _lib_diagnosis.assess_confidence
440
+ support_shortfall = _lib_diagnosis.support_shortfall
441
+ classify_class = _lib_diagnosis.classify_class
442
+ rank_rows = _lib_diagnosis.rank_rows
443
+ overall_verdict = _lib_diagnosis.overall_verdict
444
+ build_provider_result = _lib_diagnosis.build_provider_result
445
+ build_report = _lib_diagnosis.build_report
446
+ unreadable_store_is_terminal = _lib_diagnosis.unreadable_store_is_terminal
447
+
407
448
  # CLAUDE_MODEL_CONTEXT_WINDOWS / …_DEFAULT_FAMILY moved to _cctally_statusline.py (re-exported below).
408
449
 
409
450
  _lib_display_tz = _load_sibling("_lib_display_tz")
@@ -1119,6 +1160,12 @@ maybe_record_codex_budget_milestone = _cctally_record.maybe_record_codex_budget_
1119
1160
  maybe_record_projected_alert = _cctally_record.maybe_record_projected_alert
1120
1161
  _weekly_pct_week_avg_projection = _cctally_record._weekly_pct_week_avg_projection
1121
1162
  _compute_block_totals = _cctally_record._compute_block_totals
1163
+ # #620 S2 E2: the pure fold lifted out of _compute_block_totals, plus the
1164
+ # canonical priced record and bucket shapes it folds over.
1165
+ PricedEntry = _cctally_record.PricedEntry
1166
+ BlockBucket = _cctally_record.BlockBucket
1167
+ BlockTotals = _cctally_record.BlockTotals
1168
+ fold_block_totals = _cctally_record.fold_block_totals
1122
1169
  maybe_update_five_hour_block = _cctally_record.maybe_update_five_hour_block
1123
1170
  cmd_record_usage = _cctally_record.cmd_record_usage
1124
1171
  CreditPlan = _cctally_record.CreditPlan
@@ -2999,6 +3046,28 @@ cmd_diff = _cctally_diff.cmd_diff # parser: c.c
2999
3046
  _emit_diff_debug_samples = _cctally_diff._emit_diff_debug_samples # test_debug_sample_emission mod._emit_diff_debug_samples
3000
3047
 
3001
3048
 
3049
+ # Eager re-export of bin/_cctally_diagnosis.py — the `explain` handler, the
3050
+ # ONE wire adapter both surfaces serialize through, and the canonical
3051
+ # projection their equivalence is defined over (#620 S2). MUST load after the
3052
+ # _lib_diff_kernel block above, because `explain` resolves its window through
3053
+ # the same `_parse_diff_window` grammar. The store adapter it calls stays
3054
+ # lazily loaded, so an ordinary `cctally` invocation never opens a database
3055
+ # it does not need.
3056
+ #
3057
+ # Measured 2026-08-19: loading this sibling costs 20.5 ms of the median
3058
+ # `cctally --version`, which is compiling this module plus `_lib_diagnosis`.
3059
+ # It stays EAGER anyway, for the reason recorded at the `_lib_diff_kernel`
3060
+ # block below: the test surface reaches these symbols by dict-key access on
3061
+ # `mod.__dict__`, which no lazy binding can serve, and spec §4.8 makes the
3062
+ # eager pattern mandatory rather than preferred. Recovering the 20 ms belongs
3063
+ # to a change that shortens `cctally`'s import path as a whole.
3064
+ _cctally_diagnosis = _load_sibling("_cctally_diagnosis")
3065
+ cmd_explain = _cctally_diagnosis.cmd_explain # parser: c.cmd_explain
3066
+ diagnosis_to_wire = _cctally_diagnosis.diagnosis_to_wire
3067
+ canonical_projection = _cctally_diagnosis.canonical_projection
3068
+ render_diagnosis_terminal = _cctally_diagnosis.render_terminal
3069
+
3070
+
3002
3071
  # Provider-aware analytics deliberately wrap the established command entries
3003
3072
  # here, leaving their Claude implementation modules untouched below the branch.
3004
3073
  _cmd_project_claude = cmd_project
@@ -3577,6 +3646,14 @@ def _post_command_update_hooks(command: str | None, args) -> None:
3577
3646
  return
3578
3647
  if command == "doctor":
3579
3648
  return
3649
+ if command == "explain":
3650
+ # Read-only diagnostic by contract (#620 S3, spec 5.1): every store it
3651
+ # touches is opened `mode=ro`, and it must reach no update check, no
3652
+ # telemetry beat and no configuration write. Without this early return
3653
+ # `_spawn_background_update_check` writes `update-state.json` and
3654
+ # `update.log` into a data directory the command only read from. Same
3655
+ # rationale class as `doctor` and `pricing-check` below.
3656
+ return
3580
3657
  if command == "pricing-check":
3581
3658
  # Read-only diagnostic (same rationale as doctor): load_config() would
3582
3659
  # call ensure_dirs() and write a stub config.json on a fresh HOME, and
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env bash
2
+ # Thin wrapper: `cctally-explain` → `cctally explain`.
3
+ # Mirrors `cctally-forecast` / `cctally-project` pattern.
4
+ set -euo pipefail
5
+ exec "$(dirname "$0")/cctally" explain "$@"