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.cfgnew file mode 100644index 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 NormalEventuallyDeliversdiff --git a/formal/AsyncTools.tla b/formal/AsyncTools.tlanew file mode 100644index 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.cfgnew file mode 100644index 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 NoLateAdmissiondiff --git a/formal/AsyncToolsNoDedup.cfg b/formal/AsyncToolsNoDedup.cfgnew file mode 100644index 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 AtMostOnceExecutiondiff --git a/formal/AsyncToolsNoJoin.cfg b/formal/AsyncToolsNoJoin.cfgnew file mode 100644index 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 JoinedBeforeNextRequestdiff --git a/formal/EffortSelection.cfg b/formal/EffortSelection.cfgnew file mode 100644index 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+ SelectedEventuallyConsumeddiff --git a/formal/EffortSelection.tla b/formal/EffortSelection.tlanew file mode 100644index 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.cfgnew file mode 100644index 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+ AllowedJevApplicationdiff --git a/formal/README.md b/formal/README.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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())