robolang 0.2.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.
- robolang/__init__.py +38 -0
- robolang/__main__.py +22 -0
- robolang/arch02/__init__.py +41 -0
- robolang/arch02/engine.py +537 -0
- robolang/arch02/evidence.py +55 -0
- robolang/arch02/participants.py +709 -0
- robolang/arch02/record.py +112 -0
- robolang/arch02/scenario.py +102 -0
- robolang/arch02/world.py +68 -0
- robolang/bridge.py +161 -0
- robolang/cli.py +956 -0
- robolang/core/__init__.py +58 -0
- robolang/core/canonical.py +95 -0
- robolang/core/reader.py +61 -0
- robolang/core/receiver.py +261 -0
- robolang/core/schema.py +154 -0
- robolang/core/schemas/capability-descriptor-0.1.schema.json +254 -0
- robolang/core/schemas/message-0.1.schema.json +1775 -0
- robolang/core/signatures.py +48 -0
- robolang/delegate.py +575 -0
- robolang/delegate_peer.py +88 -0
- robolang/diagnostics.py +77 -0
- robolang/export_goal.py +159 -0
- robolang/ir.py +434 -0
- robolang/ir_reader.py +710 -0
- robolang/lexer.py +184 -0
- robolang/nodes.py +323 -0
- robolang/parser.py +682 -0
- robolang/paths.py +40 -0
- robolang/reference/language-reference.md +223 -0
- robolang/sim/__init__.py +89 -0
- robolang/sim/check.py +85 -0
- robolang/sim/executor.py +500 -0
- robolang/sim/outcome.py +110 -0
- robolang/sim/record.py +202 -0
- robolang/sim/values.py +81 -0
- robolang/sim/world.py +569 -0
- robolang/tokens.py +73 -0
- robolang/validator.py +355 -0
- robolang-0.2.0.dist-info/METADATA +254 -0
- robolang-0.2.0.dist-info/RECORD +45 -0
- robolang-0.2.0.dist-info/WHEEL +5 -0
- robolang-0.2.0.dist-info/entry_points.txt +2 -0
- robolang-0.2.0.dist-info/licenses/LICENSE +201 -0
- robolang-0.2.0.dist-info/top_level.txt +1 -0
robolang/__init__.py
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""
|
|
2
|
+
RoboLang front end for languages 1.1, 1.2 and 1.3: lexer, parser, AST (RL-11B), static
|
|
3
|
+
validation (RL-11C), the versioned task IR (RL-11D; schema 1.1 for 1.2 sources, LANG-1b;
|
|
4
|
+
schema 1.2 for 1.3 sources),
|
|
5
|
+
and `robolang.sim`, the symbolic, simulation-only executor (RL-BASIC-01).
|
|
6
|
+
|
|
7
|
+
`check` / `check_file` run the complete front end and never execute anything. The package
|
|
8
|
+
is not connected to the v1 interpreter (`robolang_runtime`), to any adapter, ROS 2 or
|
|
9
|
+
hardware. A program that passes is well-formed, not safe to execute on a robot.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from . import ir, nodes
|
|
13
|
+
from .diagnostics import Diagnostic, RoboLangError, Severity
|
|
14
|
+
from .lexer import Lexer, tokenize
|
|
15
|
+
from .parser import DEFAULT_VERSION, SUPPORTED_VERSION, SUPPORTED_VERSIONS, ParseResult, parse, parse_file
|
|
16
|
+
from .tokens import Token, TokenKind
|
|
17
|
+
from .validator import check, check_file, validate
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"DEFAULT_VERSION",
|
|
21
|
+
"Diagnostic",
|
|
22
|
+
"Lexer",
|
|
23
|
+
"ParseResult",
|
|
24
|
+
"RoboLangError",
|
|
25
|
+
"Severity",
|
|
26
|
+
"SUPPORTED_VERSION",
|
|
27
|
+
"SUPPORTED_VERSIONS",
|
|
28
|
+
"Token",
|
|
29
|
+
"TokenKind",
|
|
30
|
+
"check",
|
|
31
|
+
"check_file",
|
|
32
|
+
"ir",
|
|
33
|
+
"nodes",
|
|
34
|
+
"parse",
|
|
35
|
+
"parse_file",
|
|
36
|
+
"tokenize",
|
|
37
|
+
"validate",
|
|
38
|
+
]
|
robolang/__main__.py
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Entry point for the robolang command (validate, inspect, simulate).
|
|
3
|
+
|
|
4
|
+
python -m robolang validate FILE.rob (with src/ on the import path)
|
|
5
|
+
python src/robolang validate FILE.rob (straight from a checkout, nothing installed)
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import sys
|
|
9
|
+
|
|
10
|
+
if __package__ in (None, ""):
|
|
11
|
+
# Started as `python src/robolang`: the package directory itself is on
|
|
12
|
+
# sys.path. Replace it with its parent so `robolang` imports as a package.
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
|
|
15
|
+
package_dir = Path(__file__).resolve().parent
|
|
16
|
+
sys.path[:] = [p for p in sys.path if p and Path(p).resolve() != package_dir]
|
|
17
|
+
sys.path.insert(0, str(package_dir.parent))
|
|
18
|
+
|
|
19
|
+
from robolang.cli import run
|
|
20
|
+
|
|
21
|
+
if __name__ == "__main__":
|
|
22
|
+
run()
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Reference simulation of the RFC-001 section 18 scenario (ARCH-2; spec/reference-simulation-v0.1.md).
|
|
3
|
+
|
|
4
|
+
One Python process, one symbolic world, four participants exchanging Core 0.1 messages that
|
|
5
|
+
`robolang.core` checks. SIMULATION ONLY: no transport, no network, no adapter, no ROS 2, no
|
|
6
|
+
hardware, no AI model. A run that ends `succeeded` says the participants followed Core 0.1 and
|
|
7
|
+
RFC-001 sections 9-13 consistently with a declared world; it is not evidence about real robots.
|
|
8
|
+
|
|
9
|
+
`simulate_case` runs one case and returns its run record (ARCH-3); the `robolang arch02`
|
|
10
|
+
command prints it.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from .engine import Delivery, Event, Reject, RunResult, SentMessage, Simulation, run_case
|
|
16
|
+
from .record import RUN_RECORD_SCHEMA, RUN_RECORD_SCHEMA_VERSION, run_id, simulate_case, to_json, to_record
|
|
17
|
+
from .scenario import ScenarioError, apply_overrides, load_scenario, ms, time_text
|
|
18
|
+
from .world import Fact, World
|
|
19
|
+
|
|
20
|
+
__all__ = [
|
|
21
|
+
"RUN_RECORD_SCHEMA",
|
|
22
|
+
"RUN_RECORD_SCHEMA_VERSION",
|
|
23
|
+
"Delivery",
|
|
24
|
+
"Event",
|
|
25
|
+
"Fact",
|
|
26
|
+
"Reject",
|
|
27
|
+
"RunResult",
|
|
28
|
+
"ScenarioError",
|
|
29
|
+
"SentMessage",
|
|
30
|
+
"Simulation",
|
|
31
|
+
"World",
|
|
32
|
+
"apply_overrides",
|
|
33
|
+
"load_scenario",
|
|
34
|
+
"ms",
|
|
35
|
+
"run_case",
|
|
36
|
+
"run_id",
|
|
37
|
+
"simulate_case",
|
|
38
|
+
"time_text",
|
|
39
|
+
"to_json",
|
|
40
|
+
"to_record",
|
|
41
|
+
]
|
|
@@ -0,0 +1,537 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The reference simulation engine (spec/reference-simulation-v0.1.md sections 3, 5, 8 and 10).
|
|
3
|
+
|
|
4
|
+
One shared simulated clock, an event queue ordered by time and then by insertion, message
|
|
5
|
+
delivery with a fixed latency, and the scripted faults. Every delivery gets a receipt: the
|
|
6
|
+
per-message Core 0.1 checks of `robolang.core` (stages 1-3), then duplicate and order handling,
|
|
7
|
+
then the meaning checks (stage 5: `C401`, `C402`, `C404`, then the participant's own state rules,
|
|
8
|
+
`C306` and `C403`).
|
|
9
|
+
|
|
10
|
+
Order follows decision record 0008: sequence numbers count per sender, recipient and
|
|
11
|
+
conversation; a message after a gap is held, with no effect, until the gap is filled or
|
|
12
|
+
`max_hold` has passed; a message that expires while held is rejected (`C301`).
|
|
13
|
+
|
|
14
|
+
SIMULATION ONLY. Nothing here opens a connection, loads an adapter or moves a robot: the
|
|
15
|
+
world is symbolic and every "motion" is a recorded event (decision R8).
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
import hashlib
|
|
20
|
+
import heapq
|
|
21
|
+
import json
|
|
22
|
+
from dataclasses import dataclass
|
|
23
|
+
from typing import Any, Callable
|
|
24
|
+
|
|
25
|
+
from ..core import Context, Key, check_meaning, check_message, sign_sim, time_ms
|
|
26
|
+
from .scenario import apply_overrides, keys_of, ms, time_text, trusted_key_refs
|
|
27
|
+
from .world import Fact, Sensor, World
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class Reject(Exception):
|
|
31
|
+
"""A participant refuses a message that passed the per-message checks (`C306`, `C403`)."""
|
|
32
|
+
|
|
33
|
+
def __init__(self, code: str):
|
|
34
|
+
super().__init__(code)
|
|
35
|
+
self.code = code
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class SentMessage:
|
|
40
|
+
index: int
|
|
41
|
+
t_sent_ms: int
|
|
42
|
+
document: dict
|
|
43
|
+
fate: str # delivered, dropped, injected
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass(frozen=True)
|
|
47
|
+
class Delivery:
|
|
48
|
+
t_ms: int
|
|
49
|
+
message: int # index into the sent messages
|
|
50
|
+
receiver: str
|
|
51
|
+
kind: str # original, duplicate, replay, resend, released (a held message leaving the hold)
|
|
52
|
+
receipt: str # accepted, duplicate, held, rejected, not_handled
|
|
53
|
+
code: str | None
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
@dataclass(frozen=True)
|
|
57
|
+
class Event:
|
|
58
|
+
t_ms: int
|
|
59
|
+
kind: str # motion, effect, observation, state, authorization, lease_expired, escalated, custody_committed
|
|
60
|
+
participant: str
|
|
61
|
+
detail: tuple[tuple[str, Any], ...]
|
|
62
|
+
|
|
63
|
+
def get(self, key: str, default=None):
|
|
64
|
+
return dict(self.detail).get(key, default)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
@dataclass(frozen=True)
|
|
68
|
+
class RunResult:
|
|
69
|
+
"""Everything the case expectations check; ARCH-3 serializes it as the run record."""
|
|
70
|
+
|
|
71
|
+
case: str
|
|
72
|
+
seed: str
|
|
73
|
+
sent: tuple[SentMessage, ...]
|
|
74
|
+
deliveries: tuple[Delivery, ...]
|
|
75
|
+
events: tuple[Event, ...]
|
|
76
|
+
planner_status: str | None
|
|
77
|
+
goal_states: tuple[tuple[str, str], ...] # (participant, final state of its goal)
|
|
78
|
+
custody: tuple[tuple[str, str], ...] # (participant, final local custody state)
|
|
79
|
+
commitments: tuple[tuple[str, str], ...] # (participant, final local commitment state)
|
|
80
|
+
designated_custody: tuple[tuple[str, str], ...] # (thing, responsible participant)
|
|
81
|
+
final_world: tuple[Fact, ...]
|
|
82
|
+
end_t_ms: int
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _message_id(sender: str, recipient: str, conversation: str, sequence: int) -> str:
|
|
86
|
+
"""Spec 5.2 as amended by decision record 0008, Q7: the recipient is part of the ID."""
|
|
87
|
+
text = f"robolang-arch02-msg/0.1-seq\n{sender}\n{recipient}\n{conversation}\n{sequence}"
|
|
88
|
+
return "m-" + hashlib.sha256(text.encode("utf-8")).hexdigest()[:32]
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def build_message(sender: str, recipient: str, conversation: str, sequence: int, mtype: str, profile: str,
|
|
92
|
+
payload: dict, in_reply_to: str | None, now_ms: int, ttl_ms: int, key: Key,
|
|
93
|
+
message_id: str | None = None) -> dict:
|
|
94
|
+
"""One signed Core 0.1 message as the reference participants build it (spec 5.2)."""
|
|
95
|
+
return sign_sim({
|
|
96
|
+
"schema": "robolang.core.message", "schema_version": "0.1",
|
|
97
|
+
"message_id": message_id or _message_id(sender, recipient, conversation, sequence),
|
|
98
|
+
"conversation_id": conversation, "sequence": sequence, "in_reply_to": in_reply_to,
|
|
99
|
+
"profile": profile, "type": mtype, "sender": sender, "recipient": recipient,
|
|
100
|
+
"sent_at": time_text(now_ms), "expires_at": time_text(now_ms + ttl_ms), "payload": payload,
|
|
101
|
+
}, f"{sender}#k1", key)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def build_observation(participant: str, number: int, thing: str, prop: str, value: Any, observed_at_ms: int,
|
|
105
|
+
sensor_name: str, valid_for: dict, confidence: str, method: str, key: Key) -> dict:
|
|
106
|
+
"""One signed observation (Core 5.6) made by `participant`, its `number`-th."""
|
|
107
|
+
return sign_sim({
|
|
108
|
+
"kind": "observation", "id": f"rl:obs:{participant.split(':')[-1]}:{number}", "subject": thing,
|
|
109
|
+
"property": prop, "value": value, "observed_at": time_text(observed_at_ms),
|
|
110
|
+
"valid_for": valid_for, "confidence": confidence,
|
|
111
|
+
"source": {"participant": participant, "sensor": sensor_name, "method": method},
|
|
112
|
+
}, f"{participant}#k1", key)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@dataclass
|
|
116
|
+
class _Held:
|
|
117
|
+
"""A message waiting for a gap in its stream (Core 8.4); it has had no effect yet."""
|
|
118
|
+
|
|
119
|
+
document: dict
|
|
120
|
+
ref: Any # how the host identifies the delivered message (the engine: its index)
|
|
121
|
+
held_at_ms: int
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
class Inbox:
|
|
125
|
+
"""
|
|
126
|
+
One receiver's handling of a delivered message: the Core 0.1 checks of `robolang.core`
|
|
127
|
+
(stages 1-3), then duplicates, order and holds (decision record 0008), then the stage-5
|
|
128
|
+
meaning checks and the participant's own rules (Core 8.1).
|
|
129
|
+
|
|
130
|
+
The host supplies time, timers and the participant: the engine for its in-process
|
|
131
|
+
participants, and the participant process of the `robolang-sim-stdio` binding for itself.
|
|
132
|
+
It provides `now`, `tolerance_ms`, `max_hold_ms`, `at`, `context`, `receipt`, `resend`,
|
|
133
|
+
`is_silent` and `hand_over`.
|
|
134
|
+
"""
|
|
135
|
+
|
|
136
|
+
def __init__(self, host, receiver: str):
|
|
137
|
+
self.host = host
|
|
138
|
+
self.receiver = receiver
|
|
139
|
+
# A stream is one sender, this recipient and one conversation (Core 3 and 8.4): its key here
|
|
140
|
+
# is (sender, conversation_id). Duplicates are judged by message ID per sender (8.4).
|
|
141
|
+
self._processed: dict[tuple[str, str], int] = {} # (sender, message_id) -> remembered until
|
|
142
|
+
self._next: dict[tuple[str, str], int] = {} # stream -> next expected sequence
|
|
143
|
+
self._held: dict[tuple[str, str], dict[int, _Held]] = {} # stream -> sequence -> held
|
|
144
|
+
|
|
145
|
+
def _record(self, ref, kind: str, receipt: str, code: str | None = None) -> None:
|
|
146
|
+
self.host.receipt(ref, self.receiver, kind, receipt, code)
|
|
147
|
+
|
|
148
|
+
def deliver(self, data: bytes, ref, kind: str) -> None:
|
|
149
|
+
host = self.host
|
|
150
|
+
receipt = check_message(data, host.context(self.receiver), meaning=False) # stage 5 after stage 4 (D7)
|
|
151
|
+
if not receipt.accepted:
|
|
152
|
+
return self._record(ref, kind, "rejected", receipt.code)
|
|
153
|
+
# Only a message that passed form, signature, freshness and recipient reaches this point:
|
|
154
|
+
# a rejected one is never held and does not count in its stream (0008, Q2).
|
|
155
|
+
document = json.loads(data)
|
|
156
|
+
sender, message_id = document["sender"], document["message_id"]
|
|
157
|
+
stream = (sender, document["conversation_id"])
|
|
158
|
+
held = self._held.setdefault(stream, {})
|
|
159
|
+
if ((sender, message_id) in self._processed and host.now <= self._processed[(sender, message_id)]) or any(
|
|
160
|
+
h.document["message_id"] == message_id
|
|
161
|
+
for key, entries in self._held.items() if key[0] == sender for h in entries.values()
|
|
162
|
+
):
|
|
163
|
+
self._record(ref, kind, "duplicate") # Q5: processed or held already; no second effect
|
|
164
|
+
host.resend(message_id) # the original reply is sent again
|
|
165
|
+
return
|
|
166
|
+
sequence = document["sequence"]
|
|
167
|
+
expected = self._next.get(stream, 1)
|
|
168
|
+
if sequence < expected:
|
|
169
|
+
return self._record(ref, kind, "rejected", "C306") # Q6: stale and not a duplicate
|
|
170
|
+
if sequence in held:
|
|
171
|
+
# Core 8.4, 0012 P2 (D6): a different message with the sequence of a held one. The held
|
|
172
|
+
# message keeps its place and gets its own single release receipt.
|
|
173
|
+
return self._record(ref, kind, "rejected", "C306")
|
|
174
|
+
if sequence > expected:
|
|
175
|
+
# Q3: held, with no effect and no reply, until the gap is filled, `max_hold` has
|
|
176
|
+
# passed (Q4) or the message expires (judged in the safe direction).
|
|
177
|
+
held[sequence] = _Held(document, ref, host.now)
|
|
178
|
+
self._record(ref, kind, "held")
|
|
179
|
+
expires_safe_ms = time_ms(document["expires_at"]) - host.tolerance_ms
|
|
180
|
+
host.at(expires_safe_ms, None, self._check_held, stream, sequence)
|
|
181
|
+
host.at(host.now + host.max_hold_ms, None, self._check_held, stream, sequence)
|
|
182
|
+
return
|
|
183
|
+
self._process(document, ref, kind)
|
|
184
|
+
self._drain(stream)
|
|
185
|
+
|
|
186
|
+
def _process(self, document: dict, ref, kind: str) -> None:
|
|
187
|
+
"""Hand a message that is next in its stream to the participant; the stream advances."""
|
|
188
|
+
sender = document["sender"]
|
|
189
|
+
self._next[(sender, document["conversation_id"])] = document["sequence"] + 1
|
|
190
|
+
if self.host.is_silent(self.receiver):
|
|
191
|
+
return self._record(ref, kind, "not_handled")
|
|
192
|
+
meaning = check_meaning(document, self.host.context(self.receiver))
|
|
193
|
+
if not meaning.accepted:
|
|
194
|
+
return self._record(ref, kind, "rejected", meaning.code) # not remembered: 0011 N13
|
|
195
|
+
try:
|
|
196
|
+
self.host.hand_over(self.receiver, document)
|
|
197
|
+
except Reject as rejection:
|
|
198
|
+
return self._record(ref, kind, "rejected", rejection.code)
|
|
199
|
+
expiry = time_ms(document["expires_at"]) + self.host.tolerance_ms
|
|
200
|
+
self._processed[(sender, document["message_id"])] = expiry
|
|
201
|
+
self._record(ref, kind, "accepted")
|
|
202
|
+
|
|
203
|
+
def _drain(self, stream: tuple[str, str]) -> None:
|
|
204
|
+
"""Process the held messages that the stream has now reached, in sequence order."""
|
|
205
|
+
held = self._held.get(stream, {})
|
|
206
|
+
while self._next.get(stream, 1) in held:
|
|
207
|
+
entry = held.pop(self._next[stream])
|
|
208
|
+
self._process(entry.document, entry.ref, "released")
|
|
209
|
+
|
|
210
|
+
def _check_held(self, stream: tuple[str, str], sequence: int) -> None:
|
|
211
|
+
"""End a hold that expired (`C301`) or reached `max_hold` (the gap is skipped)."""
|
|
212
|
+
entry = self._held.get(stream, {}).get(sequence)
|
|
213
|
+
if entry is None:
|
|
214
|
+
return # already released
|
|
215
|
+
now = self.host.now
|
|
216
|
+
if now >= time_ms(entry.document["expires_at"]) - self.host.tolerance_ms:
|
|
217
|
+
del self._held[stream][sequence]
|
|
218
|
+
self._record(entry.ref, "released", "rejected", "C301")
|
|
219
|
+
self._next[stream] = max(self._next.get(stream, 1), sequence + 1)
|
|
220
|
+
elif now >= entry.held_at_ms + self.host.max_hold_ms:
|
|
221
|
+
del self._held[stream][sequence]
|
|
222
|
+
self._process(entry.document, entry.ref, "released")
|
|
223
|
+
else:
|
|
224
|
+
return
|
|
225
|
+
self._drain(stream)
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def _matches(rule: dict, document: dict, count: int) -> bool:
|
|
229
|
+
return rule["type"] == document["type"] and rule["sender"] == document["sender"] and rule["n"] == count
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
@dataclass
|
|
233
|
+
class _Partition:
|
|
234
|
+
between: frozenset[str]
|
|
235
|
+
start_ms: int
|
|
236
|
+
until_ms: int
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
class Simulation:
|
|
240
|
+
"""
|
|
241
|
+
`external` maps a participant ID to a factory `(simulation, participant) -> proxy` that
|
|
242
|
+
replaces the in-process participant: the proxy is that participant (`start`, final states)
|
|
243
|
+
and its inbox (`deliver`). INTEROP-1 uses it for the `robolang-sim-stdio` binding.
|
|
244
|
+
"""
|
|
245
|
+
|
|
246
|
+
def __init__(self, scenario: dict, case: dict, external: dict[str, Callable] | None = None):
|
|
247
|
+
self.case = case
|
|
248
|
+
self.scenario = apply_overrides(scenario, case["faults"])
|
|
249
|
+
p = self.scenario["parameters"]
|
|
250
|
+
self.epoch_ms = time_ms(p["epoch"])
|
|
251
|
+
self.now = self.epoch_ms
|
|
252
|
+
self.latency_ms = ms(p["latency"])
|
|
253
|
+
self.ttl_ms = ms(p["message_ttl"])
|
|
254
|
+
self.max_lifetime_ms = ms(p["max_message_lifetime"])
|
|
255
|
+
self.tolerance_ms = ms(p["clock_tolerance"])
|
|
256
|
+
self.ack_timeout_ms = ms(p["ack_timeout"])
|
|
257
|
+
self.query_interval_ms = ms(p["query_interval"])
|
|
258
|
+
self.authority_delay_ms = ms(p["authority_delay"])
|
|
259
|
+
self.max_hold_ms = ms(p["max_hold"])
|
|
260
|
+
self.conversation = self.scenario["conversation_id"]
|
|
261
|
+
self.keys: dict[str, Key] = keys_of(self.scenario)
|
|
262
|
+
self.world = World(self.scenario["initial_facts"])
|
|
263
|
+
self.participants_config = {entry["id"]: entry for entry in self.scenario["participants"]}
|
|
264
|
+
self.sensors: dict[tuple[str, str], Sensor] = {}
|
|
265
|
+
for s in self.scenario["sensors"]:
|
|
266
|
+
self.sensors[(s["participant"], s["sensor"])] = Sensor(
|
|
267
|
+
s["participant"], s["sensor"], s["scope"], tuple(s["places"] or ()), s["valid_for"],
|
|
268
|
+
s["confidence"], s["method"],
|
|
269
|
+
)
|
|
270
|
+
self._queue: list = []
|
|
271
|
+
self._order = 0
|
|
272
|
+
self._sequence: dict[tuple[str, str], int] = {} # (sender, recipient) -> last sequence sent
|
|
273
|
+
self._type_counts: dict[tuple[str, str], int] = {}
|
|
274
|
+
self._observation_counts: dict[str, int] = {}
|
|
275
|
+
self._sent: list[SentMessage] = []
|
|
276
|
+
self._deliveries: list[Delivery] = []
|
|
277
|
+
self._events: list[Event] = []
|
|
278
|
+
self._replies: dict[str, list[int]] = {}
|
|
279
|
+
self._silent: set[str] = set()
|
|
280
|
+
self._partitions: list[_Partition] = []
|
|
281
|
+
self._apply_sensor_faults()
|
|
282
|
+
from .participants import build # participants need the engine; built last
|
|
283
|
+
self.participants = build(self)
|
|
284
|
+
# Receiver-scoped verification keys (spec 5.3, decision record 0013): amr-07's trust context.
|
|
285
|
+
self._trusted: dict[str, dict[str, Key]] = {
|
|
286
|
+
pid: {ref: self.keys[ref] for ref in trusted_key_refs(self.scenario, pid)}
|
|
287
|
+
for pid, participant in self.participants.items() if participant.scoped_trust
|
|
288
|
+
}
|
|
289
|
+
self.inboxes = {pid: Inbox(self, pid) for pid in self.participants}
|
|
290
|
+
for pid, factory in (external or {}).items():
|
|
291
|
+
self.participants[pid] = self.inboxes[pid] = factory(self, pid)
|
|
292
|
+
|
|
293
|
+
# -------- faults that act on sensors --------
|
|
294
|
+
|
|
295
|
+
def _apply_sensor_faults(self) -> None:
|
|
296
|
+
for fault in self.case["faults"]:
|
|
297
|
+
if fault["kind"] == "sensor_lag":
|
|
298
|
+
self.sensors[(fault["participant"], fault["sensor"])].lag_ms = ms(fault["lag"])
|
|
299
|
+
elif fault["kind"] == "sensor_unavailable":
|
|
300
|
+
self.sensors[(fault["participant"], fault["sensor"])].unavailable_from_ms = time_ms(fault["from"])
|
|
301
|
+
|
|
302
|
+
# -------- scheduling --------
|
|
303
|
+
|
|
304
|
+
def at(self, t_ms: int, owner: str | None, callback: Callable, *args) -> None:
|
|
305
|
+
"""Run `callback` at `t_ms`, unless `owner` has gone silent by then."""
|
|
306
|
+
self._order += 1
|
|
307
|
+
heapq.heappush(self._queue, (t_ms, self._order, owner, callback, args))
|
|
308
|
+
|
|
309
|
+
def after(self, delay_ms: int, owner: str | None, callback: Callable, *args) -> None:
|
|
310
|
+
self.at(self.now + delay_ms, owner, callback, *args)
|
|
311
|
+
|
|
312
|
+
def time(self) -> str:
|
|
313
|
+
return time_text(self.now)
|
|
314
|
+
|
|
315
|
+
def event(self, kind: str, participant: str, **detail) -> None:
|
|
316
|
+
self._events.append(Event(self.now, kind, participant, tuple(sorted(detail.items()))))
|
|
317
|
+
|
|
318
|
+
def is_silent(self, participant: str) -> bool:
|
|
319
|
+
return participant in self._silent
|
|
320
|
+
|
|
321
|
+
# -------- messages --------
|
|
322
|
+
|
|
323
|
+
def send(self, sender: str, mtype: str, profile: str, recipient: str, payload: dict,
|
|
324
|
+
in_reply_to: str | None = None, injected: bool = False,
|
|
325
|
+
sequence: int | None = None, message_id: str | None = None,
|
|
326
|
+
conversation: str | None = None) -> dict | None:
|
|
327
|
+
"""Send one message. An explicit `sequence`, `message_id` or `conversation` is only for injected messages."""
|
|
328
|
+
if sender in self._silent:
|
|
329
|
+
return None
|
|
330
|
+
if sequence is None:
|
|
331
|
+
sequence = self._sequence.get((sender, recipient), 0) + 1
|
|
332
|
+
self._sequence[(sender, recipient)] = sequence
|
|
333
|
+
document = build_message(sender, recipient, conversation or self.conversation, sequence, mtype, profile,
|
|
334
|
+
payload, in_reply_to, self.now, self.ttl_ms, self.keys[f"{sender}#k1"], message_id)
|
|
335
|
+
self._dispatch(document, injected)
|
|
336
|
+
return document
|
|
337
|
+
|
|
338
|
+
def send_document(self, document: dict) -> None:
|
|
339
|
+
"""Send a message an external participant built and signed itself (binding frame `send`)."""
|
|
340
|
+
sender, recipient = document["sender"], document["recipient"]
|
|
341
|
+
if sender in self._silent:
|
|
342
|
+
return
|
|
343
|
+
self._sequence[(sender, recipient)] = max(self._sequence.get((sender, recipient), 0), document["sequence"])
|
|
344
|
+
self._dispatch(document, False)
|
|
345
|
+
|
|
346
|
+
def _dispatch(self, document: dict, injected: bool) -> None:
|
|
347
|
+
"""Record one sent message, apply the faults that match it and schedule its deliveries."""
|
|
348
|
+
sender, recipient, mtype = document["sender"], document["recipient"], document["type"]
|
|
349
|
+
in_reply_to = document["in_reply_to"]
|
|
350
|
+
count = self._type_counts.get((sender, mtype), 0) + 1
|
|
351
|
+
self._type_counts[(sender, mtype)] = count
|
|
352
|
+
index = len(self._sent)
|
|
353
|
+
data = json.dumps(document).encode("utf-8")
|
|
354
|
+
delivery_ms = self.now + self.latency_ms
|
|
355
|
+
dropped = self._partitioned(sender, recipient)
|
|
356
|
+
for fault in self.case["faults"]:
|
|
357
|
+
rule = fault.get("match")
|
|
358
|
+
if rule is None or not _matches(rule, document, count):
|
|
359
|
+
continue
|
|
360
|
+
kind = fault["kind"]
|
|
361
|
+
if kind == "drop":
|
|
362
|
+
dropped = True
|
|
363
|
+
elif kind == "delay":
|
|
364
|
+
delivery_ms += ms(fault["by"])
|
|
365
|
+
elif kind == "strip_signature":
|
|
366
|
+
data = json.dumps({k: v for k, v in document.items() if k != "signature"}).encode("utf-8")
|
|
367
|
+
elif kind == "corrupt_signature":
|
|
368
|
+
altered = dict(document, signature=dict(document["signature"], value="0" * 64))
|
|
369
|
+
data = json.dumps(altered).encode("utf-8")
|
|
370
|
+
fate = "injected" if injected else ("dropped" if dropped else "delivered")
|
|
371
|
+
self._sent.append(SentMessage(index, self.now, document, fate))
|
|
372
|
+
if in_reply_to is not None:
|
|
373
|
+
self._replies.setdefault(in_reply_to, []).append(index)
|
|
374
|
+
if not dropped:
|
|
375
|
+
self.at(delivery_ms, None, self._deliver, data, index, "original")
|
|
376
|
+
for fault in self.case["faults"]:
|
|
377
|
+
rule = fault.get("match")
|
|
378
|
+
if rule is None or not _matches(rule, document, count):
|
|
379
|
+
continue
|
|
380
|
+
if fault["kind"] == "duplicate":
|
|
381
|
+
self.at(delivery_ms + ms(fault["after"]), None, self._deliver, data, index, "duplicate")
|
|
382
|
+
elif fault["kind"] == "replay":
|
|
383
|
+
self.at(time_ms(fault["at"]), None, self._deliver, data, index, "replay")
|
|
384
|
+
|
|
385
|
+
def _partitioned(self, a: str, b: str) -> bool:
|
|
386
|
+
return any(
|
|
387
|
+
p.between == frozenset((a, b)) and p.start_ms <= self.now < p.until_ms for p in self._partitions
|
|
388
|
+
)
|
|
389
|
+
|
|
390
|
+
def _start_rules(self, document: dict) -> None:
|
|
391
|
+
"""Silence and partitions start on the delivery of the message they name (spec section 10)."""
|
|
392
|
+
count = sum(1 for s in self._sent[: self._index_of(document) + 1]
|
|
393
|
+
if s.document["type"] == document["type"] and s.document["sender"] == document["sender"])
|
|
394
|
+
for fault in self.case["faults"]:
|
|
395
|
+
rule = fault.get("from")
|
|
396
|
+
if not isinstance(rule, dict) or not _matches(rule, document, count):
|
|
397
|
+
continue
|
|
398
|
+
if fault["kind"] == "silence":
|
|
399
|
+
self._silent.add(fault["participant"])
|
|
400
|
+
elif fault["kind"] == "partition":
|
|
401
|
+
self._partitions.append(_Partition(frozenset(fault["between"]), self.now, time_ms(fault["until"])))
|
|
402
|
+
|
|
403
|
+
def _index_of(self, document: dict) -> int:
|
|
404
|
+
return next(s.index for s in self._sent if s.document["message_id"] == document["message_id"]
|
|
405
|
+
and s.document["sender"] == document["sender"])
|
|
406
|
+
|
|
407
|
+
def _deliver(self, data: bytes, index: int, kind: str) -> None:
|
|
408
|
+
sent = self._sent[index].document
|
|
409
|
+
receiver = sent["recipient"]
|
|
410
|
+
if kind == "original":
|
|
411
|
+
self._start_rules(sent)
|
|
412
|
+
if receiver in self._silent:
|
|
413
|
+
return self.receipt(index, receiver, kind, "not_handled", None)
|
|
414
|
+
self.inboxes[receiver].deliver(data, index, kind)
|
|
415
|
+
|
|
416
|
+
# -------- the inbox host (Inbox) --------
|
|
417
|
+
|
|
418
|
+
def context(self, receiver: str) -> Context:
|
|
419
|
+
"""The receiver's Core 8 context, with the keys of its trust context (spec 5.3)."""
|
|
420
|
+
return Context(receiver, self.now, self.tolerance_ms, self.max_lifetime_ms,
|
|
421
|
+
self._trusted.get(receiver, self.keys), self.scenario["authorities"], "simulation")
|
|
422
|
+
|
|
423
|
+
def receipt(self, index: int, receiver: str, kind: str, receipt: str, code: str | None) -> None:
|
|
424
|
+
self._deliveries.append(Delivery(self.now, index, receiver, kind, receipt, code))
|
|
425
|
+
|
|
426
|
+
def resend(self, message_id: str) -> None:
|
|
427
|
+
"""A duplicate was received: the replies already sent to it are sent again (0008, Q5)."""
|
|
428
|
+
for reply in self._replies.get(message_id, []):
|
|
429
|
+
reply_doc = self._sent[reply].document
|
|
430
|
+
self.after(self.latency_ms, None, self._deliver, json.dumps(reply_doc).encode("utf-8"), reply, "resend")
|
|
431
|
+
|
|
432
|
+
def hand_over(self, receiver: str, document: dict) -> None:
|
|
433
|
+
self.participants[receiver].handle(document)
|
|
434
|
+
|
|
435
|
+
# -------- world --------
|
|
436
|
+
|
|
437
|
+
def start_action(self, participant: str, action: str, duration_ms: int, effect: Callable[[], None],
|
|
438
|
+
done: Callable[[], None], **args) -> bool:
|
|
439
|
+
"""Start an action: one motion event now, its effect and `done` after `duration_ms`."""
|
|
440
|
+
if participant in self._silent:
|
|
441
|
+
return False
|
|
442
|
+
self.event("motion", participant, action=action, **args)
|
|
443
|
+
|
|
444
|
+
def finish() -> None:
|
|
445
|
+
effect()
|
|
446
|
+
self.event("effect", participant, action=action, **args)
|
|
447
|
+
done()
|
|
448
|
+
|
|
449
|
+
self.after(duration_ms, participant, finish)
|
|
450
|
+
return True
|
|
451
|
+
|
|
452
|
+
def move(self, participant: str, to: str, done: Callable[[], None]) -> bool:
|
|
453
|
+
"""Move `participant` to `to`, taking the scenario's duration (spec section 3)."""
|
|
454
|
+
from .participants import duration
|
|
455
|
+
here = self.world.get(participant, "located_in")
|
|
456
|
+
return self.start_action(participant, "move", duration(self, "move", here, to),
|
|
457
|
+
lambda: self.world.set(participant, "located_in", to), done, to=to)
|
|
458
|
+
|
|
459
|
+
def sense(self, participant: str, sensor_name: str, thing: str, prop: str) -> tuple[Any, int, int] | None:
|
|
460
|
+
"""
|
|
461
|
+
What one sensor reads now, as (value, observed_at in ms, the participant's observation
|
|
462
|
+
number), recorded as an observation event; None if the sensor cannot make one.
|
|
463
|
+
"""
|
|
464
|
+
sensor = self.sensors[(participant, sensor_name)]
|
|
465
|
+
if not sensor.available(self.now) or not sensor.sees(self.world, thing):
|
|
466
|
+
return None
|
|
467
|
+
value = self.world.get(thing, prop)
|
|
468
|
+
if value is None:
|
|
469
|
+
return None
|
|
470
|
+
number = self._observation_counts.get(participant, 0) + 1
|
|
471
|
+
self._observation_counts[participant] = number
|
|
472
|
+
self.event("observation", participant, id=f"rl:obs:{participant.split(':')[-1]}:{number}",
|
|
473
|
+
subject=thing, property=prop, value=value)
|
|
474
|
+
return value, self.now - sensor.lag_ms, number
|
|
475
|
+
|
|
476
|
+
def observe(self, participant: str, sensor_name: str, thing: str, prop: str) -> dict | None:
|
|
477
|
+
"""A signed observation of `thing` by one sensor, or None if the sensor cannot make one."""
|
|
478
|
+
reading = self.sense(participant, sensor_name, thing, prop)
|
|
479
|
+
if reading is None:
|
|
480
|
+
return None
|
|
481
|
+
value, observed_at_ms, number = reading
|
|
482
|
+
sensor = self.sensors[(participant, sensor_name)]
|
|
483
|
+
return build_observation(participant, number, thing, prop, value, observed_at_ms, sensor_name,
|
|
484
|
+
sensor.valid_for, sensor.confidence, sensor.method,
|
|
485
|
+
self.keys[f"{participant}#k1"])
|
|
486
|
+
|
|
487
|
+
# -------- run --------
|
|
488
|
+
|
|
489
|
+
def run(self) -> RunResult:
|
|
490
|
+
for fault in self.case["faults"]:
|
|
491
|
+
if fault["kind"] == "inject":
|
|
492
|
+
self.at(time_ms(fault["at"]), None, self._inject, fault["message"])
|
|
493
|
+
for participant in self.participants.values():
|
|
494
|
+
participant.start()
|
|
495
|
+
while self._queue:
|
|
496
|
+
t_ms, _, owner, callback, args = heapq.heappop(self._queue)
|
|
497
|
+
self.now = t_ms
|
|
498
|
+
if owner is not None and owner in self._silent:
|
|
499
|
+
continue
|
|
500
|
+
callback(*args)
|
|
501
|
+
return self._result()
|
|
502
|
+
|
|
503
|
+
def _inject(self, message: dict) -> None:
|
|
504
|
+
self.send(message["sender"], message["type"], message["profile"], message["recipient"],
|
|
505
|
+
message["payload"], injected=True,
|
|
506
|
+
sequence=message.get("sequence"), message_id=message.get("message_id"),
|
|
507
|
+
conversation=message.get("conversation_id"))
|
|
508
|
+
|
|
509
|
+
def _result(self) -> RunResult:
|
|
510
|
+
designated = dict(self.scenario["initial_custody"])
|
|
511
|
+
for event in self._events:
|
|
512
|
+
if event.kind == "custody_committed":
|
|
513
|
+
designated[event.get("thing")] = event.participant
|
|
514
|
+
planner = self.participants[self.scenario["goal"]["requested_by"]]
|
|
515
|
+
return RunResult(
|
|
516
|
+
case=self.case["id"],
|
|
517
|
+
seed=self.case.get("seed", "0"),
|
|
518
|
+
sent=tuple(self._sent),
|
|
519
|
+
deliveries=tuple(self._deliveries),
|
|
520
|
+
events=tuple(self._events),
|
|
521
|
+
planner_status=planner.status,
|
|
522
|
+
goal_states=tuple(sorted((pid, p.goal_state) for pid, p in self.participants.items()
|
|
523
|
+
if getattr(p, "goal_state", None))),
|
|
524
|
+
custody=tuple(sorted((pid, p.custody) for pid, p in self.participants.items()
|
|
525
|
+
if getattr(p, "custody", None))),
|
|
526
|
+
commitments=tuple(sorted((pid, p.commitment_state) for pid, p in self.participants.items()
|
|
527
|
+
if getattr(p, "commitment_state", None))),
|
|
528
|
+
designated_custody=tuple(sorted(designated.items())),
|
|
529
|
+
final_world=self.world.facts(),
|
|
530
|
+
end_t_ms=max([s.t_sent_ms for s in self._sent] + [d.t_ms for d in self._deliveries]
|
|
531
|
+
+ [e.t_ms for e in self._events]),
|
|
532
|
+
)
|
|
533
|
+
|
|
534
|
+
|
|
535
|
+
def run_case(scenario: dict, case: dict) -> RunResult:
|
|
536
|
+
"""Run one case of tests/fixtures/arch02/cases.json against a scenario."""
|
|
537
|
+
return Simulation(scenario, case).run()
|