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,295 @@
|
|
|
1
|
+
"""The gateway's calls to the simulator, on the `gw_sim` hop (0003, 0005, 0008).
|
|
2
|
+
|
|
3
|
+
`SimClient` implements `Destination` for the dispatcher and serves the read tools. It
|
|
4
|
+
sends each request through the harness transport, so every message is logged and can be
|
|
5
|
+
faulted (0006), and waits at most T, the dispatch timeout, for the answer (0005). In the
|
|
6
|
+
split topology the transport is HTTP, logged and faulted the same way
|
|
7
|
+
(`fivefold.harness.split.hops`). The
|
|
8
|
+
gateway is the only caller with a simulator credential in G modes (0008); requests name
|
|
9
|
+
it as the sender, and the simulator checks that name.
|
|
10
|
+
|
|
11
|
+
How answers map (0003):
|
|
12
|
+
|
|
13
|
+
- A write's answer: `committed` is committed; `rejected` is rejected, with reason
|
|
14
|
+
`precondition_failed` when a C3 check failed and `destination_rejected` otherwise;
|
|
15
|
+
`in_progress` is in progress; no answer within T is unknown (`timeout`), and a
|
|
16
|
+
`server_error` answer is unknown (`server_error`), because a proxy can return one
|
|
17
|
+
after the backend committed.
|
|
18
|
+
- A read, an approval call or a status call that gets no usable answer raises
|
|
19
|
+
`Unreachable`, and the caller learns nothing. A status call that times out is an
|
|
20
|
+
unanswered probe (0005).
|
|
21
|
+
- A read the simulator refuses, such as an unknown supplier, raises `ReadRefused`.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
from collections.abc import Mapping, Sequence
|
|
27
|
+
|
|
28
|
+
from pydantic import BaseModel, TypeAdapter, ValidationError
|
|
29
|
+
|
|
30
|
+
from fivefold.domain.api import (
|
|
31
|
+
ApprovalAnswer,
|
|
32
|
+
ApprovalReply,
|
|
33
|
+
FactRead,
|
|
34
|
+
GetApprovalStatus,
|
|
35
|
+
GetBudget,
|
|
36
|
+
GetInventory,
|
|
37
|
+
GetOrderStatus,
|
|
38
|
+
GetQuote,
|
|
39
|
+
GetReservationStatus,
|
|
40
|
+
ListSuppliers,
|
|
41
|
+
PurchaseOrderScope,
|
|
42
|
+
ReadReply,
|
|
43
|
+
Refusal,
|
|
44
|
+
RequestApproval,
|
|
45
|
+
ReservationScope,
|
|
46
|
+
ReserveInventory,
|
|
47
|
+
StatusAnswer,
|
|
48
|
+
StatusReply,
|
|
49
|
+
SubmitPurchaseOrder,
|
|
50
|
+
WriteCommitted,
|
|
51
|
+
WriteInProgress,
|
|
52
|
+
WriteRejected,
|
|
53
|
+
WriteRejectReason,
|
|
54
|
+
WriteReply,
|
|
55
|
+
)
|
|
56
|
+
from fivefold.domain.rules import FactKind, Operation, fact_kind
|
|
57
|
+
from fivefold.gateway.destination import ApprovalNow, FactNow, Unreachable
|
|
58
|
+
from fivefold.gateway.records import Action, Answer, ApprovalStatus, Attempt, ProbeAnswer
|
|
59
|
+
from fivefold.gateway.state_machine import AnswerClass, Reason
|
|
60
|
+
from fivefold.harness.transport import Calls, TransportTimeout
|
|
61
|
+
|
|
62
|
+
ReadRequest = GetQuote | ListSuppliers | GetBudget | GetInventory
|
|
63
|
+
|
|
64
|
+
SERVER_ERROR = "server_error"
|
|
65
|
+
"""The `answer` of a reply that reports a server error instead of an answer."""
|
|
66
|
+
|
|
67
|
+
_WRITE_ANSWER: TypeAdapter[WriteCommitted | WriteRejected | WriteInProgress] = TypeAdapter(
|
|
68
|
+
WriteReply
|
|
69
|
+
)
|
|
70
|
+
_READ_ANSWER: TypeAdapter[FactRead | Refusal] = TypeAdapter(ReadReply)
|
|
71
|
+
_APPROVAL_ANSWER: TypeAdapter[ApprovalAnswer | Refusal] = TypeAdapter(ApprovalReply)
|
|
72
|
+
_STATUS_ANSWER: TypeAdapter[StatusAnswer | Refusal] = TypeAdapter(StatusReply)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
class ReadRefused(Exception):
|
|
76
|
+
"""The simulator refused a read; the reason and detail are its own."""
|
|
77
|
+
|
|
78
|
+
def __init__(self, reason: str, detail: str) -> None:
|
|
79
|
+
super().__init__(f"{reason}: {detail}")
|
|
80
|
+
self.reason = reason
|
|
81
|
+
self.detail = detail
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class SimClient:
|
|
85
|
+
"""The simulator as the gateway reaches it."""
|
|
86
|
+
|
|
87
|
+
def __init__(
|
|
88
|
+
self,
|
|
89
|
+
transport: Calls,
|
|
90
|
+
*,
|
|
91
|
+
timeout_ms: int,
|
|
92
|
+
component: str = "gateway",
|
|
93
|
+
simulator: str = "simulator",
|
|
94
|
+
) -> None:
|
|
95
|
+
self._transport = transport
|
|
96
|
+
self._timeout_ms = timeout_ms
|
|
97
|
+
self._component = component
|
|
98
|
+
self._simulator = simulator
|
|
99
|
+
|
|
100
|
+
async def _call(
|
|
101
|
+
self,
|
|
102
|
+
request: BaseModel,
|
|
103
|
+
api: str,
|
|
104
|
+
*,
|
|
105
|
+
intent_id: str | None = None,
|
|
106
|
+
idempotency_key: str | None = None,
|
|
107
|
+
sent_vt: int | None = None,
|
|
108
|
+
) -> object:
|
|
109
|
+
"""Send one request; return its answer's body. Raises `TransportTimeout`.
|
|
110
|
+
|
|
111
|
+
`sent_vt` is the send time the gateway recorded for a write's attempt.
|
|
112
|
+
"""
|
|
113
|
+
reply = await self._transport.call(
|
|
114
|
+
hop="gw_sim",
|
|
115
|
+
sender=self._component,
|
|
116
|
+
receiver=self._simulator,
|
|
117
|
+
api=api,
|
|
118
|
+
body=request.model_dump(mode="json"),
|
|
119
|
+
timeout_ms=self._timeout_ms,
|
|
120
|
+
intent_id=intent_id,
|
|
121
|
+
idempotency_key=idempotency_key,
|
|
122
|
+
sent_vt=sent_vt,
|
|
123
|
+
)
|
|
124
|
+
return reply.body
|
|
125
|
+
|
|
126
|
+
# Reads ---------------------------------------------------------------------------------
|
|
127
|
+
|
|
128
|
+
async def read(self, request: ReadRequest) -> FactRead:
|
|
129
|
+
"""Read one fact. Raises `Unreachable` or `ReadRefused`."""
|
|
130
|
+
try:
|
|
131
|
+
body = await self._call(request, str(request.api))
|
|
132
|
+
except TransportTimeout as error:
|
|
133
|
+
raise Unreachable(str(error)) from None
|
|
134
|
+
answer = _parse(_READ_ANSWER, body)
|
|
135
|
+
if isinstance(answer, Refusal):
|
|
136
|
+
raise ReadRefused(str(answer.reason), answer.detail)
|
|
137
|
+
return answer
|
|
138
|
+
|
|
139
|
+
async def facts(self, keys: Sequence[str]) -> Mapping[str, FactNow]:
|
|
140
|
+
"""The current version and value of each fact, one read per key."""
|
|
141
|
+
found: dict[str, FactNow] = {}
|
|
142
|
+
for key in keys:
|
|
143
|
+
try:
|
|
144
|
+
fact = await self.read(read_request(key))
|
|
145
|
+
except ReadRefused as error:
|
|
146
|
+
raise Unreachable(f"{key}: {error}") from None
|
|
147
|
+
found[key] = FactNow(fact.key, fact.version, fact.data)
|
|
148
|
+
return found
|
|
149
|
+
|
|
150
|
+
# Approvals ------------------------------------------------------------------------------
|
|
151
|
+
|
|
152
|
+
async def request_approval(self, action: Action) -> ApprovalNow:
|
|
153
|
+
"""File the action's approval request, keyed by its action id (0002)."""
|
|
154
|
+
operation = Operation(action.operation)
|
|
155
|
+
request = RequestApproval(
|
|
156
|
+
intent_id=action.intent_id,
|
|
157
|
+
operation=operation,
|
|
158
|
+
scope=scope_of(operation, action.args),
|
|
159
|
+
client_request_key=action.action_id,
|
|
160
|
+
)
|
|
161
|
+
return await self._approval(request, str(request.api), action.intent_id)
|
|
162
|
+
|
|
163
|
+
async def approval(self, approval_id: str) -> ApprovalNow:
|
|
164
|
+
"""The approval's status now."""
|
|
165
|
+
request = GetApprovalStatus(approval_id=approval_id)
|
|
166
|
+
return await self._approval(request, str(request.api), None)
|
|
167
|
+
|
|
168
|
+
async def _approval(
|
|
169
|
+
self, request: RequestApproval | GetApprovalStatus, api: str, intent_id: str | None
|
|
170
|
+
) -> ApprovalNow:
|
|
171
|
+
try:
|
|
172
|
+
body = await self._call(request, api, intent_id=intent_id)
|
|
173
|
+
except TransportTimeout as error:
|
|
174
|
+
raise Unreachable(str(error)) from None
|
|
175
|
+
answer = _parse(_APPROVAL_ANSWER, body)
|
|
176
|
+
if isinstance(answer, Refusal):
|
|
177
|
+
raise Unreachable(f"{answer.reason}: {answer.detail}")
|
|
178
|
+
status = ApprovalStatus(str(answer.status))
|
|
179
|
+
expires_at = answer.expires_at if status is ApprovalStatus.APPROVED else None
|
|
180
|
+
return ApprovalNow(answer.approval_id, status, expires_at)
|
|
181
|
+
|
|
182
|
+
# Writes ---------------------------------------------------------------------------------
|
|
183
|
+
|
|
184
|
+
async def send(self, action: Action, attempt: Attempt, approval_id: str) -> Answer:
|
|
185
|
+
"""Send one attempt and classify the answer (0003).
|
|
186
|
+
|
|
187
|
+
The request carries the action's idempotency key only where the contract takes
|
|
188
|
+
keys (0005), and never in G1, which has none (0008). It carries the basis in
|
|
189
|
+
every configuration: G1 forwards the cited reads without checking them. It goes
|
|
190
|
+
out with the attempt's recorded send time, `attempt.sent_vt`, which the harness's
|
|
191
|
+
log gives the request too.
|
|
192
|
+
"""
|
|
193
|
+
operation = Operation(action.operation)
|
|
194
|
+
keyed = action.request_key is not None
|
|
195
|
+
common = {
|
|
196
|
+
"intent_id": action.intent_id,
|
|
197
|
+
"approval_id": approval_id,
|
|
198
|
+
"basis": dict(action.basis),
|
|
199
|
+
"idempotency_key": attempt.idempotency_key if keyed else None,
|
|
200
|
+
"client_ref": attempt.attempt_id,
|
|
201
|
+
**dict(action.args),
|
|
202
|
+
}
|
|
203
|
+
request: SubmitPurchaseOrder | ReserveInventory
|
|
204
|
+
if operation is Operation.SUBMIT_PURCHASE_ORDER:
|
|
205
|
+
request = SubmitPurchaseOrder.model_validate(common)
|
|
206
|
+
else:
|
|
207
|
+
request = ReserveInventory.model_validate(common)
|
|
208
|
+
try:
|
|
209
|
+
body = await self._call(
|
|
210
|
+
request,
|
|
211
|
+
str(request.api),
|
|
212
|
+
intent_id=action.intent_id,
|
|
213
|
+
idempotency_key=request.idempotency_key,
|
|
214
|
+
sent_vt=attempt.sent_vt,
|
|
215
|
+
)
|
|
216
|
+
except TransportTimeout:
|
|
217
|
+
return Answer(AnswerClass.UNKNOWN, Reason.TIMEOUT)
|
|
218
|
+
try:
|
|
219
|
+
answer = _parse(_WRITE_ANSWER, body)
|
|
220
|
+
except Unreachable:
|
|
221
|
+
return Answer(AnswerClass.UNKNOWN, Reason.SERVER_ERROR)
|
|
222
|
+
if isinstance(answer, WriteCommitted):
|
|
223
|
+
return Answer(AnswerClass.COMMITTED, Reason.COMMITTED, answer.effect_id)
|
|
224
|
+
if isinstance(answer, WriteInProgress):
|
|
225
|
+
return Answer(AnswerClass.IN_PROGRESS, Reason.IN_PROGRESS)
|
|
226
|
+
if answer.reason is WriteRejectReason.PRECONDITION_FAILED:
|
|
227
|
+
return Answer(AnswerClass.REJECTED, Reason.PRECONDITION_FAILED)
|
|
228
|
+
return Answer(AnswerClass.REJECTED, Reason.DESTINATION_REJECTED)
|
|
229
|
+
|
|
230
|
+
# Status (C1) ------------------------------------------------------------------------------
|
|
231
|
+
|
|
232
|
+
async def lookup(self, action: Action) -> ProbeAnswer:
|
|
233
|
+
"""Which effects exist for the action's intent, and as of when (0005)."""
|
|
234
|
+
request: GetOrderStatus | GetReservationStatus
|
|
235
|
+
if Operation(action.operation) is Operation.SUBMIT_PURCHASE_ORDER:
|
|
236
|
+
request = GetOrderStatus(intent_id=action.intent_id)
|
|
237
|
+
else:
|
|
238
|
+
request = GetReservationStatus(intent_id=action.intent_id)
|
|
239
|
+
try:
|
|
240
|
+
body = await self._call(request, str(request.api), intent_id=action.intent_id)
|
|
241
|
+
answer = _parse(_STATUS_ANSWER, body)
|
|
242
|
+
except (TransportTimeout, Unreachable):
|
|
243
|
+
return ProbeAnswer(answered=False)
|
|
244
|
+
if isinstance(answer, Refusal):
|
|
245
|
+
return ProbeAnswer(answered=False)
|
|
246
|
+
effects = tuple(effect.effect_id for effect in answer.effects)
|
|
247
|
+
return ProbeAnswer(answered=True, effect_ids=effects, as_of_vt=answer.as_of_vt)
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def read_request(key: str) -> ReadRequest:
|
|
251
|
+
"""The read that serves a fact key, such as `get_quote` for `quote/S-1/W-100`."""
|
|
252
|
+
kind = fact_kind(key)
|
|
253
|
+
parts = key.split("/")
|
|
254
|
+
if kind is FactKind.QUOTE:
|
|
255
|
+
return GetQuote(supplier_id=parts[1], sku=parts[2])
|
|
256
|
+
if kind is FactKind.BUDGET:
|
|
257
|
+
return GetBudget(cost_center=parts[1])
|
|
258
|
+
if kind is FactKind.INVENTORY:
|
|
259
|
+
return GetInventory(warehouse_id=parts[1], sku=parts[2])
|
|
260
|
+
return ListSuppliers()
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def scope_of(
|
|
264
|
+
operation: Operation, args: Mapping[str, str | int]
|
|
265
|
+
) -> PurchaseOrderScope | ReservationScope:
|
|
266
|
+
"""What an approval for exactly this write covers (0002, rule 5)."""
|
|
267
|
+
if operation is Operation.SUBMIT_PURCHASE_ORDER:
|
|
268
|
+
quantity, price = int(args["quantity"]), int(args["unit_price_minor"])
|
|
269
|
+
return PurchaseOrderScope(
|
|
270
|
+
supplier_id=str(args["supplier_id"]),
|
|
271
|
+
sku=str(args["sku"]),
|
|
272
|
+
max_quantity=quantity,
|
|
273
|
+
max_amount_minor=quantity * price,
|
|
274
|
+
currency=str(args["currency"]),
|
|
275
|
+
cost_center=str(args["cost_center"]),
|
|
276
|
+
)
|
|
277
|
+
return ReservationScope(
|
|
278
|
+
warehouse_id=str(args["warehouse_id"]),
|
|
279
|
+
sku=str(args["sku"]),
|
|
280
|
+
max_quantity=int(args["quantity"]),
|
|
281
|
+
)
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def _is_server_error(body: object) -> bool:
|
|
285
|
+
return isinstance(body, dict) and body.get("answer") == SERVER_ERROR
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def _parse[T](adapter: TypeAdapter[T], body: object) -> T:
|
|
289
|
+
"""Parse an answer. An answer the gateway cannot read counts as a server error."""
|
|
290
|
+
if _is_server_error(body):
|
|
291
|
+
raise Unreachable("the simulator answered with a server error")
|
|
292
|
+
try:
|
|
293
|
+
return adapter.validate_python(body)
|
|
294
|
+
except ValidationError as error:
|
|
295
|
+
raise Unreachable(f"the simulator's answer did not parse: {error}") from None
|
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
"""The action and grant state machines, as tables (0002, 0003).
|
|
2
|
+
|
|
3
|
+
This module is the only code that decides whether a transition is legal (0003, testing
|
|
4
|
+
plan). It holds no records and does no I/O: the step functions in `steps.py` and every
|
|
5
|
+
store call it before they change anything.
|
|
6
|
+
|
|
7
|
+
Two tables live here:
|
|
8
|
+
|
|
9
|
+
- `TRANSITIONS`, the action transitions T1 to T13 with their reason codes. A reason can
|
|
10
|
+
also need a capability of the contract (0003, 0005): `in_progress` and `retry` need
|
|
11
|
+
idempotency keys, the `status_*` reasons need the status lookup, and
|
|
12
|
+
`precondition_failed` needs conditional writes.
|
|
13
|
+
- `GRANT_TRANSITIONS`, the grant lifecycle from record 0002, rule 14.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
from collections.abc import Mapping
|
|
19
|
+
from dataclasses import dataclass, field
|
|
20
|
+
from enum import StrEnum
|
|
21
|
+
|
|
22
|
+
from fivefold.domain.contracts import Capability, Contract, ContractParams
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class ActionState(StrEnum):
|
|
26
|
+
"""The eight action states (0003). Values are what the agent sees (snake_case)."""
|
|
27
|
+
|
|
28
|
+
PROPOSED = "proposed"
|
|
29
|
+
PENDING_APPROVAL = "pending_approval"
|
|
30
|
+
AUTHORIZED = "authorized"
|
|
31
|
+
DISPATCHED = "dispatched"
|
|
32
|
+
OUTCOME_UNKNOWN = "outcome_unknown"
|
|
33
|
+
CONFIRMED = "confirmed"
|
|
34
|
+
REJECTED = "rejected"
|
|
35
|
+
FAILED = "failed"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
FINAL_STATES = frozenset({ActionState.CONFIRMED, ActionState.REJECTED, ActionState.FAILED})
|
|
39
|
+
"""States with no outgoing transition."""
|
|
40
|
+
|
|
41
|
+
LIVE_STATES = frozenset(set(ActionState) - FINAL_STATES)
|
|
42
|
+
"""The five states in which an action can still change (0001, item 8)."""
|
|
43
|
+
|
|
44
|
+
HOLDING_STATES = LIVE_STATES | {ActionState.CONFIRMED}
|
|
45
|
+
"""At most one action per intent may be in these states (I7)."""
|
|
46
|
+
|
|
47
|
+
UNDISPATCHED_STATES = frozenset(
|
|
48
|
+
{ActionState.PROPOSED, ActionState.PENDING_APPROVAL, ActionState.AUTHORIZED}
|
|
49
|
+
)
|
|
50
|
+
"""Live states before any attempt. Closing the run rejects actions in them (0003)."""
|
|
51
|
+
|
|
52
|
+
UNSETTLED_STATES = frozenset({ActionState.DISPATCHED, ActionState.OUTCOME_UNKNOWN})
|
|
53
|
+
"""States in which an attempt has no settled answer (0003, final report)."""
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class Reason(StrEnum):
|
|
57
|
+
"""Reason codes of transitions (0003, transition table)."""
|
|
58
|
+
|
|
59
|
+
ADMITTED = "admitted"
|
|
60
|
+
APPROVAL_REQUESTED = "approval_requested"
|
|
61
|
+
STALE_INPUT = "stale_input"
|
|
62
|
+
RUN_CLOSED = "run_closed"
|
|
63
|
+
APPROVED = "approved"
|
|
64
|
+
APPROVAL_DENIED = "approval_denied"
|
|
65
|
+
APPROVAL_TIMEOUT = "approval_timeout"
|
|
66
|
+
DISPATCHED = "dispatched"
|
|
67
|
+
APPROVAL_REVOKED = "approval_revoked"
|
|
68
|
+
APPROVAL_EXPIRED = "approval_expired"
|
|
69
|
+
COMMITTED = "committed"
|
|
70
|
+
DESTINATION_REJECTED = "destination_rejected"
|
|
71
|
+
PRECONDITION_FAILED = "precondition_failed"
|
|
72
|
+
TIMEOUT = "timeout"
|
|
73
|
+
TRANSPORT_ERROR = "transport_error"
|
|
74
|
+
SERVER_ERROR = "server_error"
|
|
75
|
+
IN_PROGRESS = "in_progress"
|
|
76
|
+
RECOVERED_OPEN_ATTEMPT = "recovered_open_attempt"
|
|
77
|
+
STATUS_FOUND = "status_found"
|
|
78
|
+
HUMAN_ATTESTED = "human_attested"
|
|
79
|
+
STATUS_SETTLED_EMPTY = "status_settled_empty"
|
|
80
|
+
RETRY = "retry"
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class Note(StrEnum):
|
|
84
|
+
"""Reasons of note events, which record something without changing the state.
|
|
85
|
+
|
|
86
|
+
Record 0003 names `escalated`. The other two are this implementation's: `probe`
|
|
87
|
+
records a status query that settled nothing, so the count toward `max_probes`
|
|
88
|
+
survives a restart; `basis_updated` records a newer basis taken from an attaching
|
|
89
|
+
proposal (0001, item 16), so a dispatch check made against the old basis cannot
|
|
90
|
+
commit (I3).
|
|
91
|
+
"""
|
|
92
|
+
|
|
93
|
+
ESCALATED = "escalated"
|
|
94
|
+
PROBE = "probe"
|
|
95
|
+
BASIS_UPDATED = "basis_updated"
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
class EscalationTrigger(StrEnum):
|
|
99
|
+
"""Why an OutcomeUnknown action was escalated (0003, escalation table)."""
|
|
100
|
+
|
|
101
|
+
AT_ONCE = "at_once"
|
|
102
|
+
MAX_PROBES = "max_probes"
|
|
103
|
+
RETRY_CHECK_FAILED = "retry_check_failed"
|
|
104
|
+
MAX_ATTEMPTS = "max_attempts"
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class EventKind(StrEnum):
|
|
108
|
+
"""Kinds of `action_event` rows (0003, data model)."""
|
|
109
|
+
|
|
110
|
+
TRANSITION = "transition"
|
|
111
|
+
NOTE = "note"
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
@dataclass(frozen=True)
|
|
115
|
+
class Transition:
|
|
116
|
+
"""One row of the transition table. `source` is None for T1, which creates the action."""
|
|
117
|
+
|
|
118
|
+
tid: str
|
|
119
|
+
source: ActionState | None
|
|
120
|
+
target: ActionState
|
|
121
|
+
reasons: frozenset[Reason]
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _t(tid: str, source: ActionState | None, target: ActionState, *reasons: Reason) -> Transition:
|
|
125
|
+
return Transition(tid, source, target, frozenset(reasons))
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
_S = ActionState
|
|
129
|
+
_R = Reason
|
|
130
|
+
|
|
131
|
+
TRANSITIONS: tuple[Transition, ...] = (
|
|
132
|
+
_t("T1", None, _S.PROPOSED, _R.ADMITTED),
|
|
133
|
+
_t("T2", _S.PROPOSED, _S.PENDING_APPROVAL, _R.APPROVAL_REQUESTED),
|
|
134
|
+
_t("T3", _S.PROPOSED, _S.REJECTED, _R.STALE_INPUT, _R.RUN_CLOSED),
|
|
135
|
+
_t("T4", _S.PENDING_APPROVAL, _S.AUTHORIZED, _R.APPROVED),
|
|
136
|
+
_t(
|
|
137
|
+
"T5",
|
|
138
|
+
_S.PENDING_APPROVAL,
|
|
139
|
+
_S.REJECTED,
|
|
140
|
+
_R.APPROVAL_DENIED,
|
|
141
|
+
_R.APPROVAL_TIMEOUT,
|
|
142
|
+
_R.APPROVAL_REVOKED,
|
|
143
|
+
_R.APPROVAL_EXPIRED,
|
|
144
|
+
_R.STALE_INPUT,
|
|
145
|
+
_R.RUN_CLOSED,
|
|
146
|
+
),
|
|
147
|
+
_t("T6", _S.AUTHORIZED, _S.DISPATCHED, _R.DISPATCHED),
|
|
148
|
+
_t(
|
|
149
|
+
"T7",
|
|
150
|
+
_S.AUTHORIZED,
|
|
151
|
+
_S.REJECTED,
|
|
152
|
+
_R.APPROVAL_REVOKED,
|
|
153
|
+
_R.APPROVAL_EXPIRED,
|
|
154
|
+
_R.STALE_INPUT,
|
|
155
|
+
_R.RUN_CLOSED,
|
|
156
|
+
),
|
|
157
|
+
_t("T8", _S.DISPATCHED, _S.CONFIRMED, _R.COMMITTED),
|
|
158
|
+
_t("T9", _S.DISPATCHED, _S.FAILED, _R.DESTINATION_REJECTED, _R.PRECONDITION_FAILED),
|
|
159
|
+
_t(
|
|
160
|
+
"T10",
|
|
161
|
+
_S.DISPATCHED,
|
|
162
|
+
_S.OUTCOME_UNKNOWN,
|
|
163
|
+
_R.TIMEOUT,
|
|
164
|
+
_R.TRANSPORT_ERROR,
|
|
165
|
+
_R.SERVER_ERROR,
|
|
166
|
+
_R.IN_PROGRESS,
|
|
167
|
+
_R.RECOVERED_OPEN_ATTEMPT,
|
|
168
|
+
),
|
|
169
|
+
_t("T11", _S.OUTCOME_UNKNOWN, _S.CONFIRMED, _R.STATUS_FOUND, _R.HUMAN_ATTESTED),
|
|
170
|
+
_t("T12", _S.OUTCOME_UNKNOWN, _S.FAILED, _R.STATUS_SETTLED_EMPTY, _R.HUMAN_ATTESTED),
|
|
171
|
+
_t("T13", _S.OUTCOME_UNKNOWN, _S.DISPATCHED, _R.RETRY),
|
|
172
|
+
)
|
|
173
|
+
"""The transition table of record 0003, as amended by record 0010. No other transitions exist."""
|
|
174
|
+
|
|
175
|
+
REASON_NEEDS: Mapping[Reason, Capability] = {
|
|
176
|
+
Reason.IN_PROGRESS: Capability.IDEMPOTENCY_KEY,
|
|
177
|
+
Reason.RETRY: Capability.IDEMPOTENCY_KEY,
|
|
178
|
+
Reason.STATUS_FOUND: Capability.STATUS,
|
|
179
|
+
Reason.STATUS_SETTLED_EMPTY: Capability.STATUS,
|
|
180
|
+
Reason.PRECONDITION_FAILED: Capability.CONDITIONAL_WRITE,
|
|
181
|
+
}
|
|
182
|
+
"""Reasons that only a contract with the named capability can produce (0003, 0005)."""
|
|
183
|
+
|
|
184
|
+
_BY_STATES: dict[tuple[ActionState | None, ActionState], Transition] = {
|
|
185
|
+
(t.source, t.target): t for t in TRANSITIONS
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
class GatewayRuleError(Exception):
|
|
190
|
+
"""A step was asked to do something the decision records do not allow."""
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
class IllegalTransition(GatewayRuleError):
|
|
194
|
+
"""The transition is not in the table, or not with this reason or contract."""
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def transition_for(source: ActionState | None, target: ActionState) -> Transition | None:
|
|
198
|
+
"""Return the table row from `source` to `target`, or None if there is none."""
|
|
199
|
+
return _BY_STATES.get((source, target))
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def check_transition(
|
|
203
|
+
source: ActionState | None, target: ActionState, reason: Reason, contract: Contract
|
|
204
|
+
) -> Transition:
|
|
205
|
+
"""Return the transition for this move, or raise `IllegalTransition`."""
|
|
206
|
+
row = _BY_STATES.get((source, target))
|
|
207
|
+
if row is None:
|
|
208
|
+
raise IllegalTransition(f"no transition from {source} to {target}")
|
|
209
|
+
if reason not in row.reasons:
|
|
210
|
+
raise IllegalTransition(f"{row.tid} ({source} to {target}) has no reason {reason}")
|
|
211
|
+
needed = REASON_NEEDS.get(reason)
|
|
212
|
+
if needed is not None and not contract.has(needed):
|
|
213
|
+
raise IllegalTransition(
|
|
214
|
+
f"{row.tid} with reason {reason} needs {needed}; {contract} lacks it"
|
|
215
|
+
)
|
|
216
|
+
return row
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
class GrantState(StrEnum):
|
|
220
|
+
"""Grant states (0002, rule 14)."""
|
|
221
|
+
|
|
222
|
+
PENDING = "pending"
|
|
223
|
+
ACTIVE = "active"
|
|
224
|
+
CONSUMED = "consumed"
|
|
225
|
+
DENIED = "denied"
|
|
226
|
+
TIMED_OUT = "timed_out"
|
|
227
|
+
RELEASED = "released"
|
|
228
|
+
REVOKED = "revoked"
|
|
229
|
+
EXPIRED = "expired"
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
_G = GrantState
|
|
233
|
+
|
|
234
|
+
GRANT_TRANSITIONS: Mapping[GrantState | None, frozenset[GrantState]] = {
|
|
235
|
+
None: frozenset({_G.PENDING}),
|
|
236
|
+
_G.PENDING: frozenset(
|
|
237
|
+
{_G.ACTIVE, _G.DENIED, _G.TIMED_OUT, _G.RELEASED, _G.REVOKED, _G.EXPIRED}
|
|
238
|
+
),
|
|
239
|
+
_G.ACTIVE: frozenset({_G.CONSUMED, _G.RELEASED, _G.REVOKED, _G.EXPIRED}),
|
|
240
|
+
_G.CONSUMED: frozenset({_G.REVOKED, _G.EXPIRED}),
|
|
241
|
+
}
|
|
242
|
+
"""Legal grant moves (0002, rule 14). States missing as keys have no outgoing move."""
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def check_grant_transition(source: GrantState | None, target: GrantState) -> None:
|
|
246
|
+
"""Raise `IllegalTransition` unless the grant may move from `source` to `target`."""
|
|
247
|
+
if target not in GRANT_TRANSITIONS.get(source, frozenset()):
|
|
248
|
+
raise IllegalTransition(f"no grant transition from {source} to {target}")
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
class AnswerClass(StrEnum):
|
|
252
|
+
"""The four classes of destination answers (0003).
|
|
253
|
+
|
|
254
|
+
Only committed and rejected are definitive, and only a definitive answer ends an
|
|
255
|
+
attempt. A 503 is unknown: a proxy can return it after the backend committed.
|
|
256
|
+
"""
|
|
257
|
+
|
|
258
|
+
COMMITTED = "committed"
|
|
259
|
+
REJECTED = "rejected"
|
|
260
|
+
IN_PROGRESS = "in_progress"
|
|
261
|
+
UNKNOWN = "unknown"
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
ANSWER_REASONS: Mapping[AnswerClass, frozenset[Reason]] = {
|
|
265
|
+
AnswerClass.COMMITTED: frozenset({Reason.COMMITTED}),
|
|
266
|
+
AnswerClass.REJECTED: frozenset({Reason.DESTINATION_REJECTED, Reason.PRECONDITION_FAILED}),
|
|
267
|
+
AnswerClass.IN_PROGRESS: frozenset({Reason.IN_PROGRESS}),
|
|
268
|
+
AnswerClass.UNKNOWN: frozenset({Reason.TIMEOUT, Reason.TRANSPORT_ERROR, Reason.SERVER_ERROR}),
|
|
269
|
+
}
|
|
270
|
+
"""The reason code each answer class records (T8, T9, T10)."""
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
class CheckKind(StrEnum):
|
|
274
|
+
"""Which checks must pass before a send (I3)."""
|
|
275
|
+
|
|
276
|
+
FULL = "full"
|
|
277
|
+
"""Authority and every dependency rule: before the first send."""
|
|
278
|
+
|
|
279
|
+
EXACT_ONLY = "exact_only"
|
|
280
|
+
"""Authority and the exact rules only: before a retry at C2."""
|
|
281
|
+
|
|
282
|
+
EXEMPT = "exempt"
|
|
283
|
+
"""No gateway check: a retry at C3, where the destination checks atomically."""
|
|
284
|
+
|
|
285
|
+
AUTHORITY_ONLY = "authority_only"
|
|
286
|
+
"""Authority only: G1's one check before its one send, which reads no fact (0008)."""
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
def required_check(
|
|
290
|
+
contract: Contract, attempt_no: int, *, authorization_only: bool = False
|
|
291
|
+
) -> CheckKind:
|
|
292
|
+
"""Return the check that must pass before attempt `attempt_no` is sent (I3, 0002 rule 17).
|
|
293
|
+
|
|
294
|
+
`authorization_only` is G1 (0008): it checks the approval and no fact before its one
|
|
295
|
+
send, and never retries.
|
|
296
|
+
|
|
297
|
+
Raises `GatewayRuleError` for a retry in G1, or on a contract without idempotency
|
|
298
|
+
keys (I4).
|
|
299
|
+
"""
|
|
300
|
+
if attempt_no < 1:
|
|
301
|
+
raise ValueError("attempt numbers start at 1")
|
|
302
|
+
if authorization_only:
|
|
303
|
+
if attempt_no > 1:
|
|
304
|
+
raise GatewayRuleError("G1 never retries (0008)")
|
|
305
|
+
return CheckKind.AUTHORITY_ONLY
|
|
306
|
+
if attempt_no == 1:
|
|
307
|
+
return CheckKind.FULL
|
|
308
|
+
if not contract.has(Capability.IDEMPOTENCY_KEY):
|
|
309
|
+
raise GatewayRuleError(f"{contract} allows no retries (I4)")
|
|
310
|
+
if contract.has(Capability.CONDITIONAL_WRITE):
|
|
311
|
+
return CheckKind.EXEMPT
|
|
312
|
+
return CheckKind.EXACT_ONLY
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
class ReconcileHow(StrEnum):
|
|
316
|
+
"""How an unknown outcome is being resolved, as the agent is told (0003)."""
|
|
317
|
+
|
|
318
|
+
ESCALATED_TO_HUMAN = "escalated_to_human"
|
|
319
|
+
QUERYING_STATUS = "querying_status"
|
|
320
|
+
RETRYING_WITH_SAME_KEY = "retrying_with_same_key"
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
def reconcile_how(contract: Contract, *, escalated: bool) -> ReconcileHow:
|
|
324
|
+
"""Return what the gateway is doing about an OutcomeUnknown action (0003, 0005)."""
|
|
325
|
+
if escalated:
|
|
326
|
+
return ReconcileHow.ESCALATED_TO_HUMAN
|
|
327
|
+
if contract.has(Capability.STATUS):
|
|
328
|
+
return ReconcileHow.QUERYING_STATUS
|
|
329
|
+
if contract.has(Capability.IDEMPOTENCY_KEY):
|
|
330
|
+
return ReconcileHow.RETRYING_WITH_SAME_KEY
|
|
331
|
+
return ReconcileHow.ESCALATED_TO_HUMAN
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
@dataclass(frozen=True)
|
|
335
|
+
class GatewaySettings:
|
|
336
|
+
"""The gateway's timing and limits (0005), with the destination's promises.
|
|
337
|
+
|
|
338
|
+
Times are virtual milliseconds. `approval_wait_ms` comes from the scenario's
|
|
339
|
+
`authority` section (0002, 0009); the other defaults are 0005's. `agent_workers` is
|
|
340
|
+
how many agent workers the run config expects to report: one, or two when its fault
|
|
341
|
+
plan includes F9, which starts a second worker (0009). The run closes in the
|
|
342
|
+
transaction that accepts the last of their reports (0010). If a planned F9 never
|
|
343
|
+
fires, the run closes when the agents' phase ends instead (0003).
|
|
344
|
+
"""
|
|
345
|
+
|
|
346
|
+
approval_wait_ms: int
|
|
347
|
+
params: ContractParams = field(default_factory=ContractParams)
|
|
348
|
+
dispatch_timeout_ms: int = 2_000
|
|
349
|
+
max_attempts: int = 5
|
|
350
|
+
max_probes: int = 20
|
|
351
|
+
agent_workers: int = 1
|
|
352
|
+
|
|
353
|
+
def __post_init__(self) -> None:
|
|
354
|
+
if self.dispatch_timeout_ms <= 2 * self.params.max_hop_latency_ms:
|
|
355
|
+
raise ValueError("dispatch_timeout_ms must exceed 2 x max_hop_latency_ms (0005)")
|
|
356
|
+
if self.approval_wait_ms <= 0 or self.max_attempts < 1 or self.max_probes < 1:
|
|
357
|
+
raise ValueError("approval_wait_ms, max_attempts and max_probes must be positive")
|
|
358
|
+
if self.agent_workers < 1:
|
|
359
|
+
raise ValueError("a run has at least one agent worker (0009)")
|
|
360
|
+
|
|
361
|
+
@property
|
|
362
|
+
def settle_ms(self) -> int:
|
|
363
|
+
"""S, the settle time: `max_hop_latency_ms + commit_deadline_ms` (0004, 0005)."""
|
|
364
|
+
return self.params.settle_ms
|
|
365
|
+
|
|
366
|
+
def backoff_ms(self, attempts_sent: int) -> int:
|
|
367
|
+
"""How long after the latest send the next retry may go (0005).
|
|
368
|
+
|
|
369
|
+
The backoff is T, then doubling, capped at 8 x T. Record 0005 does not say what it
|
|
370
|
+
is counted from; counting from the latest send keeps retries at least T apart,
|
|
371
|
+
which 0005 requires so that a rejected retry settles the attempts before it.
|
|
372
|
+
"""
|
|
373
|
+
if attempts_sent < 1:
|
|
374
|
+
raise ValueError("a retry follows at least one attempt")
|
|
375
|
+
t = self.dispatch_timeout_ms
|
|
376
|
+
return min(t << (attempts_sent - 1), 8 * t)
|