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
@@ -34,6 +34,7 @@ import sys
34
34
  from dataclasses import dataclass
35
35
 
36
36
  import _lib_account_protocol
37
+ import _lib_claude_attribution
37
38
 
38
39
  LINE_VERSION = 1
39
40
 
@@ -429,12 +430,20 @@ _WPG = _lib_account_protocol.WRITER_GENERATION_KEY
429
430
  #: metadata exactly like ``wpg``.
430
431
  _WRITER_REVISION = _lib_account_protocol.PROTOCOL_REVISION
431
432
  _WPR = _lib_account_protocol.REVISION_KEY
433
+ #: #1019/#1014 (spec 4.7 C1): the successor revision stamp, transport
434
+ #: metadata exactly like ``wpg`` and ``wpr`` and part of the same content-id
435
+ #: core, so 1.116.1 re-derives a current record's id unchanged.
436
+ _WRITER_SUCCESSOR = _lib_account_protocol.SUCCESSOR_REVISION
437
+ _WPX = _lib_account_protocol.SUCCESSOR_REVISION_KEY
432
438
  #: ``writer_revision`` default: the current revision when the record carries
433
439
  #: the current writer generation, none for a previous release's shape.
440
+ #: ``writer_successor`` default: the successor revision when the record
441
+ #: carries a protocol revision, none otherwise.
434
442
  _REVISION_DEFAULT = object()
435
443
 
436
444
 
437
- def _writer_core(core: dict, writer_generation, writer_revision) -> None:
445
+ def _writer_core(core: dict, writer_generation, writer_revision,
446
+ writer_successor=_REVISION_DEFAULT) -> None:
438
447
  if writer_generation is not None:
439
448
  core[_WPG] = writer_generation
440
449
  if writer_revision is _REVISION_DEFAULT:
@@ -442,12 +451,18 @@ def _writer_core(core: dict, writer_generation, writer_revision) -> None:
442
451
  else _WRITER_REVISION)
443
452
  if writer_revision is not None:
444
453
  core[_WPR] = writer_revision
454
+ if writer_successor is _REVISION_DEFAULT:
455
+ writer_successor = (None if writer_revision is None
456
+ else _WRITER_SUCCESSOR)
457
+ if writer_successor is not None:
458
+ core[_WPX] = writer_successor
445
459
 
446
460
 
447
461
  def make_obs(at: str, src: str, provider: str, payload: dict,
448
462
  account: str | None = None, *,
449
463
  writer_generation: str | None = _WRITER_GENERATION,
450
- writer_revision=_REVISION_DEFAULT) -> dict:
464
+ writer_revision=_REVISION_DEFAULT,
465
+ writer_successor=_REVISION_DEFAULT) -> dict:
451
466
  """Build a complete ``obs`` line record (raw capture; canonicalization is
452
467
  derivation-time, never baked into the stored line — spec §4.2).
453
468
 
@@ -467,28 +482,36 @@ def make_obs(at: str, src: str, provider: str, payload: dict,
467
482
  protocol revision, also part of the content-id core. It defaults to the
468
483
  current revision for a current-generation record and to none for a
469
484
  previous release's shape; ``None`` with the current generation builds
470
- the revision-1 (#825) shape."""
485
+ the revision-1 (#825) shape.
486
+
487
+ ``writer_successor`` (#1019/#1014 spec 4.7 C1) is the top-level ``wpx``
488
+ successor revision, also part of the content-id core. It defaults to the
489
+ successor revision for a record carrying a protocol revision; ``None``
490
+ with the current revision builds the revision-2 (1.116.x) shape."""
471
491
  core = {"t": "obs", "at": at, "src": src, "provider": provider, "payload": payload}
472
492
  if account is not None:
473
493
  core["account"] = account
474
- _writer_core(core, writer_generation, writer_revision)
494
+ _writer_core(core, writer_generation, writer_revision, writer_successor)
475
495
  return {"v": LINE_VERSION, **core, "id": content_id(core)}
476
496
 
477
497
 
478
498
  def make_op(at: str, src: str, payload: dict, *,
479
499
  writer_generation: str | None = _WRITER_GENERATION,
480
- writer_revision=_REVISION_DEFAULT) -> dict:
500
+ writer_revision=_REVISION_DEFAULT,
501
+ writer_successor=_REVISION_DEFAULT) -> dict:
481
502
  """Build a complete ``op`` (operator record) line — no ``provider``.
482
- ``writer_generation`` and ``writer_revision`` as in ``make_obs``."""
503
+ ``writer_generation``, ``writer_revision`` and ``writer_successor`` as in
504
+ ``make_obs``."""
483
505
  core = {"t": "op", "at": at, "src": src, "payload": payload}
484
- _writer_core(core, writer_generation, writer_revision)
506
+ _writer_core(core, writer_generation, writer_revision, writer_successor)
485
507
  return {"v": LINE_VERSION, **core, "id": content_id(core)}
486
508
 
487
509
 
488
510
  def prepare_record(record: dict) -> dict:
489
511
  """The single shared preparation step both append APIs apply (#825/#832
490
512
  spec 5.1): return ``record`` carrying the current writer generation and,
491
- since #797/#823/#840 (spec 4.6 B1), the current protocol revision.
513
+ since #797/#823/#840 (spec 4.6 B1), the current protocol revision and,
514
+ since #1019/#1014 (spec 4.7 C1), the successor revision.
492
515
 
493
516
  A content-id record (``id`` starting ``o:``) that is not yet fully
494
517
  stamped and whose id verifies over its current core is re-identified over
@@ -498,7 +521,8 @@ def prepare_record(record: dict) -> dict:
498
521
  stamps is returned unchanged. Only records about to be appended pass
499
522
  through here, so a retained record is never restamped."""
500
523
  if (_lib_account_protocol.is_stamped(record)
501
- and _lib_account_protocol.has_current_revision(record)):
524
+ and _lib_account_protocol.has_current_revision(record)
525
+ and _lib_account_protocol.has_successor_revision(record)):
502
526
  return record
503
527
  stamped = _lib_account_protocol.stamp(record)
504
528
  rid = record.get("id")
@@ -518,11 +542,12 @@ def unstamped_record(record: dict) -> dict:
518
542
  record whose id verifies over its stamped core, re-identifies it over the
519
543
  unstamped core. Any other id is preserved. For fixtures and tests that
520
544
  simulate a pre-stamp writer; never used on a production write path.
521
- The protocol revision (``wpr``) goes with the stamp."""
545
+ The protocol revision (``wpr``) and the successor revision (``wpx``) go
546
+ with the stamp."""
522
547
  if not isinstance(record, dict) or (
523
- _WPG not in record and _WPR not in record):
548
+ _WPG not in record and _WPR not in record and _WPX not in record):
524
549
  return record
525
- out = {k: v for k, v in record.items() if k not in (_WPG, _WPR)}
550
+ out = {k: v for k, v in record.items() if k not in (_WPG, _WPR, _WPX)}
526
551
  rid = record.get("id")
527
552
  if (record.get("t") in ("obs", "op") and isinstance(rid, str)
528
553
  and rid.startswith("o:")):
@@ -538,9 +563,24 @@ def prerevision_record(record: dict) -> dict:
538
563
  generation without the protocol revision, re-identified like
539
564
  ``unstamped_record``. For fixtures and tests that simulate the previous
540
565
  release; never used on a production write path."""
541
- if not isinstance(record, dict) or _WPR not in record:
566
+ if not isinstance(record, dict) or (_WPR not in record
567
+ and _WPX not in record):
568
+ return record
569
+ return _without_keys(record, (_WPR, _WPX))
570
+
571
+
572
+ def revision2_record(record: dict) -> dict:
573
+ """The revision-2 (1.116.x) shape of ``record`` (#1019/#1014 spec 4.7):
574
+ ``wpg`` and ``wpr`` without the successor revision, re-identified like
575
+ ``unstamped_record``. For fixtures and tests only; never used on a
576
+ production write path."""
577
+ if not isinstance(record, dict) or _WPX not in record:
542
578
  return record
543
- out = {k: v for k, v in record.items() if k != _WPR}
579
+ return _without_keys(record, (_WPX,))
580
+
581
+
582
+ def _without_keys(record: dict, keys) -> dict:
583
+ out = {k: v for k, v in record.items() if k not in keys}
544
584
  rid = record.get("id")
545
585
  if (record.get("t") in ("obs", "op") and isinstance(rid, str)
546
586
  and rid.startswith("o:")):
@@ -605,9 +645,12 @@ _PROTOCOL_RESOLUTION_V2_KIND = _lib_account_protocol.PROTOCOL_RESOLUTION_V2_KIND
605
645
  #: #797/#823/#840 (spec 4.6 B5): the previous release's v2 validator rejects
606
646
  #: the protocol revision stamp, so the current binary emits this successor.
607
647
  PROTOCOL_RESOLUTION_V3_KIND = _lib_account_protocol.PROTOCOL_RESOLUTION_V3_KIND
648
+ #: #1019/#1014 (spec 4.7 C5): 1.116.1's v3 validator rejects the successor
649
+ #: revision stamp, so the current binary emits this successor.
650
+ PROTOCOL_RESOLUTION_V4_KIND = _lib_account_protocol.PROTOCOL_RESOLUTION_V4_KIND
608
651
  PROTOCOL_RESOLUTION_KINDS = frozenset((
609
652
  _PROTOCOL_RESOLUTION_KIND, _PROTOCOL_RESOLUTION_V2_KIND,
610
- PROTOCOL_RESOLUTION_V3_KIND))
653
+ PROTOCOL_RESOLUTION_V3_KIND, PROTOCOL_RESOLUTION_V4_KIND))
611
654
  _PROTOCOL_RESOLUTION_SRC = "journal-repair"
612
655
 
613
656
 
@@ -647,7 +690,7 @@ def make_protocol_resolution(
647
690
  at=at,
648
691
  src=_PROTOCOL_RESOLUTION_SRC,
649
692
  payload={
650
- "kind": PROTOCOL_RESOLUTION_V3_KIND,
693
+ "kind": PROTOCOL_RESOLUTION_V4_KIND,
651
694
  "violations": refs,
652
695
  "journal_high_water": {
653
696
  "segment": segment,
@@ -681,7 +724,8 @@ def make_evt(kind: str, id: str, at: str, payload: dict, rev: int = 0) -> dict:
681
724
  body["kind"] = kind
682
725
  return {"v": LINE_VERSION, "t": "evt", "id": id, "rev": rev,
683
726
  "at": at, "src": "ingest", "payload": body,
684
- _WPG: _WRITER_GENERATION, _WPR: _WRITER_REVISION}
727
+ _WPG: _WRITER_GENERATION, _WPR: _WRITER_REVISION,
728
+ _WPX: _WRITER_SUCCESSOR}
685
729
 
686
730
 
687
731
  # --------------------------------------------------------------------------
@@ -721,9 +765,10 @@ def _validate_protocol_resolution(record: dict) -> dict:
721
765
  required = {"v", "t", "id", "at", "src", "payload"}
722
766
  # #825/#832: a current record also carries the writer-generation stamp,
723
767
  # which is part of its content-id core; #797/#823/#840 adds the protocol
724
- # revision (spec 4.6 B5).
768
+ # revision (spec 4.6 B5) and #1019/#1014 the successor revision (C5).
725
769
  if set(record) not in (required, required | {_WPG},
726
- required | {_WPG, _WPR}):
770
+ required | {_WPG, _WPR},
771
+ required | {_WPG, _WPR, _WPX}):
727
772
  raise JournalProtocolError(
728
773
  "journal protocol resolution record shape is invalid"
729
774
  )
@@ -747,6 +792,8 @@ def _validate_protocol_resolution(record: dict) -> dict:
747
792
  core[_WPG] = record[_WPG]
748
793
  if _WPR in record:
749
794
  core[_WPR] = record[_WPR]
795
+ if _WPX in record:
796
+ core[_WPX] = record[_WPX]
750
797
  if record.get("id") != content_id(core):
751
798
  raise JournalProtocolError(
752
799
  "journal protocol resolution record id does not match its content"
@@ -900,6 +947,7 @@ def make_correction_batch(
900
947
  "actions_hash": actions_hash,
901
948
  _WPG: _WRITER_GENERATION,
902
949
  _WPR: _WRITER_REVISION,
950
+ _WPX: _WRITER_SUCCESSOR,
903
951
  }
904
952
  records = [{**marker, "phase": "begin"}]
905
953
  for seq, core in enumerate(cores):
@@ -912,6 +960,7 @@ def make_correction_batch(
912
960
  "seq": seq,
913
961
  _WPG: _WRITER_GENERATION,
914
962
  _WPR: _WRITER_REVISION,
963
+ _WPX: _WRITER_SUCCESSOR,
915
964
  }
916
965
  )
917
966
  records.append({**marker, "phase": "commit"})
@@ -930,13 +979,22 @@ def revision_batch_id(batch_id: str, begins) -> str:
930
979
  hashes markers byte-exactly), and a copy without the stamp would land
931
980
  after the revision boundary, where admission excludes it. Its plan is
932
981
  therefore authored afresh under a derived id, and the original begin
933
- stays the inert, incomplete batch it was."""
982
+ stays the inert, incomplete batch it was.
983
+
984
+ #1019/#1014 (spec 4.7 C5 bullet 4): the reuse test is now the successor
985
+ revision. A begin with ``wpr`` but no ``wpx`` (1.116.x) is retried under
986
+ ``<logical>:wpx3``, where ``logical`` is ``batch_id`` without a trailing
987
+ ``:wpr2`` (the revision-2 retry suffix), so an interrupted revision-2
988
+ attempt and its original share one revision-3 retry identity."""
934
989
  begins = list(begins)
935
990
  if not begins or any(
936
- _lib_account_protocol.has_current_revision(begin)
991
+ _lib_account_protocol.has_successor_revision(begin)
937
992
  for begin in begins):
938
993
  return batch_id
939
- return f"{batch_id}:wpr{_lib_account_protocol.PROTOCOL_REVISION}"
994
+ suffix = f":wpr{_lib_account_protocol.PROTOCOL_REVISION}"
995
+ logical = (batch_id[:-len(suffix)] if batch_id.endswith(suffix)
996
+ else batch_id)
997
+ return f"{logical}:wpx{_lib_account_protocol.SUCCESSOR_REVISION}"
940
998
 
941
999
 
942
1000
  def _validate_batch_marker(record: dict) -> dict:
@@ -1852,6 +1910,199 @@ def make_codex_window_attribution_retract(
1852
1910
  src=WINDOW_ATTRIBUTION_SRC, payload=payload)
1853
1911
 
1854
1912
 
1913
+ # --------------------------------------------------------------------------
1914
+ # #944: durable write-time Claude cost attribution decisions
1915
+ # --------------------------------------------------------------------------
1916
+
1917
+ CLAUDE_COST_ACCOUNT_KIND = "claude_cost_account"
1918
+ CLAUDE_COST_ACCOUNT_SRC = "claude-cost-account"
1919
+ CLAUDE_COST_ACCOUNT_VERSION = 1
1920
+ _CLAUDE_COST_ACCOUNT_KEYS = frozenset((
1921
+ "kind", "v", "rule", "basis", "reason", "account_key", "decided_at",
1922
+ "journal_hw", "closing_capture", "evidence", "items",
1923
+ ))
1924
+ _HEX32_LEN = 32
1925
+ _HEX64_LEN = 64
1926
+
1927
+
1928
+ def _is_hex(value, length: int) -> bool:
1929
+ return (isinstance(value, str) and len(value) == length
1930
+ and all(ch in "0123456789abcdef" for ch in value))
1931
+
1932
+
1933
+ def _nonneg_int(value) -> bool:
1934
+ return type(value) is int and value >= 0
1935
+
1936
+
1937
+ def _valid_instant_text(value) -> bool:
1938
+ try:
1939
+ _lib_claude_attribution.capture_interval(value)
1940
+ except (ValueError, OverflowError):
1941
+ return False
1942
+ return True
1943
+
1944
+
1945
+ def _valid_stamp(value) -> bool:
1946
+ """The two-shaped stamp rule: a present account is a real key, never the
1947
+ ``unattributed`` sentinel (NULL omits the field)."""
1948
+ return (isinstance(value, str) and bool(value)
1949
+ and value != _ATTRIBUTION_SENTINEL)
1950
+
1951
+
1952
+ def _validate_claude_cost_item(item, basis: str) -> None:
1953
+ if not isinstance(item, list) or not item:
1954
+ raise ValueError("claude_cost_account item must be a non-empty list")
1955
+ form = item[0]
1956
+ preserved = basis == _lib_claude_attribution.BASIS_PRESERVED
1957
+ if form == _lib_claude_attribution.FORM_KEYED:
1958
+ size = 3 if preserved else 4
1959
+ if len(item) != size:
1960
+ raise ValueError("keyed item has the wrong shape")
1961
+ if not all(isinstance(v, str) and v for v in item[1:3]):
1962
+ raise ValueError("keyed item ids must be non-empty strings")
1963
+ if not preserved and item[3] is not None and not isinstance(
1964
+ item[3], str):
1965
+ raise ValueError("keyed item timestamp must be a string")
1966
+ return
1967
+ if form == _lib_claude_attribution.FORM_PHYSICAL:
1968
+ if preserved or len(item) != 5:
1969
+ raise ValueError("physical item has the wrong shape")
1970
+ if not _is_hex(item[1], _HEX32_LEN):
1971
+ raise ValueError("physical item location is not a location digest")
1972
+ if not _nonneg_int(item[2]) or not _is_hex(item[3], _HEX64_LEN):
1973
+ raise ValueError("physical item offset or digest is invalid")
1974
+ if item[4] is not None and not isinstance(item[4], str):
1975
+ raise ValueError("physical item timestamp must be a string")
1976
+ return
1977
+ if form == _lib_claude_attribution.FORM_LEGACY:
1978
+ if not preserved or len(item) != 5:
1979
+ raise ValueError("legacy item has the wrong shape")
1980
+ if not _is_hex(item[1], _HEX32_LEN):
1981
+ raise ValueError("legacy item location is not a location digest")
1982
+ if not _nonneg_int(item[2]) or not _is_hex(item[3], _HEX64_LEN):
1983
+ raise ValueError("legacy item offset or digest is invalid")
1984
+ projection = item[4]
1985
+ if (not isinstance(projection, list) or len(projection)
1986
+ != len(_lib_claude_attribution.PROJECTION_FIELDS)):
1987
+ raise ValueError("legacy item projection has the wrong shape")
1988
+ if _lib_claude_attribution.projection_sha256(projection) != item[3]:
1989
+ raise ValueError("legacy item digest does not match its projection")
1990
+ return
1991
+ raise ValueError(f"unknown claude_cost_account item form {form!r}")
1992
+
1993
+
1994
+ def validate_claude_cost_account(payload: dict) -> None:
1995
+ """Validate one ``claude_cost_account`` payload (#944 spec 5.4);
1996
+ ``ValueError`` on any malformed field. A rejected payload is never
1997
+ applied."""
1998
+ if not isinstance(payload, dict):
1999
+ raise ValueError("claude_cost_account payload must be an object")
2000
+ unknown = set(payload) - _CLAUDE_COST_ACCOUNT_KEYS
2001
+ if unknown:
2002
+ raise ValueError(f"unknown claude_cost_account keys {sorted(unknown)}")
2003
+ if payload.get("kind") != CLAUDE_COST_ACCOUNT_KIND:
2004
+ raise ValueError("payload is not a claude_cost_account op")
2005
+ if payload.get("v") != CLAUDE_COST_ACCOUNT_VERSION or type(
2006
+ payload.get("v")) is not int:
2007
+ raise ValueError("claude_cost_account version is invalid")
2008
+ rule = payload.get("rule")
2009
+ if type(rule) is not int or rule < 1:
2010
+ raise ValueError("claude_cost_account rule is invalid")
2011
+ basis = payload.get("basis")
2012
+ if basis not in _lib_claude_attribution.BASES:
2013
+ raise ValueError("claude_cost_account basis is invalid")
2014
+ if basis == _lib_claude_attribution.BASIS_FALLBACK:
2015
+ if payload.get("reason") not in _lib_claude_attribution.FALLBACK_REASONS:
2016
+ raise ValueError("a fallback decision needs a known reason")
2017
+ elif "reason" in payload:
2018
+ raise ValueError("only a fallback decision carries a reason")
2019
+ if "account_key" in payload and not _valid_stamp(payload["account_key"]):
2020
+ raise ValueError("claude_cost_account account_key is invalid")
2021
+ if not _valid_instant_text(payload.get("decided_at")):
2022
+ raise ValueError("claude_cost_account decided_at is invalid")
2023
+ hw = payload.get("journal_hw")
2024
+ if (not isinstance(hw, list) or len(hw) != 2
2025
+ or not isinstance(hw[0], str) or not hw[0]
2026
+ or not _nonneg_int(hw[1])):
2027
+ raise ValueError("claude_cost_account journal_hw is invalid")
2028
+ capture = payload.get("closing_capture")
2029
+ if capture is not None or "closing_capture" in payload:
2030
+ if basis != _lib_claude_attribution.BASIS_AGREEMENT:
2031
+ raise ValueError("only an agreement uses a closing capture")
2032
+ if (not isinstance(capture, dict)
2033
+ or not set(capture) <= {"at", "account_key"}
2034
+ or not _valid_instant_text(capture.get("at"))):
2035
+ raise ValueError("claude_cost_account closing_capture is invalid")
2036
+ if "account_key" in capture and not _valid_stamp(capture["account_key"]):
2037
+ raise ValueError("closing capture account_key is invalid")
2038
+ if "evidence" in payload:
2039
+ evidence = payload["evidence"]
2040
+ if basis == _lib_claude_attribution.BASIS_PRESERVED:
2041
+ raise ValueError("preserved history carries no evidence")
2042
+ if not isinstance(evidence, list):
2043
+ raise ValueError("claude_cost_account evidence must be a list")
2044
+ for entry in evidence:
2045
+ if (not isinstance(entry, list) or len(entry) != 3
2046
+ or not _valid_instant_text(entry[0])
2047
+ or not isinstance(entry[1], str) or not entry[1]
2048
+ or not _nonneg_int(entry[2])):
2049
+ raise ValueError("claude_cost_account evidence is invalid")
2050
+ items = payload.get("items")
2051
+ if not isinstance(items, list) or not items:
2052
+ raise ValueError("claude_cost_account needs at least one item")
2053
+ for item in items:
2054
+ _validate_claude_cost_item(item, basis)
2055
+
2056
+
2057
+ def make_claude_cost_account(*, basis: str, reason: "str | None",
2058
+ account_key: "str | None", decided_at: str,
2059
+ journal_hw, closing_capture: "dict | None",
2060
+ evidence: list, items: list) -> dict:
2061
+ """Build one ``claude_cost_account`` op: a homogeneous batch of durable
2062
+ Claude cost attribution decisions (#944 spec 5.4) sharing one basis,
2063
+ reason, account, rule version and closing capture.
2064
+
2065
+ Two-shaped stamp rule: a real account rides ``payload.account_key`` and a
2066
+ NULL decision OMITS it -- never the literal ``unattributed``. The payload
2067
+ carries no credential, no transcript text and no clear-text path: physical
2068
+ and legacy items name their file by its location digest only."""
2069
+ record = claude_cost_account_op_unvalidated(
2070
+ basis=basis, reason=reason, account_key=account_key,
2071
+ decided_at=decided_at, journal_hw=journal_hw,
2072
+ closing_capture=closing_capture, evidence=evidence, items=items)
2073
+ validate_claude_cost_account(record["payload"])
2074
+ return record
2075
+
2076
+
2077
+ def claude_cost_account_op_unvalidated(
2078
+ *, basis: str, reason: "str | None", account_key: "str | None",
2079
+ decided_at: str, journal_hw, closing_capture: "dict | None",
2080
+ evidence: list, items: list) -> dict:
2081
+ """The op ``make_claude_cost_account`` builds, WITHOUT validating it.
2082
+
2083
+ Only for measuring a candidate line's encoded size (the batch builder
2084
+ sizes each batch from a one-item skeleton); never append its result --
2085
+ every appended op goes through ``make_claude_cost_account``."""
2086
+ payload = {
2087
+ "kind": CLAUDE_COST_ACCOUNT_KIND,
2088
+ "v": CLAUDE_COST_ACCOUNT_VERSION,
2089
+ "rule": _lib_claude_attribution.RULE_VERSION,
2090
+ "basis": basis,
2091
+ "decided_at": decided_at,
2092
+ "journal_hw": [str(journal_hw[0]), int(journal_hw[1])],
2093
+ "items": [list(item) for item in items],
2094
+ }
2095
+ if reason is not None:
2096
+ payload["reason"] = reason
2097
+ if account_key is not None:
2098
+ payload["account_key"] = account_key
2099
+ if closing_capture is not None:
2100
+ payload["closing_capture"] = dict(closing_capture)
2101
+ if evidence:
2102
+ payload["evidence"] = [list(entry) for entry in evidence]
2103
+ return make_op(at=decided_at, src=CLAUDE_COST_ACCOUNT_SRC, payload=payload)
2104
+
2105
+
1855
2106
  # --------------------------------------------------------------------------
1856
2107
  # segment naming + canonical order
1857
2108
  # --------------------------------------------------------------------------
package/bin/_lib_jsonl.py CHANGED
@@ -31,6 +31,7 @@ from typing import Any
31
31
 
32
32
  from _lib_codex_pools import codex_model_scoped_quota_pool
33
33
  from _lib_source_identity import canonical_identity_from_root_key
34
+ from _lib_claude_attribution import valid_record_id as _valid_record_id
34
35
 
35
36
 
36
37
  def _eprint(*args: Any) -> None:
@@ -262,8 +263,19 @@ def _classify_cost_entry(obj, path_str: str):
262
263
  except ValueError:
263
264
  return None, "bad-timestamp"
264
265
 
266
+ # #944 F1: only a non-empty string names a record. An empty, numeric or
267
+ # object id counts as missing HERE, at the shared parser chokepoint, so the
268
+ # dedup index, the id-less partial indexes, the direct fallback's dedup map
269
+ # and the attribution identity all see the same NULL: such a line is
270
+ # deduplicated by its location and attributed by its bytes, and can never
271
+ # reach the journal as a keyed item it would reject (which aborted every
272
+ # later sync).
265
273
  msg_id = msg.get("id")
266
274
  req_id = obj.get("requestId")
275
+ if not _valid_record_id(msg_id):
276
+ msg_id = None
277
+ if not _valid_record_id(req_id):
278
+ req_id = None
267
279
  cost_usd_raw = obj.get("costUSD")
268
280
  try:
269
281
  cost_usd = float(cost_usd_raw) if cost_usd_raw is not None else None
@@ -156,6 +156,16 @@ class RateChangeTransition:
156
156
  #: status. Folding it into `withholding_status` is rejected: it would make
157
157
  #: an otherwise healthy successor read as currently withheld.
158
158
  baseline_withheld_days: "int | None" = None
159
+ #: #1015 spec 5.7: the frozen `transitionLineage` the detecting reduction
160
+ #: wrote on the successor regime (the union of both sides' dependency
161
+ #: windows and the detector coverage, the scope, the basis, the
162
+ #: descriptor and its digest), or None for a transition with no lineage
163
+ #: (the owed sweep's identity-only descriptor, a legacy path). It is not
164
+ #: part of `identity()`, not compared, and never reaches the v1 payload,
165
+ #: which stays byte-frozen; a version-2 payload journals it as
166
+ #: `fit_lineage`.
167
+ fit_lineage: "dict | None" = dataclasses.field(default=None,
168
+ compare=False)
159
169
 
160
170
  def identity(self) -> tuple:
161
171
  """The §6.3 key: `(provider, account identity, effectiveFrom)`.
@@ -413,6 +423,11 @@ def event_payload_v2(transition: RateChangeTransition, *,
413
423
  payload["detector_input_causes"] = transition.detector_input_causes
414
424
  payload["composition_provenance"] = transition.composition_provenance
415
425
  payload["baseline_withheld_days"] = transition.baseline_withheld_days
426
+ if transition.fit_lineage is not None:
427
+ # #1015 spec 5.7: only a newly emitted event carries the lineage, and
428
+ # only when one was frozen at detection. A key absent rather than
429
+ # null keeps every pre-#1015 v2 payload byte-identical.
430
+ payload["fit_lineage"] = transition.fit_lineage
416
431
  return payload
417
432
 
418
433
 
@@ -457,6 +472,63 @@ def rate_change_ratio(transition: RateChangeTransition) -> "float | None":
457
472
  return transition.new_units_per_point / transition.previous_units_per_point
458
473
 
459
474
 
475
+ def active_pair_among(regimes, keep) -> "tuple | None":
476
+ """The `(predecessor, successor)` pair `active_rate_change` reads over
477
+ ``[r for r in regimes if keep(r)]``, or None — asking ``keep`` lazily,
478
+ newest start first, and only about regimes that can decide the answer
479
+ (#1015 R6: a lineage assessment per regime is not free, and a closed
480
+ regime far behind the active pair never decides the marker).
481
+
482
+ It restates `_adjacent_pairs` and `active_rate_change` exactly. At each
483
+ start instant, newest first, that some regime starting there leaves
484
+ open: the predecessor is the FIRST kept, non-stale regime (in list
485
+ order) closing at that instant; the pair's successor is the LAST kept
486
+ regime starting there that is not that predecessor and shares its
487
+ fingerprint and coefficient era. The newest start whose successor is
488
+ open is the active pair. ``keep`` is called at most once per regime.
489
+ """
490
+ kept: dict = {}
491
+
492
+ def keeps(regime) -> bool:
493
+ if id(regime) not in kept:
494
+ kept[id(regime)] = bool(keep(regime))
495
+ return kept[id(regime)]
496
+
497
+ regimes = [r for r in (regimes or ()) if isinstance(r, dict)]
498
+ starts: dict = {}
499
+ for regime in regimes:
500
+ start = _instant(regime.get("effectiveFrom"))
501
+ if start is not None:
502
+ starts.setdefault(start, []).append(regime)
503
+ for start in sorted(starts, reverse=True):
504
+ candidates = starts[start]
505
+ if not any(r.get("effectiveUntil") in (None, "") for r in candidates):
506
+ continue
507
+ predecessor = None
508
+ for regime in regimes:
509
+ if str(regime.get("status") or "") == "stale":
510
+ continue
511
+ if _instant(regime.get("effectiveUntil")) == start \
512
+ and keeps(regime):
513
+ predecessor = regime
514
+ break
515
+ if predecessor is None:
516
+ continue
517
+ for regime in reversed(candidates):
518
+ if regime is predecessor:
519
+ continue
520
+ if predecessor.get("fingerprint") != regime.get("fingerprint") \
521
+ or predecessor.get("coefficientEra") \
522
+ != regime.get("coefficientEra"):
523
+ continue
524
+ if not keeps(regime):
525
+ continue
526
+ if regime.get("effectiveUntil") in (None, ""):
527
+ return predecessor, regime
528
+ break
529
+ return None
530
+
531
+
460
532
  def active_rate_change(regimes) -> "dict | None":
461
533
  """Spec §6.6's marker predicate: the ACTIVE open regime has a confirmed
462
534
  predecessor, and the marker shows for the whole of that successor regime.