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,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)