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.
- fivefold/__init__.py +4 -0
- fivefold/_data/db/bootstrap.sql +26 -0
- fivefold/_data/db/migrations/0001_schemas.sql +67 -0
- fivefold/_data/db/migrations/0002_gateway.sql +224 -0
- fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
- fivefold/_data/db/migrations/0004_harness.sql +141 -0
- fivefold/_data/db/migrations/0005_sim.sql +679 -0
- fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
- fivefold/_data/db/migrations/0007_eval.sql +33 -0
- fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
- fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
- fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
- fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
- fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
- fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
- fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
- fivefold/_data/db/registry/0001_registry.sql +31 -0
- fivefold/_data/faults/expected.yaml +406 -0
- fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
- fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
- fivefold/agents/__init__.py +7 -0
- fivefold/agents/branch.py +187 -0
- fivefold/agents/checkpoint.py +77 -0
- fivefold/agents/connection.py +153 -0
- fivefold/agents/live.py +492 -0
- fivefold/agents/policy.py +426 -0
- fivefold/agents/remote.py +333 -0
- fivefold/agents/replay.py +170 -0
- fivefold/agents/scripted.py +122 -0
- fivefold/agents/tools.py +229 -0
- fivefold/agents/worker.py +164 -0
- fivefold/domain/__init__.py +5 -0
- fivefold/domain/api.py +517 -0
- fivefold/domain/authority.py +149 -0
- fivefold/domain/contracts.py +80 -0
- fivefold/domain/identity.py +113 -0
- fivefold/domain/prices.py +178 -0
- fivefold/domain/report.py +92 -0
- fivefold/domain/rules.py +346 -0
- fivefold/domain/scenario.py +524 -0
- fivefold/evaluator/__init__.py +155 -0
- fivefold/evaluator/__main__.py +127 -0
- fivefold/evaluator/authorization.py +146 -0
- fivefold/evaluator/checks.py +331 -0
- fivefold/evaluator/evaluate.py +109 -0
- fivefold/evaluator/evidence.py +392 -0
- fivefold/evaluator/freshness.py +136 -0
- fivefold/evaluator/liveness.py +236 -0
- fivefold/evaluator/load.py +354 -0
- fivefold/evaluator/metrics.py +95 -0
- fivefold/evaluator/records.py +452 -0
- fivefold/evaluator/recovery.py +209 -0
- fivefold/evaluator/report.py +1096 -0
- fivefold/evaluator/result.py +344 -0
- fivefold/evaluator/store.py +83 -0
- fivefold/faults/__init__.py +5 -0
- fivefold/faults/catalog.py +278 -0
- fivefold/faults/plan.py +538 -0
- fivefold/gateway/__init__.py +6 -0
- fivefold/gateway/admin.py +179 -0
- fivefold/gateway/admin_api.py +398 -0
- fivefold/gateway/codec.py +372 -0
- fivefold/gateway/destination.py +64 -0
- fivefold/gateway/dispatcher.py +379 -0
- fivefold/gateway/freshness.py +83 -0
- fivefold/gateway/invariants.py +761 -0
- fivefold/gateway/memory.py +277 -0
- fivefold/gateway/pg_store.py +657 -0
- fivefold/gateway/records.py +592 -0
- fivefold/gateway/server.py +102 -0
- fivefold/gateway/sim_client.py +295 -0
- fivefold/gateway/state_machine.py +376 -0
- fivefold/gateway/steps.py +897 -0
- fivefold/gateway/store.py +635 -0
- fivefold/gateway/tools.py +424 -0
- fivefold/gateway/twin.py +199 -0
- fivefold/gateway/wire.py +138 -0
- fivefold/harness/__init__.py +6 -0
- fivefold/harness/actors.py +230 -0
- fivefold/harness/cells.py +303 -0
- fivefold/harness/clock.py +209 -0
- fivefold/harness/demo.py +397 -0
- fivefold/harness/fault_effects.py +122 -0
- fivefold/harness/live_options.py +159 -0
- fivefold/harness/log.py +540 -0
- fivefold/harness/mcp_link.py +409 -0
- fivefold/harness/migrations.py +520 -0
- fivefold/harness/models.py +368 -0
- fivefold/harness/registry.py +105 -0
- fivefold/harness/reports.py +100 -0
- fivefold/harness/rng.py +57 -0
- fivefold/harness/run.py +881 -0
- fivefold/harness/scheduler.py +441 -0
- fivefold/harness/sim_points.py +215 -0
- fivefold/harness/split/__init__.py +34 -0
- fivefold/harness/split/__main__.py +275 -0
- fivefold/harness/split/credentials.py +74 -0
- fivefold/harness/split/faults.py +75 -0
- fivefold/harness/split/gateway.py +769 -0
- fivefold/harness/split/hops.py +291 -0
- fivefold/harness/split/lifecycle.py +322 -0
- fivefold/harness/split/rundir.py +152 -0
- fivefold/harness/split/service.py +157 -0
- fivefold/harness/split/simulator.py +432 -0
- fivefold/harness/study.py +643 -0
- fivefold/harness/transport.py +533 -0
- fivefold/paths.py +24 -0
- fivefold/py.typed +0 -0
- fivefold/recorder/__init__.py +18 -0
- fivefold/recorder/__main__.py +308 -0
- fivefold/recorder/cassette.py +322 -0
- fivefold/recorder/playback.py +316 -0
- fivefold/recorder/recording.py +133 -0
- fivefold/sim/__init__.py +37 -0
- fivefold/sim/config.py +52 -0
- fivefold/sim/endpoint.py +176 -0
- fivefold/sim/ledger.py +583 -0
- fivefold/sim/service.py +834 -0
- fivefold/viewer/__init__.py +14 -0
- fivefold/viewer/__main__.py +75 -0
- fivefold/viewer/app.py +122 -0
- fivefold/viewer/records.py +108 -0
- fivefold/viewer/source.py +196 -0
- fivefold/viewer/timeline.py +61 -0
- fivefold-0.1.0.dist-info/METADATA +169 -0
- fivefold-0.1.0.dist-info/RECORD +128 -0
- fivefold-0.1.0.dist-info/WHEEL +4 -0
- 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)
|