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,424 @@
1
+ """The gateway's tools, as an agent worker calls them over MCP (0001, 0003, 0008).
2
+
3
+ G1 and G2 expose the same tools with the same schemas; only their behaviour differs
4
+ (0008). The list below is G2's. G1, authorization only, is the store with identity off:
5
+
6
+ - Every write call is a new action with its own approval request, and no fact is
7
+ checked. When the send's outcome is unknown at the end of the call's wait (a timeout
8
+ or a server error), the call fails with the tool error `gateway_timeout`, as a proxy
9
+ returns 504, so the agent's framework retries it. The action stays OutcomeUnknown.
10
+ - `submit_final_report` hands the report to the harness's report sink as it came and
11
+ checks nothing. The sink records it and says what breaks the schema, as it does for
12
+ B0's reports, and the agent is told the same.
13
+
14
+ - Reads (`get_quote`, `list_suppliers`, `get_budget`, `get_inventory`) take the
15
+ simulator's own arguments, read through the gateway's simulator client, record the
16
+ read and return `{read_id, key, version, data}`.
17
+ - Writes (`submit_purchase_order`, `reserve_inventory`) take the business arguments,
18
+ `intent_id`, `based_on` (read ids) and an optional `note`. Fields outside the schema
19
+ are allowed and ignored, because they are volatile (0001, item 7). A call runs
20
+ admission (0001, item 17), starts the action's driver, waits at most `tool_wait_ms`
21
+ for a state the agent can act on, and returns the action's result (0003).
22
+ - `get_action_status(action_id, wait_ms)` waits at most `wait_ms` for a final state. It
23
+ never contacts the destination (0003). Its schema allows at most 60,000 ms, 0005's
24
+ default; a wait above the run's own `max_wait_ms` is refused too, as `invalid_args`,
25
+ so the schema the agent sees stays the same in every run.
26
+ - `submit_final_report(claims)` refuses a report that breaks the schema with
27
+ `invalid_args`, checks the rest against the records, and hands an accepted report to
28
+ the harness's report sink (0003, 0008).
29
+
30
+ What has no refusal reason in 0003 is a tool error, as MCP reports one: a read the
31
+ simulator refused or did not answer in time (`gateway_timeout`, as a proxy's 504), a
32
+ status call for an action that does not exist, and an unknown tool.
33
+
34
+ The store logs the response to each write, status call and G2 report with the call's
35
+ arguments as they arrived (`gw.tool_call`, 0003). Reads are recorded as reads; tool
36
+ errors, G1's reports and a report that breaks the schema are not logged.
37
+ """
38
+
39
+ from __future__ import annotations
40
+
41
+ from collections.abc import Awaitable, Callable, Mapping
42
+ from dataclasses import dataclass
43
+ from typing import Annotated, Literal, Protocol
44
+
45
+ from pydantic import (
46
+ AfterValidator,
47
+ BaseModel,
48
+ ConfigDict,
49
+ Field,
50
+ StrictInt,
51
+ StringConstraints,
52
+ ValidationError,
53
+ )
54
+
55
+ from fivefold.domain.api import (
56
+ FactRead,
57
+ GetBudget,
58
+ GetInventory,
59
+ GetQuote,
60
+ Id,
61
+ ListSuppliers,
62
+ Minor,
63
+ Quantity,
64
+ WaitLimit,
65
+ within_wait_limit,
66
+ )
67
+ from fivefold.domain.identity import InvalidArgs, action_key, normalize, target_of
68
+ from fivefold.domain.report import FinalReport, InvalidReport, parse_report, validation_messages
69
+ from fivefold.domain.rules import Operation, dependencies
70
+ from fivefold.gateway import wire
71
+ from fivefold.gateway.destination import Unreachable
72
+ from fivefold.gateway.dispatcher import Dispatcher
73
+ from fivefold.gateway.records import (
74
+ ActionResult,
75
+ Claim,
76
+ ClaimStatus,
77
+ Refusal,
78
+ RefusalReason,
79
+ ReportAccepted,
80
+ WriteCall,
81
+ )
82
+ from fivefold.gateway.sim_client import ReadRefused, ReadRequest
83
+ from fivefold.gateway.state_machine import FINAL_STATES, ActionState, EventKind
84
+ from fivefold.gateway.store import ActionStore, UnknownAction
85
+ from fivefold.harness.scheduler import Scheduler
86
+
87
+ _S = ActionState
88
+
89
+ ANSWERED_STATES = frozenset(
90
+ {_S.PENDING_APPROVAL, _S.CONFIRMED, _S.REJECTED, _S.FAILED, _S.OUTCOME_UNKNOWN}
91
+ )
92
+ """The states a write call returns as soon as the action reaches one (0003)."""
93
+
94
+ ReadId = Annotated[str, StringConstraints(pattern=r"^[^\x00-\x1f\x7f]{1,64}$")]
95
+ """A cited read id. One the gateway never issued is refused as `unknown_read`."""
96
+
97
+ Note = Annotated[str, StringConstraints(pattern=r"^[^\x00]*$", max_length=2_000)]
98
+ AnyCaseCurrency = Annotated[str, StringConstraints(pattern=r"^[A-Za-z]{3}$")]
99
+ """A currency code in any case. The gateway uppercases it (0001, item 7)."""
100
+
101
+
102
+ class WriteArgs(BaseModel):
103
+ """What every write tool takes besides its business arguments (0001, 0008)."""
104
+
105
+ model_config = ConfigDict(extra="allow", frozen=True)
106
+
107
+ intent_id: Id
108
+ based_on: list[ReadId] = []
109
+ note: Note | None = None
110
+
111
+
112
+ class PurchaseOrderArgs(WriteArgs):
113
+ """Arguments of `submit_purchase_order`."""
114
+
115
+ supplier_id: Id
116
+ sku: Id
117
+ quantity: Quantity
118
+ unit_price_minor: Minor
119
+ currency: AnyCaseCurrency
120
+ cost_center: Id
121
+
122
+
123
+ class ReservationArgs(WriteArgs):
124
+ """Arguments of `reserve_inventory`."""
125
+
126
+ warehouse_id: Id
127
+ sku: Id
128
+ quantity: Quantity
129
+
130
+
131
+ class ActionStatusArgs(BaseModel):
132
+ """Arguments of `get_action_status`."""
133
+
134
+ model_config = ConfigDict(extra="forbid", frozen=True)
135
+
136
+ action_id: Annotated[str, StringConstraints(pattern=r"^A-[0-9]{4,}$")]
137
+ wait_ms: Annotated[StrictInt, Field(ge=0, le=60_000), AfterValidator(within_wait_limit)] = 0
138
+ """At most 60,000 by the schema, and at most the run's `max_wait_ms` when validated
139
+ with a `WaitLimit`."""
140
+
141
+
142
+ @dataclass(frozen=True)
143
+ class ToolDefinition:
144
+ """A tool as `tools/list` describes it."""
145
+
146
+ name: str
147
+ description: str
148
+ arguments: type[BaseModel]
149
+
150
+ def input_schema(self) -> dict[str, object]:
151
+ """The tool's input as JSON Schema."""
152
+ return self.arguments.model_json_schema()
153
+
154
+
155
+ TOOLS: tuple[ToolDefinition, ...] = (
156
+ ToolDefinition("get_quote", "Read a supplier's quote for a sku.", GetQuote),
157
+ ToolDefinition("list_suppliers", "Read the supplier directory.", ListSuppliers),
158
+ ToolDefinition("get_budget", "Read a cost center's budget.", GetBudget),
159
+ ToolDefinition("get_inventory", "Read a sku's stock in a warehouse.", GetInventory),
160
+ ToolDefinition(
161
+ "submit_purchase_order",
162
+ "Propose a purchase order for an intent, citing the reads it relies on.",
163
+ PurchaseOrderArgs,
164
+ ),
165
+ ToolDefinition(
166
+ "reserve_inventory",
167
+ "Propose an inventory reservation for an intent, citing the reads it relies on.",
168
+ ReservationArgs,
169
+ ),
170
+ ToolDefinition(
171
+ "get_action_status",
172
+ "An action's result. Waits up to wait_ms (at most 60000) for a final state.",
173
+ ActionStatusArgs,
174
+ ),
175
+ ToolDefinition(
176
+ "submit_final_report",
177
+ "Report, for every intent of the task, whether it is done, not done or unknown.",
178
+ FinalReport,
179
+ ),
180
+ )
181
+ """Every tool G modes expose, in `tools/list` order."""
182
+
183
+
184
+ class ToolError(Exception):
185
+ """A tool call that failed without a refusal reason; MCP reports it as an error."""
186
+
187
+ def __init__(self, code: str, message: str) -> None:
188
+ super().__init__(f"{code}: {message}")
189
+ self.code = code
190
+ self.message = message
191
+
192
+
193
+ class Reader(Protocol):
194
+ """Reads facts from the simulator: the gateway's simulator client."""
195
+
196
+ async def read(self, request: ReadRequest) -> FactRead:
197
+ """Read one fact. Raises `Unreachable` or `ReadRefused`."""
198
+
199
+
200
+ class ReportSink(Protocol):
201
+ """The harness's report sink."""
202
+
203
+ def submit(
204
+ self,
205
+ worker: str,
206
+ report: object,
207
+ *,
208
+ accepted_by: Literal["gateway", "sink"],
209
+ message_seq: int | None = None,
210
+ ) -> tuple[str, ...]:
211
+ """Record a report; return what breaks its schema."""
212
+
213
+
214
+ @dataclass(frozen=True)
215
+ class ToolTiming:
216
+ """How long tools wait, in virtual ms (0003, 0005)."""
217
+
218
+ tool_wait_ms: int = 2_500
219
+ max_wait_ms: int = 60_000
220
+ """The longest `wait_ms` `get_action_status` accepts: the scenario's `max_wait_ms`."""
221
+
222
+
223
+ Json = dict[str, object]
224
+ Handler = Callable[[Mapping[str, object], "Call"], Awaitable[Json]]
225
+
226
+
227
+ @dataclass(frozen=True)
228
+ class Call:
229
+ """Who made a tool call: the agent worker, and the message that carried the call."""
230
+
231
+ worker: str
232
+ message_seq: int | None
233
+
234
+
235
+ class GatewayTools:
236
+ """G2's tools for one run. `call` serves one tool call of one agent worker."""
237
+
238
+ def __init__(
239
+ self,
240
+ scheduler: Scheduler,
241
+ store: ActionStore,
242
+ dispatcher: Dispatcher,
243
+ reader: Reader,
244
+ reports: ReportSink,
245
+ *,
246
+ task_id: str,
247
+ intents: Mapping[str, str],
248
+ timing: ToolTiming | None = None,
249
+ ) -> None:
250
+ self._scheduler = scheduler
251
+ self._store = store
252
+ self._dispatcher = dispatcher
253
+ self._reader = reader
254
+ self._reports = reports
255
+ self._task_id = task_id
256
+ self._intents = dict(intents)
257
+ self._timing = timing if timing is not None else ToolTiming()
258
+ self._handlers: dict[str, Handler] = {
259
+ "get_quote": self._read_with(GetQuote),
260
+ "list_suppliers": self._read_with(ListSuppliers),
261
+ "get_budget": self._read_with(GetBudget),
262
+ "get_inventory": self._read_with(GetInventory),
263
+ "submit_purchase_order": self._write_with(PurchaseOrderArgs),
264
+ "reserve_inventory": self._write_with(ReservationArgs),
265
+ "get_action_status": self._status,
266
+ "submit_final_report": self._report,
267
+ }
268
+
269
+ async def call(
270
+ self,
271
+ name: str,
272
+ arguments: Mapping[str, object],
273
+ *,
274
+ worker: str,
275
+ message_seq: int | None = None,
276
+ ) -> Json:
277
+ """Serve one tool call from `worker`. Raises `ToolError`.
278
+
279
+ `message_seq` is the harness's seq of the message that carried the call.
280
+ """
281
+ handler = self._handlers.get(name)
282
+ if handler is None:
283
+ raise ToolError("unknown_tool", f"no tool named {name!r}")
284
+ return await handler(arguments, Call(worker, message_seq))
285
+
286
+ @property
287
+ def _now(self) -> int:
288
+ return self._scheduler.now
289
+
290
+ # Reads -----------------------------------------------------------------------------------
291
+
292
+ def _read_with(self, model: type[ReadRequest]) -> Handler:
293
+ async def read(arguments: Mapping[str, object], call: Call) -> Json:
294
+ try:
295
+ request = model.model_validate(dict(arguments))
296
+ except ValidationError as error:
297
+ raise ToolError("invalid_args", "; ".join(validation_messages(error))) from None
298
+ try:
299
+ fact = await self._reader.read(request)
300
+ except Unreachable as error:
301
+ raise ToolError("gateway_timeout", str(error)) from None
302
+ except ReadRefused as error:
303
+ raise ToolError(error.reason, error.detail) from None
304
+ record = self._store.record_read(fact.key, fact.version, fact.data, self._now)
305
+ return wire.read(record)
306
+
307
+ return read
308
+
309
+ # Writes ----------------------------------------------------------------------------------
310
+
311
+ def _write_with(self, model: type[PurchaseOrderArgs] | type[ReservationArgs]) -> Handler:
312
+ async def write(arguments: Mapping[str, object], caller: Call) -> Json:
313
+ operation = (
314
+ Operation.SUBMIT_PURCHASE_ORDER
315
+ if model is PurchaseOrderArgs
316
+ else Operation.RESERVE_INVENTORY
317
+ )
318
+ try:
319
+ args = model.model_validate(dict(arguments))
320
+ normal = normalize(operation, args.model_dump())
321
+ except ValidationError as error:
322
+ return self._invalid(operation, arguments, "; ".join(validation_messages(error)))
323
+ except InvalidArgs as error:
324
+ return self._invalid(operation, arguments, str(error))
325
+ call = WriteCall(
326
+ intent_id=args.intent_id,
327
+ operation=str(operation),
328
+ target=target_of(operation, normal),
329
+ args=normal,
330
+ action_key=action_key(self._task_id, args.intent_id, operation, normal),
331
+ based_on=tuple(args.based_on),
332
+ dependencies=tuple(d.key for d in dependencies(operation, normal)),
333
+ )
334
+ outcome = self._store.propose(call, self._now, args=arguments)
335
+ if isinstance(outcome, Refusal):
336
+ return wire.refusal(outcome)
337
+ self._dispatcher.drive(outcome.action_id)
338
+ await self._dispatcher.wait(
339
+ outcome.action_id, ANSWERED_STATES.__contains__, self._timing.tool_wait_ms
340
+ )
341
+ if self._store.authorization_only:
342
+ self._fail_unknown_outcome(outcome.action_id)
343
+ result = self._store.status(
344
+ outcome.action_id, self._now, tool=str(operation), args=arguments
345
+ )
346
+ return wire.action(result)
347
+
348
+ return write
349
+
350
+ def _fail_unknown_outcome(self, action_id: str) -> None:
351
+ """G1: a send with no usable answer ends the call as a proxy's 504 does (0008).
352
+
353
+ Raises `ToolError("gateway_timeout")` when the action's outcome is unknown. The
354
+ records keep the action OutcomeUnknown; the response holds no action state, so,
355
+ like every tool error, it is not logged as a response (I5).
356
+ """
357
+ view = self._store.view(action_id)
358
+ action = view.action
359
+ if action.state is not _S.OUTCOME_UNKNOWN:
360
+ return
361
+ reason = next(e.reason for e in reversed(view.events) if e.kind is EventKind.TRANSITION)
362
+ raise ToolError(
363
+ "gateway_timeout",
364
+ f"{action.operation} for {action.intent_id}: no usable answer from the simulator"
365
+ f" ({reason})",
366
+ )
367
+
368
+ def _invalid(self, operation: Operation, arguments: Mapping[str, object], why: str) -> Json:
369
+ refusal = self._store.refuse_invalid(str(operation), dict(arguments), why, self._now)
370
+ return wire.refusal(refusal)
371
+
372
+ # Status ----------------------------------------------------------------------------------
373
+
374
+ async def _status(self, arguments: Mapping[str, object], call: Call) -> Json:
375
+ limit = WaitLimit(self._timing.max_wait_ms)
376
+ try:
377
+ args = ActionStatusArgs.model_validate(dict(arguments), context=limit)
378
+ except ValidationError as error:
379
+ raise ToolError("invalid_args", "; ".join(validation_messages(error))) from None
380
+ try:
381
+ self._store.view(args.action_id)
382
+ except UnknownAction:
383
+ raise ToolError("unknown_action", f"no action {args.action_id}") from None
384
+ await self._dispatcher.wait(args.action_id, FINAL_STATES.__contains__, args.wait_ms)
385
+ result: ActionResult = self._store.status(args.action_id, self._now, args=arguments)
386
+ return wire.action(result)
387
+
388
+ # The final report --------------------------------------------------------------------------
389
+
390
+ async def _report(self, arguments: Mapping[str, object], call: Call) -> Json:
391
+ if self._store.authorization_only:
392
+ return self._forward_report(arguments, call)
393
+ try:
394
+ report = parse_report(dict(arguments), self._intents)
395
+ except InvalidReport as invalid:
396
+ message = "; ".join(invalid.errors)
397
+ return wire.refusal(Refusal(RefusalReason.INVALID_ARGS, message=message))
398
+ claims = [
399
+ Claim(c.intent_id, ClaimStatus(str(c.status)), tuple(c.effect_ids), c.note)
400
+ for c in report.claims
401
+ ]
402
+ outcome = self._store.submit_report(claims, self._now, worker=call.worker, args=arguments)
403
+ if isinstance(outcome, ReportAccepted):
404
+ self._reports.submit(
405
+ call.worker,
406
+ report.model_dump(mode="json"),
407
+ accepted_by="gateway",
408
+ message_seq=call.message_seq,
409
+ )
410
+ return wire.report(outcome)
411
+
412
+ def _forward_report(self, arguments: Mapping[str, object], call: Call) -> Json:
413
+ """G1: hand the report to the report sink unchanged, and check nothing (0008).
414
+
415
+ The sink records every report with whether it is valid, and returns what breaks
416
+ the report schema; the agent is told that, as B0's sink tells it, so it can fix the
417
+ report and resubmit. G1 keeps no record of reports.
418
+ """
419
+ errors = self._reports.submit(
420
+ call.worker, dict(arguments), accepted_by="gateway", message_seq=call.message_seq
421
+ )
422
+ if errors:
423
+ return wire.refusal(Refusal(RefusalReason.INVALID_ARGS, message="; ".join(errors)))
424
+ return wire.accepted()
@@ -0,0 +1,199 @@
1
+ """A store that runs every operation on two stores and compares them (0003, testing plan).
2
+
3
+ `TwinStore` checks a store against the in-memory store, the oracle. Every operation runs
4
+ on both. Both must return equal results, or raise the same kind of error with the same
5
+ message, and must hold equal records afterwards, down to the counters that number them.
6
+ Testing plan item 3 of record 0003 runs the gateway's Hypothesis machine this way against
7
+ the Postgres store. It belongs to the tests, not to a running gateway.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from collections.abc import Mapping, Sequence
13
+ from typing import Any, cast
14
+
15
+ from fivefold.gateway.memory import MemoryStore
16
+ from fivefold.gateway.pg_store import PgStore
17
+ from fivefold.gateway.records import (
18
+ NO_ARGS,
19
+ ActionResult,
20
+ Answer,
21
+ ApprovalStatus,
22
+ Attempt,
23
+ BasisCheck,
24
+ CheckRecord,
25
+ CheckTicket,
26
+ Claim,
27
+ ProbeAnswer,
28
+ ReadRecord,
29
+ Refusal,
30
+ ReportAccepted,
31
+ Resolution,
32
+ Snapshot,
33
+ WriteCall,
34
+ )
35
+ from fivefold.gateway.state_machine import GatewaySettings
36
+ from fivefold.gateway.steps import ActionView
37
+
38
+
39
+ class StoreMismatch(AssertionError):
40
+ """The two stores disagreed."""
41
+
42
+
43
+ class TwinStore:
44
+ """The in-memory oracle and a Postgres store, run side by side."""
45
+
46
+ def __init__(self, oracle: MemoryStore, pg: PgStore) -> None:
47
+ self.oracle = oracle
48
+ self.pg = pg
49
+
50
+ def _both(self, name: str, *args: object, **kwargs: object) -> Any:
51
+ try:
52
+ expected = getattr(self.oracle, name)(*args, **kwargs)
53
+ except Exception as error:
54
+ try:
55
+ getattr(self.pg, name)(*args, **kwargs)
56
+ except Exception as other:
57
+ if type(other) is not type(error) or str(other) != str(error):
58
+ raise StoreMismatch(
59
+ f"{name}: memory raised {error!r}, Postgres raised {other!r}"
60
+ ) from other
61
+ else:
62
+ raise StoreMismatch(f"{name}: memory raised {error!r}, Postgres did not") from error
63
+ self.compare()
64
+ raise
65
+ actual = getattr(self.pg, name)(*args, **kwargs)
66
+ if actual != expected:
67
+ raise StoreMismatch(f"{name}: Postgres gave {actual!r}, memory {expected!r}")
68
+ self.compare()
69
+ return expected
70
+
71
+ def compare(self) -> None:
72
+ """Raise `StoreMismatch` unless both stores hold the same records."""
73
+ pg, oracle = self.pg.snapshot(), self.oracle.snapshot()
74
+ parts = ("intents", "actions", "grants", "attempts", "events", "escalations")
75
+ for part in (*parts, "closed_intents", "reports", "reads", "proposals"):
76
+ if getattr(pg, part) != getattr(oracle, part):
77
+ raise StoreMismatch(f"{part} differ")
78
+ if pg.tool_calls != oracle.tool_calls:
79
+ raise StoreMismatch("tool calls differ")
80
+ if pg.run_closed != oracle.run_closed:
81
+ raise StoreMismatch("run_closed differs")
82
+ last_seq = oracle.events[-1].seq if oracle.events else 0
83
+ expected = (
84
+ len(oracle.actions),
85
+ last_seq,
86
+ len(oracle.tool_calls),
87
+ len(oracle.reads),
88
+ len(oracle.proposals),
89
+ )
90
+ if self.pg.counters() != expected:
91
+ raise StoreMismatch(f"counters {self.pg.counters()} differ from {expected}")
92
+
93
+ @property
94
+ def settings(self) -> GatewaySettings:
95
+ return self.oracle.settings
96
+
97
+ def snapshot(self) -> Snapshot:
98
+ return self.oracle.snapshot()
99
+
100
+ def view(self, action_id: str) -> ActionView:
101
+ expected = self.oracle.view(action_id)
102
+ if self.pg.view(action_id) != expected:
103
+ raise StoreMismatch(f"views of {action_id} differ")
104
+ return expected
105
+
106
+ def begin_check(self, action_id: str) -> CheckTicket:
107
+ return cast(CheckTicket, self._both("begin_check", action_id))
108
+
109
+ def record_read(
110
+ self, key: str, version: int, data: Mapping[str, object], vt: int
111
+ ) -> ReadRecord:
112
+ return cast(ReadRecord, self._both("record_read", key, version, data, vt))
113
+
114
+ def read_of(self, key: str, version: int) -> ReadRecord | None:
115
+ expected = self.oracle.read_of(key, version)
116
+ if self.pg.read_of(key, version) != expected:
117
+ raise StoreMismatch(f"reads of {key} at {version} differ")
118
+ return expected
119
+
120
+ def propose(
121
+ self, call: WriteCall, vt: int, *, args: Mapping[str, object] = NO_ARGS
122
+ ) -> ActionResult | Refusal:
123
+ return cast(ActionResult | Refusal, self._both("propose", call, vt, args=args))
124
+
125
+ def refuse_invalid(
126
+ self, operation: str, args: Mapping[str, object], message: str, vt: int
127
+ ) -> Refusal:
128
+ return cast(Refusal, self._both("refuse_invalid", operation, args, message, vt))
129
+
130
+ def status(
131
+ self,
132
+ action_id: str,
133
+ vt: int,
134
+ *,
135
+ tool: str = "get_action_status",
136
+ args: Mapping[str, object] = NO_ARGS,
137
+ ) -> ActionResult:
138
+ return cast(ActionResult, self._both("status", action_id, vt, tool=tool, args=args))
139
+
140
+ def submit_report(
141
+ self,
142
+ claims: Sequence[Claim],
143
+ vt: int,
144
+ *,
145
+ worker: str,
146
+ args: Mapping[str, object] = NO_ARGS,
147
+ ) -> ReportAccepted | Refusal:
148
+ outcome = self._both("submit_report", claims, vt, worker=worker, args=args)
149
+ return cast(ReportAccepted | Refusal, outcome)
150
+
151
+ def file_approval(
152
+ self,
153
+ action_id: str,
154
+ basis: BasisCheck | None,
155
+ approval_id: str | None,
156
+ vt: int,
157
+ *,
158
+ seen_seq: int,
159
+ ) -> None:
160
+ self._both("file_approval", action_id, basis, approval_id, vt, seen_seq=seen_seq)
161
+
162
+ def poll_approval(
163
+ self,
164
+ action_id: str,
165
+ approval: ApprovalStatus,
166
+ basis: BasisCheck | None,
167
+ vt: int,
168
+ *,
169
+ seen_seq: int,
170
+ ) -> None:
171
+ self._both("poll_approval", action_id, approval, basis, vt, seen_seq=seen_seq)
172
+
173
+ def time_out_approval(
174
+ self, action_id: str, approval: ApprovalStatus, vt: int, *, seen_seq: int
175
+ ) -> None:
176
+ self._both("time_out_approval", action_id, approval, vt, seen_seq=seen_seq)
177
+
178
+ def dispatch(self, action_id: str, check: CheckRecord, vt: int) -> Attempt | None:
179
+ return cast(Attempt | None, self._both("dispatch", action_id, check, vt))
180
+
181
+ def retry(self, action_id: str, check: CheckRecord, vt: int) -> Attempt | None:
182
+ return cast(Attempt | None, self._both("retry", action_id, check, vt))
183
+
184
+ def answer(self, action_id: str, attempt_no: int, answer: Answer, vt: int) -> None:
185
+ self._both("answer", action_id, attempt_no, answer, vt)
186
+
187
+ def probe(self, action_id: str, result: ProbeAnswer, vt: int) -> None:
188
+ self._both("probe", action_id, result, vt)
189
+
190
+ def attest(
191
+ self, action_id: str, resolution: Resolution, effect_id: str | None, actor: str, vt: int
192
+ ) -> None:
193
+ self._both("attest", action_id, resolution, effect_id, actor, vt)
194
+
195
+ def restart(self, vt: int) -> None:
196
+ self._both("restart", vt)
197
+
198
+ def close_run(self, vt: int) -> None:
199
+ self._both("close_run", vt)