Skip to content

Commit a4f9389

Browse files
claudeclaude
committed
feat(formal/tla): TLA+ model of Invoker — isolation + classification coverage
Adds Invoker.tla: formal model of BojRest.Invoker (Phase 2 fork-per-request dispatcher). Invoker is stateless and synchronous — System.cmd blocks until boj-invoke exits, with no shared state between concurrent calls. Properties verified: - DoneOnce: each invocation resolves at most once (subprocess exits once; no race on resolution) - Consistent: running ↔ no result yet; done ↔ exactly one result - EventuallyDone [ASSUMED]: running ~> done under well-behaved CLI (noted gap: Phase 2 has no per-invocation timeout; ADR-0005 specifies 5 s for the future pool, not yet implemented) Non-vacuity: all 7 result kinds refuted by TLC (ReachOk through ReachInitFailed), proving every exit-code branch is reachable. Documents the known gap (no timeout in Phase 2 Invoker) and the future work (model the ADR-0005 GenServer pool checkout/backpressure when it lands). Formal coverage is now complete for all three Phase 2 Elixir components: - JsWorker.tla — single GenServer slot (ReplyOnce, EventuallyReplied) - JsWorkerPool.tla — N-slot pool (RouteConsistency, CrashIsolation) - Invoker.tla — stateless Zig-FFI dispatcher (DoneOnce, classification) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01F8pqMfJViUaKabWKNQ9wUg
1 parent 9fb8223 commit a4f9389

3 files changed

Lines changed: 256 additions & 3 deletions

File tree

‎specs/elixir-harness/Invoker.cfg‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
\* SPDX-License-Identifier: MPL-2.0
2+
\* Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
3+
\* TLC config for the Invoker model.
4+
\* Run: java -cp /path/to/tla2tools.jar tlc2.TLC Invoker.tla
5+
\*
6+
\* Three concurrent invocations — enough to exercise every interleaving of
7+
\* the eight terminal outcomes while keeping the state space small.
8+
CONSTANTS
9+
Requests = {r1, r2, r3}
10+
11+
SPECIFICATION Spec
12+
13+
INVARIANTS
14+
TypeOK
15+
DoneOnce
16+
Consistent
17+
18+
PROPERTIES
19+
EventuallyDone

‎specs/elixir-harness/Invoker.tla‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
------------------------------ MODULE Invoker ------------------------------
2+
\* SPDX-License-Identifier: MPL-2.0
3+
\* Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
(***************************************************************************)
5+
(* Formal model of `BojRest.Invoker` *)
6+
(* (elixir/lib/boj_rest/invoker.ex). *)
7+
(* *)
8+
(* Invoker is a STATELESS, SYNCHRONOUS dispatcher. Every call to *)
9+
(* Invoker.invoke/4 either short-circuits immediately (CLI binary not *)
10+
(* found → :cli_missing) or blocks on `System.cmd/3` until the `boj-invoke` *)
11+
(* OS subprocess exits. There is no GenServer, no pool, and no per- *)
12+
(* invocation timeout in the current Phase 2 implementation (ADR-0005). *)
13+
(* Because `System.cmd` is blocking, the caller's Erlang process is the *)
14+
(* only thing waiting — no shared mailbox, no shared ETS, no shared port. *)
15+
(* *)
16+
(* The headline property is ISOLATION: for any two concurrent invocations *)
17+
(* r1 ≠ r2, the outcome of r1 is entirely independent of r2. This is *)
18+
(* structurally guaranteed because every action in Next touches exactly one *)
19+
(* request id; DoneOnce and Consistent confirm no request is resolved twice. *)
20+
(* *)
21+
(* Exit-code → result classification (boj_invoke_cli.zig contract): *)
22+
(* CLI not found → cli_missing (no subprocess spawned) *)
23+
(* exit 0 + valid JSON → ok *)
24+
(* exit 0 + invalid JSON → cli_crashed (JSON parse failure) *)
25+
(* exit 2 → args_err *)
26+
(* exit 3 → open_err *)
27+
(* exit 4 → missing_symbol_err *)
28+
(* exit 5 → init_failed_err *)
29+
(* exit other → cli_crashed *)
30+
(* *)
31+
(* Note on timeouts: the current code has NO per-invocation timeout. *)
32+
(* `System.cmd` blocks indefinitely if the subprocess hangs. ADR-0005 *)
33+
(* specifies 5 s (future pool) but the Phase 2 skeleton does not implement *)
34+
(* it. The liveness property below (EventuallyDone) therefore carries an *)
35+
(* [ASSUMED] tag: it holds only if the `boj-invoke` subprocess eventually *)
36+
(* exits on its own. See README.adoc §"Known gaps". *)
37+
(***************************************************************************)
38+
EXTENDS Naturals, FiniteSets
39+
40+
CONSTANTS Requests \* finite set of opaque invocation ids
41+
42+
Results == {"none", "ok", "cli_missing", "cli_crashed",
43+
"args_err", "open_err", "missing_symbol_err", "init_failed_err"}
44+
45+
VARIABLES
46+
status, \* [Requests -> {"new", "running", "done"}]
47+
result, \* [Requests -> Results]
48+
doneCount \* [Requests -> 0..2] (double-resolution detector)
49+
50+
vars == <<status, result, doneCount>>
51+
52+
TypeOK ==
53+
/\ status \in [Requests -> {"new", "running", "done"}]
54+
/\ result \in [Requests -> Results]
55+
/\ doneCount \in [Requests -> 0..2]
56+
57+
Init ==
58+
/\ status = [r \in Requests |-> "new"]
59+
/\ result = [r \in Requests |-> "none"]
60+
/\ doneCount = [r \in Requests |-> 0]
61+
62+
(*-------------------------- DISPATCH ACTIONS ----------------------------*)
63+
64+
\* Invoker.run/4 finds the CLI binary → spawns subprocess via System.cmd.
65+
\* Moves the request from "new" to "running" (subprocess is now live).
66+
Invoke(r) ==
67+
/\ status[r] = "new"
68+
/\ status' = [status EXCEPT ![r] = "running"]
69+
/\ UNCHANGED <<result, doneCount>>
70+
71+
\* Invoker.cli_path() returns nil → immediate short-circuit, no subprocess.
72+
\* The request goes from "new" directly to "done".
73+
CliMissing(r) ==
74+
/\ status[r] = "new"
75+
/\ status' = [status EXCEPT ![r] = "done"]
76+
/\ result' = [result EXCEPT ![r] = "cli_missing"]
77+
/\ doneCount' = [doneCount EXCEPT ![r] = @ + 1]
78+
79+
(*-------------------------- RESOLUTION ACTIONS --------------------------*)
80+
81+
\* The single guarded resolution path: status[r] = "running" guard +
82+
\* atomic move to "done" disables all competing resolution actions.
83+
\* (The subprocess can only exit once; the Erlang process unblocks once.)
84+
Resolve(r, kind) ==
85+
/\ status[r] = "running"
86+
/\ status' = [status EXCEPT ![r] = "done"]
87+
/\ result' = [result EXCEPT ![r] = kind]
88+
/\ doneCount' = [doneCount EXCEPT ![r] = @ + 1]
89+
90+
\* exit 0 + Jason.decode succeeds → {:ok, map}
91+
RespondOk(r) == Resolve(r, "ok")
92+
93+
\* exit 0 + Jason.decode fails, OR exit code not in {2,3,4,5} → :cli_crashed
94+
RespondCliCrashed(r) == Resolve(r, "cli_crashed")
95+
96+
\* exit 2 → :args
97+
RespondArgs(r) == Resolve(r, "args_err")
98+
99+
\* exit 3 → :open
100+
RespondOpen(r) == Resolve(r, "open_err")
101+
102+
\* exit 4 → :missing_symbol
103+
RespondMissingSym(r) == Resolve(r, "missing_symbol_err")
104+
105+
\* exit 5 → :init_failed
106+
RespondInitFailed(r) == Resolve(r, "init_failed_err")
107+
108+
Next ==
109+
\E r \in Requests :
110+
Invoke(r) \/ CliMissing(r) \/
111+
RespondOk(r) \/ RespondCliCrashed(r) \/ RespondArgs(r) \/
112+
RespondOpen(r) \/ RespondMissingSym(r) \/ RespondInitFailed(r)
113+
114+
\* [ASSUMED] Each subprocess eventually exits on its own (no timeout in
115+
\* Phase 2; the outer Cowboy connection timeout is the de-facto bound).
116+
\* WF_vars on the disjunction of all resolution actions captures: once
117+
\* a subprocess is running, some resolution action eventually fires.
118+
Spec ==
119+
/\ Init /\ [][Next]_vars
120+
/\ \A r \in Requests :
121+
WF_vars(RespondOk(r) \/ RespondCliCrashed(r) \/ RespondArgs(r) \/
122+
RespondOpen(r) \/ RespondMissingSym(r) \/ RespondInitFailed(r))
123+
124+
(*-------------------------------- SAFETY --------------------------------*)
125+
126+
\* Each invocation resolves at most once (no double System.cmd reply).
127+
DoneOnce == \A r \in Requests : doneCount[r] <= 1
128+
129+
Consistent ==
130+
/\ \A r \in Requests : (status[r] = "running") => (result[r] = "none")
131+
/\ \A r \in Requests : (status[r] = "done") => (result[r] # "none")
132+
/\ \A r \in Requests : (status[r] = "new") => (result[r] = "none")
133+
134+
(*------------------------------ LIVENESS --------------------------------*)
135+
136+
\* [ASSUMED] Once a subprocess is spawned, it eventually exits and the
137+
\* invocation resolves. Relies on well-behaved CLI + WF above.
138+
EventuallyDone ==
139+
\A r \in Requests : (status[r] = "running") ~> (status[r] = "done")
140+
141+
(*------------------------ SANITY CONTROLS (non-vacuity) ----------------*)
142+
\* Each of these is EXPECTED TO BE VIOLATED when checked as an invariant.
143+
\* TLC refutes them with short witness traces, proving every result kind is
144+
\* genuinely reachable. They are NOT in Invoker.cfg.
145+
ReachOk == \A r \in Requests : result[r] # "ok"
146+
ReachCliMissing == \A r \in Requests : result[r] # "cli_missing"
147+
ReachCliCrashed == \A r \in Requests : result[r] # "cli_crashed"
148+
ReachArgs == \A r \in Requests : result[r] # "args_err"
149+
ReachOpen == \A r \in Requests : result[r] # "open_err"
150+
ReachMissingSym == \A r \in Requests : result[r] # "missing_symbol_err"
151+
ReachInitFailed == \A r \in Requests : result[r] # "init_failed_err"
152+
153+
============================================================================

‎specs/elixir-harness/README.adoc‎

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -183,13 +183,94 @@ for inv in ReachOk ReachTimeout ReachCrashed ReachFallback; do
183183
printf 'CONSTANTS\n Requests = {r1, r2, r3}\n Workers = {w0, w1}\n Route = [r1 |-> w0, r2 |-> w1, r3 |-> w0]\nSPECIFICATION Spec\nINVARIANT %s\n' "$inv" > /tmp/ctrl.cfg
184184
java -cp tla2tools.jar tlc2.TLC -config /tmp/ctrl.cfg JsWorkerPool.tla
185185
done
186+
187+
# Sanity controls for Invoker — each EXPECTED to report "Invariant ... is violated"
188+
for inv in ReachOk ReachCliMissing ReachCliCrashed ReachArgs ReachOpen ReachMissingSym ReachInitFailed; do
189+
printf 'CONSTANTS Requests = {r1, r2, r3}\nSPECIFICATION Spec\nINVARIANT %s\n' "$inv" > /tmp/ctrl.cfg
190+
java -cp tla2tools.jar tlc2.TLC -config /tmp/ctrl.cfg Invoker.tla
191+
done
186192
----
187193

188194
`JsWorker.tla` verified with TLC 2026.05.26 (tla2tools) on OpenJDK 21:
189195
341 distinct states, search depth 8.
190196

197+
== Invoker.tla — models `BojRest.Invoker`
198+
199+
Source: `elixir/lib/boj_rest/invoker.ex`.
200+
`Invoker` is a *stateless, synchronous* dispatcher: every call either
201+
short-circuits immediately (CLI binary not found → `:cli_missing`) or blocks
202+
on `System.cmd/3` until the `boj-invoke` OS subprocess exits. There is no
203+
GenServer, no pool, and no per-invocation timeout in the Phase 2 implementation.
204+
205+
Because `System.cmd` is synchronous and each invocation spawns its own
206+
subprocess, there is **no shared mutable state** between concurrent calls.
207+
208+
=== Abstraction
209+
210+
* Requests are opaque ids.
211+
* The `boj-invoke` subprocess is a nondeterministic oracle: it may exit with
212+
any of the documented exit codes, or produce unparseable JSON on exit 0.
213+
* The CLI-missing short-circuit (`cli_path() == nil`) is modelled as
214+
`CliMissing(r)`, which resolves directly from `"new"` without spawning.
215+
* Out of scope: JSON encoding, the HTTP layer, and the Zig FFI internals.
216+
217+
=== Code → model mapping
218+
219+
[cols="1,1",options="header"]
220+
|===
221+
| `invoker.ex` | model action
222+
223+
| `Invoker.invoke/4` → `cli_path()` returns a path → `System.cmd` blocks
224+
| `Invoke(r)` (new → running)
225+
226+
| `cli_path()` returns `nil` → immediate `{:error, :cli_missing}`
227+
| `CliMissing(r)` (new → done)
228+
229+
| `System.cmd` returns `{stdout, 0}` + `Jason.decode` succeeds
230+
| `RespondOk(r)`
231+
232+
| `System.cmd` returns `{stdout, 0}` + `Jason.decode` fails, OR other exit
233+
| `RespondCliCrashed(r)`
234+
235+
| exit 2 / 3 / 4 / 5
236+
| `RespondArgs` / `RespondOpen` / `RespondMissingSym` / `RespondInitFailed`
237+
|===
238+
239+
=== Properties verified (TLC, `Requests = {r1, r2, r3}`)
240+
241+
Safety invariants:
242+
243+
* `DoneOnce` — each invocation resolves at most once. Since `System.cmd` is
244+
blocking and synchronous, the subprocess can only exit once; this invariant
245+
confirms no race condition can deliver two results for the same call.
246+
* `Consistent` — running ⟺ no result yet; done ⟺ exactly one result.
247+
248+
Liveness (tagged `[ASSUMED]` — see §"Known gaps"):
249+
250+
* `EventuallyDone` — every running invocation eventually resolves.
251+
Requires the subprocess to exit on its own; the Phase 2 code has no timeout.
252+
253+
=== Non-vacuity (sanity controls)
254+
255+
All seven result kinds (`ReachOk`, `ReachCliMissing`, `ReachCliCrashed`,
256+
`ReachArgs`, `ReachOpen`, `ReachMissingSym`, `ReachInitFailed`) are *refuted*
257+
by TLC with short witness traces, proving every exit-code branch is reachable
258+
and the invariants are not passing vacuously.
259+
260+
=== Known gaps
261+
262+
[ASSUMED] *No per-invocation timeout.* `System.cmd` blocks indefinitely if
263+
the `boj-invoke` subprocess hangs. ADR-0005 specifies a 5 s default for the
264+
future GenServer pool; the Phase 2 skeleton relies on the outer Cowboy
265+
connection timeout as the de-facto bound. `EventuallyDone` therefore rests on
266+
the assumption that the subprocess exits on its own.
267+
268+
[FUTURE] *Invoker pool (ADR-0005 Phase 3).* Once the GenServer pool lands,
269+
model its checkout/checkin FSM and backpressure — the interesting state machine
270+
is in the pool, not in the stateless Phase 2 skeleton.
271+
191272
== Not yet modelled (future work)
192273

193-
* **`Invoker`** (Zig-FFI path) is currently fork-per-request — *no pool yet*;
194-
the ADR-0005 OS-port pool is future work (waits on ADR-0006). Model the pool's
195-
checkout/backpressure when it lands.
274+
* **`Invoker` pool** — the ADR-0005 GenServer pool is not yet implemented.
275+
Model checkout/backpressure when it lands (waits on ADR-0006 + reference
276+
cartridge).

0 commit comments

Comments
 (0)