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
@@ -1442,7 +1442,74 @@ def _do_update_check() -> None:
1442
1442
  c._save_update_state(state)
1443
1443
 
1444
1444
 
1445
- def _spawn_detached(command: str) -> bool:
1445
+ #: The environment the next `_spawn_detached` call on this thread merges into
1446
+ #: its child's (#939 D5): the detached Codex workers' attempt id travels this
1447
+ #: way, so the spawn sites keep calling `_spawn_detached(command)` and every
1448
+ #: one-argument test double of it keeps working.
1449
+ _DETACHED_ENV = threading.local()
1450
+
1451
+
1452
+ class detached_env:
1453
+ """Scope ``mapping`` onto every `_spawn_detached` call this thread makes
1454
+ inside the ``with`` block (#939 D5)."""
1455
+
1456
+ def __init__(self, mapping):
1457
+ self.mapping = dict(mapping or {})
1458
+ self.previous = None
1459
+
1460
+ def __enter__(self):
1461
+ self.previous = getattr(_DETACHED_ENV, "mapping", None)
1462
+ _DETACHED_ENV.mapping = {**(self.previous or {}), **self.mapping}
1463
+ return self.mapping
1464
+
1465
+ def __exit__(self, *_exc):
1466
+ _DETACHED_ENV.mapping = self.previous
1467
+ return False
1468
+
1469
+
1470
+ def detached_env_current() -> dict:
1471
+ """The mapping `_spawn_detached` would merge on this thread right now."""
1472
+ return dict(getattr(_DETACHED_ENV, "mapping", None) or {})
1473
+
1474
+
1475
+ def take_detached_pid() -> "int | None":
1476
+ """The pid of the child the last `_spawn_detached` call on this thread
1477
+ launched, cleared as it is read (#939 D5: the Codex worker spawner records
1478
+ it as the attempt's ``spawnPid``). ``None`` after a failed spawn, or when
1479
+ a test double replaced `_spawn_detached`."""
1480
+ pid = getattr(_DETACHED_ENV, "pid", None)
1481
+ _DETACHED_ENV.pid = None
1482
+ return pid
1483
+
1484
+
1485
+ def _spawn_detached_pid(command: str, *, env: "dict | None" = None) -> "int | None":
1486
+ """`_spawn_detached`'s launch with its environment merge, returning the
1487
+ child's pid (``None`` when the spawn raised)."""
1488
+ extra = {**detached_env_current(), **(env or {})}
1489
+ try:
1490
+ proc = subprocess.Popen(
1491
+ [sys.executable, os.path.realpath(sys.argv[0]), command],
1492
+ stdin=subprocess.DEVNULL,
1493
+ stdout=subprocess.DEVNULL,
1494
+ stderr=subprocess.DEVNULL,
1495
+ start_new_session=True,
1496
+ close_fds=True,
1497
+ env=({**os.environ, **extra} if extra else None),
1498
+ )
1499
+ except Exception:
1500
+ # Fire-and-forget: never let a spawn failure propagate.
1501
+ return None
1502
+ try:
1503
+ # #939 R8-04: keep the handle, so a worker-liveness probe can see
1504
+ # that this child exited without `os.waitid` (macOS Python < 3.13).
1505
+ import _lib_codex_worker_lifecycle as lifecycle
1506
+ lifecycle.remember_launch(proc, attempt=extra.get(lifecycle.ATTEMPT_ENV))
1507
+ except Exception: # noqa: BLE001 — bookkeeping never fails a spawn
1508
+ pass
1509
+ return proc.pid
1510
+
1511
+
1512
+ def _spawn_detached(command: str, *, env: "dict | None" = None) -> bool:
1446
1513
  """Fire-and-forget a hidden self-subcommand as a detached worker.
1447
1514
 
1448
1515
  Returns whether the spawn was issued. The two update/telemetry callers
@@ -1459,20 +1526,16 @@ def _spawn_detached(command: str) -> bool:
1459
1526
  background workers below — `_update-check` and `_telemetry-beat` stay
1460
1527
  deliberately separate spawns (spec review finding #1) and share only
1461
1528
  this Popen shape.
1529
+
1530
+ ``env`` (and any `detached_env` scope on this thread) is merged into a copy
1531
+ of this process's environment; with neither, the child inherits it as
1532
+ before (#939 D5). The child's pid is kept for `take_detached_pid`, so the
1533
+ spawn sites keep calling this one-argument form and its test doubles keep
1534
+ working.
1462
1535
  """
1463
- try:
1464
- subprocess.Popen(
1465
- [sys.executable, os.path.realpath(sys.argv[0]), command],
1466
- stdin=subprocess.DEVNULL,
1467
- stdout=subprocess.DEVNULL,
1468
- stderr=subprocess.DEVNULL,
1469
- start_new_session=True,
1470
- close_fds=True,
1471
- )
1472
- return True
1473
- except Exception:
1474
- # Fire-and-forget: never let a spawn failure propagate.
1475
- return False
1536
+ pid = _spawn_detached_pid(command, env=env)
1537
+ _DETACHED_ENV.pid = pid
1538
+ return pid is not None
1476
1539
 
1477
1540
 
1478
1541
  def _spawn_detached_with_pid(
@@ -33,6 +33,16 @@ codec; after it, a Claude-scoped record without ``wpr == 2`` is excluded
33
33
  exactly as an unstamped record is after the original cutover. The revision
34
34
  boundary never re-admits a record the original rule excludes.
35
35
 
36
+ #1019/#1014 (spec section 4.7, C1-C8): revision 3 of the fence. ``wpg`` and
37
+ ``wpr`` keep their values (1.116.1's exact-equality checks must keep
38
+ admitting what the current binary writes), and a third reserved top-level
39
+ field ``wpx`` carries the successor revision. A durable
40
+ ``account_bound_revision_v3`` op records a third physical boundary with the
41
+ same codec plus the revision-2 op's coordinate; after it, a Claude-scoped
42
+ record admitted by its stamps is excluded unless it also carries
43
+ ``wpx == 3`` (``revision-3-unstamped``). No boundary re-admits what an
44
+ earlier rule excludes, and the Codex-only exemptions are unchanged.
45
+
36
46
  Pure: no I/O, no clock, no SQLite.
37
47
  """
38
48
  from __future__ import annotations
@@ -54,6 +64,12 @@ REVISION_KEY = "wpr"
54
64
  PROTOCOL_REVISION = 2
55
65
  REVISION_OP_KIND = "account_bound_revision"
56
66
  REVISION_OP_ID = "account-bound-revision-2"
67
+ #: #1019/#1014 (spec 4.7 C1, C2): the successor-revision stamp and the
68
+ #: durable op that records where revision 3 begins.
69
+ SUCCESSOR_REVISION_KEY = "wpx"
70
+ SUCCESSOR_REVISION = 3
71
+ REVISION3_OP_KIND = "account_bound_revision_v3"
72
+ REVISION3_OP_ID = "account-bound-revision-3"
57
73
  #: Spec revision 5 (section 7, operator decision on Codex design-fix-round-5
58
74
  #: Q4): the `legacy_spool_activity` reason of an incomplete inventory. Such an
59
75
  #: op records typed failure evidence and no digest, so it anchors no baseline.
@@ -67,6 +83,17 @@ INVENTORY_INCOMPLETE_REASON = "inventory-incomplete"
67
83
  INVENTORY_COMPLETE_REASON = "inventory-complete"
68
84
  #: The reasons whose unresolved markers an incomplete inventory left.
69
85
  INVENTORY_REASONS = (INVENTORY_INCOMPLETE_REASON, INVENTORY_COMPLETE_REASON)
86
+ #: #948 spec 6.2: the three non-trigger recovery ops of the outcome
87
+ #: quarantine. An inventory-episode completion (a complete scan found the
88
+ #: spool unchanged while the journal shows the episode open), an OAuth
89
+ #: authority completion (appended after its reconciliation committed) and a
90
+ #: per-axis release (appended right after its witness). The previous release
91
+ #: ignores an unknown op kind.
92
+ INVENTORY_COMPLETION_OP_KIND = "legacy_spool_inventory_completion"
93
+ AUTHORITY_COMPLETION_OP_KIND = "outcome_authority_completion"
94
+ AXIS_RELEASE_OP_KIND = "outcome_axis_release"
95
+ RECOVERY_OP_KINDS = (INVENTORY_COMPLETION_OP_KIND,
96
+ AUTHORITY_COMPLETION_OP_KIND, AXIS_RELEASE_OP_KIND)
70
97
  #: The operations an inventory can fail at (the evidence's ``operation``).
71
98
  INVENTORY_OPERATIONS = ("list", "stat", "read")
72
99
 
@@ -79,6 +106,11 @@ PROTOCOL_RESOLUTION_V2_KIND = "journal_protocol_resolution_v2"
79
106
  #: binary emits repair acknowledgements under this successor kind, which the
80
107
  #: previous release ignores as an unknown op.
81
108
  PROTOCOL_RESOLUTION_V3_KIND = "journal_protocol_resolution_v3"
109
+ #: #1019/#1014 (spec 4.7 C5): 1.116.1's strict validator of the v3
110
+ #: acknowledgement has an exact key set and an identity core without
111
+ #: ``wpx``, so the current binary emits repair acknowledgements under this
112
+ #: successor kind, which 1.116.1 ignores as an unknown op.
113
+ PROTOCOL_RESOLUTION_V4_KIND = "journal_protocol_resolution_v4"
82
114
  WEEKLY_OBSERVATION_DECISION_V2_KIND = "claude_weekly_observation_decision_v2"
83
115
 
84
116
  #: Admission families. ``codex`` is the only family admitted without a stamp.
@@ -93,15 +125,20 @@ FAMILIES = (
93
125
  )
94
126
 
95
127
  ADMISSION_REASONS = ("no-cutover", "historical", "stamped", "codex-only",
96
- "excluded", "revision-unstamped")
128
+ "excluded", "revision-unstamped",
129
+ "revision-3-unstamped")
97
130
  #: The reasons that exclude a record.
98
- EXCLUDED_REASONS = frozenset(("excluded", "revision-unstamped"))
131
+ EXCLUDED_REASONS = frozenset(("excluded", "revision-unstamped",
132
+ "revision-3-unstamped"))
99
133
 
100
134
  _DIGEST_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
101
135
 
102
136
  _CLAUDE_OP_KINDS = frozenset((
103
137
  "account_observe", "account_label", "accounts_cutover",
104
138
  "weekly_credit_floor", "sync_week",
139
+ # #944 spec 5.10: a Claude cost attribution decision is Claude-scoped
140
+ # accounting truth, so an unstamped post-boundary one is excluded.
141
+ "claude_cost_account",
105
142
  ))
106
143
  _CODEX_OP_KINDS = frozenset((
107
144
  "codex_file_account", "codex_window_attribution",
@@ -110,15 +147,17 @@ _CODEX_OP_KINDS = frozenset((
110
147
  _ADMIN_OP_KINDS = frozenset((
111
148
  "journal_protocol_resolution", "claude_weekly_observation_decision",
112
149
  PROTOCOL_RESOLUTION_V2_KIND, PROTOCOL_RESOLUTION_V3_KIND,
113
- WEEKLY_OBSERVATION_DECISION_V2_KIND,
150
+ PROTOCOL_RESOLUTION_V4_KIND, WEEKLY_OBSERVATION_DECISION_V2_KIND,
114
151
  ))
115
152
  _PROTOCOL_OP_KINDS = frozenset((CUTOVER_OP_KIND, LEGACY_SPOOL_ACTIVITY_KIND,
116
- REVISION_OP_KIND))
153
+ REVISION_OP_KIND, REVISION3_OP_KIND,
154
+ *RECOVERY_OP_KINDS))
117
155
  _ADMIN_RECORD_TYPES = frozenset(("correction", "correction_batch"))
118
156
  _CLAUDE_EVT_KINDS = frozenset((
119
157
  "snapshot_accept", "weekly_cost_snapshot", "week_reset", "five_hour_credit",
120
158
  "five_hour_block_close", "percent_milestone", "five_hour_milestone",
121
159
  "weekly_credit_effects", "projected", "project_budget", "meter_rate_change",
160
+ "meter_rate_change_supersession",
122
161
  ))
123
162
  #: Evt kinds admitted without a stamp only when their payload proves a Codex
124
163
  #: quota source (``payload.source == "codex"``, the source every Codex quota
@@ -165,6 +204,10 @@ class CutoverBoundary:
165
204
  #: the admission summary records the revision separately.
166
205
  revision: "RevisionBoundary | None" = dataclasses.field(
167
206
  default=None, compare=False)
207
+ #: #1019/#1014 (spec 4.7 C3): the revision-3 boundary a lookup found
208
+ #: after ``revision``, carried the same way and for the same reason.
209
+ revision3: "Revision3Boundary | None" = dataclasses.field(
210
+ default=None, compare=False)
168
211
 
169
212
 
170
213
  @dataclasses.dataclass(frozen=True)
@@ -196,6 +239,30 @@ class RevisionBoundary:
196
239
  continued_inventory_episode: "tuple[str, int] | None" = None
197
240
 
198
241
 
242
+ @dataclasses.dataclass(frozen=True)
243
+ class Revision3Boundary:
244
+ """The revision-3 boundary recorded by the ``account_bound_revision_v3``
245
+ op (#1019/#1014 spec 4.7 C2): the `RevisionBoundary` fields plus the
246
+ revision-2 op it extends (``revision2_segment`` and ``revision2_offset``,
247
+ the coordinate of that op).
248
+
249
+ ``legacy_spool_baseline_digest`` is the baseline digest of the inventory
250
+ that also covers the retired v2 directory's coordination state (C4), or
251
+ None with ``legacy_spool_inventory_failure`` when that inventory could
252
+ not complete; ``continued_inventory_episode`` as for revision 2."""
253
+
254
+ segment: str
255
+ end_offset: int
256
+ frozen_extents: Mapping[str, int]
257
+ legacy_spool_baseline_digest: "str | None"
258
+ cutover_segment: str
259
+ cutover_offset: int
260
+ revision2_segment: str
261
+ revision2_offset: int
262
+ legacy_spool_inventory_failure: "Mapping[str, object] | None" = None
263
+ continued_inventory_episode: "tuple[str, int] | None" = None
264
+
265
+
199
266
  @dataclasses.dataclass(frozen=True)
200
267
  class Admission:
201
268
  admitted: bool
@@ -209,10 +276,11 @@ class Admission:
209
276
 
210
277
  def stamp(record: dict) -> dict:
211
278
  """Return a shallow copy of ``record`` carrying the current writer
212
- generation and protocol revision (spec 4.6 B1). Idempotent; refuses a
213
- record that already names a DIFFERENT generation or revision (a caller
214
- must never relabel another protocol's record). The payload is never
215
- touched: both stamps are transport metadata."""
279
+ generation, protocol revision and successor revision (spec 4.6 B1;
280
+ #1019/#1014 spec 4.7 C1). Idempotent; refuses a record that already
281
+ names a DIFFERENT value of any of them (a caller must never relabel
282
+ another protocol's record). The payload is never touched: the stamps
283
+ are transport metadata."""
216
284
  if not isinstance(record, dict):
217
285
  raise ValueError("journal record must be a dict")
218
286
  existing = record.get(WRITER_GENERATION_KEY)
@@ -223,9 +291,14 @@ def stamp(record: dict) -> dict:
223
291
  raise ValueError(
224
292
  f"record already carries protocol revision "
225
293
  f"{record[REVISION_KEY]!r}")
294
+ if SUCCESSOR_REVISION_KEY in record and not has_successor_revision(record):
295
+ raise ValueError(
296
+ f"record already carries successor revision "
297
+ f"{record[SUCCESSOR_REVISION_KEY]!r}")
226
298
  out = dict(record)
227
299
  out[WRITER_GENERATION_KEY] = PROTOCOL_GENERATION
228
300
  out[REVISION_KEY] = PROTOCOL_REVISION
301
+ out[SUCCESSOR_REVISION_KEY] = SUCCESSOR_REVISION
229
302
  return out
230
303
 
231
304
 
@@ -245,15 +318,29 @@ def has_current_revision(record: dict) -> bool:
245
318
  return type(value) is int and value == PROTOCOL_REVISION
246
319
 
247
320
 
321
+ def has_successor_revision(record: dict) -> bool:
322
+ """Whether ``record`` carries exactly successor revision 3 (#1019/#1014
323
+ spec 4.7 C1), the writer-authority check after the revision-3 boundary.
324
+ Only an ``int`` equal to 3: never ``True``, ``"3"``, ``3.0`` or a later
325
+ revision."""
326
+ if not isinstance(record, dict):
327
+ return False
328
+ value = record.get(SUCCESSOR_REVISION_KEY)
329
+ return type(value) is int and value == SUCCESSOR_REVISION
330
+
331
+
332
+ _STAMP_KEYS = (WRITER_GENERATION_KEY, REVISION_KEY, SUCCESSOR_REVISION_KEY)
333
+
334
+
248
335
  def strip_stamp(record: dict) -> dict:
249
- """``record`` without its writer-generation and protocol-revision fields
250
- — the comparison shape for semantic event duplicate/conflict
251
- classification."""
252
- if not isinstance(record, dict) or (
253
- WRITER_GENERATION_KEY not in record and REVISION_KEY not in record):
336
+ """``record`` without its writer-generation, protocol-revision and
337
+ successor-revision fields — the comparison shape for semantic event
338
+ duplicate/conflict classification. Comparison only: a content id is
339
+ computed over the stamped core."""
340
+ if not isinstance(record, dict) or not any(
341
+ key in record for key in _STAMP_KEYS):
254
342
  return record
255
- return {k: v for k, v in record.items()
256
- if k not in (WRITER_GENERATION_KEY, REVISION_KEY)}
343
+ return {k: v for k, v in record.items() if k not in _STAMP_KEYS}
257
344
 
258
345
 
259
346
  # --------------------------------------------------------------------------
@@ -364,7 +451,45 @@ def with_revision(boundary: "CutoverBoundary | None",
364
451
  (revision.cutover_segment, revision.cutover_offset)
365
452
  != (boundary.segment, boundary.end_offset)):
366
453
  raise ValueError("revision boundary names a different cutover")
367
- return dataclasses.replace(boundary, revision=revision)
454
+ revision3 = boundary.revision3
455
+ if revision3 is not None and (
456
+ revision is None
457
+ or (revision3.revision2_segment, revision3.revision2_offset)
458
+ != (revision.segment, revision.end_offset)):
459
+ # A revision-3 boundary never outlives the revision-2 boundary it
460
+ # extends.
461
+ revision3 = None
462
+ return dataclasses.replace(boundary, revision=revision,
463
+ revision3=revision3)
464
+
465
+
466
+ def with_revision3(boundary: "CutoverBoundary | None",
467
+ revision3: "Revision3Boundary | None"):
468
+ """``boundary`` carrying ``revision3`` (#1019/#1014 spec 4.7 C3), or None
469
+ when there is no cutover. A revision 3 that names a different cutover or
470
+ revision-2 op (or arrives without a revision 2) is malformed and never
471
+ attached."""
472
+ if boundary is None:
473
+ return None
474
+ if revision3 is not None:
475
+ revision = boundary.revision
476
+ if ((revision3.cutover_segment, revision3.cutover_offset)
477
+ != (boundary.segment, boundary.end_offset)):
478
+ raise ValueError("revision-3 boundary names a different cutover")
479
+ if revision is None or (
480
+ (revision3.revision2_segment, revision3.revision2_offset)
481
+ != (revision.segment, revision.end_offset)):
482
+ raise ValueError(
483
+ "revision-3 boundary names a different revision-2 op")
484
+ return dataclasses.replace(boundary, revision3=revision3)
485
+
486
+
487
+ def original_boundary(boundary: "CutoverBoundary | None"):
488
+ """``boundary`` with neither revision attached: the cutover op's own
489
+ boundary."""
490
+ if boundary is None:
491
+ return None
492
+ return dataclasses.replace(boundary, revision=None, revision3=None)
368
493
 
369
494
 
370
495
  def revision_boundary_payload(boundary: RevisionBoundary) -> dict:
@@ -439,6 +564,76 @@ def revision_boundary_from_op(op_record: dict) -> RevisionBoundary:
439
564
  )
440
565
 
441
566
 
567
+ def revision3_boundary_payload(boundary: Revision3Boundary) -> dict:
568
+ """The camelCase payload fields of the revision-3 op (without ``kind``):
569
+ the revision-2 codec with ``revision: 3`` and the revision-2 op's
570
+ coordinate beside the cutover's."""
571
+ payload = {
572
+ "revision": SUCCESSOR_REVISION,
573
+ "cutover": {"segment": boundary.cutover_segment,
574
+ "offset": boundary.cutover_offset},
575
+ "revision2": {"segment": boundary.revision2_segment,
576
+ "offset": boundary.revision2_offset},
577
+ "segment": boundary.segment,
578
+ "endOffset": boundary.end_offset,
579
+ "frozenExtents": {k: boundary.frozen_extents[k]
580
+ for k in sorted(boundary.frozen_extents)},
581
+ "legacySpoolBaselineDigest": boundary.legacy_spool_baseline_digest,
582
+ }
583
+ if boundary.legacy_spool_inventory_failure is not None:
584
+ payload["legacySpoolInventoryFailure"] = dict(
585
+ boundary.legacy_spool_inventory_failure)
586
+ if boundary.continued_inventory_episode is not None:
587
+ segment, offset = boundary.continued_inventory_episode
588
+ payload["inventoryEpisode"] = {"segment": segment,
589
+ "offset": offset}
590
+ return payload
591
+
592
+
593
+ def _coordinate_member(value) -> bool:
594
+ return (isinstance(value, dict) and set(value) == {"segment", "offset"}
595
+ and isinstance(value.get("segment"), str) and value["segment"]
596
+ and _nonneg_int(value.get("offset")))
597
+
598
+
599
+ def revision3_boundary_from_op(op_record: dict) -> Revision3Boundary:
600
+ """Decode the revision-3 boundary from an ``account_bound_revision_v3``
601
+ op. Raises ``ValueError`` on any shape failure, including a revision
602
+ other than exactly 3. Whether the op itself carries ``wpx == 3`` is the
603
+ caller's check (as `revision_boundary_from_op` leaves ``wpr``)."""
604
+ if not isinstance(op_record, dict) or op_record.get("t") != "op":
605
+ raise ValueError("revision-3 boundary must come from an op record")
606
+ payload = op_record.get("payload")
607
+ if (not isinstance(payload, dict)
608
+ or payload.get("kind") != REVISION3_OP_KIND):
609
+ raise ValueError("record is not an account_bound_revision_v3 op")
610
+ if type(payload.get("revision")) is not int or (
611
+ payload["revision"] != SUCCESSOR_REVISION):
612
+ raise ValueError("revision-3 boundary revision is invalid")
613
+ revision2 = payload.get("revision2")
614
+ if not _coordinate_member(revision2):
615
+ raise ValueError("revision-3 boundary revision-2 coordinate is invalid")
616
+ base = revision_boundary_from_op({
617
+ "t": "op",
618
+ "payload": {**{k: v for k, v in payload.items()
619
+ if k != "revision2"},
620
+ "kind": REVISION_OP_KIND,
621
+ "revision": PROTOCOL_REVISION},
622
+ })
623
+ return Revision3Boundary(
624
+ segment=base.segment,
625
+ end_offset=base.end_offset,
626
+ frozen_extents=base.frozen_extents,
627
+ legacy_spool_baseline_digest=base.legacy_spool_baseline_digest,
628
+ cutover_segment=base.cutover_segment,
629
+ cutover_offset=base.cutover_offset,
630
+ revision2_segment=revision2["segment"],
631
+ revision2_offset=revision2["offset"],
632
+ legacy_spool_inventory_failure=base.legacy_spool_inventory_failure,
633
+ continued_inventory_episode=base.continued_inventory_episode,
634
+ )
635
+
636
+
442
637
  # --------------------------------------------------------------------------
443
638
  # admission
444
639
  # --------------------------------------------------------------------------
@@ -498,6 +693,7 @@ def record_family(record: dict) -> str:
498
693
  def classify_admission(record: dict, coord: Coordinate,
499
694
  boundary: CutoverBoundary | None,
500
695
  revision_boundary: "RevisionBoundary | None" = None,
696
+ revision3_boundary: "Revision3Boundary | None" = None,
501
697
  ) -> Admission:
502
698
  """The single admission predicate (spec 5.3; #797/#823/#840 spec 4.6 B3).
503
699
 
@@ -511,7 +707,12 @@ def classify_admission(record: dict, coord: Coordinate,
511
707
  a record the original rule admitted only by its writer generation unless
512
708
  it also carries ``wpr == 2`` (``revision-unstamped``). The revision never
513
709
  re-admits what the original rule excludes, and the Codex-only exemptions
514
- are unchanged."""
710
+ are unchanged.
711
+
712
+ Composed with revision 3 (#1019/#1014 spec 4.7 C3): ``revision3_boundary``
713
+ (default: ``boundary.revision3``) excludes, after its own frozen extents,
714
+ a record the earlier rules admitted only by its stamps unless it also
715
+ carries ``wpx == 3`` (``revision-3-unstamped``)."""
515
716
  family, codex_only = _family(record)
516
717
  if boundary is None:
517
718
  return Admission(True, family, "no-cutover")
@@ -520,12 +721,19 @@ def classify_admission(record: dict, coord: Coordinate,
520
721
  if is_stamped(record):
521
722
  revision = (revision_boundary if revision_boundary is not None
522
723
  else boundary.revision)
523
- if (revision is None or is_historical(coord, revision)
724
+ if not (revision is None or is_historical(coord, revision)
524
725
  or has_current_revision(record)):
726
+ if codex_only:
727
+ return Admission(True, family, "codex-only")
728
+ return Admission(False, family, "revision-unstamped")
729
+ revision3 = (revision3_boundary if revision3_boundary is not None
730
+ else boundary.revision3)
731
+ if (revision3 is None or is_historical(coord, revision3)
732
+ or has_successor_revision(record)):
525
733
  return Admission(True, family, "stamped")
526
734
  if codex_only:
527
735
  return Admission(True, family, "codex-only")
528
- return Admission(False, family, "revision-unstamped")
736
+ return Admission(False, family, "revision-3-unstamped")
529
737
  if codex_only:
530
738
  return Admission(True, family, "codex-only")
531
739
  return Admission(False, family, "excluded")