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,372 @@
|
|
|
1
|
+
"""Gateway records to and from JSON, for the `jsonb` columns of the `gw` schema.
|
|
2
|
+
|
|
3
|
+
Decoding gives back records equal to the ones encoded, so the Postgres store's snapshots
|
|
4
|
+
compare equal to the in-memory store's. JSON has no tuples and no record types, so the
|
|
5
|
+
decoder restores them: lists become tuples, objects with exactly a stale fact's keys
|
|
6
|
+
become `StaleFact`, and other objects become read-only mappings. Enum values decode as
|
|
7
|
+
plain strings, except in event details, where the keys that hold enums (`trigger` and
|
|
8
|
+
`approval`) get their enum back, so decoded details are equal and of the same types.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import math
|
|
14
|
+
from collections.abc import Mapping, Sequence
|
|
15
|
+
from enum import StrEnum
|
|
16
|
+
from typing import cast
|
|
17
|
+
|
|
18
|
+
from fivefold.domain.contracts import Contract
|
|
19
|
+
from fivefold.gateway.records import (
|
|
20
|
+
ActionResult,
|
|
21
|
+
ApprovalStatus,
|
|
22
|
+
BasisCheck,
|
|
23
|
+
CheckRecord,
|
|
24
|
+
Claim,
|
|
25
|
+
ClaimConflict,
|
|
26
|
+
ClaimStatus,
|
|
27
|
+
Reconcile,
|
|
28
|
+
RecordedAction,
|
|
29
|
+
Refusal,
|
|
30
|
+
RefusalReason,
|
|
31
|
+
ReportAccepted,
|
|
32
|
+
StaleFact,
|
|
33
|
+
frozen,
|
|
34
|
+
)
|
|
35
|
+
from fivefold.gateway.state_machine import (
|
|
36
|
+
ActionState,
|
|
37
|
+
CheckKind,
|
|
38
|
+
EscalationTrigger,
|
|
39
|
+
Reason,
|
|
40
|
+
ReconcileHow,
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
JSON = object
|
|
44
|
+
"""A value `json.loads` can return."""
|
|
45
|
+
|
|
46
|
+
_STALE_KEYS = frozenset({"key", "cited_version", "current_version", "changed_fields"})
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class CodecError(ValueError):
|
|
50
|
+
"""Stored JSON does not have the shape a record needs."""
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
# Generic values ------------------------------------------------------------------------
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def to_json(value: object) -> JSON:
|
|
57
|
+
"""Encode a detail value, an argument or a basis as JSON-compatible data."""
|
|
58
|
+
if isinstance(value, StaleFact):
|
|
59
|
+
return {
|
|
60
|
+
"key": value.key,
|
|
61
|
+
"cited_version": value.cited_version,
|
|
62
|
+
"current_version": value.current_version,
|
|
63
|
+
"changed_fields": list(value.changed_fields),
|
|
64
|
+
}
|
|
65
|
+
if isinstance(value, StrEnum):
|
|
66
|
+
return str(value)
|
|
67
|
+
if value is None or isinstance(value, str | int | bool):
|
|
68
|
+
return value
|
|
69
|
+
if isinstance(value, Mapping):
|
|
70
|
+
return {str(key): to_json(item) for key, item in value.items()}
|
|
71
|
+
if isinstance(value, tuple | list):
|
|
72
|
+
return [to_json(item) for item in value]
|
|
73
|
+
raise CodecError(f"cannot store {type(value).__name__} as JSON")
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def from_json(data: JSON) -> object:
|
|
77
|
+
"""Decode what `to_json` wrote: tuples, stale facts and read-only mappings."""
|
|
78
|
+
if isinstance(data, list):
|
|
79
|
+
return tuple(from_json(item) for item in data)
|
|
80
|
+
if isinstance(data, dict):
|
|
81
|
+
if data.keys() == _STALE_KEYS:
|
|
82
|
+
return _stale(data)
|
|
83
|
+
return frozen({str(key): from_json(item) for key, item in data.items()})
|
|
84
|
+
if data is None or isinstance(data, str | int | bool):
|
|
85
|
+
return data
|
|
86
|
+
raise CodecError(f"unexpected JSON value {data!r}")
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
_DETAIL_ENUMS: Mapping[str, type[StrEnum]] = {
|
|
90
|
+
"trigger": EscalationTrigger,
|
|
91
|
+
"approval": ApprovalStatus,
|
|
92
|
+
}
|
|
93
|
+
"""Event detail keys whose values are enum members."""
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def storable(value: object) -> JSON:
|
|
97
|
+
"""Arguments an agent sent, as JSON that every store can hold and give back unchanged.
|
|
98
|
+
|
|
99
|
+
PostgreSQL text cannot hold a NUL character and `jsonb` has no NaN or infinity, so a
|
|
100
|
+
NUL becomes U+FFFD and a number that is not finite becomes its name as text.
|
|
101
|
+
"""
|
|
102
|
+
if isinstance(value, str):
|
|
103
|
+
return value.replace("\x00", "\ufffd")
|
|
104
|
+
if isinstance(value, float) and not math.isfinite(value):
|
|
105
|
+
return str(value)
|
|
106
|
+
if value is None or isinstance(value, bool | int | float):
|
|
107
|
+
return value
|
|
108
|
+
if isinstance(value, Mapping):
|
|
109
|
+
return {str(storable(str(key))): storable(item) for key, item in value.items()}
|
|
110
|
+
if isinstance(value, list | tuple):
|
|
111
|
+
return [storable(item) for item in value]
|
|
112
|
+
return str(storable(repr(value)))
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def plain_from_json(data: JSON) -> object:
|
|
116
|
+
"""Decoded JSON with arrays as tuples and objects as read-only mappings."""
|
|
117
|
+
if isinstance(data, Mapping):
|
|
118
|
+
return frozen({str(key): plain_from_json(item) for key, item in data.items()})
|
|
119
|
+
if isinstance(data, list | tuple):
|
|
120
|
+
return tuple(plain_from_json(item) for item in data)
|
|
121
|
+
return data
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def mapping_from_json(data: JSON) -> Mapping[str, object]:
|
|
125
|
+
"""Decode a JSON object, such as an event's details, restoring enum members."""
|
|
126
|
+
decoded = from_json(data)
|
|
127
|
+
if not isinstance(decoded, Mapping):
|
|
128
|
+
raise CodecError(f"expected a JSON object, found {data!r}")
|
|
129
|
+
restored = dict(decoded)
|
|
130
|
+
for key, enum in _DETAIL_ENUMS.items():
|
|
131
|
+
value = restored.get(key)
|
|
132
|
+
if isinstance(value, str):
|
|
133
|
+
restored[key] = enum(value)
|
|
134
|
+
return frozen(restored)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def args_from_json(data: JSON) -> Mapping[str, str | int]:
|
|
138
|
+
"""Decode an action's business arguments."""
|
|
139
|
+
values = _object(data)
|
|
140
|
+
for key, item in values.items():
|
|
141
|
+
if not isinstance(item, str | int) or isinstance(item, bool):
|
|
142
|
+
raise CodecError(f"argument {key} must be text or an integer")
|
|
143
|
+
return frozen(cast(dict[str, str | int], values))
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def versions_from_json(data: JSON) -> Mapping[str, int]:
|
|
147
|
+
"""Decode a basis: fact key to version."""
|
|
148
|
+
values = _object(data)
|
|
149
|
+
for key, item in values.items():
|
|
150
|
+
if not isinstance(item, int) or isinstance(item, bool):
|
|
151
|
+
raise CodecError(f"version of {key} must be an integer")
|
|
152
|
+
return frozen(cast(dict[str, int], values))
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
# Checks ----------------------------------------------------------------------------------
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def basis_to_json(basis: BasisCheck | None) -> JSON:
|
|
159
|
+
"""Encode the basis part of a check."""
|
|
160
|
+
if basis is None:
|
|
161
|
+
return None
|
|
162
|
+
return {
|
|
163
|
+
"exact_ok": basis.exact_ok,
|
|
164
|
+
"sufficient_ok": basis.sufficient_ok,
|
|
165
|
+
"versions_seen": to_json(basis.versions_seen),
|
|
166
|
+
"stale": to_json(basis.stale),
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def check_from_columns(
|
|
171
|
+
kind: str,
|
|
172
|
+
approval: str | None,
|
|
173
|
+
basis: JSON,
|
|
174
|
+
seen_seq: int,
|
|
175
|
+
check_vt: int,
|
|
176
|
+
approval_expires_at: int | None,
|
|
177
|
+
) -> CheckRecord:
|
|
178
|
+
"""Rebuild a check record from an attempt row's check columns."""
|
|
179
|
+
decoded: BasisCheck | None = None
|
|
180
|
+
if basis is not None:
|
|
181
|
+
values = _object(basis)
|
|
182
|
+
sufficient = values.get("sufficient_ok")
|
|
183
|
+
decoded = BasisCheck(
|
|
184
|
+
exact_ok=_bool(values.get("exact_ok")),
|
|
185
|
+
sufficient_ok=None if sufficient is None else _bool(sufficient),
|
|
186
|
+
versions_seen=versions_from_json(values.get("versions_seen", {})),
|
|
187
|
+
stale=tuple(_stale(item) for item in _list(values.get("stale", []))),
|
|
188
|
+
)
|
|
189
|
+
status = None if approval is None else ApprovalStatus(approval)
|
|
190
|
+
return CheckRecord(CheckKind(kind), status, decoded, seen_seq, check_vt, approval_expires_at)
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
# Responses -------------------------------------------------------------------------------
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def result_to_json(result: ActionResult | Refusal | ReportAccepted) -> JSON:
|
|
197
|
+
"""Encode a logged response in the shapes the agent sees (0003)."""
|
|
198
|
+
if isinstance(result, ActionResult):
|
|
199
|
+
reconcile = result.reconcile
|
|
200
|
+
return {
|
|
201
|
+
"result": "action",
|
|
202
|
+
"action_id": result.action_id,
|
|
203
|
+
"intent_id": result.intent_id,
|
|
204
|
+
"state": str(result.state),
|
|
205
|
+
"effect_id": result.effect_id,
|
|
206
|
+
"reason": str(result.reason),
|
|
207
|
+
"stale": to_json(result.stale),
|
|
208
|
+
"reconcile": None
|
|
209
|
+
if reconcile is None
|
|
210
|
+
else {
|
|
211
|
+
"contract": str(reconcile.contract),
|
|
212
|
+
"how": str(reconcile.how),
|
|
213
|
+
"escalation_id": reconcile.escalation_id,
|
|
214
|
+
"what": reconcile.what,
|
|
215
|
+
},
|
|
216
|
+
}
|
|
217
|
+
if isinstance(result, Refusal):
|
|
218
|
+
return {
|
|
219
|
+
"result": "refused",
|
|
220
|
+
"reason": str(result.reason),
|
|
221
|
+
"action_id": result.action_id,
|
|
222
|
+
"state": None if result.state is None else str(result.state),
|
|
223
|
+
"effect_id": result.effect_id,
|
|
224
|
+
"args": None if result.args is None else to_json(result.args),
|
|
225
|
+
"conflicts": [
|
|
226
|
+
{
|
|
227
|
+
"intent_id": conflict.intent_id,
|
|
228
|
+
"claimed": str(conflict.claimed),
|
|
229
|
+
"claimed_effect_ids": list(conflict.claimed_effect_ids),
|
|
230
|
+
"recorded": [
|
|
231
|
+
{
|
|
232
|
+
"action_id": recorded.action_id,
|
|
233
|
+
"state": str(recorded.state),
|
|
234
|
+
"effect_ids": list(recorded.effect_ids),
|
|
235
|
+
}
|
|
236
|
+
for recorded in conflict.recorded
|
|
237
|
+
],
|
|
238
|
+
}
|
|
239
|
+
for conflict in result.conflicts
|
|
240
|
+
],
|
|
241
|
+
"unknown_reads": list(result.unknown_reads),
|
|
242
|
+
"missing_keys": list(result.missing_keys),
|
|
243
|
+
"message": result.message,
|
|
244
|
+
}
|
|
245
|
+
return {"result": "accepted", "claims": [_claim_to_json(claim) for claim in result.claims]}
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
def result_from_json(data: JSON) -> ActionResult | Refusal | ReportAccepted:
|
|
249
|
+
"""Decode a logged response."""
|
|
250
|
+
values = _object(data)
|
|
251
|
+
kind = values.get("result")
|
|
252
|
+
if kind == "action":
|
|
253
|
+
reconcile_data = values.get("reconcile")
|
|
254
|
+
reconcile = None
|
|
255
|
+
if reconcile_data is not None:
|
|
256
|
+
r = _object(reconcile_data)
|
|
257
|
+
reconcile = Reconcile(
|
|
258
|
+
Contract(_str(r.get("contract"))),
|
|
259
|
+
ReconcileHow(_str(r.get("how"))),
|
|
260
|
+
_optional_str(r.get("escalation_id")),
|
|
261
|
+
_str(r.get("what")),
|
|
262
|
+
)
|
|
263
|
+
return ActionResult(
|
|
264
|
+
_str(values.get("action_id")),
|
|
265
|
+
_str(values.get("intent_id")),
|
|
266
|
+
ActionState(_str(values.get("state"))),
|
|
267
|
+
_optional_str(values.get("effect_id")),
|
|
268
|
+
Reason(_str(values.get("reason"))),
|
|
269
|
+
tuple(_stale(item) for item in _list(values.get("stale", []))),
|
|
270
|
+
reconcile,
|
|
271
|
+
)
|
|
272
|
+
if kind == "refused":
|
|
273
|
+
state = values.get("state")
|
|
274
|
+
args = values.get("args")
|
|
275
|
+
return Refusal(
|
|
276
|
+
RefusalReason(_str(values.get("reason"))),
|
|
277
|
+
_optional_str(values.get("action_id")),
|
|
278
|
+
None if state is None else ActionState(_str(state)),
|
|
279
|
+
_optional_str(values.get("effect_id")),
|
|
280
|
+
None if args is None else args_from_json(args),
|
|
281
|
+
tuple(_conflict(item) for item in _list(values.get("conflicts", []))),
|
|
282
|
+
tuple(_str(item) for item in _list(values.get("unknown_reads", []))),
|
|
283
|
+
tuple(_str(item) for item in _list(values.get("missing_keys", []))),
|
|
284
|
+
_str(values.get("message", "")),
|
|
285
|
+
)
|
|
286
|
+
if kind == "accepted":
|
|
287
|
+
return ReportAccepted(tuple(_claim(item) for item in _list(values.get("claims", []))))
|
|
288
|
+
raise CodecError(f"unknown response kind {kind!r}")
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
def _claim_to_json(claim: Claim) -> JSON:
|
|
292
|
+
return {
|
|
293
|
+
"intent_id": claim.intent_id,
|
|
294
|
+
"status": str(claim.status),
|
|
295
|
+
"effect_ids": list(claim.effect_ids),
|
|
296
|
+
"note": claim.note,
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
def _claim(data: JSON) -> Claim:
|
|
301
|
+
values = _object(data)
|
|
302
|
+
return Claim(
|
|
303
|
+
_str(values.get("intent_id")),
|
|
304
|
+
ClaimStatus(_str(values.get("status"))),
|
|
305
|
+
tuple(_str(item) for item in _list(values.get("effect_ids", []))),
|
|
306
|
+
_str(values.get("note", "")),
|
|
307
|
+
)
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
def _conflict(data: JSON) -> ClaimConflict:
|
|
311
|
+
values = _object(data)
|
|
312
|
+
recorded = tuple(
|
|
313
|
+
RecordedAction(
|
|
314
|
+
_str(item.get("action_id")),
|
|
315
|
+
ActionState(_str(item.get("state"))),
|
|
316
|
+
tuple(_str(e) for e in _list(item.get("effect_ids", []))),
|
|
317
|
+
)
|
|
318
|
+
for item in (_object(entry) for entry in _list(values.get("recorded", [])))
|
|
319
|
+
)
|
|
320
|
+
return ClaimConflict(
|
|
321
|
+
_str(values.get("intent_id")),
|
|
322
|
+
ClaimStatus(_str(values.get("claimed"))),
|
|
323
|
+
tuple(_str(item) for item in _list(values.get("claimed_effect_ids", []))),
|
|
324
|
+
recorded,
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
# Checked access to decoded JSON ------------------------------------------------------------
|
|
329
|
+
|
|
330
|
+
|
|
331
|
+
def _stale(data: JSON) -> StaleFact:
|
|
332
|
+
values = _object(data)
|
|
333
|
+
return StaleFact(
|
|
334
|
+
_str(values.get("key")),
|
|
335
|
+
_int(values.get("cited_version")),
|
|
336
|
+
_int(values.get("current_version")),
|
|
337
|
+
tuple(_str(item) for item in _list(values.get("changed_fields", []))),
|
|
338
|
+
)
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
def _object(data: JSON) -> dict[str, object]:
|
|
342
|
+
if not isinstance(data, dict):
|
|
343
|
+
raise CodecError(f"expected a JSON object, found {data!r}")
|
|
344
|
+
return {str(key): item for key, item in data.items()}
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
def _list(data: JSON) -> Sequence[object]:
|
|
348
|
+
if not isinstance(data, list | tuple):
|
|
349
|
+
raise CodecError(f"expected a JSON array, found {data!r}")
|
|
350
|
+
return data
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def _str(data: JSON) -> str:
|
|
354
|
+
if not isinstance(data, str):
|
|
355
|
+
raise CodecError(f"expected text, found {data!r}")
|
|
356
|
+
return data
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
def _optional_str(data: JSON) -> str | None:
|
|
360
|
+
return None if data is None else _str(data)
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def _int(data: JSON) -> int:
|
|
364
|
+
if not isinstance(data, int) or isinstance(data, bool):
|
|
365
|
+
raise CodecError(f"expected an integer, found {data!r}")
|
|
366
|
+
return data
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
def _bool(data: JSON) -> bool:
|
|
370
|
+
if not isinstance(data, bool):
|
|
371
|
+
raise CodecError(f"expected true or false, found {data!r}")
|
|
372
|
+
return data
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
"""What the gateway asks the world: facts, approvals and the destination (0002, 0003, 0005).
|
|
2
|
+
|
|
3
|
+
The dispatcher reaches the simulator only through this protocol, so its logic can be
|
|
4
|
+
tested with a stand-in and the gateway never imports the simulator (0008). The real
|
|
5
|
+
implementation sends each request on the `gw_sim` hop.
|
|
6
|
+
|
|
7
|
+
Every method may raise `Unreachable`: no answer arrived in time, or the answer was a
|
|
8
|
+
server error. The dispatcher then tries again later and changes nothing. A write is the
|
|
9
|
+
exception: `send` always returns an `Answer`, because a timeout or a server error after
|
|
10
|
+
a send is itself evidence, and moves the action to OutcomeUnknown (0003).
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from collections.abc import Mapping, Sequence
|
|
16
|
+
from dataclasses import dataclass
|
|
17
|
+
from typing import Protocol
|
|
18
|
+
|
|
19
|
+
from fivefold.gateway.records import Action, Answer, ApprovalStatus, Attempt, ProbeAnswer
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class Unreachable(Exception):
|
|
23
|
+
"""A check's request got no usable answer in time; nothing was learned."""
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass(frozen=True)
|
|
27
|
+
class FactNow:
|
|
28
|
+
"""A fact as the simulator holds it now: its key, version and value."""
|
|
29
|
+
|
|
30
|
+
key: str
|
|
31
|
+
version: int
|
|
32
|
+
value: Mapping[str, object]
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass(frozen=True)
|
|
36
|
+
class ApprovalNow:
|
|
37
|
+
"""An approval as the approvals service reports it now (0002)."""
|
|
38
|
+
|
|
39
|
+
approval_id: str
|
|
40
|
+
status: ApprovalStatus
|
|
41
|
+
expires_at: int | None
|
|
42
|
+
"""When an approved approval expires; None unless it is approved."""
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class Destination(Protocol):
|
|
46
|
+
"""The gateway's view of the simulator's API."""
|
|
47
|
+
|
|
48
|
+
async def facts(self, keys: Sequence[str]) -> Mapping[str, FactNow]:
|
|
49
|
+
"""The current version and value of each fact."""
|
|
50
|
+
|
|
51
|
+
async def request_approval(self, action: Action) -> ApprovalNow:
|
|
52
|
+
"""File the action's approval request, keyed by its action id, and return the
|
|
53
|
+
policy's immediate answer (0002). Filing again returns the same approval."""
|
|
54
|
+
|
|
55
|
+
async def approval(self, approval_id: str) -> ApprovalNow:
|
|
56
|
+
"""The approval's status now."""
|
|
57
|
+
|
|
58
|
+
async def send(self, action: Action, attempt: Attempt, approval_id: str) -> Answer:
|
|
59
|
+
"""Send one attempt of the write, citing the action's approval, and classify the
|
|
60
|
+
answer (0003). A timeout, a transport error or a server error gives an unknown
|
|
61
|
+
answer."""
|
|
62
|
+
|
|
63
|
+
async def lookup(self, action: Action) -> ProbeAnswer:
|
|
64
|
+
"""C1: which effects exist for the action's intent, and as of when (0005)."""
|