lemmascript 0.5.1 → 0.5.3

package/README.md

@@ -18,15 +18,24 @@ See the external case studies:
 - **[collab-todo-lemmascript](https://github.com/midspiral/collab-todo-lemmascript/)** — collaborative task management web app (React + Supabase) with a verified domain model. Single `domain.ts` imported directly by the UI, hooks, and edge functions — no adapter layer. 123 Dafny lemmas (120 in a separate `domain.proofs.dfy`): 16-conjunct invariant preserved across 25 single-project + 3 cross-project actions, NoOp completeness/soundness, initialization. Dafny only.
 - **[colorwheel-lemmascript](https://github.com/midspiral/colorwheel-lemmascript/)** — verified color palette generator with mood + harmony constraints. 31 Lean proofs + 18 behavioral properties, 115 Dafny lemmas (invariant preservation, commutativity, NoOp completeness).
 - **[clear-split-lemmascript](https://github.com/midspiral/clear-split-lemmascript/)** — greenfield verified expense splitting web app. Conservation theorem, invariant preservation, delta laws — all proven in both Lean (no sorry) and Dafny (56 lemmas).
+- **[eventab-lemmascript](https://github.com/midspiral/eventab-lemmascript/)** — greenfield verified group bill-splitter, shipped as a single self-contained client-side page. Largest-remainder allocation in integer cents proves the money never leaks: per-person shares sum exactly to the tab, non-claimers pay nothing, and the settlement nets to zero even when payments are rounded to the dollar (the payer absorbs the difference). Dafny only.
 - **[github-star-checker-lemmascript](https://github.com/midspiral/github-star-checker-lemmascript/)** — small verified CLI that tracks GitHub star counts across repos and reports per-run deltas. Verifies: per-row diff correctness and `totalDiff == sumDiffs(rows)` (via an inductive `SumDiffs_append` lemma); three sign-classified extractors (gainers / losers / unchanged) with soundness, completeness, **ordered completeness** (gainers appear in the notification in the same order they were listed on the command line), and count/sum equalities against prefix-indexed `upTo` helpers; conservation theorem `decompose(r)` — the three splits partition every row exactly once, and `sumDiffs(increases) + sumDiffs(decreases) == totalDiff`. 33 Dafny VCs, 0 errors; proof additions include a head/tail bridge (`sumDiffs` ↔ `sumDiffsUpTo`) and two partition-on-n inductions. Dafny only.
 - **[equality-game-lemmascript](https://github.com/midspiral/equality-game-lemmascript/)** — greenfield verified arithmetic equality card game (React + Tailwind). Sound + complete decision procedure for "can these two card lists be combined into equal expressions": `canEqualize(L, R) ⟺ ∃ eL, eR. eval(eL) == eval(eR) ∧ multiset(leaves(eL)) == multiset(L) ∧ same for R`. Algorithm is subset-DP over a bitmask `m ∈ [1, 2^n − 1)`; the proof composes a `PopCount` upper/lower bound chain (with stdlib `LemmaDivDenominator` / `LemmaFundamentalDivModConverse`), a `splitLeft`/`splitRight` ↔ imperative-loop connection, a `WitnessCombine` lemma threading existential `Expr` witnesses through the cross-product loops, and a `ChooseMask` combinatorial constructor that, given any sub-multiset of `cards`, produces the realizing mask. Capped by `CompletenessFromMaskCoverage`. 753 verification conditions, 0 errors, 0 `assume`s, 0 axioms under `--isolate-assertions --verification-time-limit 180`. Dafny only.
 - **[talktimer-lemmascript](https://github.com/midspiral/talktimer-lemmascript/)** — verified talk timer React app, ported from a Dafny-only [`talktimer-lemmafit`](https://github.com/midspiral/talktimer-lemmafit/) twin. 17-variant `Action` state machine + verified `History` (undo/redo/preview/commitFrom) all in one `domain.ts` — the original Dafny's `Domain refines Kernel` abstract-module pattern inlined since LS has no abstract modules. 108 VCs in `domain.dfy` (invariant preservation) + 123 in `domain.proofs.dfy` (behavioral lemmas + Kernel round-trip). Dafny only.
 - **[node-casbin-lemmascript](https://github.com/midspiral/node-casbin-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield verification of [node-casbin](https://github.com/casbin/node-casbin). 5 functions verified, 217 existing tests pass. End-to-end correctness and order independence for all 4 effect modes in both Lean and Dafny (39 lemmas).
 - **[hono-lemmascript](https://github.com/midspiral/hono-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield verification of [hono](https://github.com/honojs/hono)'s security middleware. Four CVEs covered: IP restriction bypass ([CVE-2026-39409](https://github.com/honojs/hono/security/advisories/GHSA-3mpf-rcc7-5347)) and cookie name bypass ([CVE-2026-39410](https://github.com/honojs/hono/security/advisories/GHSA-r5rp-j6wh-rvv4)) — 51 Dafny lemmas, [cookie verification **in-place**](https://github.com/midspiral/hono-lemmascript/blob/lemmascript/src/utils/cookie.ts#L79); plus `serveStatic`'s URL-encoded directory traversal ([CVE-2024-32869](https://github.com/honojs/hono/security/advisories/GHSA-q5w7-8mq6-2hxq)) + repeated-slash bypass ([CVE-2026-39407](https://github.com/honojs/hono/security/advisories/GHSA-jw53-c2g8-vmwm)), proved as a *composition* — `decode(rawPath)` before `check(decoded)`, so a buggy implementation that reordered the steps would fail the proof. First use of `//@ assume` + `//@ havoc`-on-assign. Dafny only.
+- **[hono-rate-limiter-with-lemmascript](https://github.com/midspiral/hono-rate-limiter-with-lemmascript)** — a greenfield verified feature shipped through a brownfield host's *middleware seam*: a standalone [Hono](https://hono.dev) rate-limit middleware whose admission decision is a machine-checked theorem. Every fixed-window "N per minute" limiter leaks the same way — a client fires `limit` requests just before a boundary and `limit` more just after, a 2× burst the docs swear can't happen. The verified core proves the crisp guarantee people actually want: over an integer-millisecond admission log, `admit` keeps `|log| ≤ limit` and window-faithful, and folding it over **any** monotone request stream (`run`) keeps the cumulative log `Spread` — so **no half-open window `(s, s+W]` ever admits more than `limit`** (`SlidingWindowBound`); the boundary burst is not mitigated but *impossible*. The naive cousin is refuted in the same file: `FixedWindowLeaks` exhibits a concrete trace where a fixed-window counter admits `2 × limit` in one sliding window while the verified `admit` rejects the overflow. An invariant-over-a-stateful-core proof (not a one-shot algorithm), wired into a live Hono server that gates real HTTP. 23 Dafny VCs, 0 errors; the clock's monotonicity and the per-key store's atomicity are the named trust boundary. Dafny only.
 - **[charmchat](https://github.com/CHARM-BDF/charmchat/blob/lemma/README_LemmaScript.md)** — brownfield verification of an AI agent orchestration backend. `isEmptyResult` (string emptiness predicate, 8 postconditions, <1s) and `topologicalSort` (Kahn's algorithm — memory safety, output bounds, completeness via acyclicity ranking witness, termination). Full completeness proof: 23 helper lemmas, 14 opaque ghost predicates, 115 loop invariants; 736 VCs verified under `--isolate-assertions --verification-time-limit 600`. Key technique: snapshot-based inner invariants (`ghost var originalRemDeps := remDeps`) replace the mid-iteration SEEN/UNSEEN split so preservation is frame reasoning against a ghost-constant rather than set-subtraction against mutating state. Dafny only.
-- **[xyflow-lemmascript](https://github.com/midspiral/xyflow-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield verification of [xyflow](https://github.com/xyflow/xyflow)'s core edge and geometry utilities. 9 functions verified: `addEdge` (dedup — never loses edges, adds at most one), `reconnectEdge` (semantic: under a unique-id precondition, the result is in-place — `|result| ≤ |edges|`, no insertion — *and* when a matching edge existed with non-empty new endpoints, the output contains an edge with those endpoints. Uses `//@ assume` to characterize destructuring, `find`, and the constructed edge), `connectionExists`, `getEdgeCenter` (midpoint correctness), `clamp` (bounds), `rectToBox`/`boxToRect` (field arithmetic), `getBoundsOfBoxes` (enclosure), `getOverlappingArea` (non-negative), `areSetsEqual` (subset + same size). 14 Dafny proof obligations. Dafny only.
+- **[xyflow-lemmascript](https://github.com/midspiral/xyflow-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield verification of [xyflow](https://github.com/xyflow/xyflow)'s core edge and geometry utilities. 9 functions verified: `addEdge` (dedup — never loses edges, adds at most one), `reconnectEdge` (semantic: under a unique-id precondition, the result is in-place — `|result| ≤ |edges|`, no insertion — *and* when a matching edge existed with non-empty new endpoints, the output contains an edge with those endpoints. Uses `//@ assume` to characterize destructuring, `find`, and the constructed edge), `connectionExists`, `getEdgeCenter` (midpoint correctness), `clamp` (bounds), `rectToBox`/`boxToRect` (field arithmetic), `getBoundsOfBoxes` (enclosure), `getOverlappingArea` (non-negative), `areSetsEqual` (subset + same size). 14 Dafny proof obligations. Also adds a new verified feature — a **DAG connection gate**: `canReach` decides reachability soundly *and* completely, and `wouldCreateCycle` gates both new connections and edge reconnections so the graph is proven to stay acyclic, with `isAcyclic` (sound + complete) establishing the base case and a topological-rank witness giving a safe evaluation order (+29 obligations), shown live in a React Flow demo that refuses cycle-closing edges — extending the case study from verifying existing code to adding a verified feature. Dafny only.
 - **[rallly-lemmascript](https://github.com/midspiral/rallly-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield verification of [rallly](https://github.com/lukevella/rallly)'s meeting-poll Next.js app. 2 functions: `validateRedirectUrl` (in-place — open-redirect predicate; non-`undefined` outputs start with `/` but not `//`) and `scorePoll` (extracted ranking core — length preservation, score bounds, top-choice characterization, score-formula equality, within-poll monotonicity, tiebreaker injectivity). The injectivity proof surfaced a real spec-level constraint on the existing `(yes + ifNeedBe) * 1000 + yes` encoding: it overflows when an option has ≥ 1000 yes votes. 10 Dafny VCs, 0 errors. Drove four toolchain additions: `s.startsWith()`, `T | null` nullability, `\result` narrowing under `==>`, `Math.max(...arr)` spread. Dafny only.
 - **[opencode-lemmascript](https://github.com/midspiral/opencode-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield verification of [opencode](https://github.com/anomalyco/opencode)'s permission system and unified-diff patch parser. Highlights: (1) `Patch.parsePatch` carries conservation loop invariants over local ghost state — a parser bug here would silently corrupt user files when an AI applies a patch, and (2) the permission-engine work mechanically closes opencode bug #26514 (subagents bypassing Plan Mode's file-edit restrictions). 9 functions verified in-place, 0 errors. Dafny only.
+- **[pi-lemmascript](https://github.com/midspiral/pi-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield, **in-place** verification of the context-compaction cut-point selector in **pi** (the [earendil-works](https://pi.dev) agent harness). When the context window fills, pi discards history before a chosen cut; a provider API rejects a retained prefix containing an orphaned `toolResult` (a tool result whose tool call was cut away). Both selector functions proven: the cut never lets the kept suffix *start with* — nor *split a tool-use/tool-result run* into — an orphaned tool result, even across the backward metadata snap. The no-orphan result forced the session tree's tool-pairing ordering into an explicit `requires`. 4 VCs, 0 errors. Drove five toolchain additions, headlined by an **opaque fall-through type**: a union LemmaScript can't discriminate (here an array-element union of unreachable imports) becomes a single opaque `type` — the field stays present so distinct values stay distinct, and with no constructor or tag predicate it can only be passed through, never unsoundly observed. Dafny only.
+- **[balanced-match-lemmascript](https://github.com/midspiral/balanced-match-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield, **in-place** verification of [balanced-match](https://github.com/juliangruber/balanced-match), the ~70-line balanced-bracket finder pulled in by `npm`, `webpack`, and most of the JS tooling stack (1B+ downloads/month). The stack-based `range` core is verified by **refinement**: a pure recursive spec `range_spec` mirrors the loop one branch per recursive case, so the single equivalence `range == range_spec` transfers every property automatically — including an unconditional Dyck body-balance theorem for the interior of every returned pair. 2233 VCs, 0 errors under `--isolate-assertions` (registered on the `dafny-slow` track). Dafny only.
+- **[guardians-lemmascript](https://github.com/midspiral/guardians-lemmascript)** — greenfield verification of the core safety argument behind [Guardians](https://github.com/metareflection/guardians) (Erik Meijer, "Guardians of the Agents", CACM Jan 2026), a generate-verify-execute checker for AI-agent workflows. Instead of verifying an app, it proves the agent *guardrail itself sound* — that a static taint/automaton check over the real recursive workflow AST can never admit an unsafe plan. Highlights: taint over **nested conditionals** as a sound branch-union over-approximation; per-source **provenance** with a join (a multi-input tool is tainted if *any* input was); **unbounded loops** discharged by a one-step pre-fixpoint (`sat = t0 ‖ bodyTaint(t0)`) that bounds taint over any iteration count without iterating to a fixpoint; and a **unified capstone** (`verifyWfSound`) — one clean verdict rules out, on *every* path, both a tainted-data-to-sink leak and a security-automaton error. 54 Dafny obligations, 0 errors. The verified cores are reached from a Guardians-style `Workflow`/`Policy` through a thin *unverified* adapter, differentially tested against the real Python Guardians (used as the oracle, not a porting target). Dafny only.
+- **[quorum-lemmascript](https://github.com/midspiral/quorum-lemmascript)** — greenfield verified when2meet/Doodle-style group scheduler (React + Cloudflare Durable Objects), with one `domain.ts` running unchanged in the browser, the in-app query, and the server. The standout is that **the proof licenses the architecture**: `countFree` is a homomorphism from participant-list concatenation to integer addition (so the heatmap is order-independent) plus same-participant last-writer-wins convergence — which is exactly what makes the lock-free, no-login, *optimistic* multi-device backend safe, with the Durable Object and the browser applying the **same** verified `applyOp` (server-authoritatively, client-optimistically) with no rollback or operational transform. Also: heatmap is exactly the per-slot count and `isBest` exactly its argmax; monotonicity; invariant-preserving mutations + op-log `replay`; a sparse export codec round-trip; an in-app `whoIsFree(e, s)` whose length provably equals the cell's count; and a separate `grid.ts` proving the `(day, time) → slot` map in-range + injective — which makes specific-dates-vs-days-of-the-week pure shell labeling at zero proof cost; and full element-level permutation invariance (`heatmapPermInvariant` — the heatmap depends only on the *multiset* of participant rows), which drove the `perm(...)` spec predicate into LemmaScript itself. 100 Dafny VCs (90 + 10), 0 errors. The *aggregate* is proven; the React UI, WebSocket/DO I/O, and timezone labeling are the stated trust boundary. Dafny only.
+- **[quota-lemmascript](https://github.com/midspiral/quota-lemmascript)** — greenfield verified booking app: providers publish a page of limited-capacity *featured slots*, signed-in users grab them (React + Cloudflare Durable Objects + D1). A deliberate **inverse** of [quorum-lemmascript](https://github.com/midspiral/quorum-lemmascript): where Quorum counts *up to* a threshold over data partitioned **per participant** (no conflicts ⇒ optimistic, lock-free, no rollback), Quota's bookings **contend** for shared inventory, so the load-bearing fact flips from a count to a **bound** — for every slot `j`, `confirmedCount(bookings, j) <= slots[j].capacity` — and so does the concurrency story: the *same* `domain.ts` runs in the browser and the Durable Object, but **server-authoritatively** (it never oversells under contention; no optimistic client apply). Proven: no overbooking (invariant preservation across `tryBook` / cancel), accept-iff-room, an **idempotent three-way `tryBook`** (a retry reads as success, not rejection — only "confirmed" mutates), cancellation frees seats, replay determinism, and full order-invariance of availability under contention — `confirmedCountPerm` / `hasRoomPermInvariant` show availability depends only on the *multiset* of the booking log (any reordering, not just a pairwise swap), via the same `perm(...)` predicate Quorum drove into LemmaScript. NDJSON export is built on the verified `confirmedOnly`. The counting kernel is Quorum's `countFree` re-pointed at bookings — total and precondition-free so it composes. 80 Dafny VCs, 0 errors. Trust boundary (stated plainly): auth, the React UI, WebSocket/DO/D1 I/O, email, slot date/time labeling, and abuse/rate-limiting. Dafny only.
+- **[henri-lemmascript](https://github.com/midspiral/henri-lemmascript)** — a runnable TypeScript coding-agent CLI (a port of [henri](https://github.com/metareflection/henri/); multi-provider, Anthropic + AWS Bedrock) whose security- and protocol-critical core is verified and **imported directly by the live agent** — `decide()` gates every real tool call and the conversation invariant is asserted on every turn (it streams end-to-end against Bedrock). Three modules, 48 Dafny VCs, 0 errors. (1) **Permission gate**: soundness (`decide == Allow ⟺ isAllowed`), **path-traversal containment** — auto-allow-in-cwd can never resolve outside cwd, with `.`/`..` normalization proved in-core so the shell is trusted only to `resolve().split('/')` — grant monotonicity, and `rejectPrompts` is deny-only. (2) **Conversation protocol**: tool-call/result pairing plus the [pi-lemmascript](https://github.com/midspiral/pi-lemmascript)-style **no-orphaned-`tool_result`** property, proved as an invariant *preserved by the loop* — `wellFormed(msgs + [assistant(calls), tool(makeResults(calls))])` — not checked after the fact. (3) **Hook/config merge**: removal, **tool-name uniqueness — a fix** (henri concatenated hook tool lists with no dedup, so two hooks could shadow a name), order-independence, and additivity composed **cross-module** with the gate's monotonicity (merging only grows the allow-sets, which by P3 never revokes an `Allow`). The merge is verified **in place** via `//@ declare-type Tool { name: string }`, shadowing the real `Tool`'s function-valued `execute` so the actual `mergeTools(Tool[])` is the proof target rather than a parallel model. Dafny only.
+- **[eslint-plugin-with-lemmascript](https://github.com/midspiral/eslint-plugin-with-lemmascript)** — a greenfield verified feature shipped through a brownfield host's *extension API*: a real, npm-published [ESLint](https://eslint.org) flat-config plugin whose rule decision is a machine-checked theorem. `no-forbidden-reach` enforces architecture boundaries — "the UI must never reach the DB layer" — through **any** import chain, catching the *laundered* `ui → service → db` violation that every one-hop incumbent (`import/no-restricted-paths`, `eslint-plugin-boundaries`, Nx module boundaries) silently passes. The verified core decides reachability soundly *and* completely (`reachesAny` / `violates`) and **constructs** the offending chain in proven code (`findReachPath` — a path-carrying BFS proven sound + complete by mirroring the frontier's endpoints in a ghost seq, so completeness reduces to the same closure argument as the reachability search; the chain printed in the lint error is therefore itself a *verified* import path, not a heuristic guess). The headline is a meta-theorem — `Domination` + `Strictness` — proving the transitive check **strictly dominates** one-hop checking: every direct violation is caught, *and* there provably exist laundered violations that direct-edge checks miss. 30 Dafny VCs, 0 errors. The reachability decision and the witness are proven; the import-graph extraction (which edges exist) is the stated trust boundary, and `dist/*.js` is `tsc`'s erasure of the verified source it ships alongside. Dafny only.
 
 ## Setup
 
@@ -71,9 +80,7 @@ npx lsc gen --backend=lean src/myModule.ts
 lake build
 ```
 
-## What's Supported
-
-### Annotations
+## Annotations
 
 ```typescript
 //@ requires arr.length > 0
@@ -83,6 +90,8 @@ lake build
 //@ type i nat
 ```
 
+For the full surface, see [SPEC.md](SPEC.md).
+
 ## File Structure
 
 ### Dafny backend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemmascript",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "A verification toolchain for TypeScript — generates Lean 4 or Dafny from annotated TS",
   "type": "module",
   "engines": {
@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "tsx": "^4.0.0",
+    "tsx": "^4.22.4",
     "typescript": "^5.7.0"
   },
   "license": "MIT",
@@ -32,6 +32,7 @@
     "url": "https://github.com/midspiral/LemmaScript"
   },
   "keywords": [
+    "lemmascript",
     "verification",
     "typescript",
     "lean4",

package/tools/dist/autohavoc.js

@@ -0,0 +1,536 @@
+/**
+ * auto-havoc pass — validation mode.
+ *
+ * Rewrites every *unmodellable* expression in the Typed IR to a `havoc` node,
+ * and drops unmodellable side-effecting statements. "Unmodellable" = the value
+ * derives from something outside LemmaScript's model (an `unknown`-typed
+ * receiver/result — e.g. `res.status()`, `req.body`, `JSON.parse(x)`,
+ * `process.env.X ?? y`, `uuidv4()` — or an anonymous object literal).
+ *
+ * This is the abstraction policy for verifying *validation* properties: the
+ * only thing that matters is that values reaching a contracted sink (an extern
+ * with `//@ requires sanitizer(x)`) are dominated by the sanitizer guard.
+ * Everything else is noise and is replaced by an arbitrary value.
+ *
+ * Soundness: `havoc` is a nondeterministic over-approximation — the verifier
+ * assumes nothing about a havoc'd value — so this can only make a proof FAIL
+ * (false positive), never spuriously pass. It uses havoc, never assume.
+ * (Trust boundary: a real sink hidden inside an unmodellable call is invisible;
+ * sinks must be the declared/annotated externs.)
+ *
+ * It runs after narrow, so any legitimate optional (`?.`, `??` on an
+ * optional-typed value) is already a `someMatch`; a `nullish`/`optChain` that
+ * survives to here is unmodellable and gets havoc'd.
+ */
+/** A node whose own value can't be modeled and must become an arbitrary value.
+ *  Leaves (var/literal/havoc) are never havoc'd — a reference to an already
+ *  havoc'd variable is fine; only the *source* expression is replaced. */
+function isBadNode(e) {
+    switch (e.kind) {
+        case "var":
+        case "num":
+        case "str":
+        case "bool":
+        case "havoc":
+            return false;
+        // A field/index is unmodellable when its *object* is opaque (`req.body`,
+        // `process.env.X`). It is NOT unmodellable just because its own type is
+        // `unknown`: a method reference on a known receiver (`path.includes`) has
+        // `unknown` type yet emits fine — the method dispatch happens at emit on
+        // the object's type, so havocing it would wreck a legitimate call.
+        case "field": return e.obj.ty.kind === "unknown";
+        case "index": return e.obj.ty.kind === "unknown";
+        // anonymous object literal — Dafny has no model for it
+        case "record": return e.ty.kind !== "user";
+        // a call / nullish / opt-chain / conditional whose *result* is opaque
+        default: return e.ty.kind === "unknown";
+    }
+}
+/** Does the subtree (including lambda bodies) contain anything unmodellable?
+ *  Used to havoc a *whole* call like `xs.map(v => ({...}))` whose receiver is
+ *  modellable but whose lambda produces an unmodellable value — havocing the
+ *  lambda interior would leave a nondeterministic `*` inside a pure lambda. */
+function containsBad(e) {
+    let found = false;
+    const visit = (n) => {
+        if (found)
+            return;
+        if (isBadNode(n)) {
+            found = true;
+            return;
+        }
+        forEachChildExpr(n, visit);
+    };
+    visit(e);
+    return found;
+}
+function mustHavoc(e) {
+    if (isBadNode(e))
+        return true;
+    if (e.kind === "call" && e.args.some(a => a.kind === "lambda" && a.body.some(s => stmtContainsBad(s))))
+        return true;
+    return false;
+}
+// ── structural recursion helpers ────────────────────────────
+function forEachChildExpr(e, f) {
+    switch (e.kind) {
+        case "binop":
+            f(e.left);
+            f(e.right);
+            return;
+        case "unop":
+            f(e.expr);
+            return;
+        case "call":
+            f(e.fn);
+            e.args.forEach(f);
+            return;
+        case "index":
+            f(e.obj);
+            f(e.idx);
+            return;
+        case "field":
+            f(e.obj);
+            return;
+        case "record":
+            if (e.spread)
+                f(e.spread);
+            e.fields.forEach(fl => f(fl.value));
+            return;
+        case "arrayLiteral":
+            e.elems.forEach(f);
+            return;
+        case "conditional":
+            f(e.cond);
+            f(e.then);
+            f(e.else);
+            return;
+        case "optChain":
+            f(e.obj);
+            return;
+        case "nullish":
+            f(e.left);
+            f(e.right);
+            return;
+        case "forall":
+        case "exists":
+            f(e.body);
+            return;
+        case "someMatch":
+            f(e.scrutinee);
+            f(e.someBody);
+            f(e.noneBody);
+            return;
+        case "tagMatch":
+            f(e.scrutinee);
+            e.cases.forEach(c => f(c.body));
+            if (e.fallthrough)
+                f(e.fallthrough);
+            return;
+        case "lambda":
+            e.body.forEach(s => forEachChildExprInStmt(s, f));
+            return;
+    }
+}
+function forEachChildExprInStmt(s, f) {
+    switch (s.kind) {
+        case "let":
+        case "ghostLet":
+            f(s.init);
+            return;
+        case "assign":
+        case "ghostAssign":
+            f(s.value);
+            return;
+        case "return":
+            f(s.value);
+            return;
+        case "expr":
+            f(s.expr);
+            return;
+        case "assert":
+            f(s.expr);
+            return;
+        case "if":
+            f(s.cond);
+            s.then.forEach(st => forEachChildExprInStmt(st, f));
+            s.else.forEach(st => forEachChildExprInStmt(st, f));
+            return;
+        case "while":
+            f(s.cond);
+            s.body.forEach(st => forEachChildExprInStmt(st, f));
+            return;
+        case "forof":
+            f(s.iterable);
+            s.body.forEach(st => forEachChildExprInStmt(st, f));
+            return;
+        case "switch":
+            f(s.expr);
+            s.cases.forEach(c => c.body.forEach(st => forEachChildExprInStmt(st, f)));
+            s.defaultBody.forEach(st => forEachChildExprInStmt(st, f));
+            return;
+        case "someMatch":
+            f(s.scrutinee);
+            s.someBody.forEach(st => forEachChildExprInStmt(st, f));
+            s.noneBody.forEach(st => forEachChildExprInStmt(st, f));
+            return;
+        case "tagMatch":
+            f(s.scrutinee);
+            s.cases.forEach(c => c.body.forEach(st => forEachChildExprInStmt(st, f)));
+            s.fallthrough.forEach(st => forEachChildExprInStmt(st, f));
+            return;
+    }
+}
+function stmtContainsBad(s) {
+    let found = false;
+    forEachChildExprInStmt(s, e => { if (containsBad(e))
+        found = true; });
+    return found;
+}
+// ── contracted-call ("sink") detection ──────────────────────
+// A call whose callee carries a `//@ requires` precondition. When we havoc an
+// unmodellable expression we must NOT silently discard such a call nested
+// inside it — its precondition would go unchecked (a false pass). Instead we
+// hoist it to a discard statement so the precondition is still verified.
+let _guarded = new Set();
+// Every name LemmaScript models: local functions + all externs. A call to
+// anything else with an unknown callee is "opaque" — abstracted by havoc.
+let _known = new Set();
+function calleeName(e) {
+    if (e.kind !== "call")
+        return null;
+    if (e.fn.kind === "var")
+        return e.fn.name;
+    if (e.fn.kind === "field")
+        return e.fn.field;
+    return null;
+}
+/** Root variable a receiver chain bottoms out at (`fs.x.y` → `fs`,
+ *  `res.status(400).send` → `res`, `templateJson.variables.map` → `templateJson`). */
+function rootVar(e) {
+    let cur = e;
+    for (;;) {
+        if (cur.kind === "var")
+            return cur.name;
+        if (cur.kind === "field")
+            cur = cur.obj;
+        else if (cur.kind === "call")
+            cur = cur.fn;
+        else if (cur.kind === "index")
+            cur = cur.obj;
+        else
+            return null;
+    }
+}
+/** Display name of an *opaque external* call this pass abstracts away — a call
+ *  on an unknown receiver rooted at a module/global (`fs.readFileSync`,
+ *  `JSON.parse`) or an unknown free function (`uuidv4`). Returns null for
+ *  modelled calls (local functions, contracted/dispatched externs, methods on
+ *  known receivers) and for calls rooted at a function-local/param (e.g.
+ *  `templateJson.variables.map`, `res.status().send` — framework objects and
+ *  havoc'd locals, not external sinks). These are the calls a completeness
+ *  reviewer must confirm are not unguarded sinks. */
+function opaqueCallName(e, locals) {
+    // Report exactly the calls the pass abstracts. A call is havoc'd iff its
+    // result type is unknown (the same `isBadNode`/`mustHavoc` criterion the pass
+    // uses) — keying on that, rather than re-matching the callee's syntax, makes
+    // the report complete: it can't miss an unusual form like `fs["read"](p)`.
+    if (e.kind !== "call" || e.ty.kind !== "unknown")
+        return null;
+    const root = rootVar(e.fn);
+    // Not an external sink: rooted at a parameter/local value (framework objects,
+    // havoc'd locals) or at a known function/extern (already modelled).
+    if (root && (locals.has(root) || _known.has(root)))
+        return null;
+    // Best display we can give the callee.
+    const f = e.fn;
+    if (f.kind === "field" && f.obj.kind === "var")
+        return `${f.obj.name}.${f.field}`;
+    if (f.kind === "field")
+        return f.field;
+    if (f.kind === "index" && f.obj.kind === "var" && f.idx.kind === "str")
+        return `${f.obj.name}.${f.idx.value}`;
+    if (f.kind === "var")
+        return f.name;
+    return root ?? "<computed call>";
+}
+/** Every binder in scope anywhere in a function body — params (seed) + let /
+ *  forof / lambda parameters — so a call rooted at any of them is treated as a
+ *  local value, not an external sink. A call rooted at a *free* name (a module
+ *  or global like `fs`/`JSON`/`console`, or a free function like `uuidv4`) is
+ *  what the report keeps. Still descends into lambdas so a sink hidden in a
+ *  callback (`arr.forEach(x => fs.writeFileSync(x))`) is not missed. */
+function localNames(stmts, seed) {
+    const out = new Set(seed);
+    const inExpr = (e) => {
+        if (e.kind === "lambda") {
+            e.params.forEach(p => out.add(p.name));
+            inStmts(e.body);
+            return;
+        }
+        forEachChildExpr(e, inExpr);
+    };
+    const inStmts = (ss) => {
+        for (const s of ss) {
+            if (s.kind === "let" || s.kind === "ghostLet")
+                out.add(s.name);
+            if (s.kind === "forof")
+                s.names.forEach(n => out.add(n));
+            forEachChildExprInStmt(s, inExpr);
+            if (s.kind === "if") {
+                inStmts(s.then);
+                inStmts(s.else);
+            }
+            else if (s.kind === "while" || s.kind === "forof")
+                inStmts(s.body);
+            else if (s.kind === "switch") {
+                s.cases.forEach(c => inStmts(c.body));
+                inStmts(s.defaultBody);
+            }
+            else if (s.kind === "someMatch") {
+                inStmts(s.someBody);
+                inStmts(s.noneBody);
+            }
+            else if (s.kind === "tagMatch") {
+                s.cases.forEach(c => inStmts(c.body));
+                inStmts(s.fallthrough);
+            }
+        }
+    };
+    inStmts(stmts);
+    return out;
+}
+/** All opaque external calls in a function body (deduped, sorted). */
+function collectOpaqueCalls(stmts, locals) {
+    const found = new Set();
+    const visit = (e) => {
+        const n = opaqueCallName(e, locals);
+        if (n)
+            found.add(n);
+        forEachChildExpr(e, visit);
+    };
+    for (const s of stmts)
+        forEachChildExprInStmt(s, visit);
+    return [...found].sort();
+}
+/** Outermost contracted calls inside `e`'s subtree (excluding `e` itself, which
+ *  is the havoc'd wrapper). Does not descend into lambdas — a sink there would
+ *  reference the lambda's binder and can't be hoisted to the enclosing scope. */
+function collectSinks(e) {
+    const out = [];
+    const walk = (n) => {
+        if (n.kind === "lambda")
+            return;
+        const name = calleeName(n);
+        if (name && _guarded.has(name)) {
+            out.push(n);
+            return;
+        } // outermost: don't descend
+        forEachChildExpr(n, walk);
+    };
+    forEachChildExpr(e, walk);
+    return out;
+}
+// ── rewrite ──────────────────────────────────────────────────
+// `hoisted` accumulates discard statements (preserved contracted calls) to be
+// emitted, in order, immediately before the statement being rewritten.
+function rewriteExpr(e, hoisted) {
+    if (mustHavoc(e)) {
+        // Preserve any contracted call nested inside the discarded value so its
+        // precondition is still checked. transform lowers the `expr` discard to
+        // `var _ := call(...)` (and lifts any havoc'd args), so we lean on it.
+        for (const sink of collectSinks(e)) {
+            hoisted.push({ kind: "expr", expr: rewriteExpr(sink, hoisted) });
+        }
+        return { kind: "havoc", ty: e.ty };
+    }
+    switch (e.kind) {
+        case "var":
+        case "num":
+        case "str":
+        case "bool":
+        case "havoc": return e;
+        case "binop": return { ...e, left: rewriteExpr(e.left, hoisted), right: rewriteExpr(e.right, hoisted) };
+        case "unop": return { ...e, expr: rewriteExpr(e.expr, hoisted) };
+        case "call": return { ...e, fn: rewriteExpr(e.fn, hoisted), args: e.args.map(a => rewriteExpr(a, hoisted)) };
+        case "index": return { ...e, obj: rewriteExpr(e.obj, hoisted), idx: rewriteExpr(e.idx, hoisted) };
+        case "field": return { ...e, obj: rewriteExpr(e.obj, hoisted) };
+        case "record": return { ...e, spread: e.spread ? rewriteExpr(e.spread, hoisted) : null,
+            fields: e.fields.map(fl => ({ ...fl, value: rewriteExpr(fl.value, hoisted) })) };
+        case "arrayLiteral": return { ...e, elems: e.elems.map(el => rewriteExpr(el, hoisted)) };
+        case "conditional": return { ...e, cond: rewriteExpr(e.cond, hoisted), then: rewriteExpr(e.then, hoisted), else: rewriteExpr(e.else, hoisted) };
+        case "optChain": return { ...e, obj: rewriteExpr(e.obj, hoisted) };
+        case "nullish": return { ...e, left: rewriteExpr(e.left, hoisted), right: rewriteExpr(e.right, hoisted) };
+        case "forall":
+        case "exists": return { ...e, body: rewriteExpr(e.body, hoisted) };
+        case "someMatch": return { ...e, scrutinee: rewriteExpr(e.scrutinee, hoisted), someBody: rewriteExpr(e.someBody, hoisted), noneBody: rewriteExpr(e.noneBody, hoisted) };
+        case "tagMatch": return { ...e, scrutinee: rewriteExpr(e.scrutinee, hoisted),
+            cases: e.cases.map(c => ({ ...c, body: rewriteExpr(c.body, hoisted) })),
+            fallthrough: e.fallthrough ? rewriteExpr(e.fallthrough, hoisted) : null };
+        // A lambda body is its own statement scope; rewrite it independently
+        // (its hoists belong inside the lambda, not the enclosing statement).
+        case "lambda": return { ...e, body: rewriteStmts(e.body) };
+    }
+}
+/** A condition in a boolean context. If it touches anything unmodellable
+ *  (`!fs.existsSync(...)`), the whole condition becomes a nondeterministic
+ *  `bool` — havocing a subexpression would leave a non-bool `*` under `!`/`if`.
+ *  A fully modellable guard (`!validPath(x)`, `s === ""`) is left intact, so
+ *  the verifier still reasons about it. Contracted calls inside an havoc'd
+ *  condition are still hoisted. */
+function rewriteCond(e, hoisted) {
+    if (containsBad(e)) {
+        for (const sink of collectSinks(e)) {
+            hoisted.push({ kind: "expr", expr: rewriteExpr(sink, hoisted) });
+        }
+        return { kind: "havoc", ty: { kind: "bool" } };
+    }
+    return rewriteExpr(e, hoisted);
+}
+function rewriteStmts(stmts) {
+    const out = [];
+    for (const s of stmts) {
+        // A side-effecting statement whose value is unmodellable (`xs.forEach(...)`,
+        // `console.log(x)`) carries no verification content — drop it, but still
+        // preserve any contracted call nested inside it.
+        if (s.kind === "expr" && mustHavoc(s.expr)) {
+            const h = [];
+            for (const sink of collectSinks(s.expr)) {
+                h.push({ kind: "expr", expr: rewriteExpr(sink, h) });
+            }
+            out.push(...h);
+            continue;
+        }
+        out.push(...rewriteStmt(s));
+    }
+    return out;
+}
+function rewriteStmt(s) {
+    const h = [];
+    const rw = (e) => rewriteExpr(e, h);
+    switch (s.kind) {
+        case "let": {
+            const init = rw(s.init);
+            return [...h, { ...s, init }];
+        }
+        case "ghostLet": {
+            const init = rw(s.init);
+            return [...h, { ...s, init }];
+        }
+        case "assign": {
+            const value = rw(s.value);
+            return [...h, { ...s, value }];
+        }
+        case "ghostAssign": {
+            const value = rw(s.value);
+            return [...h, { ...s, value }];
+        }
+        case "return": {
+            const value = rw(s.value);
+            return [...h, { ...s, value }];
+        }
+        case "expr": {
+            const expr = rw(s.expr);
+            return [...h, { ...s, expr }];
+        }
+        case "assert": {
+            const expr = rw(s.expr);
+            return [...h, { ...s, expr }];
+        }
+        case "if": {
+            const cond = rewriteCond(s.cond, h);
+            return [...h, { ...s, cond, then: rewriteStmts(s.then), else: rewriteStmts(s.else) }];
+        }
+        case "while": {
+            const cond = rewriteCond(s.cond, h);
+            return [...h, { ...s, cond, body: rewriteStmts(s.body) }];
+        }
+        case "forof": {
+            const iterable = rw(s.iterable);
+            return [...h, { ...s, iterable, body: rewriteStmts(s.body) }];
+        }
+        case "switch": {
+            const expr = rw(s.expr);
+            return [...h, { ...s, expr,
+                    cases: s.cases.map(c => ({ ...c, body: rewriteStmts(c.body) })),
+                    defaultBody: rewriteStmts(s.defaultBody) }];
+        }
+        case "someMatch": {
+            const scrutinee = rw(s.scrutinee);
+            return [...h, { ...s, scrutinee, someBody: rewriteStmts(s.someBody), noneBody: rewriteStmts(s.noneBody) }];
+        }
+        case "tagMatch": {
+            const scrutinee = rw(s.scrutinee);
+            return [...h, { ...s, scrutinee,
+                    cases: s.cases.map(c => ({ ...c, body: rewriteStmts(c.body) })),
+                    fallthrough: rewriteStmts(s.fallthrough) }];
+        }
+        case "break":
+        case "continue":
+        case "throw": return [s];
+    }
+}
+/** Does any statement in the body contain a havoc expression? Havoc is only
+ *  valid in Dafny `method`s (its `*` can't appear in a deterministic
+ *  `function`), so a body we've havoc'd must be classified impure. */
+function bodyHasHavoc(stmts) {
+    let found = false;
+    const visit = (e) => {
+        if (found)
+            return;
+        if (e.kind === "havoc") {
+            found = true;
+            return;
+        }
+        forEachChildExpr(e, visit);
+    };
+    for (const s of stmts)
+        forEachChildExprInStmt(s, visit);
+    return found;
+}
+/** Apply the auto-havoc abstraction to functions opted in via `//@ autohavoc`
+ *  (file-level or per-function). A no-op when nothing is annotated. When any
+ *  function opts in, also drop module constants whose initializer is
+ *  unmodellable (e.g. `const fs = require("fs")` pulled in by reachability). */
+export function autoHavocModule(mod) {
+    if (!mod.functions.some(f => f.autohavoc))
+        return mod;
+    // Names of calls carrying a `//@ requires` precondition — these must never be
+    // silently discarded by havoc (see collectSinks / rewriteExpr).
+    _guarded = new Set();
+    for (const e of mod.externs)
+        if (e.requires.length > 0) {
+            _guarded.add(e.qualified);
+            _guarded.add(e.flat);
+        }
+    for (const f of mod.functions)
+        if (f.requires.length > 0)
+            _guarded.add(f.name);
+    _known = new Set();
+    for (const f of mod.functions)
+        _known.add(f.name);
+    for (const e of mod.externs) {
+        _known.add(e.qualified);
+        _known.add(e.flat);
+    }
+    return {
+        ...mod,
+        constants: mod.constants.filter(c => !containsBad(c.value)),
+        functions: mod.functions.map(f => {
+            if (!f.autohavoc)
+                return f;
+            // Completeness transparency: surface the opaque external calls this pass
+            // abstracts away, so a forgotten sink (e.g. a raw `fs.readFileSync`) is
+            // visible rather than silently havoc'd behind a green check.
+            const locals = localNames(f.body, new Set(f.params.map(p => p.name)));
+            const opaque = collectOpaqueCalls(f.body, locals);
+            if (opaque.length > 0) {
+                console.error(`autohavoc: ${f.name} abstracts ${opaque.length} external call(s) — confirm none is an unguarded sink: ${opaque.join(", ")}`);
+            }
+            const body = rewriteStmts(f.body);
+            // Havoc forces Dafny `method` emission (`*` is invalid in a `function`).
+            const isPure = f.isPure && !bodyHasHavoc(body);
+            return { ...f, body, isPure, forcePure: f.forcePure && isPure };
+        }),
+    };
+}