fivefold 0.1.0__py3-none-any.whl

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 (128) hide show
  1. fivefold/__init__.py +4 -0
  2. fivefold/_data/db/bootstrap.sql +26 -0
  3. fivefold/_data/db/migrations/0001_schemas.sql +67 -0
  4. fivefold/_data/db/migrations/0002_gateway.sql +224 -0
  5. fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
  6. fivefold/_data/db/migrations/0004_harness.sql +141 -0
  7. fivefold/_data/db/migrations/0005_sim.sql +679 -0
  8. fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
  9. fivefold/_data/db/migrations/0007_eval.sql +33 -0
  10. fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
  11. fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
  12. fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
  13. fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
  14. fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
  15. fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
  16. fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
  17. fivefold/_data/db/registry/0001_registry.sql +31 -0
  18. fivefold/_data/faults/expected.yaml +406 -0
  19. fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
  20. fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
  21. fivefold/agents/__init__.py +7 -0
  22. fivefold/agents/branch.py +187 -0
  23. fivefold/agents/checkpoint.py +77 -0
  24. fivefold/agents/connection.py +153 -0
  25. fivefold/agents/live.py +492 -0
  26. fivefold/agents/policy.py +426 -0
  27. fivefold/agents/remote.py +333 -0
  28. fivefold/agents/replay.py +170 -0
  29. fivefold/agents/scripted.py +122 -0
  30. fivefold/agents/tools.py +229 -0
  31. fivefold/agents/worker.py +164 -0
  32. fivefold/domain/__init__.py +5 -0
  33. fivefold/domain/api.py +517 -0
  34. fivefold/domain/authority.py +149 -0
  35. fivefold/domain/contracts.py +80 -0
  36. fivefold/domain/identity.py +113 -0
  37. fivefold/domain/prices.py +178 -0
  38. fivefold/domain/report.py +92 -0
  39. fivefold/domain/rules.py +346 -0
  40. fivefold/domain/scenario.py +524 -0
  41. fivefold/evaluator/__init__.py +155 -0
  42. fivefold/evaluator/__main__.py +127 -0
  43. fivefold/evaluator/authorization.py +146 -0
  44. fivefold/evaluator/checks.py +331 -0
  45. fivefold/evaluator/evaluate.py +109 -0
  46. fivefold/evaluator/evidence.py +392 -0
  47. fivefold/evaluator/freshness.py +136 -0
  48. fivefold/evaluator/liveness.py +236 -0
  49. fivefold/evaluator/load.py +354 -0
  50. fivefold/evaluator/metrics.py +95 -0
  51. fivefold/evaluator/records.py +452 -0
  52. fivefold/evaluator/recovery.py +209 -0
  53. fivefold/evaluator/report.py +1096 -0
  54. fivefold/evaluator/result.py +344 -0
  55. fivefold/evaluator/store.py +83 -0
  56. fivefold/faults/__init__.py +5 -0
  57. fivefold/faults/catalog.py +278 -0
  58. fivefold/faults/plan.py +538 -0
  59. fivefold/gateway/__init__.py +6 -0
  60. fivefold/gateway/admin.py +179 -0
  61. fivefold/gateway/admin_api.py +398 -0
  62. fivefold/gateway/codec.py +372 -0
  63. fivefold/gateway/destination.py +64 -0
  64. fivefold/gateway/dispatcher.py +379 -0
  65. fivefold/gateway/freshness.py +83 -0
  66. fivefold/gateway/invariants.py +761 -0
  67. fivefold/gateway/memory.py +277 -0
  68. fivefold/gateway/pg_store.py +657 -0
  69. fivefold/gateway/records.py +592 -0
  70. fivefold/gateway/server.py +102 -0
  71. fivefold/gateway/sim_client.py +295 -0
  72. fivefold/gateway/state_machine.py +376 -0
  73. fivefold/gateway/steps.py +897 -0
  74. fivefold/gateway/store.py +635 -0
  75. fivefold/gateway/tools.py +424 -0
  76. fivefold/gateway/twin.py +199 -0
  77. fivefold/gateway/wire.py +138 -0
  78. fivefold/harness/__init__.py +6 -0
  79. fivefold/harness/actors.py +230 -0
  80. fivefold/harness/cells.py +303 -0
  81. fivefold/harness/clock.py +209 -0
  82. fivefold/harness/demo.py +397 -0
  83. fivefold/harness/fault_effects.py +122 -0
  84. fivefold/harness/live_options.py +159 -0
  85. fivefold/harness/log.py +540 -0
  86. fivefold/harness/mcp_link.py +409 -0
  87. fivefold/harness/migrations.py +520 -0
  88. fivefold/harness/models.py +368 -0
  89. fivefold/harness/registry.py +105 -0
  90. fivefold/harness/reports.py +100 -0
  91. fivefold/harness/rng.py +57 -0
  92. fivefold/harness/run.py +881 -0
  93. fivefold/harness/scheduler.py +441 -0
  94. fivefold/harness/sim_points.py +215 -0
  95. fivefold/harness/split/__init__.py +34 -0
  96. fivefold/harness/split/__main__.py +275 -0
  97. fivefold/harness/split/credentials.py +74 -0
  98. fivefold/harness/split/faults.py +75 -0
  99. fivefold/harness/split/gateway.py +769 -0
  100. fivefold/harness/split/hops.py +291 -0
  101. fivefold/harness/split/lifecycle.py +322 -0
  102. fivefold/harness/split/rundir.py +152 -0
  103. fivefold/harness/split/service.py +157 -0
  104. fivefold/harness/split/simulator.py +432 -0
  105. fivefold/harness/study.py +643 -0
  106. fivefold/harness/transport.py +533 -0
  107. fivefold/paths.py +24 -0
  108. fivefold/py.typed +0 -0
  109. fivefold/recorder/__init__.py +18 -0
  110. fivefold/recorder/__main__.py +308 -0
  111. fivefold/recorder/cassette.py +322 -0
  112. fivefold/recorder/playback.py +316 -0
  113. fivefold/recorder/recording.py +133 -0
  114. fivefold/sim/__init__.py +37 -0
  115. fivefold/sim/config.py +52 -0
  116. fivefold/sim/endpoint.py +176 -0
  117. fivefold/sim/ledger.py +583 -0
  118. fivefold/sim/service.py +834 -0
  119. fivefold/viewer/__init__.py +14 -0
  120. fivefold/viewer/__main__.py +75 -0
  121. fivefold/viewer/app.py +122 -0
  122. fivefold/viewer/records.py +108 -0
  123. fivefold/viewer/source.py +196 -0
  124. fivefold/viewer/timeline.py +61 -0
  125. fivefold-0.1.0.dist-info/METADATA +169 -0
  126. fivefold-0.1.0.dist-info/RECORD +128 -0
  127. fivefold-0.1.0.dist-info/WHEEL +4 -0
  128. fivefold-0.1.0.dist-info/licenses/LICENSE +202 -0
@@ -0,0 +1,897 @@
1
+ """The gateway's decisions, one pure function per step (0001, 0002, 0003, 0005).
2
+
3
+ Each step reads an `ActionView` of one action's records plus its own inputs, and returns
4
+ the `Change` to apply, or None when there is nothing to do. Steps never mutate anything
5
+ and never do I/O, and every state change goes through `check_transition`. A store
6
+ applies a change in one transaction, with its events, while holding the action's row
7
+ lock (I6). Both stores, in memory and in PostgreSQL, call these functions through the
8
+ operations in `store.py`, so each rule exists once.
9
+
10
+ Steps raise `StepRefused` when a step does not apply (wrong state, too early, already
11
+ escalated). Malformed inputs raise `ValueError`. In both cases nothing changes.
12
+
13
+ G1's actions, those with identity off, follow the same table with fewer steps (0008). No
14
+ basis is checked: the approval request is filed at once (T2), and an approval moves the
15
+ action to Authorized (T4). The check before the one send covers the approval only, with
16
+ its own check kind. G1 never retries, probes or escalates, so an action that enters
17
+ OutcomeUnknown stays there, and the agent is told nothing about reconciling it.
18
+
19
+ Ids that depend on one action are derived from its id: grant `G-0007` and escalation
20
+ `ESC-0007` belong to action `A-0007`, and its attempts are `A-0007/1`, `A-0007/2` and so
21
+ on. One grant and at most one escalation per action follow from the rules (I2; an
22
+ escalated action leaves OutcomeUnknown only by attestation).
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ from collections.abc import Collection, Mapping, Sequence
28
+ from dataclasses import dataclass, replace
29
+ from enum import StrEnum
30
+
31
+ from fivefold.domain.contracts import Capability, Contract
32
+ from fivefold.gateway.records import (
33
+ NO_DETAILS,
34
+ Action,
35
+ ActionEvent,
36
+ ActionResult,
37
+ Answer,
38
+ ApprovalStatus,
39
+ Attempt,
40
+ BasisCheck,
41
+ CheckRecord,
42
+ CheckTicket,
43
+ Claim,
44
+ ClaimConflict,
45
+ ClaimStatus,
46
+ Escalation,
47
+ Grant,
48
+ ProbeAnswer,
49
+ Proposal,
50
+ ReadRecord,
51
+ Reconcile,
52
+ RecordedAction,
53
+ Refusal,
54
+ RefusalReason,
55
+ Resolution,
56
+ StaleFact,
57
+ WriteCall,
58
+ frozen,
59
+ )
60
+ from fivefold.gateway.state_machine import (
61
+ HOLDING_STATES,
62
+ UNDISPATCHED_STATES,
63
+ UNSETTLED_STATES,
64
+ ActionState,
65
+ AnswerClass,
66
+ CheckKind,
67
+ EscalationTrigger,
68
+ EventKind,
69
+ GatewayRuleError,
70
+ GatewaySettings,
71
+ GrantState,
72
+ Note,
73
+ Reason,
74
+ check_grant_transition,
75
+ check_transition,
76
+ reconcile_how,
77
+ required_check,
78
+ )
79
+
80
+ _S = ActionState
81
+
82
+
83
+ class StepRefused(GatewayRuleError):
84
+ """The step does not apply to the action in its current state, or not yet."""
85
+
86
+
87
+ @dataclass(frozen=True)
88
+ class ActionView:
89
+ """One action's records, as a step reads them. `events` are in seq order."""
90
+
91
+ action: Action
92
+ grant: Grant | None
93
+ attempts: tuple[Attempt, ...]
94
+ escalation: Escalation | None
95
+ events: tuple[ActionEvent, ...]
96
+
97
+ @property
98
+ def last_seq(self) -> int:
99
+ """The seq of the action's latest event."""
100
+ return self.events[-1].seq
101
+
102
+
103
+ @dataclass(frozen=True)
104
+ class NewEvent:
105
+ """An event a step asks the store to append. The store assigns its seq and vt."""
106
+
107
+ kind: EventKind
108
+ from_state: ActionState | None
109
+ to_state: ActionState
110
+ reason: Reason | Note
111
+ details: Mapping[str, object] = NO_DETAILS
112
+
113
+
114
+ @dataclass(frozen=True)
115
+ class Change:
116
+ """Records to write in one transaction: the action, its events, and any other record."""
117
+
118
+ action: Action
119
+ events: tuple[NewEvent, ...]
120
+ grant: Grant | None = None
121
+ attempt: Attempt | None = None
122
+ escalation: Escalation | None = None
123
+
124
+
125
+ class Match(StrEnum):
126
+ """The outcome of the matching rule (0001, item 10)."""
127
+
128
+ CREATE = "create"
129
+ ATTACH = "attach"
130
+ BUSY = "busy"
131
+ DONE = "done"
132
+
133
+
134
+ # Ids -----------------------------------------------------------------------------------
135
+
136
+
137
+ def action_number(action_id: str) -> int:
138
+ """Return the counter of an action id such as `A-0007`."""
139
+ prefix, _, number = action_id.partition("-")
140
+ if prefix != "A" or not number.isdigit():
141
+ raise ValueError(f"not an action id: {action_id!r}")
142
+ return int(number)
143
+
144
+
145
+ def action_id_for(number: int) -> str:
146
+ """Return the action id for the run's `number`-th action."""
147
+ return f"A-{number:04d}"
148
+
149
+
150
+ def grant_id_for(action_id: str) -> str:
151
+ """Return the id of the action's grant."""
152
+ return f"G-{action_number(action_id):04d}"
153
+
154
+
155
+ def escalation_id_for(action_id: str) -> str:
156
+ """Return the id of the action's escalation."""
157
+ return f"ESC-{action_number(action_id):04d}"
158
+
159
+
160
+ def attempt_id_for(action_id: str, attempt_no: int) -> str:
161
+ """Return the id of the action's attempt `attempt_no`."""
162
+ return f"{action_id}/{attempt_no}"
163
+
164
+
165
+ # Helpers -------------------------------------------------------------------------------
166
+
167
+
168
+ def _require(condition: bool, message: str) -> None:
169
+ if not condition:
170
+ raise StepRefused(message)
171
+
172
+
173
+ def _move(
174
+ view: ActionView,
175
+ target: ActionState,
176
+ reason: Reason,
177
+ vt: int,
178
+ details: Mapping[str, object] = NO_DETAILS,
179
+ ) -> tuple[Action, NewEvent]:
180
+ action = view.action
181
+ check_transition(action.state, target, reason, action.contract)
182
+ event = NewEvent(EventKind.TRANSITION, action.state, target, reason, frozen(details))
183
+ return replace(action, state=target, updated_vt=vt), event
184
+
185
+
186
+ def _note(action: Action, reason: Note, details: Mapping[str, object]) -> NewEvent:
187
+ return NewEvent(EventKind.NOTE, action.state, action.state, reason, frozen(details))
188
+
189
+
190
+ def _grant_to(grant: Grant, target: GrantState, *, consumed_vt: int | None = None) -> Grant:
191
+ check_grant_transition(grant.state, target)
192
+ if consumed_vt is None:
193
+ return replace(grant, state=target)
194
+ return replace(grant, state=target, consumed_vt=consumed_vt)
195
+
196
+
197
+ def _grant_in(view: ActionView, *states: GrantState) -> Grant:
198
+ grant = view.grant
199
+ if grant is None or grant.state not in states:
200
+ found = None if grant is None else grant.state
201
+ raise StepRefused(f"{view.action.action_id} needs a grant in {states}, found {found}")
202
+ return grant
203
+
204
+
205
+ def _full_basis(basis: BasisCheck) -> BasisCheck:
206
+ if basis.sufficient_ok is None:
207
+ raise ValueError("this step checks every dependency rule, the sufficient ones too")
208
+ return basis
209
+
210
+
211
+ def _no_basis_in_g1(action: Action, basis: BasisCheck | None) -> None:
212
+ """G1 checks no basis (0008), so its steps never come with a basis check."""
213
+ if action.authorization_only and basis is not None:
214
+ raise ValueError(f"{action.action_id} is G1's, which checks no basis (0008)")
215
+
216
+
217
+ def _escalate(
218
+ action: Action, trigger: EscalationTrigger, vt: int, details: Mapping[str, object]
219
+ ) -> tuple[Escalation, NewEvent]:
220
+ escalation_id = escalation_id_for(action.action_id)
221
+ escalation = Escalation(escalation_id, action.action_id, vt, None, None, None, None)
222
+ note = _note(
223
+ action, Note.ESCALATED, {"escalation_id": escalation_id, "trigger": trigger, **details}
224
+ )
225
+ return escalation, note
226
+
227
+
228
+ def _trigger_on_unknown(
229
+ action: Action, attempts_sent: int, settings: GatewaySettings
230
+ ) -> EscalationTrigger | None:
231
+ """When entering OutcomeUnknown escalates at once (0003, escalation; 0005).
232
+
233
+ G1 never escalates: it has no recovery, so its action stays OutcomeUnknown (0008).
234
+ """
235
+ if action.authorization_only:
236
+ return None
237
+ contract = action.contract
238
+ if not contract.capabilities:
239
+ return EscalationTrigger.AT_ONCE
240
+ if contract.has(Capability.IDEMPOTENCY_KEY) and attempts_sent >= settings.max_attempts:
241
+ return EscalationTrigger.MAX_ATTEMPTS
242
+ return None
243
+
244
+
245
+ def _enter_unknown(
246
+ view: ActionView,
247
+ reason: Reason,
248
+ vt: int,
249
+ settings: GatewaySettings,
250
+ attempt: Attempt | None,
251
+ ) -> Change:
252
+ attempt_no = len(view.attempts)
253
+ action, event = _move(view, _S.OUTCOME_UNKNOWN, reason, vt, {"attempt_no": attempt_no})
254
+ trigger = _trigger_on_unknown(action, attempt_no, settings)
255
+ if trigger is None:
256
+ return Change(action, (event,), attempt=attempt)
257
+ escalation, note = _escalate(action, trigger, vt, NO_DETAILS)
258
+ return Change(action, (event, note), attempt=attempt, escalation=escalation)
259
+
260
+
261
+ def _latest_sent_vt(view: ActionView) -> int:
262
+ if not view.attempts:
263
+ raise StepRefused(f"{view.action.action_id} has no attempt")
264
+ return max(attempt.sent_vt for attempt in view.attempts)
265
+
266
+
267
+ def _retry_allowed(view: ActionView, settings: GatewaySettings) -> int:
268
+ """Check the conditions for any retry (I4, 0005) and return the next attempt number."""
269
+ action = view.action
270
+ _require(action.state is _S.OUTCOME_UNKNOWN, f"{action.action_id} is {action.state}")
271
+ _require(not action.authorization_only, f"{action.action_id} is G1's; G1 never retries (0008)")
272
+ _require(
273
+ action.contract.has(Capability.IDEMPOTENCY_KEY),
274
+ f"{action.contract} allows no retries (I4)",
275
+ )
276
+ _require(view.escalation is None, f"{action.action_id} is escalated; a human resolves it")
277
+ attempt_no = len(view.attempts) + 1
278
+ _require(attempt_no <= settings.max_attempts, f"{action.action_id} used max_attempts")
279
+ _grant_in(view, GrantState.CONSUMED)
280
+ return attempt_no
281
+
282
+
283
+ # Admission and matching (0001) -------------------------------------------------------
284
+
285
+
286
+ def read_id_for(number: int) -> str:
287
+ """Return the id of the run's `number`-th read."""
288
+ return f"R-{number:04d}"
289
+
290
+
291
+ def proposal_id_for(number: int) -> str:
292
+ """Return the id of the run's `number`-th write call."""
293
+ return f"P-{number:04d}"
294
+
295
+
296
+ def resolve_basis(call: WriteCall, reads: Mapping[str, ReadRecord]) -> Proposal | Refusal:
297
+ """Resolve a write call's citations to its basis, or refuse it (0001, items 13 to 15).
298
+
299
+ `reads` holds the cited reads the gateway issued. A cited id it lacks is refused
300
+ with `unknown_read`; a dependency no citation covers, with `missing_basis`. The basis
301
+ holds each dependency at its newest cited version and nothing else.
302
+ """
303
+ unknown = tuple(dict.fromkeys(r for r in call.based_on if r not in reads))
304
+ if unknown:
305
+ return Refusal(RefusalReason.UNKNOWN_READ, unknown_reads=unknown)
306
+ newest: dict[str, int] = {}
307
+ for read_id in call.based_on:
308
+ read = reads[read_id]
309
+ newest[read.key] = max(read.version, newest.get(read.key, read.version))
310
+ missing = tuple(dict.fromkeys(k for k in call.dependencies if k not in newest))
311
+ if missing:
312
+ return Refusal(RefusalReason.MISSING_BASIS, missing_keys=missing)
313
+ basis = {key: newest[key] for key in call.dependencies}
314
+ return Proposal(call.intent_id, call.operation, call.target, call.args, call.action_key, basis)
315
+
316
+
317
+ def match_proposal(holders: Sequence[Action], proposal: Proposal) -> tuple[Match, Action | None]:
318
+ """Apply the matching rule to the intent's live or Confirmed actions (0001, item 10)."""
319
+ if len(holders) > 1:
320
+ ids = ", ".join(holder.action_id for holder in holders)
321
+ raise AssertionError(f"I7 broken: {proposal.intent_id} has live or Confirmed {ids}")
322
+ if not holders:
323
+ return Match.CREATE, None
324
+ holder = holders[0]
325
+ if holder.state not in HOLDING_STATES:
326
+ raise ValueError(f"{holder.action_id} is {holder.state}, so it holds no intent")
327
+ same = holder.action_key == proposal.action_key
328
+ if holder.state is _S.CONFIRMED:
329
+ return (Match.ATTACH if same else Match.DONE), holder
330
+ return (Match.ATTACH if same else Match.BUSY), holder
331
+
332
+
333
+ def admit(
334
+ action_id: str,
335
+ task_id: str,
336
+ proposal: Proposal,
337
+ contract: Contract,
338
+ *,
339
+ identity: bool,
340
+ vt: int,
341
+ ) -> Change:
342
+ """T1: create an action from an admitted proposal (0001, 0003)."""
343
+ check_transition(None, _S.PROPOSED, Reason.ADMITTED, contract)
344
+ action = Action(
345
+ action_id=action_id,
346
+ task_id=task_id,
347
+ intent_id=proposal.intent_id,
348
+ operation=proposal.operation,
349
+ target=proposal.target,
350
+ args=frozen(proposal.args),
351
+ action_key=proposal.action_key,
352
+ identity=identity,
353
+ contract=contract,
354
+ basis=frozen(proposal.basis),
355
+ state=_S.PROPOSED,
356
+ grant_id=None,
357
+ idempotency_key=action_id,
358
+ effect_id=None,
359
+ created_vt=vt,
360
+ updated_vt=vt,
361
+ )
362
+ event = NewEvent(EventKind.TRANSITION, None, _S.PROPOSED, Reason.ADMITTED)
363
+ return Change(action, (event,))
364
+
365
+
366
+ def attach(view: ActionView, proposal: Proposal) -> Change | None:
367
+ """Take a newer basis from an attaching proposal, before the first send (0001, item 16).
368
+
369
+ The basis is replaced only if every cited version is at least as new as the one held.
370
+ After the first dispatch the basis is frozen. The note makes any dispatch check that
371
+ began against the old basis stale (I3).
372
+ """
373
+ action = view.action
374
+ if action.action_key != proposal.action_key:
375
+ raise ValueError("only a proposal with the same action key attaches")
376
+ if action.state not in UNDISPATCHED_STATES:
377
+ return None
378
+ held, cited = dict(action.basis), dict(proposal.basis)
379
+ if cited == held or cited.keys() != held.keys():
380
+ return None
381
+ if any(cited[key] < held[key] for key in cited):
382
+ return None
383
+ note = _note(action, Note.BASIS_UPDATED, {"from": frozen(held), "to": frozen(cited)})
384
+ return Change(replace(action, basis=frozen(cited)), (note,))
385
+
386
+
387
+ # Approval (0002) ---------------------------------------------------------------------
388
+
389
+
390
+ def file_approval(
391
+ view: ActionView,
392
+ basis: BasisCheck | None,
393
+ approval_id: str | None,
394
+ vt: int,
395
+ *,
396
+ seen_seq: int,
397
+ ) -> Change | None:
398
+ """T2 or T3: check the basis; if fresh, record the filed approval request as a grant.
399
+
400
+ The gateway files the request (keyed by the action id) only after the basis passed,
401
+ so a stale basis comes with no approval id. `seen_seq` is the seq of the action's
402
+ latest event when the gateway began its check, which reads facts over the network
403
+ and so runs without a lock. If the action has a newer event, such as a newer basis
404
+ from an attaching proposal, nothing is written (0003, dispatch).
405
+
406
+ G1 checks no basis (0008): for its actions `basis` is None, and the request is filed
407
+ at once (T2). Every other action needs a full basis check.
408
+ """
409
+ if seen_seq != view.last_seq:
410
+ return None
411
+ action = view.action
412
+ _require(action.state is _S.PROPOSED, f"{action.action_id} is {action.state}")
413
+ _require(view.grant is None, f"{action.action_id} already has a grant")
414
+ _no_basis_in_g1(action, basis)
415
+ if basis is None and not action.authorization_only:
416
+ raise ValueError("the approval request is filed only after a basis check (T2, T3)")
417
+ if basis is not None and not _full_basis(basis).fresh:
418
+ if approval_id is not None:
419
+ raise ValueError("no approval request is filed for a stale basis")
420
+ rejected, event = _move(view, _S.REJECTED, Reason.STALE_INPUT, vt, {"stale": basis.stale})
421
+ return Change(rejected, (event,))
422
+ if approval_id is None:
423
+ raise ValueError("T2 comes with the filed approval request's id")
424
+ check_grant_transition(None, GrantState.PENDING)
425
+ grant = Grant(
426
+ grant_id_for(action.action_id), action.action_id, approval_id, GrantState.PENDING, vt, None
427
+ )
428
+ pending, event = _move(
429
+ view, _S.PENDING_APPROVAL, Reason.APPROVAL_REQUESTED, vt, {"approval_id": approval_id}
430
+ )
431
+ return Change(replace(pending, grant_id=grant.grant_id), (event,), grant=grant)
432
+
433
+
434
+ def poll_approval(
435
+ view: ActionView,
436
+ approval: ApprovalStatus,
437
+ basis: BasisCheck | None,
438
+ vt: int,
439
+ *,
440
+ seen_seq: int,
441
+ ) -> Change | None:
442
+ """T4 or T5 from what the approvals service reports while the action waits (0002).
443
+
444
+ `basis` is the basis check made with this poll. It is optional while the approval is
445
+ pending and required once it is approved (T4 needs a fresh basis). Dead authority
446
+ (denied, or revoked or expired before the gateway saw it, 0010) is named before a
447
+ stale basis. Nothing is written if the action has an event newer than `seen_seq`, as
448
+ in `file_approval`.
449
+
450
+ G1 checks no basis (0008): for its actions `basis` is always None, and an approval
451
+ alone moves the action to Authorized (T4).
452
+ """
453
+ if seen_seq != view.last_seq:
454
+ return None
455
+ action = view.action
456
+ _require(action.state is _S.PENDING_APPROVAL, f"{action.action_id} is {action.state}")
457
+ grant = _grant_in(view, GrantState.PENDING)
458
+ _no_basis_in_g1(action, basis)
459
+ if basis is not None:
460
+ _full_basis(basis)
461
+ if approval is ApprovalStatus.DENIED:
462
+ rejected, event = _move(view, _S.REJECTED, Reason.APPROVAL_DENIED, vt)
463
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.DENIED))
464
+ if approval is ApprovalStatus.REVOKED:
465
+ rejected, event = _move(view, _S.REJECTED, Reason.APPROVAL_REVOKED, vt)
466
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.REVOKED))
467
+ if approval is ApprovalStatus.EXPIRED:
468
+ rejected, event = _move(view, _S.REJECTED, Reason.APPROVAL_EXPIRED, vt)
469
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.EXPIRED))
470
+ stale = {"stale": basis.stale} if basis is not None else NO_DETAILS
471
+ if approval is ApprovalStatus.PENDING:
472
+ if basis is None or basis.fresh:
473
+ return None
474
+ rejected, event = _move(view, _S.REJECTED, Reason.STALE_INPUT, vt, stale)
475
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.RELEASED))
476
+ active = _grant_to(grant, GrantState.ACTIVE)
477
+ if basis is None:
478
+ if not action.authorization_only:
479
+ raise ValueError("an approved request is acted on only with a basis check (T4)")
480
+ authorized, event = _move(view, _S.AUTHORIZED, Reason.APPROVED, vt)
481
+ return Change(authorized, (event,), grant=active)
482
+ if basis.fresh:
483
+ authorized, event = _move(view, _S.AUTHORIZED, Reason.APPROVED, vt)
484
+ return Change(authorized, (event,), grant=active)
485
+ rejected, event = _move(view, _S.REJECTED, Reason.STALE_INPUT, vt, stale)
486
+ return Change(rejected, (event,), grant=_grant_to(active, GrantState.RELEASED))
487
+
488
+
489
+ def time_out_approval(
490
+ view: ActionView,
491
+ approval: ApprovalStatus,
492
+ vt: int,
493
+ settings: GatewaySettings,
494
+ *,
495
+ seen_seq: int,
496
+ ) -> Change | None:
497
+ """T5 when no decision came within the scenario's `approval_wait_ms` (0002, rule 14).
498
+
499
+ "No decision" is checked, not assumed: `approval` is what a final poll found, and it
500
+ must still be pending. A decision that arrived first is acted on by `poll_approval`.
501
+ Nothing is written if the action has an event newer than `seen_seq`.
502
+ """
503
+ if seen_seq != view.last_seq:
504
+ return None
505
+ action = view.action
506
+ _require(action.state is _S.PENDING_APPROVAL, f"{action.action_id} is {action.state}")
507
+ grant = _grant_in(view, GrantState.PENDING)
508
+ _require(
509
+ approval is ApprovalStatus.PENDING,
510
+ f"{action.action_id}: the approval is {approval}; act on the decision instead",
511
+ )
512
+ _require(
513
+ vt >= grant.requested_vt + settings.approval_wait_ms,
514
+ f"{action.action_id}: approval_wait_ms has not passed",
515
+ )
516
+ rejected, event = _move(view, _S.REJECTED, Reason.APPROVAL_TIMEOUT, vt)
517
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.TIMED_OUT))
518
+
519
+
520
+ # Dispatch and retries (0002, 0003, 0005) ------------------------------------------------
521
+
522
+
523
+ def begin_check(view: ActionView, settings: GatewaySettings) -> CheckTicket:
524
+ """Start a dispatch check: say which check is due and from which event (0003, dispatch).
525
+
526
+ The dispatcher runs the check without a lock, then calls `dispatch` or `retry`, which
527
+ commit only if the action has no event newer than `seen_seq`. G1's one check covers
528
+ the approval only (0008).
529
+ """
530
+ action = view.action
531
+ if action.state is _S.AUTHORIZED:
532
+ _grant_in(view, GrantState.ACTIVE)
533
+ _require(not view.attempts, f"{action.action_id} is Authorized but has attempts")
534
+ kind = required_check(action.contract, 1, authorization_only=action.authorization_only)
535
+ return CheckTicket(action.action_id, 1, kind, view.last_seq, action.updated_vt)
536
+ attempt_no = _retry_allowed(view, settings)
537
+ due = _latest_sent_vt(view) + settings.backoff_ms(len(view.attempts))
538
+ kind = required_check(action.contract, attempt_no)
539
+ return CheckTicket(action.action_id, attempt_no, kind, view.last_seq, due)
540
+
541
+
542
+ def _new_attempt(view: ActionView, check: CheckRecord, vt: int) -> Attempt:
543
+ action = view.action
544
+ attempt_no = len(view.attempts) + 1
545
+ grant_id = action.grant_id
546
+ if grant_id is None:
547
+ raise StepRefused(f"{action.action_id} has no grant")
548
+ return Attempt(
549
+ attempt_id=attempt_id_for(action.action_id, attempt_no),
550
+ action_id=action.action_id,
551
+ attempt_no=attempt_no,
552
+ idempotency_key=action.idempotency_key,
553
+ grant_id=grant_id,
554
+ check=check,
555
+ sent_vt=vt,
556
+ answer_class=None,
557
+ answer_ref=None,
558
+ answered_vt=None,
559
+ )
560
+
561
+
562
+ def _expiry_details(check: CheckRecord) -> Mapping[str, object]:
563
+ """When an approved approval counts as expired, the expiry that made it so (0010)."""
564
+ if check.approval is ApprovalStatus.APPROVED and check.approval_expires_at is not None:
565
+ return {"expires_at": check.approval_expires_at}
566
+ return NO_DETAILS
567
+
568
+
569
+ def dispatch(
570
+ view: ActionView, check: CheckRecord, vt: int, settings: GatewaySettings
571
+ ) -> Change | None:
572
+ """T6 or T7: commit the first send, or reject, after a full check (I3; 0002, rule 17-18).
573
+
574
+ The send is at `vt`, so an approval that expires by `vt + S` counts as expired
575
+ (0010, change 4). Returns None, committing nothing, if the action has a newer event
576
+ than the check saw. G1's check covers the approval only (0008), so G1 rejects only
577
+ for dead authority.
578
+ """
579
+ if check.seen_seq != view.last_seq:
580
+ return None
581
+ action = view.action
582
+ _require(action.state is _S.AUTHORIZED, f"{action.action_id} is {action.state}")
583
+ needed = required_check(action.contract, 1, authorization_only=action.authorization_only)
584
+ _require(check.kind is needed, f"the first send needs the {needed} check (I3)")
585
+ _require(check.check_vt <= vt, "the check must come before the send")
586
+ grant = _grant_in(view, GrantState.ACTIVE)
587
+ approval = check.approval_at_send(vt, settings.settle_ms)
588
+ if approval is ApprovalStatus.REVOKED:
589
+ rejected, event = _move(view, _S.REJECTED, Reason.APPROVAL_REVOKED, vt)
590
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.REVOKED))
591
+ if approval is ApprovalStatus.EXPIRED:
592
+ details = _expiry_details(check)
593
+ rejected, event = _move(view, _S.REJECTED, Reason.APPROVAL_EXPIRED, vt, details)
594
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.EXPIRED))
595
+ if approval is not ApprovalStatus.APPROVED:
596
+ raise ValueError(f"an active grant's approval cannot be {check.approval}")
597
+ if not check.passes(vt, settings.settle_ms):
598
+ stale = {"stale": check.basis.stale if check.basis is not None else ()}
599
+ rejected, event = _move(view, _S.REJECTED, Reason.STALE_INPUT, vt, stale)
600
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.RELEASED))
601
+ sent, event = _move(view, _S.DISPATCHED, Reason.DISPATCHED, vt, {"attempt_no": 1})
602
+ consumed = _grant_to(grant, GrantState.CONSUMED, consumed_vt=vt)
603
+ return Change(sent, (event,), grant=consumed, attempt=_new_attempt(view, check, vt))
604
+
605
+
606
+ def retry(
607
+ view: ActionView, check: CheckRecord, vt: int, settings: GatewaySettings
608
+ ) -> Change | None:
609
+ """T13 with the same idempotency key, or escalation if the retry check fails (0005).
610
+
611
+ At C2 the retry check covers authority and the exact rules; if it fails, nothing is
612
+ sent and the action is escalated (0002, rule 19). An approval that expires by
613
+ `vt + S` counts as expired (0010, change 4). C3 retries are exempt (rule 20).
614
+ Returns None, committing nothing, if the action has a newer event than the check saw.
615
+ """
616
+ if check.seen_seq != view.last_seq:
617
+ return None
618
+ action = view.action
619
+ attempt_no = _retry_allowed(view, settings)
620
+ _require(
621
+ check.kind is required_check(action.contract, attempt_no),
622
+ f"attempt {attempt_no} at {action.contract} needs a different check (I3)",
623
+ )
624
+ due = _latest_sent_vt(view) + settings.backoff_ms(len(view.attempts))
625
+ _require(vt >= due, f"{action.action_id}: the retry backoff has not passed")
626
+ _require(check.check_vt <= vt, "the check must come before the send")
627
+ grant = _grant_in(view, GrantState.CONSUMED)
628
+ if check.kind is CheckKind.EXACT_ONLY and not check.passes(vt, settings.settle_ms):
629
+ approval = check.approval_at_send(vt, settings.settle_ms)
630
+ observed: Grant | None = None
631
+ if approval is ApprovalStatus.REVOKED:
632
+ observed = _grant_to(grant, GrantState.REVOKED)
633
+ elif approval is ApprovalStatus.EXPIRED:
634
+ observed = _grant_to(grant, GrantState.EXPIRED)
635
+ elif approval is not ApprovalStatus.APPROVED:
636
+ raise ValueError(f"a consumed grant's approval cannot be {check.approval}")
637
+ stale = check.basis.stale if check.basis is not None else ()
638
+ escalation, note = _escalate(
639
+ action,
640
+ EscalationTrigger.RETRY_CHECK_FAILED,
641
+ vt,
642
+ {"approval": check.approval, "stale": stale, **_expiry_details(check)},
643
+ )
644
+ return Change(action, (note,), grant=observed, escalation=escalation)
645
+ sent, event = _move(view, _S.DISPATCHED, Reason.RETRY, vt, {"attempt_no": attempt_no})
646
+ return Change(sent, (event,), attempt=_new_attempt(view, check, vt))
647
+
648
+
649
+ def answer(
650
+ view: ActionView, attempt_no: int, result: Answer, vt: int, settings: GatewaySettings
651
+ ) -> Change:
652
+ """T8, T9 or T10 from the destination's answer to the open attempt (0003).
653
+
654
+ The transport drops answers to timed-out requests (0006), so answers arrive only for
655
+ the latest attempt while the action is Dispatched. A timeout is the gateway's own
656
+ answer, due `dispatch_timeout_ms` after the send.
657
+ """
658
+ action = view.action
659
+ _require(action.state is _S.DISPATCHED, f"{action.action_id} is {action.state}")
660
+ attempt = view.attempts[-1]
661
+ _require(attempt_no == attempt.attempt_no, "answers arrive only for the latest attempt")
662
+ _require(attempt.answer_class is None, f"attempt {attempt_no} already has an answer")
663
+ if result.reason is Reason.TIMEOUT:
664
+ _require(
665
+ vt >= attempt.sent_vt + settings.dispatch_timeout_ms,
666
+ "a timeout comes dispatch_timeout_ms after the send",
667
+ )
668
+ answered = replace(
669
+ attempt, answer_class=result.answer_class, answer_ref=result.effect_id, answered_vt=vt
670
+ )
671
+ if result.answer_class is AnswerClass.COMMITTED:
672
+ effect_id = result.effect_id
673
+ details = {"attempt_no": attempt_no, "effect_id": effect_id}
674
+ confirmed, event = _move(view, _S.CONFIRMED, Reason.COMMITTED, vt, details)
675
+ return Change(replace(confirmed, effect_id=effect_id), (event,), attempt=answered)
676
+ if result.answer_class is AnswerClass.REJECTED:
677
+ failed, event = _move(view, _S.FAILED, result.reason, vt, {"attempt_no": attempt_no})
678
+ return Change(failed, (event,), attempt=answered)
679
+ return _enter_unknown(view, result.reason, vt, settings, answered)
680
+
681
+
682
+ def recover(view: ActionView, vt: int, settings: GatewaySettings) -> Change | None:
683
+ """Startup recovery, step 1: an open attempt moves to OutcomeUnknown (0003).
684
+
685
+ Other states need no change: OutcomeUnknown resumes its recovery, Authorized
686
+ actions return to the outbox, PendingApproval resumes polling, Proposed resumes its
687
+ basis check. The open attempt keeps no answer, because none arrived.
688
+ """
689
+ if view.action.state is not _S.DISPATCHED:
690
+ return None
691
+ if view.attempts[-1].answer_class is not None:
692
+ raise AssertionError(f"{view.action.action_id} is Dispatched with an answered attempt")
693
+ return _enter_unknown(view, Reason.RECOVERED_OPEN_ATTEMPT, vt, settings, None)
694
+
695
+
696
+ # Settling an unknown outcome (0003, 0004, 0005) --------------------------------------
697
+
698
+
699
+ def probe(view: ActionView, result: ProbeAnswer, vt: int, settings: GatewaySettings) -> Change:
700
+ """T11, T12 or a probe note from a C1 status query (0005).
701
+
702
+ A listed effect confirms the action. An empty answer fails it only when the answer is
703
+ accurate to at least S after the send (`as_of_vt >= sent_vt + S`), the same rule the
704
+ evaluator uses (0004). Otherwise the probe is noted, and the `max_probes`-th note
705
+ escalates.
706
+ """
707
+ action = view.action
708
+ _require(action.state is _S.OUTCOME_UNKNOWN, f"{action.action_id} is {action.state}")
709
+ _require(not action.authorization_only, f"{action.action_id} is G1's; G1 never probes (0008)")
710
+ _require(action.contract.has(Capability.STATUS), f"{action.contract} has no status lookup")
711
+ _require(view.escalation is None, f"{action.action_id} is escalated; a human resolves it")
712
+ if result.as_of_vt is not None and result.as_of_vt > vt:
713
+ raise ValueError("a status answer cannot be accurate to a later time than now")
714
+ sent_vt = _latest_sent_vt(view)
715
+ if result.effect_ids:
716
+ effect_id = result.effect_ids[0]
717
+ details = {"effect_id": effect_id, "listed": result.effect_ids, "as_of_vt": result.as_of_vt}
718
+ confirmed, event = _move(view, _S.CONFIRMED, Reason.STATUS_FOUND, vt, details)
719
+ return Change(replace(confirmed, effect_id=effect_id), (event,))
720
+ if result.as_of_vt is not None and result.as_of_vt >= sent_vt + settings.settle_ms:
721
+ details = {"as_of_vt": result.as_of_vt}
722
+ failed, event = _move(view, _S.FAILED, Reason.STATUS_SETTLED_EMPTY, vt, details)
723
+ return Change(failed, (event,))
724
+ probe_no = 1 + sum(1 for event in view.events if event.reason is Note.PROBE)
725
+ note = _note(
726
+ action,
727
+ Note.PROBE,
728
+ {"probe_no": probe_no, "answered": result.answered, "as_of_vt": result.as_of_vt},
729
+ )
730
+ if probe_no < settings.max_probes:
731
+ return Change(action, (note,))
732
+ escalation, escalated = _escalate(action, EscalationTrigger.MAX_PROBES, vt, NO_DETAILS)
733
+ return Change(action, (note, escalated), escalation=escalation)
734
+
735
+
736
+ def attest(
737
+ view: ActionView,
738
+ resolution: Resolution,
739
+ effect_id: str | None,
740
+ actor: str,
741
+ vt: int,
742
+ settings: GatewaySettings,
743
+ ) -> Change:
744
+ """T11 or T12 with reason human_attested, resolving the open escalation (0003).
745
+
746
+ An attestation that nothing committed is accepted only at or after S past the latest
747
+ send, because only then does it settle every attempt in the evaluator's evidence
748
+ rules (0004), which the gateway applies too.
749
+ """
750
+ action = view.action
751
+ _require(action.state is _S.OUTCOME_UNKNOWN, f"{action.action_id} is {action.state}")
752
+ escalation = view.escalation
753
+ if escalation is None or escalation.resolved_vt is not None:
754
+ raise StepRefused(f"{action.action_id} has no open escalation")
755
+ if resolution is Resolution.COMMITTED:
756
+ if effect_id is None:
757
+ raise ValueError("an attestation of a commit names the effect")
758
+ details = {"effect_id": effect_id, "actor": actor}
759
+ moved, event = _move(view, _S.CONFIRMED, Reason.HUMAN_ATTESTED, vt, details)
760
+ moved = replace(moved, effect_id=effect_id)
761
+ else:
762
+ if effect_id is not None:
763
+ raise ValueError("an attestation that nothing committed names no effect")
764
+ due = _latest_sent_vt(view) + settings.settle_ms
765
+ _require(
766
+ vt >= due,
767
+ f"{action.action_id}: nothing can be attested as not committed before vt {due},"
768
+ " S after the last send",
769
+ )
770
+ moved, event = _move(view, _S.FAILED, Reason.HUMAN_ATTESTED, vt, {"actor": actor})
771
+ resolved = replace(
772
+ escalation, resolved_vt=vt, resolution=resolution, effect_id=effect_id, actor=actor
773
+ )
774
+ return Change(moved, (event,), escalation=resolved)
775
+
776
+
777
+ # Closing the run and reporting (0003) ------------------------------------------------
778
+
779
+
780
+ def close(view: ActionView, vt: int) -> Change | None:
781
+ """Reject an action that was never dispatched when the run closes (0003)."""
782
+ action = view.action
783
+ if action.state is _S.PROPOSED:
784
+ rejected, event = _move(view, _S.REJECTED, Reason.RUN_CLOSED, vt)
785
+ return Change(rejected, (event,))
786
+ if action.state is _S.PENDING_APPROVAL:
787
+ grant = _grant_in(view, GrantState.PENDING)
788
+ rejected, event = _move(view, _S.REJECTED, Reason.RUN_CLOSED, vt)
789
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.RELEASED))
790
+ if action.state is _S.AUTHORIZED:
791
+ grant = _grant_in(view, GrantState.ACTIVE)
792
+ rejected, event = _move(view, _S.REJECTED, Reason.RUN_CLOSED, vt)
793
+ return Change(rejected, (event,), grant=_grant_to(grant, GrantState.RELEASED))
794
+ return None
795
+
796
+
797
+ def result_for(view: ActionView) -> ActionResult:
798
+ """The agent-facing result for the action as it is now (0003, what the agent is told).
799
+
800
+ `reconcile` says how an unknown outcome is being resolved. G1 resolves none (0008), so
801
+ a G1 action in OutcomeUnknown is reported without it: none of 0003's three ways would
802
+ be true.
803
+ """
804
+ action = view.action
805
+ last = next(e for e in reversed(view.events) if e.kind is EventKind.TRANSITION)
806
+ if not isinstance(last.reason, Reason):
807
+ raise AssertionError(f"transition {last.seq} has a note reason")
808
+ stale: tuple[StaleFact, ...] = ()
809
+ if action.state is _S.REJECTED and last.reason is Reason.STALE_INPUT:
810
+ found = last.details.get("stale", ())
811
+ if isinstance(found, tuple):
812
+ stale = tuple(item for item in found if isinstance(item, StaleFact))
813
+ reconcile = None
814
+ if action.state is _S.OUTCOME_UNKNOWN and not action.authorization_only:
815
+ escalation = view.escalation
816
+ escalated = escalation is not None and escalation.resolved_vt is None
817
+ reconcile = Reconcile(
818
+ action.contract,
819
+ reconcile_how(action.contract, escalated=escalated),
820
+ escalation.escalation_id if escalation is not None else None,
821
+ f"The {action.operation} for {action.intent_id} at {action.target} "
822
+ "may or may not have taken effect.",
823
+ )
824
+ effect_id = action.effect_id if action.state is _S.CONFIRMED else None
825
+ return ActionResult(
826
+ action.action_id, action.intent_id, action.state, effect_id, last.reason, stale, reconcile
827
+ )
828
+
829
+
830
+ def known_effects(view: ActionView) -> tuple[str, ...]:
831
+ """Every effect id the gateway learned for the action, in the order it learned them.
832
+
833
+ That is the effect id the action records (I1) and every other id a status answer
834
+ listed. A C1 status answer can list two when the transport delivered the request
835
+ twice (fault F4), and the evaluator counts both as known (0004, property 5).
836
+ """
837
+ found: list[str] = []
838
+ if view.action.effect_id is not None:
839
+ found.append(view.action.effect_id)
840
+ for event in view.events:
841
+ listed = event.details.get("listed", ())
842
+ if not isinstance(listed, tuple):
843
+ continue
844
+ for effect_id in listed:
845
+ if isinstance(effect_id, str) and effect_id not in found:
846
+ found.append(effect_id)
847
+ return tuple(found)
848
+
849
+
850
+ def report_closes(
851
+ claims: Sequence[Claim], reported: Collection[str], worker: str, settings: GatewaySettings
852
+ ) -> tuple[frozenset[str], bool]:
853
+ """What an accepted report from `worker` closes in its own transaction (0010, item 6).
854
+
855
+ Each intent the report claims `not_done` closes, so the claim stays true whichever
856
+ report counts (0004). The whole run closes too if this is the last report the run
857
+ expects: each of the `agent_workers` workers (0009) has now had a report accepted.
858
+ `reported` are the workers whose reports were accepted before.
859
+ """
860
+ intents = frozenset(c.intent_id for c in claims if c.status is ClaimStatus.NOT_DONE)
861
+ return intents, len({*reported, worker}) >= settings.agent_workers
862
+
863
+
864
+ def report_conflicts(
865
+ claims: Sequence[Claim],
866
+ intents: Collection[str],
867
+ views_by_intent: Mapping[str, Sequence[ActionView]],
868
+ ) -> tuple[ClaimConflict, ...]:
869
+ """Return every claim that contradicts the gateway's records (0003, final report).
870
+
871
+ `done` needs a Confirmed action and exactly the effect ids the gateway recorded for
872
+ the intent, which include every effect a status answer listed (`known_effects`).
873
+ `not_done` needs every action to be Rejected, Failed or not yet dispatched.
874
+ `unknown` needs an attempt without a settled answer: an action in Dispatched or
875
+ OutcomeUnknown.
876
+ """
877
+ claimed = [claim.intent_id for claim in claims]
878
+ if sorted(claimed) != sorted(intents):
879
+ raise ValueError("a report has exactly one claim per task intent")
880
+ conflicts: list[ClaimConflict] = []
881
+ for claim in claims:
882
+ views = views_by_intent.get(claim.intent_id, ())
883
+ states = {view.action.state for view in views}
884
+ recorded = sorted({effect for view in views for effect in known_effects(view)})
885
+ if claim.status is ClaimStatus.DONE:
886
+ ok = _S.CONFIRMED in states and sorted(claim.effect_ids) == recorded
887
+ elif claim.status is ClaimStatus.NOT_DONE:
888
+ ok = states <= (UNDISPATCHED_STATES | {_S.REJECTED, _S.FAILED})
889
+ else:
890
+ ok = bool(states & UNSETTLED_STATES)
891
+ if not ok:
892
+ record = tuple(
893
+ RecordedAction(view.action.action_id, view.action.state, known_effects(view))
894
+ for view in views
895
+ )
896
+ conflicts.append(ClaimConflict(claim.intent_id, claim.status, claim.effect_ids, record))
897
+ return tuple(conflicts)