Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Model effort and asynchronous tool lifecycles

Rach Pradhan7158d62e37a9
diff --git a/formal/AsyncTools.cfg b/formal/AsyncTools.cfg
new file mode 100644
index 00000000..3730406f
--- /dev/null
+++ b/formal/AsyncTools.cfg
@@ -0,0 +1,16 @@
+SPECIFICATION Spec
+CONSTANTS IDs = {a, b}
+ BypassJoin = FALSE
+ BypassDedup = FALSE
+ BypassBarrier = FALSE
+INVARIANTS TypeOK
+ OnlyCompleteItemsRun
+ AtMostOnceExecution
+ AtMostOnceHistory
+ AtMostOnceDelivery
+ JoinedBeforeNextRequest
+ NoLiveWorkerAfterReset
+ NoReplayAfterAdmission
+ DeliveryHasOriginalAdmission
+ NoLateAdmission
+PROPERTIES NormalEventuallyDelivers
diff --git a/formal/AsyncTools.tla b/formal/AsyncTools.tla
new file mode 100644
index 00000000..8e6ed8cf
--- /dev/null
+++ b/formal/AsyncTools.tla
@@ -0,0 +1,233 @@
+------------------------------ MODULE AsyncTools ------------------------------
+EXTENDS Naturals, FiniteSets, TLC
+
+\* A finite abstraction of the owner-thread async tool state. IDs stand for
+\* original response call IDs, not tool names or synthesized result IDs.
+CONSTANTS IDs, BypassJoin, BypassDedup, BypassBarrier
+ASSUME /\ IDs # {}
+ /\ IsFiniteSet(IDs)
+ /\ BypassJoin \in BOOLEAN
+ /\ BypassDedup \in BOOLEAN
+ /\ BypassBarrier \in BOOLEAN
+
+VARIABLES partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, admittedAtBarrier, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen, response,
+ failed, cancelled, reset, nextRequest, fallback
+
+vars == <<partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, admittedAtBarrier, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen, response,
+ failed, cancelled, reset, nextRequest, fallback>>
+
+Init ==
+ /\ partial = {}
+ /\ complete = {}
+ /\ admitted = {}
+ /\ running = {}
+ /\ done = {}
+ /\ joined = {}
+ /\ history = {}
+ /\ delivered = {}
+ /\ announced = {}
+ /\ presented = {}
+ /\ admittedAtBarrier = {}
+ /\ executionCount = [i \in IDs |-> 0]
+ /\ historyCount = [i \in IDs |-> 0]
+ /\ deliveryCount = [i \in IDs |-> 0]
+ /\ barrier = FALSE
+ /\ hostedSeen = FALSE
+ /\ response = FALSE
+ /\ failed = FALSE
+ /\ cancelled = FALSE
+ /\ reset = FALSE
+ /\ nextRequest = FALSE
+ /\ fallback = FALSE
+
+\* output_item.added and incomplete deltas never dispatch. A complete item
+\* can arrive without a prior added event; only the complete item is admitted.
+Partial(i) ==
+ /\ i \in IDs
+ /\ ~response /\ ~failed /\ ~cancelled /\ ~reset
+ /\ i \notin partial
+ /\ partial' = partial \cup {i}
+ /\ UNCHANGED <<complete, admitted, running, done, joined, history,
+ delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen,
+ response, failed, cancelled, reset, nextRequest, fallback, admittedAtBarrier>>
+
+\* A hosted schema-discovery item neither dispatches nor closes admission.
+HostedDiscovery ==
+ /\ ~hostedSeen /\ ~response /\ ~failed /\ ~cancelled
+ /\ hostedSeen' = TRUE
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, barrier, response, failed,
+ cancelled, reset, nextRequest, fallback, admittedAtBarrier>>
+
+\* A synchronous, unknown, or ineligible predecessor closes the early
+\* admission prefix. Already admitted work remains owned and must be joined.
+SynchronousPredecessor ==
+ /\ ~barrier /\ ~response /\ ~failed /\ ~cancelled
+ /\ barrier' = TRUE
+ /\ admittedAtBarrier' = admitted
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, hostedSeen, response, failed,
+ cancelled, reset, nextRequest, fallback>>
+
+CompleteEligible(i) ==
+ /\ i \in IDs
+ /\ (BypassBarrier \/ ~barrier) /\ ~response /\ ~failed /\ ~cancelled /\ ~reset
+ /\ executionCount[i] < 2
+ /\ BypassDedup \/ i \notin admitted
+ /\ complete' = complete \cup {i}
+ /\ admitted' = admitted \cup {i}
+ /\ running' = running \cup {i}
+ /\ announced' = announced \cup {i}
+ /\ executionCount' = [executionCount EXCEPT ![i] = @ + 1]
+ /\ UNCHANGED <<partial, done, joined, history, delivered, presented,
+ historyCount, deliveryCount, barrier, hostedSeen, response,
+ failed, cancelled, reset, nextRequest, fallback, admittedAtBarrier>>
+
+WorkerDone(i) ==
+ /\ i \in running /\ ~reset
+ /\ running' = running \ {i}
+ /\ done' = done \cup {i}
+ /\ UNCHANGED <<partial, complete, admitted, joined, history, delivered,
+ announced, presented, executionCount, historyCount,
+ deliveryCount, barrier, hostedSeen, response, failed,
+ cancelled, reset, nextRequest, fallback, admittedAtBarrier>>
+
+ResponseComplete ==
+ /\ ~response /\ ~failed /\ ~cancelled /\ ~reset
+ /\ response' = TRUE
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen, failed,
+ cancelled, reset, nextRequest, fallback, admittedAtBarrier>>
+
+\* The owner awaits every future after the response and before runTools.
+Join(i) ==
+ /\ response /\ ~cancelled /\ ~reset
+ /\ i \in done \ joined
+ /\ joined' = joined \cup {i}
+ /\ UNCHANGED <<partial, complete, admitted, running, done, history,
+ delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen, response,
+ failed, cancelled, reset, nextRequest, fallback, admittedAtBarrier>>
+
+\* duplicateItem allows the first final item into history and drops repeats.
+\* Repeated claim() invocations are deliberately absent: they return cached
+\* results, so the property is single execution/history/delivery, not claim.
+HistoryItem(i) ==
+ /\ response /\ ~cancelled /\ ~reset /\ i \in admitted
+ /\ historyCount[i] < 2
+ /\ BypassDedup \/ i \notin history
+ /\ history' = history \cup {i}
+ /\ historyCount' = [historyCount EXCEPT ![i] = @ + 1]
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ delivered, announced, presented, executionCount,
+ deliveryCount, barrier, hostedSeen, response, failed,
+ cancelled, reset, nextRequest, fallback, admittedAtBarrier>>
+
+Deliver(i) ==
+ /\ response /\ ~cancelled /\ ~reset
+ /\ i \in joined \cap history
+ /\ i \notin delivered
+ /\ delivered' = delivered \cup {i}
+ /\ presented' = presented \cup {i}
+ /\ deliveryCount' = [deliveryCount EXCEPT ![i] = @ + 1]
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ history, announced, executionCount, historyCount, barrier,
+ hostedSeen, response, failed, cancelled, reset, nextRequest,
+ fallback, admittedAtBarrier>>
+
+\* No next model request until owned work and its original-ID result have
+\* been joined/delivered. BypassJoin is the deliberate negative mutation.
+NextRequest ==
+ /\ response /\ ~failed /\ ~cancelled /\ ~reset /\ ~nextRequest
+ /\ BypassJoin \/ (admitted \subseteq joined /\ admitted \subseteq delivered)
+ /\ nextRequest' = TRUE
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen, response,
+ failed, cancelled, reset, fallback, admittedAtBarrier>>
+
+TransportFailure ==
+ /\ ~response /\ ~failed /\ ~cancelled /\ ~reset
+ /\ failed' = TRUE
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen, response,
+ cancelled, reset, nextRequest, fallback, admittedAtBarrier>>
+
+\* Retry/fallback is available only if no async work was ever admitted.
+Fallback ==
+ /\ failed /\ admitted = {} /\ ~fallback /\ ~reset
+ /\ fallback' = TRUE
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen, response,
+ failed, cancelled, reset, nextRequest, admittedAtBarrier>>
+
+Cancel ==
+ /\ ~cancelled /\ ~reset /\ ~nextRequest
+ /\ cancelled' = TRUE
+ /\ UNCHANGED <<partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, executionCount,
+ historyCount, deliveryCount, barrier, hostedSeen, response,
+ failed, reset, nextRequest, fallback, admittedAtBarrier>>
+
+\* Future.cancel joins before the owned state can be freed. Announced UI
+\* entries receive a terminal canceled result if not already presented.
+CancelAndReset ==
+ /\ (cancelled \/ failed) /\ ~reset
+ /\ running' = {}
+ /\ joined' = admitted
+ /\ presented' = announced
+ /\ reset' = TRUE
+ /\ UNCHANGED <<partial, complete, admitted, done, history, delivered,
+ announced, executionCount, historyCount, deliveryCount,
+ barrier, hostedSeen, response, failed, cancelled,
+ nextRequest, fallback, admittedAtBarrier>>
+
+Next ==
+ \/ \E i \in IDs : Partial(i) \/ CompleteEligible(i) \/ WorkerDone(i)
+ \/ Join(i) \/ HistoryItem(i) \/ Deliver(i)
+ \/ HostedDiscovery \/ SynchronousPredecessor \/ ResponseComplete
+ \/ NextRequest \/ TransportFailure \/ Fallback \/ Cancel \/ CancelAndReset
+
+TypeOK ==
+ /\ \A s \in {partial, complete, admitted, running, done, joined,
+ history, delivered, announced, presented, admittedAtBarrier} : s \subseteq IDs
+ /\ executionCount \in [IDs -> 0..2]
+ /\ historyCount \in [IDs -> 0..2]
+ /\ deliveryCount \in [IDs -> 0..2]
+ /\ \A b \in {barrier, hostedSeen, response, failed, cancelled,
+ reset, nextRequest, fallback} : b \in BOOLEAN
+
+OnlyCompleteItemsRun == admitted \subseteq complete
+AtMostOnceExecution == \A i \in IDs : executionCount[i] <= 1
+AtMostOnceHistory == \A i \in IDs : historyCount[i] <= 1
+AtMostOnceDelivery == \A i \in IDs : deliveryCount[i] <= 1
+JoinedBeforeNextRequest == nextRequest =>
+ (admitted \subseteq joined /\ admitted \subseteq delivered)
+NoLiveWorkerAfterReset == reset => running = {}
+NoReplayAfterAdmission == admitted # {} => ~fallback
+DeliveryHasOriginalAdmission == delivered \subseteq admitted \cap history
+NoLateAdmission == barrier => admitted = admittedAtBarrier
+
+\* Fair worker completion, owner join, history assembly, and delivery imply
+\* normal progress. Cancellation may terminate that obligation instead.
+FairProgress ==
+ /\ \A i \in IDs : WF_vars(WorkerDone(i))
+ /\ \A i \in IDs : WF_vars(Join(i))
+ /\ \A i \in IDs : WF_vars(HistoryItem(i))
+ /\ \A i \in IDs : WF_vars(Deliver(i))
+ /\ WF_vars(NextRequest)
+NormalEventuallyDelivers ==
+ \A i \in IDs : (response /\ i \in admitted) ~> (i \in delivered \/ cancelled)
+
+Spec == Init /\ [][Next]_vars /\ FairProgress
+=============================================================================
diff --git a/formal/AsyncToolsNoBarrier.cfg b/formal/AsyncToolsNoBarrier.cfg
new file mode 100644
index 00000000..6f37298d
--- /dev/null
+++ b/formal/AsyncToolsNoBarrier.cfg
@@ -0,0 +1,6 @@
+SPECIFICATION Spec
+CONSTANTS IDs = {a, b}
+ BypassJoin = FALSE
+ BypassDedup = FALSE
+ BypassBarrier = TRUE
+INVARIANT NoLateAdmission
diff --git a/formal/AsyncToolsNoDedup.cfg b/formal/AsyncToolsNoDedup.cfg
new file mode 100644
index 00000000..380a9e8f
--- /dev/null
+++ b/formal/AsyncToolsNoDedup.cfg
@@ -0,0 +1,6 @@
+SPECIFICATION Spec
+CONSTANTS IDs = {a, b}
+ BypassJoin = FALSE
+ BypassDedup = TRUE
+ BypassBarrier = FALSE
+INVARIANT AtMostOnceExecution
diff --git a/formal/AsyncToolsNoJoin.cfg b/formal/AsyncToolsNoJoin.cfg
new file mode 100644
index 00000000..55a014aa
--- /dev/null
+++ b/formal/AsyncToolsNoJoin.cfg
@@ -0,0 +1,6 @@
+SPECIFICATION Spec
+CONSTANTS IDs = {a, b}
+ BypassJoin = TRUE
+ BypassDedup = FALSE
+ BypassBarrier = FALSE
+INVARIANT JoinedBeforeNextRequest
diff --git a/formal/EffortSelection.cfg b/formal/EffortSelection.cfg
new file mode 100644
index 00000000..be247738
--- /dev/null
+++ b/formal/EffortSelection.cfg
@@ -0,0 +1,13 @@
+CONSTANTS
+ MaxGen = 3
+ MutateStaleGuard = FALSE
+SPECIFICATION Spec
+INVARIANTS
+ TypeOK
+ ActiveAdmissionIsCurrent
+ SelectedOriginIsCurrent
+ ManualWins
+ OwnerOnlyWritesEffort
+ AllowedJevApplication
+PROPERTIES
+ SelectedEventuallyConsumed
diff --git a/formal/EffortSelection.tla b/formal/EffortSelection.tla
new file mode 100644
index 00000000..06a66301
--- /dev/null
+++ b/formal/EffortSelection.tla
@@ -0,0 +1,181 @@
+----------------------------- MODULE EffortSelection -----------------------------
+EXTENDS Integers, FiniteSets, TLC
+
+\* A finite abstraction of one Agent's jev_effort_pending. Worker completions
+\* may arrive after invalidation; only the owner may change reasoning effort.
+CONSTANTS MaxGen, MutateStaleGuard
+ASSUME MaxGen \in Nat \ {0}
+ASSUME MutateStaleGuard \in BOOLEAN
+
+Routes == {"routeA", "routeB", "binaryRoute", "unsupported"}
+Efforts == {"none", "low", "medium", "high", "xhigh", "ultra"}
+NoRoute == "unset"
+NoEffort == "unset"
+Phases == {"idle", "flight", "selected"}
+Boundaries == {"nextRequest", "normalExit"}
+
+Levels(r) ==
+ IF r = "binaryRoute" THEN {"none", "high"}
+ ELSE IF r = "routeA" \/ r = "routeB"
+ THEN {"low", "medium", "high", "xhigh", "ultra"}
+ ELSE {}
+Eligible(r) == r # "unsupported"
+Attempt == [tok : 1..MaxGen, route : Routes]
+
+VARIABLES phase, gen, currentRoute, effort, ownerEffort,
+ pendingGen, pendingRoute, pendingEffort, selectionOrigin,
+ attempts, manualFence, lastWriter, lastJevGen,
+ lastJevRoute, lastJevEffort, lastBoundary
+vars == <<phase, gen, currentRoute, effort, ownerEffort,
+ pendingGen, pendingRoute, pendingEffort, selectionOrigin,
+ attempts, manualFence, lastWriter, lastJevGen,
+ lastJevRoute, lastJevEffort, lastBoundary>>
+
+Init ==
+ /\ phase = "idle"
+ /\ gen = 0
+ /\ currentRoute = "routeA"
+ /\ effort = "medium"
+ /\ ownerEffort = "medium"
+ /\ pendingGen = -1
+ /\ pendingRoute = NoRoute
+ /\ pendingEffort = NoEffort
+ /\ selectionOrigin = -1
+ /\ attempts = {}
+ /\ manualFence = -1
+ /\ lastWriter = "initial"
+ /\ lastJevGen = -1
+ /\ lastJevRoute = NoRoute
+ /\ lastJevEffort = NoEffort
+ /\ lastBoundary = "none"
+
+\* Pending.begin: an idle slot admits one request and stamps its generation.
+Begin ==
+ /\ phase = "idle"
+ /\ gen < MaxGen
+ /\ Eligible(currentRoute)
+ /\ gen' = gen + 1
+ /\ phase' = "flight"
+ /\ pendingGen' = gen + 1
+ /\ pendingRoute' = currentRoute
+ /\ pendingEffort' = NoEffort
+ /\ selectionOrigin' = -1
+ /\ attempts' = attempts \cup {[tok |-> gen + 1, route |-> currentRoute]}
+ /\ UNCHANGED <<currentRoute, effort, ownerEffort, manualFence,
+ lastWriter, lastJevGen, lastJevRoute, lastJevEffort,
+ lastBoundary>>
+
+\* A completion carries the token and route copied by its worker. The
+\* mutation removes only Pending.commit's token equality check, leaving its
+\* phase check and the separate route/allowlist checks unchanged.
+Complete(a, choice) ==
+ LET accepted == phase = "flight" /\ (MutateStaleGuard \/ a.tok = gen)
+ IN
+ /\ a \in attempts
+ /\ choice \in Levels(a.route)
+ /\ attempts' = attempts \ {a}
+ /\ phase' = IF accepted THEN "selected" ELSE phase
+ /\ pendingEffort' = IF accepted THEN choice ELSE pendingEffort
+ /\ selectionOrigin' = IF accepted THEN a.tok ELSE selectionOrigin
+ /\ UNCHANGED <<gen, currentRoute, effort, ownerEffort,
+ pendingGen, pendingRoute, manualFence, lastWriter,
+ lastJevGen, lastJevRoute, lastJevEffort, lastBoundary>>
+
+\* Pending.abort on a failed/invalid Jev response. A late abort cannot clear
+\* a newer admission.
+Abort(a) ==
+ /\ a \in attempts
+ /\ attempts' = attempts \ {a}
+ /\ phase' = IF phase = "flight" /\ a.tok = gen THEN "idle" ELSE phase
+ /\ UNCHANGED <<gen, currentRoute, effort, ownerEffort,
+ pendingGen, pendingRoute, pendingEffort, selectionOrigin,
+ manualFence, lastWriter, lastJevGen, lastJevRoute,
+ lastJevEffort, lastBoundary>>
+
+\* Pending.invalidate is reached by manual /effort or ACP configuration,
+\* provider/model replacement, cancellation, and turn error. The worker may
+\* still complete later, so attempts is deliberately not cleared.
+Invalidate(kind, route, choice) ==
+ /\ kind \in {"manual", "route", "cancel", "error"}
+ /\ gen < MaxGen
+ /\ (IF kind = "route" THEN route \in Routes ELSE route = currentRoute)
+ /\ (IF kind = "manual" THEN choice \in Levels(currentRoute)
+ ELSE choice = effort)
+ /\ gen' = gen + 1
+ /\ phase' = "idle"
+ /\ currentRoute' = route
+ /\ effort' = choice
+ /\ ownerEffort' = choice
+ /\ pendingGen' = -1
+ /\ pendingRoute' = NoRoute
+ /\ pendingEffort' = NoEffort
+ /\ selectionOrigin' = -1
+ /\ manualFence' = IF kind = "manual" THEN gen + 1 ELSE manualFence
+ /\ lastWriter' = IF kind = "manual" THEN "ownerManual" ELSE lastWriter
+ /\ UNCHANGED <<attempts, lastJevGen, lastJevRoute,
+ lastJevEffort, lastBoundary>>
+
+\* Pending.take + effort_route.allows on the owning thread. Both the next
+\* request boundary and normal turn exit use this transition. A route change
+\* before take consumes the selection without applying it.
+OwnerBoundaryKind(kind) ==
+ LET allowed == pendingRoute = currentRoute
+ /\ pendingEffort \in Levels(currentRoute)
+ IN
+ /\ kind \in Boundaries
+ /\ phase = "selected"
+ /\ phase' = "idle"
+ /\ effort' = IF allowed THEN pendingEffort ELSE effort
+ /\ ownerEffort' = IF allowed THEN pendingEffort ELSE ownerEffort
+ /\ lastWriter' = IF allowed THEN "ownerJev" ELSE lastWriter
+ /\ lastJevGen' = IF allowed THEN selectionOrigin ELSE lastJevGen
+ /\ lastJevRoute' = IF allowed THEN currentRoute ELSE lastJevRoute
+ /\ lastJevEffort' = IF allowed THEN pendingEffort ELSE lastJevEffort
+ /\ lastBoundary' = kind
+ /\ UNCHANGED <<gen, currentRoute, pendingGen, pendingRoute,
+ pendingEffort, selectionOrigin, attempts, manualFence>>
+
+OwnerBoundary == \E kind \in Boundaries : OwnerBoundaryKind(kind)
+Next ==
+ \/ Begin
+ \/ \E a \in Attempt : \E choice \in Efforts : Complete(a, choice)
+ \/ \E a \in Attempt : Abort(a)
+ \/ \E kind \in {"manual", "route", "cancel", "error"} :
+ \E route \in Routes : \E choice \in Efforts :
+ Invalidate(kind, route, choice)
+ \/ OwnerBoundary
+
+TypeOK ==
+ /\ phase \in Phases
+ /\ gen \in 0..MaxGen
+ /\ currentRoute \in Routes
+ /\ effort \in Efforts
+ /\ ownerEffort \in Efforts
+ /\ pendingGen \in {-1} \cup 1..MaxGen
+ /\ pendingRoute \in Routes \cup {NoRoute}
+ /\ pendingEffort \in Efforts \cup {NoEffort}
+ /\ selectionOrigin \in {-1} \cup 1..MaxGen
+ /\ attempts \subseteq Attempt
+ /\ manualFence \in {-1} \cup 1..MaxGen
+ /\ lastWriter \in {"initial", "ownerManual", "ownerJev"}
+ /\ lastJevGen \in {-1} \cup 1..MaxGen
+ /\ lastJevRoute \in Routes \cup {NoRoute}
+ /\ lastJevEffort \in Efforts \cup {NoEffort}
+ /\ lastBoundary \in Boundaries \cup {"none"}
+
+\* A first admission keeps the slot until commit, abort, or invalidation.
+ActiveAdmissionIsCurrent == phase = "idle" \/ pendingGen = gen
+\* Ghost provenance makes a late worker's selection observable to TLC even
+\* though the Zig Pending stores only the chosen effort.
+SelectedOriginIsCurrent == phase # "selected" \/ selectionOrigin = gen
+\* A manual change fences all older work; only a newly admitted Jev call may
+\* subsequently supersede it.
+ManualWins == lastWriter # "ownerJev" \/ lastJevGen > manualFence
+\* Worker completions and aborts never mutate the owner's reasoning field.
+OwnerOnlyWritesEffort == effort = ownerEffort
+AllowedJevApplication ==
+ lastWriter # "ownerJev" \/ lastJevEffort \in Levels(lastJevRoute)
+
+Spec == Init /\ [][Next]_vars /\ WF_vars(OwnerBoundary)
+SelectedEventuallyConsumed == [](phase = "selected" ~> phase = "idle")
+================================================================================
diff --git a/formal/EffortSelectionStale.cfg b/formal/EffortSelectionStale.cfg
new file mode 100644
index 00000000..de16fda6
--- /dev/null
+++ b/formal/EffortSelectionStale.cfg
@@ -0,0 +1,11 @@
+CONSTANTS
+ MaxGen = 3
+ MutateStaleGuard = TRUE
+SPECIFICATION Spec
+INVARIANTS
+ TypeOK
+ ActiveAdmissionIsCurrent
+ SelectedOriginIsCurrent
+ ManualWins
+ OwnerOnlyWritesEffort
+ AllowedJevApplication
diff --git a/formal/README.md b/formal/README.md
new file mode 100644
index 00000000..673e4ae6
--- /dev/null
+++ b/formal/README.md
@@ -0,0 +1,53 @@
+# Harness lifecycle models
+
+These TLA+ models describe concurrency rules in the harness. TLC explores the
+finite configurations committed beside each model, including interleavings that
+are difficult to reproduce with ordinary tests.
+
+- [Effort selection](effort-selection.md): admission, stale completions, manual
+ changes, cancellation, and owner-boundary application.
+- [Async tools](async-tools.md): early admission, call identity, ordering
+ barriers, result ownership, joining, and cancellation.
+
+Each model has a normal configuration and a deliberately broken configuration.
+The negative control must fail the intended invariant. A syntax error, timeout,
+or unrelated failure is not a successful negative control.
+
+## Scope
+
+Passing TLC establishes the checked properties of these finite abstractions.
+It is not a proof that the Zig implementation refines the models, an unbounded
+mathematical proof, or evidence of faster execution or lower token usage. The
+companion documents map actions to code and state what is omitted. Runtime
+regression tests remain necessary, particularly for parsing, allocation,
+transport behavior, and cancellation implementation.
+
+Changes to the corresponding runtime lifecycle should update its model and
+mapping in the same change. A counterexample is a design or model finding until
+it is reproduced against the implementation; do not report it as a runtime bug
+without that check.
+
+## Toolchain
+
+Use Java 11 or newer and the official
+[TLA+ command-line tools](https://github.com/tlaplus/tlaplus/blob/master/USE.md).
+The checked tool release is
+[v1.7.4](https://github.com/tlaplus/tlaplus/releases/tag/v1.7.4), whose
+`tla2tools.jar` has SHA-256:
+
+```text
+936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88
+```
+
+Set `JAVA` to the Java executable and `TLA2TOOLS` to that jar. The check runner
+uses a bounded heap, one worker, and temporary state directories. It does not
+download tools or call a model provider.
+
+```sh
+python3 scripts/check-formal.py
+```
+
+Keep model-checker state and counterexample output outside the source tree.
+See the individual model documents for configuration bounds, invariants, and
+any fairness assumptions. These checks are separate from the Zig unit suite;
+running `zig build test` alone does not run TLC.
diff --git a/formal/async-tools.md b/formal/async-tools.md
new file mode 100644
index 00000000..f3425598
--- /dev/null
+++ b/formal/async-tools.md
@@ -0,0 +1,52 @@
+# Owned asynchronous tool lifecycle
+
+`AsyncTools.tla` is a finite model of the early execution path described by
+[ADR 0177](../docs/adr/0177-owned-async-tool-execution.md). It uses two original
+call IDs and explores arbitrary interleavings of stream events, worker
+completion, response assembly, cancellation, and owner-thread consumption.
+The IDs are deliberately distinct; repeating an ID models duplicate stream or
+final-response items. The model is about lifecycle and ordering, not tool
+content or transport bytes.
+
+| Model action | Implementation boundary |
+| --- | --- |
+| `Partial`, `CompleteEligible`, `SynchronousPredecessor`, `HostedDiscovery` | `agent_stream.zig` passes each line to `agent_async_tools.onLine`; `onEvent` ignores incomplete items, admits only complete eligible async calls, deduplicates `call_id`, closes its barrier on an unknown/synchronous predecessor, and exempts hosted discovery. |
+| `WorkerDone`, `Join` | `agent_async_tools.execute` publishes a completed result; `join` awaits owned futures before the successful Responses request returns in `agent_request.zig`. |
+| `HistoryItem`, `Deliver` | `agent_steps.stepResponses` calls `duplicateItem` before appending a final item; `agent_tools.runTools` calls `claim`, whose cached result is returned for repeated invocations; the tool result message uses the original call ID. |
+| `NextRequest` | `agent_request.request` joins before returning a response; `stepResponses` consumes and appends results before the model loop can request again. |
+| `TransportFailure`, `Fallback`, `Cancel`, `CancelAndReset` | `agent_request.request` rejects retry/rebuild after `started`; `agent_async_tools.reset` cancels and joins futures before destroying owned storage and closes announced UI entries. `agent.runTurn` defers reset. |
+
+The baseline checks single execution and history inclusion per original ID,
+single result delivery, no admission after the first barrier, no next request
+before every admitted job is joined and delivered, no live worker after reset,
+and no fallback after admission. `admittedAtBarrier` snapshots the actual
+admitted set when the barrier closes: `NoLateAdmission` would fail if the
+barrier guard were removed. The next-request invariant checks live state,
+not a counter recording whether a join was called. Repeated `claim()` calls
+are valid because they return the cached result; no invariant prohibits them.
+
+Weak fairness for worker completion, owner join, history assembly, delivery,
+and next request gives `NormalEventuallyDelivers`: a completed response with
+admitted work eventually delivers its result or is cancelled. This is a
+conditional scheduling argument. It does not assert that external tool work
+terminates, that a network response arrives, or that cancellation always
+occurs. `CancelAndReset` models `Future.cancel` as a joined operation, matching
+its required contract; TLC does not prove that Zig's runtime implements it.
+
+Run TLC from `formal/` with `-deadlock`, since an ended turn is an expected
+terminal state. `AsyncTools.cfg` is the positive model. The negative configs
+each switch off one guard and must produce the named counterexample:
+
+| Config | Deliberate mutation | Violated invariant |
+| --- | --- | --- |
+| `AsyncToolsNoJoin.cfg` | Allow the next request before owned work joins | `JoinedBeforeNextRequest` |
+| `AsyncToolsNoDedup.cfg` | Admit a repeated original ID | `AtMostOnceExecution` |
+| `AsyncToolsNoBarrier.cfg` | Admit a later call after a synchronous predecessor | `NoLateAdmission` |
+
+The finite abstraction admits any two eligible read-only calls and does not
+encode the full tool allowlist, argument parsing, user approval, rate limits,
+UI timing, network failure classifications, or the separate RLM path. Local
+admission denial and failed worker creation are omitted: the concrete code
+keeps an owned job with a ready error result and no worker in those cases.
+The model does not establish a refinement proof from Zig to TLA+.
+Implementation tests and transport fixtures remain necessary.
diff --git a/formal/effort-selection.md b/formal/effort-selection.md
new file mode 100644
index 00000000..1c7c76ab
--- /dev/null
+++ b/formal/effort-selection.md
@@ -0,0 +1,48 @@
+# Effort selection lifecycle
+
+`EffortSelection.tla` abstracts one agent's pending effort choice. A worker
+may finish after cancellation or a manual change; the owner alone can apply a
+choice at the next request boundary or normal turn exit. This models the
+optional effort selector in ADR 0193 and the shared session setting in ADR
+0191. It does not model a general judgment tool.
+
+| Model action or state | Implementation |
+| --- | --- |
+| `Begin`, `phase`, `gen`, `pendingRoute` | `Pending.begin` in `src/jev_effort_state.zig` admits only an idle slot, increments its token, and copies the provider/model. `jev_tool.execute` calls it after input and eligibility checks. |
+| `Complete` | `jev_tool.selectedEffort` parses a choice and checks `effort_route.allows`; `Pending.commit` accepts it only while in flight and only for the current token. The model's `selectionOrigin` is ghost state that exposes which worker supplied a choice. |
+| `Abort` | `jev_tool.execute` defers `Pending.abort`; a failed or invalid response clears only its own in-flight admission. |
+| `Invalidate` | `Pending.invalidate` increments the token and clears the slot. Callers include `commands_effort.zig` and `acp_config.zig` for manual effort, `jev_tool.updateProvider` for route changes, `agent_request.zig` and `jev_effort_state.finishTurn` for cancellation, and `Agent.runTurn` error cleanup. The outstanding worker remains in the model so a late completion is explored. |
+| `OwnerBoundary` | `jev_effort_state.take` consumes a selection and checks the copied route; `applyToState` checks the current allowlist before changing `agent.reasoning`. `agent_request.request` calls `apply` at the next request boundary; `finishTurn` calls it on normal exit. |
+| `Levels`, `Eligible` | Abstract finite classes of `effort_route.levels/allows` and `jev_model_scope.eligible`. Two routes share a multi-level allowlist, one route has a binary allowlist, and one is ineligible. Their names deliberately carry no provider or model identity. |
+
+The normal configuration bounds the generation to 3. That is enough to
+explore admission, invalidation, readmission, and completion from the first
+worker after the newer admission. `SelectedOriginIsCurrent` checks the
+selected worker's generation. `ActiveAdmissionIsCurrent` and the guarded
+`Begin` action capture first-admission ownership of the slot.
+`ManualWins` ensures a manual change cannot be overwritten by an older
+worker; a fresh admitted choice may supersede it. `OwnerOnlyWritesEffort`
+uses a ghost owner copy to check that worker completion does not mutate the
+setting. `AllowedJevApplication` checks the route's allowlist at application.
+
+`SelectedEventuallyConsumed` is checked only with weak fairness for
+`OwnerBoundary`: if a selection remains pending, the owner eventually reaches
+a request boundary or normal exit. Cancellation or an error may instead clear
+it. This is a conditional scheduling assumption, not a claim that every
+process run finishes. TLC uses `-deadlock` because the finite generation
+bound intentionally creates terminal states.
+
+`EffortSelectionStale.cfg` changes one rule: `Complete` ignores the token
+equality check in `Pending.commit`. TLC then finds a trace in which token 1
+begins, invalidation advances the generation, token 3 begins, and token 1's
+late completion fills the selected slot. `SelectedOriginIsCurrent` fails.
+This mutation checks that the invariant has discriminatory power; it is not
+an implementation defect.
+
+The model treats each mutex operation as atomic and interleaves the worker and
+owner actions. It omits token wraparound, byte limits, allocator failures,
+parser details, network behavior, persistence, notifications, and multiple
+agents. Its static route classes mean a route change invalidates the pending
+slot before `take`; the route and allowlist checks remain modeled but their
+rejection branch is defensive under the current call paths. Passing TLC
+establishes these finite-model properties, not refinement of the Zig code.
diff --git a/scripts/check-formal.py b/scripts/check-formal.py
new file mode 100644
index 00000000..6d42f419
--- /dev/null
+++ b/scripts/check-formal.py
@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Run bounded TLC lifecycle models and verify their negative controls."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tempfile
+
+
+ROOT = Path(__file__).resolve().parents[1]
+FORMAL = ROOT / "formal"
+JAR_SHA256 = "936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88"
+TIMEOUT_SECONDS = 120
+CASES = (
+ ("EffortSelection.tla", "EffortSelection.cfg", None),
+ ("EffortSelection.tla", "EffortSelectionStale.cfg", "SelectedOriginIsCurrent"),
+ ("AsyncTools.tla", "AsyncTools.cfg", None),
+ ("AsyncTools.tla", "AsyncToolsNoJoin.cfg", "JoinedBeforeNextRequest"),
+ ("AsyncTools.tla", "AsyncToolsNoDedup.cfg", "AtMostOnceExecution"),
+ ("AsyncTools.tla", "AsyncToolsNoBarrier.cfg", "NoLateAdmission"),
+)
+
+
+def run_case(java: str, jar: Path, module: str, config: str, expected: str | None) -> None:
+ with tempfile.TemporaryDirectory(prefix="codegraff-tlc-") as scratch:
+ metadata = Path(scratch) / "state"
+ metadata.mkdir()
+ command = [
+ java,
+ "-Xmx512m",
+ "-XX:+UseParallelGC",
+ "-cp",
+ str(jar),
+ "tlc2.TLC",
+ "-workers",
+ "1",
+ "-deadlock",
+ "-coverage",
+ "1",
+ "-metadir",
+ str(metadata),
+ "-config",
+ config,
+ module,
+ ]
+ try:
+ result = subprocess.run(
+ command,
+ cwd=FORMAL,
+ capture_output=True,
+ text=True,
+ timeout=TIMEOUT_SECONDS,
+ check=False,
+ )
+ except subprocess.TimeoutExpired as exc:
+ raise RuntimeError(f"{config}: TLC exceeded {TIMEOUT_SECONDS}s") from exc
+
+ output = result.stdout + result.stderr
+ if expected is None:
+ if result.returncode != 0 or "Model checking completed. No error has been found." not in output:
+ raise RuntimeError(f"{config}: expected a complete safe model check\n{output[-2000:]}")
+ else:
+ needle = re.compile(rf"^Error: Invariant {re.escape(expected)} is violated\.$", re.MULTILINE)
+ if result.returncode == 0 or needle.search(output) is None:
+ raise RuntimeError(f"{config}: expected counterexample for {expected}\n{output[-2000:]}")
+
+ totals = re.findall(r"(\d+) states generated, (\d+) distinct states found", output)
+ counts = f"{totals[-1][1]} distinct states" if totals else "counterexample found"
+ outcome = "PASS" if expected is None else f"EXPECTED {expected}"
+ print(f"{config}: {outcome}; {counts}")
+
+
+def main() -> int:
+ java = os.environ.get("JAVA", "java")
+ jar_name = os.environ.get("TLA2TOOLS")
+ if not jar_name:
+ print("Set TLA2TOOLS to the checked tla2tools.jar path.", file=sys.stderr)
+ return 2
+ jar = Path(jar_name).expanduser().resolve()
+ if not jar.is_file():
+ print(f"TLA2TOOLS is not a file: {jar}", file=sys.stderr)
+ return 2
+ if hashlib.sha256(jar.read_bytes()).hexdigest() != JAR_SHA256:
+ print("TLA2TOOLS does not match the checked v1.7.4 jar hash.", file=sys.stderr)
+ return 2
+ try:
+ for module, config, expected in CASES:
+ run_case(java, jar, module, config, expected)
+ except (OSError, RuntimeError) as exc:
+ print(exc, file=sys.stderr)
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())