graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Model permission and connection ownership lifecycles
Rach Pradhanacb4269c3463
diff --git a/formal/AcpPermissions.cfg b/formal/AcpPermissions.cfgnew file mode 100644index 00000000..99237246--- /dev/null+++ b/formal/AcpPermissions.cfg@@ -0,0 +1,9 @@+CONSTANTS BypassTokenOwner = FALSE+ BypassCancelGuard = FALSE+ BypassTokenConsume = FALSE+SPECIFICATION Spec+INVARIANTS TypeOK+ StaleTransportNeverGrants+ CancelNeverGrantsLate+ UnofferedNeverGrants+ TokenConsumedAtMostOncediff --git a/formal/AcpPermissions.tla b/formal/AcpPermissions.tlanew file mode 100644index 00000000..159370f1--- /dev/null+++ b/formal/AcpPermissions.tla@@ -0,0 +1,201 @@+----------------------------- MODULE AcpPermissions -----------------------------+EXTENDS Naturals, FiniteSets, Sequences, TLC++\* Two workers may reuse both the saved session name and server request ID.+CONSTANTS BypassTokenOwner, BypassCancelGuard, BypassTokenConsume+ASSUME /\ BypassTokenOwner \in BOOLEAN+ /\ BypassCancelGuard \in BOOLEAN+ /\ BypassTokenConsume \in BOOLEAN++Generations == {1, 2}+Tokens == {"old", "new"}+NoToken == "none"+Choices == {"once", "always", "reject"}+NoChoice == "none"+ServerStates == {"idle", "pending", "denied", "granted"}+Owner(t) == IF t = "old" THEN 1 ELSE 2+TokenFor(g) == IF g = 1 THEN "old" ELSE "new"++VARIABLES gen, asked, server, offeredAlways, cancelled,+ activeToken, issued, delivered, used,+ wire, grants+vars == <<gen, asked, server, offeredAlways, cancelled,+ activeToken, issued, delivered, used, wire, grants>>++EmptyWire == [present |-> FALSE, token |-> NoToken, choice |-> NoChoice,+ route |-> 1, serverId |-> 1]++Init ==+ /\ gen = 1+ /\ asked = {}+ /\ server = "idle"+ /\ offeredAlways = FALSE+ /\ cancelled = FALSE+ /\ activeToken = NoToken+ /\ issued = {}+ /\ delivered = {}+ /\ used = [t \in Tokens |-> 0]+ /\ wire = EmptyWire+ /\ grants = <<>>++\* Bridge.ask admits one permission request at a time. We bound this model to+\* one request per generation; both use server ID 1 and session name "saved".+ServerAsk(always) ==+ /\ always \in BOOLEAN+ /\ server = "idle"+ /\ gen \notin asked+ /\ asked' = asked \cup {gen}+ /\ server' = "pending"+ /\ offeredAlways' = always+ /\ cancelled' = FALSE+ /\ UNCHANGED <<gen, activeToken, issued, delivered, used, wire, grants>>++\* The stdout reader creates a fresh, transport-local token. GUI notification+\* is separate; a response cannot be sent merely because stdout was parsed.+FrontendReceive ==+ /\ server = "pending"+ /\ activeToken = NoToken+ /\ TokenFor(gen) \notin issued+ /\ activeToken' = TokenFor(gen)+ /\ issued' = issued \cup {TokenFor(gen)}+ /\ UNCHANGED <<gen, asked, server, offeredAlways, cancelled,+ delivered, used, wire, grants>>++GuiDeliver ==+ /\ activeToken \in Tokens+ /\ activeToken \notin delivered+ /\ delivered' = delivered \cup {activeToken}+ /\ UNCHANGED <<gen, asked, server, offeredAlways, cancelled,+ activeToken, issued, used, wire, grants>>++\* Route lookup chooses the current worker, then respondPermission looks up+\* the token in precisely that transport. A stale GUI event may use an old+\* token with the repeated session and server ID, but must not be sent.+FrontendRespond(t, route, choice) ==+ /\ t \in issued+ /\ route \in Generations+ /\ choice \in Choices+ /\ wire.present = FALSE+ /\ t \in delivered+ /\ IF BypassTokenConsume THEN used[t] < 2 ELSE used[t] = 0+ /\ route = gen+ /\ IF BypassTokenOwner THEN TRUE ELSE activeToken = t /\ Owner(t) = route+ /\ choice # "always" \/ offeredAlways+ /\ wire' = [present |-> TRUE, token |-> t, choice |-> choice,+ route |-> route, serverId |-> 1]+ /\ used' = [used EXCEPT ![t] = @ + 1]+ /\ activeToken' = IF BypassTokenConsume THEN activeToken+ ELSE IF activeToken = t THEN NoToken ELSE activeToken+ /\ UNCHANGED <<gen, asked, server, offeredAlways, cancelled,+ issued, delivered, grants>>++\* Untrusted/malformed ACP input may carry an unoffered choice. The frontend+\* does not produce this action; it exercises the bridge's own allowlist.+InjectUnoffered ==+ /\ server = "pending"+ /\ ~offeredAlways+ /\ wire.present = FALSE+ /\ wire' = [present |-> TRUE, token |-> NoToken, choice |-> "always",+ route |-> gen, serverId |-> 1]+ /\ UNCHANGED <<gen, asked, server, offeredAlways, cancelled,+ activeToken, issued, delivered, used, grants>>++\* The GUI can retire a delivered token before server cancellation is read.+FrontendCancel ==+ /\ activeToken \in Tokens+ /\ activeToken' = NoToken+ /\ UNCHANGED <<gen, asked, server, offeredAlways, cancelled,+ issued, delivered, used, wire, grants>>++\* Bridge.cancel / inbox EOF retires the pending request and wakes ask.+ServerCancel ==+ /\ server = "pending"+ /\ server' = "denied"+ /\ cancelled' = TRUE+ /\ UNCHANGED <<gen, asked, offeredAlways, activeToken,+ issued, delivered, used, wire, grants>>++\* A valid response already accepted by the bridge can authorize execution+\* before a later cancel. This model does not claim cancel undoes that work.+ServerAccept ==+ /\ wire.present+ /\ LET sameWorker == wire.route = gen+ offered == wire.choice # "always" \/ offeredAlways+ mayGrant == sameWorker /\ offered /\ wire.choice # "reject"+ /\ (IF BypassCancelGuard THEN TRUE+ ELSE server = "pending" /\ ~cancelled)+ IN /\ server' = IF mayGrant THEN "granted"+ ELSE IF sameWorker /\ server = "pending" THEN "denied"+ ELSE server+ /\ grants' = IF mayGrant+ THEN Append(grants,+ [generation |-> gen, token |-> wire.token,+ tokenOwner |-> IF wire.token = NoToken THEN 0 ELSE Owner(wire.token),+ choice |-> wire.choice, offered |-> offered,+ pending |-> server = "pending",+ wasCancelled |-> cancelled,+ route |-> wire.route])+ ELSE grants+ /\ wire' = EmptyWire+ /\ UNCHANGED <<gen, asked, offeredAlways, cancelled,+ activeToken, issued, delivered, used>>++\* A new worker has its own stdin and bridge. A late frame for the prior+\* process remains addressed to that process, even if ID/session repeat.+Restart ==+ /\ gen = 1+ /\ gen' = 2+ /\ server' = "idle"+ /\ offeredAlways' = FALSE+ /\ cancelled' = FALSE+ /\ activeToken' = NoToken+ /\ UNCHANGED <<asked, issued, delivered, used, wire, grants>>++Next ==+ \/ \E a \in BOOLEAN : ServerAsk(a)+ \/ FrontendReceive+ \/ GuiDeliver+ \/ \E t \in Tokens, r \in Generations, c \in Choices : FrontendRespond(t, r, c)+ \/ InjectUnoffered+ \/ FrontendCancel+ \/ ServerCancel+ \/ ServerAccept+ \/ Restart++Spec == Init /\ [][Next]_vars++TypeOK ==+ /\ gen \in Generations+ /\ asked \subseteq Generations+ /\ server \in ServerStates+ /\ offeredAlways \in BOOLEAN+ /\ cancelled \in BOOLEAN+ /\ activeToken \in Tokens \cup {NoToken}+ /\ issued \subseteq Tokens+ /\ delivered \subseteq issued+ /\ used \in [Tokens -> {0, 1, 2}]+ /\ wire.present \in BOOLEAN+ /\ wire.token \in Tokens \cup {NoToken}+ /\ wire.choice \in Choices \cup {NoChoice}+ /\ wire.route \in Generations+ /\ wire.serverId = 1+ /\ grants \in Seq([generation : Generations, token : Tokens \cup {NoToken},+ tokenOwner : {0, 1, 2}, choice : Choices,+ offered : BOOLEAN, pending : BOOLEAN,+ wasCancelled : BOOLEAN, route : Generations])++StaleTransportNeverGrants ==+ \A i \in 1..Len(grants) :+ grants[i].token = NoToken \/+ (grants[i].tokenOwner = grants[i].generation /\+ grants[i].route = grants[i].generation)++CancelNeverGrantsLate ==+ \A i \in 1..Len(grants) : grants[i].pending /\ ~grants[i].wasCancelled++UnofferedNeverGrants ==+ \A i \in 1..Len(grants) : grants[i].offered++TokenConsumedAtMostOnce == \A t \in Tokens : used[t] <= 1++=============================================================================diff --git a/formal/AcpPermissionsNoCancelGuard.cfg b/formal/AcpPermissionsNoCancelGuard.cfgnew file mode 100644index 00000000..41a22257--- /dev/null+++ b/formal/AcpPermissionsNoCancelGuard.cfg@@ -0,0 +1,6 @@+CONSTANTS BypassTokenOwner = FALSE+ BypassCancelGuard = TRUE+ BypassTokenConsume = FALSE+SPECIFICATION Spec+INVARIANTS TypeOK+ CancelNeverGrantsLatediff --git a/formal/AcpPermissionsNoConsume.cfg b/formal/AcpPermissionsNoConsume.cfgnew file mode 100644index 00000000..59466a0c--- /dev/null+++ b/formal/AcpPermissionsNoConsume.cfg@@ -0,0 +1,6 @@+CONSTANTS BypassTokenOwner = FALSE+ BypassCancelGuard = FALSE+ BypassTokenConsume = TRUE+SPECIFICATION Spec+INVARIANTS TypeOK+ TokenConsumedAtMostOncediff --git a/formal/AcpPermissionsNoTokenOwner.cfg b/formal/AcpPermissionsNoTokenOwner.cfgnew file mode 100644index 00000000..0a4d8761--- /dev/null+++ b/formal/AcpPermissionsNoTokenOwner.cfg@@ -0,0 +1,6 @@+CONSTANTS BypassTokenOwner = TRUE+ BypassCancelGuard = FALSE+ BypassTokenConsume = FALSE+SPECIFICATION Spec+INVARIANTS TypeOK+ StaleTransportNeverGrantsdiff --git a/formal/Http2Leases.cfg b/formal/Http2Leases.cfgnew file mode 100644index 00000000..d5c4c196--- /dev/null+++ b/formal/Http2Leases.cfg@@ -0,0 +1,9 @@+CONSTANTS RetainIdleOnLease = FALSE+ ReuseBeforeEnd = FALSE+SPECIFICATION Spec+INVARIANTS TypeOK+ IdleActiveDisjoint+ EveryLeaseOwnsLiveSession+ OnlyEndedIdle+ IdleOriginKnown+ OccupiedWinnerPreserveddiff --git a/formal/Http2Leases.tla b/formal/Http2Leases.tlanew file mode 100644index 00000000..7b3e9adf--- /dev/null+++ b/formal/Http2Leases.tla@@ -0,0 +1,156 @@+------------------------------- MODULE Http2Leases -------------------------------+EXTENDS Naturals, FiniteSets, TLC++CONSTANTS RetainIdleOnLease, ReuseBeforeEnd+ASSUME /\ RetainIdleOnLease \in BOOLEAN+ /\ ReuseBeforeEnd \in BOOLEAN++Requests == {"first", "second"}+Origins == {"A", "B"}+Sessions == {1, 2, 3}+None == 0+States == {"fresh", "active", "idle", "closed"}++VARIABLES created, requested, lease, idle, state, owner, originOf,+ ended, reusable, lastOccupied+vars == <<created, requested, lease, idle, state, owner, originOf,+ ended, reusable, lastOccupied>>++NoOccupied == [happened |-> FALSE, before |-> None,+ after |-> None, surplus |-> None, surplusClosed |-> FALSE]++Init ==+ /\ created = {}+ /\ requested = {}+ /\ lease = [r \in Requests |-> None]+ /\ idle = None+ /\ state = [s \in Sessions |-> "fresh"]+ /\ owner = [s \in Sessions |-> "none"]+ /\ originOf = [s \in Sessions |-> "none"]+ /\ ended = [s \in Sessions |-> FALSE]+ /\ reusable = [s \in Sessions |-> TRUE]+ /\ lastOccupied = NoOccupied++\* takeIdle removes the slot under the mutex before an active request obtains+\* its lease. A mismatched origin closes that idle session, then dials anew.+Acquire(r, origin) ==+ /\ r \in Requests+ /\ origin \in Origins+ /\ r \notin requested+ /\ LET same == idle # None /\ originOf[idle] = origin+ fresh == Sessions \ created+ IN /\ same \/ fresh # {}+ /\ LET chosen == IF same THEN idle ELSE CHOOSE s \in fresh : TRUE+ IN /\ created' = created \cup {chosen}+ /\ requested' = requested \cup {r}+ /\ lease' = [lease EXCEPT ![r] = chosen]+ /\ idle' = IF same /\ RetainIdleOnLease THEN idle ELSE None+ /\ state' = [s \in Sessions |->+ IF s = chosen THEN "active"+ ELSE IF ~same /\ s = idle THEN "closed"+ ELSE state[s]]+ /\ owner' = [owner EXCEPT ![chosen] = r]+ /\ originOf' = [originOf EXCEPT ![chosen] = origin]+ /\ ended' = [ended EXCEPT ![chosen] = FALSE]+ /\ reusable' = [reusable EXCEPT ![chosen] = TRUE]+ /\ UNCHANGED lastOccupied++\* The stream reader observes END_STREAM before a session may be reused.+MarkEnd(r) ==+ /\ r \in Requests+ /\ lease[r] # None+ /\ ~ended[lease[r]]+ /\ ended' = [ended EXCEPT ![lease[r]] = TRUE]+ /\ UNCHANGED <<created, requested, lease, idle, state, owner,+ originOf, reusable, lastOccupied>>++\* GOAWAY/non-reusable state must also stop a completed stream from pooling.+MarkUnusable(r) ==+ /\ r \in Requests+ /\ lease[r] # None+ /\ reusable[lease[r]]+ /\ reusable' = [reusable EXCEPT ![lease[r]] = FALSE]+ /\ UNCHANGED <<created, requested, lease, idle, state, owner,+ originOf, ended, lastOccupied>>++\* Lease.release: a successful session fills an empty slot. If another idle+\* session already won, this request closes only its own surplus session.+Release(r) ==+ /\ r \in Requests+ /\ lease[r] # None+ /\ LET s == lease[r]+ canKeep == reusable[s] /\ (ReuseBeforeEnd \/ ended[s])+ wins == canKeep /\ idle = None+ IN /\ lease' = [lease EXCEPT ![r] = None]+ /\ owner' = [owner EXCEPT ![s] = "none"]+ /\ idle' = IF wins THEN s ELSE idle+ /\ state' = [state EXCEPT ![s] = IF wins THEN "idle" ELSE "closed"]+ /\ lastOccupied' = IF idle # None /\ canKeep+ THEN [happened |-> TRUE, before |-> idle, after |-> idle',+ surplus |-> s, surplusClosed |-> state'[s] = "closed"]+ ELSE lastOccupied+ /\ UNCHANGED <<created, requested, originOf, ended, reusable>>++\* Cancellation owns only the request's lease; it never reaches the pool's+\* idle pointer or another request's active session.+Cancel(r) ==+ /\ r \in Requests+ /\ lease[r] # None+ /\ LET s == lease[r]+ IN /\ lease' = [lease EXCEPT ![r] = None]+ /\ owner' = [owner EXCEPT ![s] = "none"]+ /\ state' = [state EXCEPT ![s] = "closed"]+ /\ UNCHANGED <<created, requested, idle, originOf,+ ended, reusable, lastOccupied>>++\* Runtime shutdown detaches and closes the idle session only.+Shutdown ==+ /\ idle # None+ /\ state' = [state EXCEPT ![idle] = "closed"]+ /\ idle' = None+ /\ UNCHANGED <<created, requested, lease, owner, originOf,+ ended, reusable, lastOccupied>>++Next ==+ \/ \E r \in Requests, o \in Origins : Acquire(r, o)+ \/ \E r \in Requests : MarkEnd(r)+ \/ \E r \in Requests : MarkUnusable(r)+ \/ \E r \in Requests : Release(r)+ \/ \E r \in Requests : Cancel(r)+ \/ Shutdown++Spec == Init /\ [][Next]_vars++TypeOK ==+ /\ created \subseteq Sessions+ /\ requested \subseteq Requests+ /\ lease \in [Requests -> Sessions \cup {None}]+ /\ idle \in Sessions \cup {None}+ /\ state \in [Sessions -> States]+ /\ owner \in [Sessions -> Requests \cup {"none"}]+ /\ originOf \in [Sessions -> Origins \cup {"none"}]+ /\ ended \in [Sessions -> BOOLEAN]+ /\ reusable \in [Sessions -> BOOLEAN]+ /\ lastOccupied \in [happened : BOOLEAN, before : Sessions \cup {None},+ after : Sessions \cup {None}, surplus : Sessions \cup {None},+ surplusClosed : BOOLEAN]++IdleActiveDisjoint ==+ idle = None \/ (state[idle] = "idle" /\+ \A r \in Requests : lease[r] # idle)++EveryLeaseOwnsLiveSession ==+ \A r \in Requests : lease[r] = None \/+ (state[lease[r]] = "active" /\ owner[lease[r]] = r /\+ \A other \in Requests \ {r} : lease[other] # lease[r])++OnlyEndedIdle == idle = None \/ ended[idle]++IdleOriginKnown == idle = None \/ originOf[idle] \in Origins++OccupiedWinnerPreserved ==+ ~lastOccupied.happened \/+ (lastOccupied.before = lastOccupied.after /\+ lastOccupied.surplusClosed)++=============================================================================diff --git a/formal/Http2LeasesEarlyReuse.cfg b/formal/Http2LeasesEarlyReuse.cfgnew file mode 100644index 00000000..512e5f95--- /dev/null+++ b/formal/Http2LeasesEarlyReuse.cfg@@ -0,0 +1,5 @@+CONSTANTS RetainIdleOnLease = FALSE+ ReuseBeforeEnd = TRUE+SPECIFICATION Spec+INVARIANTS TypeOK+ OnlyEndedIdlediff --git a/formal/Http2LeasesRetainIdle.cfg b/formal/Http2LeasesRetainIdle.cfgnew file mode 100644index 00000000..0c39982e--- /dev/null+++ b/formal/Http2LeasesRetainIdle.cfg@@ -0,0 +1,5 @@+CONSTANTS RetainIdleOnLease = TRUE+ ReuseBeforeEnd = FALSE+SPECIFICATION Spec+INVARIANTS TypeOK+ IdleActiveDisjointdiff --git a/formal/README.md b/formal/README.mdindex 673e4ae6..36d9d2c5 100644--- a/formal/README.md+++ b/formal/README.md@@ -8,11 +8,25 @@ are difficult to reproduce with ordinary tests.changes, cancellation, and owner-boundary application.- [Async tools](async-tools.md): early admission, call identity, orderingbarriers, result ownership, joining, and cancellation.+- [ACP permissions](acp-permissions.md): transport-owned GUI tokens, replaced+ workers, offered choices, and responses racing with cancellation.+- [HTTP/2 leases](http2-leases.md): exclusive ownership, idle pooling,+ cancellation, shutdown, and reuse only after stream completion.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.+See [change evidence](change-evidence.md) for connecting source diffs, model+counterexamples, and runtime regressions.++See the [ranked extension plan](roadmap.md) for the next ownership, retry,+budget, and session properties to model.++The [DGM integration design](dgm-integration.md) separates formal admission+from task correctness and measured fitness, and identifies the native promotion+paths that need their own integration.+## ScopePassing TLC establishes the checked properties of these finite abstractions.diff --git a/formal/acp-permissions.md b/formal/acp-permissions.mdnew file mode 100644index 00000000..c8fdc1b2--- /dev/null+++ b/formal/acp-permissions.md@@ -0,0 +1,22 @@+# ACP permission ownership model++`AcpPermissions.tla` checks the permission decision path across a server bridge and the desktop transport. The finite baseline has two worker generations. Both use the same saved session name and the same server request ID (`1`); their token atoms differ. This makes a stale desktop response meaningful even when ordinary ID and session checks would pass. The token atoms abstract unpredictable, distinct UUIDs, not their random number generator.++The model separates parsing a server request (`FrontendReceive`) from delivering it to the GUI (`GuiDeliver`), choosing a response (`FrontendRespond`), and reading that response on server stdin (`ServerAccept`). It also separates frontend cancellation (`FrontendCancel`) from server cancellation (`ServerCancel`). This allows a response to be accepted before cancel, or to be queued and rejected after cancel. `Restart` changes the active worker and clears its live token while leaving a historical GUI token available for a stale-click test. A queued wire response remains addressed to its original transport.++| Model step or guard | Current implementation |+| --- | --- |+| `ServerAsk`, one pending request, offered choices | `src/acp_permission.zig` `Bridge.ask`, especially the `closed`/`pending` check, sequence assignment, and option array |+| `FrontendReceive`, transport-local token | `apps/native/lib/acp-transport.ts` `feed` creates a token and stores request ID, session, and offered options in that transport's `permissions` map |+| `GuiDeliver` | `feed` notifies/subscribes listeners; `apps/native/lib/acp-client.ts` maps requests to `gui_permission` for prompt and idle streams |+| `FrontendRespond` and token consumption | `apps/native/app/api/acp/route.ts` handles `session/permission` against the current chat slot; `AcpTransport.respondPermission` checks token, session, option, and failure, deletes the token before writing |+| `ServerAccept` | `src/acp_permission.zig` `Bridge.accept` checks the pending server ID, closed/decision state, and offered `allow_always`; an unknown result becomes denial |+| `FrontendCancel` | `AcpTransport.notify("session/cancel")`, `clearPermissions`, transport failure, or prompt completion clears live tokens |+| `ServerCancel` | `Bridge.cancel`, called from `src/acp_inbox.zig` on cancellation or EOF and from `src/acp_live_turn.zig` on turn exit |+| `Restart` | The route's current chat slot can point to a replacement `AcpTransport`; an old token is absent from its map even if the saved session and server ID recur |++`StaleTransportNeverGrants` checks every recorded grant's token owner against the worker that granted it. `CancelNeverGrantsLate` checks the pending and cancellation state *at acceptance*; it does not say that a later cancel revokes a completed grant or tool execution. `UnofferedNeverGrants` checks the server's independent allowlist with `InjectUnoffered`, an invalid `allow_always` response that bypasses the frontend. `TokenConsumedAtMostOnce` checks frontend token consumption. The first three inspect a grant history rather than merely restating state types. There is no liveness claim: a client may disconnect or never answer, and the source does not promise eventual approval or rejection without an external event.++The normal configuration is `AcpPermissions.cfg`. Three targeted negative controls change transition guards: `AcpPermissionsNoTokenOwner.cfg` lets a previously delivered token be sent through a replacement transport and violates `StaleTransportNeverGrants`; `AcpPermissionsNoCancelGuard.cfg` lets an in-flight response grant after server cancellation and violates `CancelNeverGrantsLate`; `AcpPermissionsNoConsume.cfg` retains a token after sending and allows a second send, violating `TokenConsumedAtMostOnce`. Each counterexample uses the same action sequence as the baseline until the removed guard matters.++This is a state-machine abstraction, not a proof of the Zig or TypeScript implementations. It assumes serial processing within each bridge/transport, correctly scoped chat lookup, and distinct generated tokens; it abstracts JSON parsing, OS process lifetime, write errors, clock time, persistent approvals, and engine policy checks. It fixes the session name to the same value in both generations, so it exercises the harder repeated-session restart case but does not check wrong-session input. It bounds one request per worker generation and one in-flight wire response; arbitrary duplicate server replies are outside the state space, while duplicate desktop clicks are rejected by token removal. A direct client with stdin access is the ACP trust boundary: the server can accept a valid pending `allow_once` response without a desktop token. The model's token-ownership property therefore applies to the desktop route, while the server's pending-ID and option checks are modeled separately. `Bridge.begin` is used only after the previous ask has retired; this is an explicit source/lifecycle assumption, not a property established by this model.diff --git a/formal/change-evidence.md b/formal/change-evidence.mdnew file mode 100644index 00000000..25859ebc--- /dev/null+++ b/formal/change-evidence.md@@ -0,0 +1,49 @@+# Making behavioral changes reviewable++A Git diff shows edited text. A lifecycle model states which behaviors that edit+allows or forbids across concurrent events. Neither replaces evidence from the+running implementation.++For each behavioral change, retain this chain:++1. **Source revision and rule.** Identify the exact before/after code and the+ changed transition or guard. Do not silently replace the historical code with+ a hypothetical broken version.+2. **Model difference.** Show the corresponding before/after action, invariant+ and explicit environment assumptions. Record finite bounds for both checks.+3. **Counterexample or check result.** When an invariant fails, describe the+ shortest useful sequence of actions. When it passes, state only the bounded+ properties checked; a state count is not a coverage percentage.+4. **Runtime scenario.** Exercise that sequence through the corresponding code+ path. Ideally the regression test fails on the actual old revision and passes+ on the new one. A test that only inspects source text is weaker evidence.+5. **Outcome evidence.** Separately measure any claimed performance improvement.+ Correctness model checks establish no wall-time, token, caching or cost win.++## Existing connections++| Behavioral rule | Formal check | Existing runtime regression anchor |+| --- | --- | --- |+| An old effort worker cannot fill a newer admission | `SelectedOriginIsCurrent` | `src/jev_effort_state.zig`: `pending effort is per agent, first admission wins, and stale routes or tokens do not apply` |+| A repeated tool ID must not execute twice | `AtMostOnceExecution` | `src/agent_async_tools.zig`: `async tools complete call dispatches once in headless mode and claims once` |+| A synchronous predecessor stops early admission | `NoLateAdmission` | `src/agent_async_tools.zig`: `async tools do not cross a synchronous predecessor or execute partial arguments` |+| Owned workers retire before their storage is freed | Async cancellation/reset model | `src/agent_async_tools.zig`: `async tools reset cancels and joins workers before freeing owned state` |+| Permission replies belong to their live transport and session | ACP permission extension | `apps/native/lib/acp-permission.test.ts`: `permission replies bind process, session, original ID and offered option exactly once` |++These anchors connect intent and implementation tests. They do not establish+that every modeled interleaving is exercised by a runtime test, or that the+implementation refines the model. Inspect and run the relevant tests when the+mapped code changes.++## Negative controls are not historical regressions++The existing `*Stale` and `*No*` configurations deliberately remove guards from+the model. Their counterexamples establish that the invariant detects that+mistake. They do **not** by themselves show that a historical release contained+it. Describe those results as mutation checks unless an actual earlier source+revision and failing runtime test support the historical claim.++A future change report should explicitly mark its evidence level: model only,+model plus current runtime test, or before/after source with a runtime regression+reproduced on both revisions. Missing evidence stays missing; do not turn a+plausible source mapping into a claim of proof.diff --git a/formal/dgm-integration.md b/formal/dgm-integration.mdnew file mode 100644index 00000000..d4cbd717--- /dev/null+++ b/formal/dgm-integration.md@@ -0,0 +1,75 @@+# Formal checks in the evolution loop++Formal evidence is an admission condition, not a fitness reward. Passing a+model check must never compensate for failed task correctness, and neither+formal success nor a smaller prompt establishes a performance improvement.++## Prompt evolution and source evolution++`examples/dgm_loop.py` evolves prompt genomes. Its correctness gate is the+external held-out replay judge. Its current passing score ranks tool economy:+`total / (total + tool_calls)`. Formal checks validate the pinned harness+baseline beneath those prompt candidates; they do not prove prompt behavior.+Keep the reward formula unchanged when adding the gate.++For harness-source evolution, each candidate instead needs an immutable source+identity, a reviewed mapping between its lifecycle changes and formal actions,+model checks, and runtime regressions. Hashing a source tree and an executable+records their identities; it does not prove the executable was built from that+source. A reproducible build or attested build receipt supplies that separate+link.++## Evaluation flow++```mermaid+flowchart TD+ A[Pin evaluator, models, source and executable] --> B[Run formal baseline checks]+ B -->|Fail or unavailable| X[Stop formal-enabled evaluation]+ B -->|Pass| C[Generate prompt candidate]+ C --> D[Revalidate pins and bind candidate receipt]+ D --> E[Run held-out replay tests]+ E -->|Any failure| F[Keep below passing score band]+ E -->|All pass| G[Compute existing efficiency score]+ G --> H[Revalidate inputs before score write]+ H --> I[Archive signed evidence digest and score]+```++The same checked baseline can be reused for multiple prompts while every pinned+input remains unchanged. Input drift invalidates admission; it must not silently+trigger a new baseline or allow the candidate to rewrite its own checker.+Keep evaluator copies and pin files outside the editable task workspace. These+integrity checks do not replace OS isolation for adversarial evolution.++A receipt should distinguish source/model identity, finite checked properties,+checker result, candidate prompt identity, held-out suite identity and executable+identity. Preserve the original replay suite hash and bind the formal receipt+into score provenance. Retain formal failure separately from replay failure,+unknown measurement and an ordinary low efficiency score.++## Other native promotion paths++The repository also has native learning and persona promotion paths. Integrating+the Python example alone does not gate all of them:++- `src/learn_tournament.zig` selects one primary winner and applies holdout+ eligibility. Formal evidence belongs in admission and final eligibility,+ without allowing it to rescue a primary or holdout rejection.+- `src/learn_run.zig` persists checkpoints and comparison records. A resumed run+ needs the same checked identity; a receipt from an earlier source cannot be+ reused merely because the prompt genome matches.+- `src/learn_receipt.zig` signs aggregate learning evidence. Adding a formal+ receipt to this path requires a versioned signed schema and validation.+- `src/fleet.zig` promotes local archive champions. Historical scores without+ formal evidence cannot be represented as formally checked evaluations.++These are separate integration points, not properties established by the+Python gate. A rollout must identify which entry points enforce formal mode,+and preserve explicit distinction between unchecked and checked archives.++## Performance evidence remains separate++Wall time, input/output tokens, cached input, cache writes and cost need paired+runtime measurements with preserved failures and per-metric completeness.+Unknown usage is not zero, and subscription usage is not a billed-dollar receipt.+The formal gate does not change these measurement requirements or establish+that a candidate is faster, cheaper, or more capable.diff --git a/formal/http2-leases.md b/formal/http2-leases.mdnew file mode 100644index 00000000..8a6d1873--- /dev/null+++ b/formal/http2-leases.md@@ -0,0 +1,16 @@+# HTTP/2 lease ownership model++`Http2Leases.tla` models two concurrent requests, two origins, and three possible session identities. The pool has one idle slot. An active request owns an exclusive lease; a second request can dial a different session while the first is active. The source's connection reader is sequential, so the model deliberately does not permit simultaneous streams on one session. This follows ADR 0162.++| Model step | Implementation |+| --- | --- |+| `Acquire` | `src/http2_pool.zig` `takeIdle` removes the idle pointer under `mu`, closes a mismatched-origin idle session, and `acquire` opens a new session outside the lock when needed. `src/agent_stream_h2.zig` `headTask` obtains the lease before `startLines`; `src/http2_buffered.zig` `tryH2` uses the same pool. |+| `MarkEnd` | The `LineStream.ended` state observed after END_STREAM. `agent_stream_h2.zig` `settleAfterEnd` checks this after the application terminal event. |+| `MarkUnusable` | `Session.reusable()` can reject a connection after GOAWAY; streaming and buffered callers require it before setting `keep`. |+| `Release` | `Lease.release` closes a failed/cancelled or surplus session; a reusable lease fills only an empty idle slot. Both callers defer release until their stream is destroyed. |+| `Cancel` | A cancelled request unwinds its own lease with `keep = false`; it does not close the pool's idle pointer or a different active lease. |+| `Shutdown` | `http2_pool.shutdown` removes and closes only the idle session. |++The baseline checks `IdleActiveDisjoint`, `EveryLeaseOwnsLiveSession`, `OnlyEndedIdle`, `IdleOriginKnown`, and `OccupiedWinnerPreserved`. The last property records the occupied-slot release result: the original idle winner remains in the slot and the surplus lease closes. `Http2LeasesRetainIdle.cfg` removes idle-slot detachment on acquire and produces an `IdleActiveDisjoint` counterexample. `Http2LeasesEarlyReuse.cfg` permits a live request to return a session before END_STREAM and produces an `OnlyEndedIdle` counterexample. The mutations alter actions; the invariants remain unchanged.++This is a finite state-machine check, not a proof of HTTP/2 framing, TLS, cancellation machinery, or the implementation language. A session has one exclusive request at a time; the three identities bound at most two active sessions plus one idle candidate. Request origins are abstract atoms, so case-insensitive host normalization and ports are outside the model. Dial/ALPN failures, stream IDs, connection flow control, and OS socket races are omitted. The model treats `ended` as a reliable signal from the pinned HTTP library and `reusable` as its independent connection-health gate. It states safety only: there is no fairness assumption and no eventual-completion or throughput claim.diff --git a/formal/roadmap.md b/formal/roadmap.mdnew file mode 100644index 00000000..c744bf1c--- /dev/null+++ b/formal/roadmap.md@@ -0,0 +1,64 @@+# Further lifecycle formalization++This is a ranked plan, not a list of proved properties. Add a model only when+its state transitions can be mapped to implementation boundaries and a negative+control can demonstrate that its invariants detect the intended mistake.++| Priority | Lifecycle | Properties to check | Implementation anchors |+| --- | --- | --- | --- |+| 1 | ACP permissions | Only a pending request on the owning live transport accepts an offered option; stale or duplicate replies cannot grant; cancellation denies pending input. | `src/acp_permission.zig`, `apps/native/lib/acp-transport.ts`, ADR 0180 |+| 2 | HTTP/2 lease ownership | A connection has at most one active owner; idle and leased sets are disjoint; cancellation closes only its lease; only completed streams return to the idle slot. | `src/http2_pool.zig`, `src/agent_stream_h2.zig`, ADR 0162 |+| 3 | Retry and usage accounting | An ambiguous send cannot silently fall back; every retry crosses request admission; an unresolved attempt remains unknown after later success; cleanup cannot count it twice. | `src/agent_request.zig`, `src/request_usage_attempts.zig`, ADR 0183 |+| 4 | Shared descendant budgets | Concurrent tool reservations cannot exceed a finite limit; failed tools still consume admission; each concurrency permit releases once; cancellation can retire a waiter. | `src/run_budget.zig`, ADR 0169 |+| 5 | Session configuration and restore | A setting received during a turn applies at the boundary; a delayed response cannot change another session; restoring history cannot execute saved tools again. | `src/acp_config.zig`, ADRs 0181 and 0191 |++## What makes the next models useful++Use at least two actors where ownership matters. For permissions, include two+transport generations with a repeated server request ID: proving uniqueness+only within one process misses the frontend replacement hazard. Model delivery+and cancellation as separate steps so their ordering is explored.++For HTTP/2, include two concurrent requests, two origins, an occupied idle slot,+and shutdown while another lease is active. Do not assume shared connection+multiplexing: the implementation deliberately uses exclusive leases. A model+must distinguish connection ownership from request success.++For retries, distinguish failures before send, proven-unprocessed requests and+ambiguous delivery. Remote exactly-once execution is not a property the harness+promises. Correctness means that retry policy and uncertainty accounting see+every ambiguous attempt, including when a later retry succeeds.++Budget liveness needs explicit environmental assumptions. A concurrency bound+does not prove that a remote call terminates or that every waiter is scheduled.+Model call limits separately from concurrency and tool-call limits.++## DGM admission++The existing `examples/dgm_loop.py` evolves prompt genomes. A formal gate can+validate the pinned harness baseline used for evaluation, but cannot certify+that a generated prompt obeys its instructions. Keep deterministic held-out+tests as the prompt correctness gate. Formal failure must prevent promotion;+formal success must not add fitness points.++For future harness-source evolution, model each changed lifecycle and bind the+check receipt to that candidate source, checker, configuration and executable.+A separate promotion-state model could check that no stale or missing formal+receipt, failed replay, or changed candidate can reach the passing score band.+That model would describe admission policy, not prove the underlying evaluator+or model implementation trustworthy.++## Closing the gap to code++Each model should ship with a source mapping, finite bounds, safety invariants,+explicit fairness assumptions for any liveness property, and targeted broken+variants. Counterexample traces should become deterministic runtime regression+scenarios where practical. Keep parser, allocator, socket and frontend delivery+tests: the model abstracts these mechanisms rather than verifying them.++After the models stabilize, add a separate pinned-toolchain CI job for changes+to the modeled source paths and formal files. A green Zig test job alone does+not establish that TLC ran. A future trace-conformance checker could compare+sanitized runtime state transitions to allowed model actions; it would improve+implementation evidence but would still not establish an unbounded refinement+proof. Do not export private traces to the public tracker.diff --git a/scripts/check-formal.py b/scripts/check-formal.pyindex 6d42f419..08dacd4c 100644--- a/scripts/check-formal.py+++ b/scripts/check-formal.py@@ -23,6 +23,13 @@ CASES = (("AsyncTools.tla", "AsyncToolsNoJoin.cfg", "JoinedBeforeNextRequest"),("AsyncTools.tla", "AsyncToolsNoDedup.cfg", "AtMostOnceExecution"),("AsyncTools.tla", "AsyncToolsNoBarrier.cfg", "NoLateAdmission"),+ ("AcpPermissions.tla", "AcpPermissions.cfg", None),+ ("AcpPermissions.tla", "AcpPermissionsNoTokenOwner.cfg", "StaleTransportNeverGrants"),+ ("AcpPermissions.tla", "AcpPermissionsNoCancelGuard.cfg", "CancelNeverGrantsLate"),+ ("AcpPermissions.tla", "AcpPermissionsNoConsume.cfg", "TokenConsumedAtMostOnce"),+ ("Http2Leases.tla", "Http2Leases.cfg", None),+ ("Http2Leases.tla", "Http2LeasesRetainIdle.cfg", "IdleActiveDisjoint"),+ ("Http2Leases.tla", "Http2LeasesEarlyReuse.cfg", "OnlyEndedIdle"),)