lemmascript 0.5.18 → 0.5.20

package/README.md

@@ -34,7 +34,7 @@ See the external case studies:
 - **[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.
+- **[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). The deliberate **inverse** of [quorum-lemmascript](https://github.com/midspiral/quorum-lemmascript): bookings **contend** for shared inventory, so the invariant is a **bound** — for every slot `j`, `confirmedCount(bookings, j) <= slots[j].capacity` — and the *same* `domain.ts` runs in the browser and the Durable Object **server-authoritatively**, never overselling under contention (no optimistic client apply). Proven: no overbooking across `tryBook`/cancel, accept-iff-room, an **idempotent three-way `tryBook`** (a retry reads as success, not rejection), cancellation frees seats, replay determinism, and order-invariance — `confirmedCountPerm` / `hasRoomPermInvariant` show availability depends only on the *multiset* of the booking log, via the same `perm(...)` predicate Quorum drove into LemmaScript. 80 Dafny VCs, 0 errors. Trust boundary: 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.
 - **[infisical-lemmascript](https://github.com/midspiral/infisical-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield, **in-place** verification of the permission-boundary glob set-containment check in [Infisical](https://github.com/Infisical/infisical) — the privilege-escalation guard that stops a role from delegating broader secret-path access than it holds. The loop-bearing `segmentMatch` compiles to a Dafny `method` (unnameable in specs), so soundness is proven by **refinement**: the method certifies `result == segMatchSpec` (a pure mirror), and a standalone lemma proves that spec sound against a hand-written segment-glob semantics — *if it returns true, every path the subset glob matches, the parent matches too*. 12 Dafny VCs, 0 errors; drove a toolchain fix (recursive `method`s now carry a method-level `//@ decreases`). Dafny only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemmascript",
-  "version": "0.5.18",
+  "version": "0.5.20",
   "description": "A verification toolchain for TypeScript — generates Lean 4 or Dafny from annotated TS",
   "type": "module",
   "engines": {

package/tools/dist/autohavoc.js

@@ -29,6 +29,7 @@ function isBadNode(e) {
     switch (e.kind) {
         case "var":
         case "num":
+        case "bigint":
         case "str":
         case "bool":
         case "havoc":
@@ -347,6 +348,7 @@ function rewriteExpr(e, hoisted) {
     switch (e.kind) {
         case "var":
         case "num":
+        case "bigint":
         case "str":
         case "bool":
         case "havoc": return e;

package/tools/dist/builtins.js

@@ -0,0 +1,125 @@
+/**
+ * Builtin registry — the single classification table for builtin methods on
+ * collection/string receivers (DESIGN_LS_IN_LS.md §3).
+ *
+ * One stable `BuiltinId` per supported operation, one entry per identity.
+ * `resolve` recognizes `(receiver type kind, method name)` once — via
+ * `recognizeBuiltin` — and stamps the typed call node (and optChain call
+ * steps) with the id. Downstream, `narrow` reads `pure` and `transform`
+ * reads `hof`/`intArgPositions` from the stamp; neither re-recognizes by
+ * spelling. The emitters are deliberately NOT keyed on the stamp: they
+ * dispatch on `(objTy, method)` over the backend IR, where transform
+ * legitimately synthesizes method calls with no source-level identity.
+ *
+ * The registry holds classification only — no lowerings. Namespace builtins
+ * (`Math.*`, `Array.isArray`) are recognized syntactically in resolve and
+ * are not registry entries: they are not methods on receiver values.
+ *
+ * Classification values mirror the historical per-pass lists exactly
+ * (byte-for-byte gauntlet compatibility), including their quirks — e.g.
+ * `array.shift` returns the element type un-wrapped and `array.with` types
+ * as `unknown`. Widen such bits deliberately, with tests.
+ */
+const UNKNOWN = { kind: "unknown" };
+const BOOL = () => ({ kind: "bool" });
+const INT = () => ({ kind: "int" });
+const STRING = () => ({ kind: "string" });
+const self = (objTy) => objTy;
+const elem = (objTy) => objTy.kind === "array" ? objTy.elem : UNKNOWN;
+const optElem = (objTy) => objTy.kind === "array" ? { kind: "optional", inner: objTy.elem } : UNKNOWN;
+/** The table is the single source: each key is `<RecvKind>.<method>`, which
+ *  *is* the `BuiltinId`. */
+export const BUILTINS = {
+    // ── array ─────────────────────────────────────────────────
+    "array.includes": { ret: BOOL, pure: true,
+        intArgPositions: [1], argIsKey: true },
+    "array.indexOf": { ret: INT, pure: true,
+        intArgPositions: [1] },
+    "array.shift": { ret: elem, pure: false },
+    "array.pop": { ret: optElem, pure: false },
+    "array.push": { ret: self, pure: false },
+    "array.unshift": { ret: self, pure: false },
+    "array.concat": { ret: self, pure: true },
+    "array.sort": { ret: self, pure: false,
+        hof: { shape: "comparator" } },
+    "array.filter": { ret: self, pure: false,
+        hof: { shape: "unary" } },
+    "array.every": { ret: BOOL, pure: false,
+        hof: { shape: "unary" } },
+    "array.some": { ret: BOOL, pure: false,
+        hof: { shape: "unary" } },
+    "array.reduce": { pure: false,
+        hof: { shape: "reduce" },
+        ret: (_objTy, args) => args.length === 2 ? args[1].ty : UNKNOWN },
+    "array.find": { ret: optElem, pure: false,
+        hof: { shape: "unary" } },
+    "array.findLast": { ret: optElem, pure: false,
+        hof: { shape: "unary" } },
+    "array.findIndex": { ret: INT, pure: false,
+        hof: { shape: "unary" } },
+    "array.findLastIndex": { ret: INT,
+        pure: false, hof: { shape: "unary" } },
+    "array.flat": { pure: true,
+        ret: (objTy) => objTy.kind === "array" && objTy.elem.kind === "array"
+            ? { kind: "array", elem: objTy.elem.elem } : UNKNOWN },
+    "array.slice": { ret: self, pure: true },
+    "array.join": { pure: true,
+        ret: (objTy) => objTy.kind === "array" && objTy.elem.kind === "string"
+            ? STRING() : UNKNOWN },
+    "array.map": { pure: false,
+        hof: { shape: "unary" },
+        // Prefer the lambda's declared return type (handles multi-statement bodies
+        // where body[0] is an `if`, not a `return`); fall back to the body's return.
+        ret: (_objTy, args) => {
+            if (args.length >= 1 && args[0].kind === "lambda") {
+                const lam = args[0];
+                const retTy = lam.ty.kind === "fn" ? lam.ty.result
+                    : lam.body.length > 0 && lam.body[0].kind === "return" ? lam.body[0].value.ty : UNKNOWN;
+                return { kind: "array", elem: retTy };
+            }
+            return UNKNOWN;
+        } },
+    "array.with": { ret: () => UNKNOWN, pure: true,
+        intArgPositions: [0] },
+    // ── string ────────────────────────────────────────────────
+    "string.trim": { ret: STRING, pure: true },
+    "string.trimEnd": { ret: STRING, pure: true },
+    "string.trimStart": { ret: STRING, pure: true },
+    "string.toLowerCase": { ret: STRING, pure: true },
+    "string.toUpperCase": { ret: STRING, pure: true },
+    "string.repeat": { ret: STRING, pure: true },
+    "string.slice": { ret: STRING, pure: true },
+    "string.substring": { ret: STRING, pure: true },
+    "string.split": { pure: true,
+        ret: () => ({ kind: "array", elem: { kind: "string" } }) },
+    "string.includes": { ret: BOOL, pure: true },
+    "string.startsWith": { ret: BOOL, pure: true },
+    "string.endsWith": { ret: BOOL, pure: true },
+    // ── map ───────────────────────────────────────────────────
+    "map.get": { pure: true, argIsKey: true,
+        ret: (objTy, _args, c) => objTy.kind !== "map" ? UNKNOWN
+            : c.inSpec ? objTy.value : { kind: "optional", inner: objTy.value } },
+    "map.has": { ret: BOOL, pure: true, argIsKey: true },
+    "map.set": { ret: self, pure: false },
+    "map.delete": { ret: self, pure: false },
+    "map.keys": { ret: () => UNKNOWN, pure: true },
+    "map.values": { ret: () => UNKNOWN, pure: true },
+    // ── set ───────────────────────────────────────────────────
+    "set.has": { ret: BOOL, pure: true, argIsKey: true },
+    "set.add": { ret: self, pure: false },
+    "set.delete": { ret: self, pure: false },
+};
+/** Recognize a builtin method call by receiver type kind + method name.
+ *  Called by resolve (once per call node); everything downstream reads the
+ *  stamped id. `hasOwn`, not `in`: `method` comes from user source, and `in`
+ *  would match inherited names (`constructor`, `toString`). */
+export function recognizeBuiltin(objTy, method) {
+    const k = objTy.kind;
+    if (k !== "array" && k !== "string" && k !== "map" && k !== "set")
+        return null;
+    const id = `${k}.${method}`;
+    return Object.hasOwn(BUILTINS, id) ? id : null;
+}
+export function builtinSpec(id) {
+    return BUILTINS[id];
+}

package/tools/dist/condition-facts.js

@@ -0,0 +1,364 @@
+/**
+ * condition-facts — what a condition establishes (DESIGN_LS_IN_LS.md §4).
+ *
+ * One module owns condition semantics: detecting the facts a condition
+ * establishes (optional presence, discriminant variants, synth array-union
+ * branches, `||`-chain None-detectors, in-bounds) and materializing them as
+ * IR (`someMatch` / `tagMatch` / bounds conditionals). `narrow`'s rules are
+ * positional drivers over these helpers; `resolve` consults the same
+ * detection for branch typing.
+ *
+ * Analysis shape: a condition yields ONE leading fact plus a residual
+ * condition (`leadingPresent` on `&&`-chains); nesting comes from the
+ * drivers re-walking the residual, so recursion order carries the
+ * dependency between chained facts (`x !== undefined && x.f !== undefined`
+ * reifies the second check inside the match introduced by the first). This
+ * realizes §4's ordered-fact list iteratively rather than as a returned
+ * list — same semantics, no intermediate structure.
+ *
+ * State is explicit (§6.1): detection that mints binders or consults type
+ * declarations takes a `CondCtx`; nothing module-level.
+ */
+import { freshName } from "./names.js";
+import { unionDeclOfTy, discriminantOf } from "./typedecls.js";
+export function freshOcBinder(ctx) {
+    return freshName(`_oc${ctx.oc.n++}_val`);
+}
+/** Pure access paths: var(x) or field(purePath, name). Walks down to the
+ *  var root, collecting field names. Returns `_root_field1..._val` (or
+ *  `_root_val` for a bare var); null for non-path shapes. */
+export function binderHintFor(e) {
+    const fields = [];
+    let cur = e;
+    while (cur.kind === "field") {
+        fields.unshift(cur.field);
+        cur = cur.obj;
+    }
+    if (cur.kind !== "var")
+        return null;
+    // \result is stored as the IR var name "\\result"; sanitize for a valid identifier.
+    const root = cur.name === "\\result" ? "result" : cur.name;
+    return fields.length === 0 ? `_${root}_val` : `_${root}_${fields.join("_")}_val`;
+}
+/** Detect optional checks: `e !== undefined`, `e === undefined`, `!e`, or a
+ *  bare optional `e` — for a pure-access-path optional-typed `e`. `!e` and
+ *  bare `e` are truthiness forms. Following TS, only pure access paths
+ *  narrow; complex scrutinees return null. */
+export function presentFact(cond) {
+    // `!e` where e is optional — a truthiness form: false iff e is absent OR its
+    // inner value is itself falsy (so `Some(0)`/`Some("")` count as falsy too).
+    if (cond.kind === "unop" && cond.op === "!" && cond.expr.ty.kind === "optional") {
+        const e = cond.expr;
+        const innerTy = cond.expr.ty.inner;
+        const hint = binderHintFor(e);
+        if (hint === null)
+            return null;
+        return { scrutinee: e, innerTy, negated: true, binder: freshName(hint), truthiness: true };
+    }
+    if (cond.kind !== "binop" || (cond.op !== "!==" && cond.op !== "===")) {
+        // Bare optional truthiness: `if (e)` where e: T | undefined — true iff e is
+        // present AND its inner value is truthy.
+        if (cond.ty.kind === "optional") {
+            const hint = binderHintFor(cond);
+            if (hint === null)
+                return null;
+            return { scrutinee: cond, innerTy: cond.ty.inner, negated: false, binder: freshName(hint), truthiness: true };
+        }
+        return null;
+    }
+    // Explicit `e === undefined` / `e !== undefined` — a pure presence check,
+    // independent of the inner value (so NOT a truthiness form).
+    let e = null;
+    if (cond.right.kind === "var" && cond.right.name === "undefined")
+        e = cond.left;
+    if (cond.left.kind === "var" && cond.left.name === "undefined")
+        e = cond.right;
+    if (!e || e.ty.kind !== "optional")
+        return null;
+    const hint = binderHintFor(e);
+    if (hint === null)
+        return null;
+    return { scrutinee: e, innerTy: e.ty.inner, negated: cond.op === "===", binder: freshName(hint), truthiness: false };
+}
+/** Which types have falsy values in JS (`0`, `""`, `false`); everything else
+ *  (array, user type, …) is always truthy. The single home of that set —
+ *  transform's `valueTruthyCond` gates on it too. */
+export const isFalsyCapableTy = (ty) => ["int", "nat", "string", "bool"].includes(ty.kind);
+// `Some(0)` / `Some("")` / `Some(false)` are falsy, so a truthiness check
+// (`if (o)`, `!o`, `o ? :`) over a nullable primitive must still test the bound
+// value. Nullable objects/arrays are always truthy, and `!== undefined` is a pure
+// presence check — neither needs the gate.
+export const canBeFalsy = (f) => f.truthiness && isFalsyCapableTy(f.innerTy);
+export const bound = (f) => ({ kind: "var", name: f.binder, ty: f.innerTy });
+// ── `&&`-chain analysis: one leading fact + residual ────────
+/** Pull one `parse`-matching conjunct out of an `&&` tree, returning it plus
+ *  the tree with that conjunct removed:
+ *  `(x !== undefined && b) && c` → { check, restCond: b && c }.
+ *
+ *  Search order is shallowest-first, left-biased — both immediate operands
+ *  before either nested chain — so the conjunct found is not necessarily the
+ *  source-leftmost one. That is sound because every `parse` passed here
+ *  (`leadingPresent`, `leadingIsArray`) matches only pure, total checks on an
+ *  already-typed path, so hoisting one above the others is observationally
+ *  neutral. The one thing it does change: the residual now sits inside the
+ *  match arm, so a conjunct that would have run before a failing check no
+ *  longer runs at all.
+ *  Harmless while conditions stay pure — revisit if that ever stops holding. */
+export function extractConjunct(cond, parse) {
+    if (cond.kind !== "binop" || cond.op !== "&&")
+        return null;
+    const left = parse(cond.left);
+    if (left)
+        return { check: left, restCond: cond.right };
+    const right = parse(cond.right);
+    if (right)
+        return { check: right, restCond: cond.left };
+    if (cond.left.kind === "binop" && cond.left.op === "&&") {
+        const inner = extractConjunct(cond.left, parse);
+        if (inner)
+            return { check: inner.check, restCond: { ...cond, left: inner.restCond } };
+    }
+    if (cond.right.kind === "binop" && cond.right.op === "&&") {
+        const inner = extractConjunct(cond.right, parse);
+        if (inner)
+            return { check: inner.check, restCond: { ...cond, right: inner.restCond } };
+    }
+    return null;
+}
+/** The positive presence fact an `&&` chain contributes, plus the residual.
+ *  "Leading" describes the rewrite, not the source: this fact becomes the
+ *  outermost match, wherever in the chain it was written. */
+export function leadingPresent(cond) {
+    return extractConjunct(cond, e => {
+        const f = presentFact(e);
+        return f && !f.negated ? f : null;
+    });
+}
+// ── `||`-chain analysis (De Morgan): None-detectors ─────────
+/** Flatten a nested `||` chain into its leaf conditions. */
+export function flattenOr(e) {
+    if (e.kind === "binop" && e.op === "||")
+        return [...flattenOr(e.left), ...flattenOr(e.right)];
+    return [e];
+}
+export function noneDetector(leaf, ctx) {
+    // `x?.chain !== lit` — `undefined !== lit` is true when x is None.
+    if (leaf.kind === "binop" && leaf.op === "!==") {
+        const oc = leaf.left.kind === "optChain" ? leaf.left : leaf.right.kind === "optChain" ? leaf.right : null;
+        if (oc && oc.kind === "optChain" && oc.obj.ty.kind === "optional") {
+            const hint = binderHintFor(oc.obj);
+            if (hint === null)
+                return null;
+            const binder = freshName(hint);
+            const unwrapped = applyChain({ kind: "var", name: binder, ty: oc.obj.ty.inner }, oc.chain);
+            restoreDiscriminantFlag(unwrapped, ctx.decls);
+            const lit = leaf.left === oc ? leaf.right : leaf.left;
+            return { scrutinee: oc.obj, innerTy: oc.obj.ty.inner, binder, residual: { kind: "binop", op: "!==", left: unwrapped, right: lit, ty: { kind: "bool" } } };
+        }
+    }
+    // `!x` / `x === undefined`.
+    const f = presentFact(leaf);
+    if (f && f.negated) {
+        const residual = canBeFalsy(f)
+            ? { kind: "unop", op: "!", expr: { kind: "var", name: f.binder, ty: f.innerTy }, ty: { kind: "bool" } }
+            : null;
+        return { scrutinee: f.scrutinee, innerTy: f.innerTy, binder: f.binder, residual };
+    }
+    return null;
+}
+/** Apply an optional chain's steps (field / index / call) to a base expr. */
+export function applyChain(body, chain) {
+    for (const step of chain) {
+        if (step.kind === "field")
+            body = { kind: "field", obj: body, field: step.name, ty: step.ty };
+        else if (step.kind === "index")
+            body = { kind: "index", obj: body, idx: step.idx, ty: step.ty };
+        else
+            body = { kind: "call", fn: body, args: step.args, ty: step.ty, callKind: step.callKind,
+                ...(step.builtinId ? { builtinId: step.builtinId } : {}) };
+    }
+    return body;
+}
+/** `applyChain` rebuilds a field access without the `isDiscriminant` flag
+ *  resolve sets on a direct `x.disc`; restore it when the unwrapped access
+ *  is the binder union's discriminant, so the guard feeds discriminant
+ *  narrowing. (The single home of a fixup formerly duplicated per rule.) */
+export function restoreDiscriminantFlag(unwrapped, decls) {
+    if (unwrapped.kind === "field" &&
+        discriminantOf(decls, unwrapped.obj.ty) === unwrapped.field) {
+        unwrapped.isDiscriminant = true;
+    }
+}
+// ── In-bounds facts ─────────────────────────────────────────
+/** `0 <= idx && idx < arr.length` — the in-bounds guard for an array index. */
+export function arrayBoundsCond(arr, idx) {
+    const len = { kind: "field", obj: arr, field: "length", ty: { kind: "int" } };
+    const lo = { kind: "binop", op: "<=", left: { kind: "num", value: 0, ty: { kind: "int" } }, right: idx, ty: { kind: "bool" } };
+    const hi = { kind: "binop", op: "<", left: idx, right: len, ty: { kind: "bool" } };
+    return { kind: "binop", op: "&&", left: lo, right: hi, ty: { kind: "bool" } };
+}
+// ── Map-membership facts ────────────────────────────────────
+/** Minimal structural equality on the IR shapes we narrow against: var, field
+ *  chain, and index (with pure key). Enough to recognize `m[k]` on both sides
+ *  of a `k in m ? m[k] : default` ternary. */
+export function exprEqual(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    if (a.kind === "var" && b.kind === "var")
+        return a.name === b.name;
+    if (a.kind === "field" && b.kind === "field")
+        return a.field === b.field && exprEqual(a.obj, b.obj);
+    if (a.kind === "index" && b.kind === "index")
+        return exprEqual(a.obj, b.obj) && exprEqual(a.idx, b.idx);
+    return false;
+}
+/** Produce a reader-friendly binder hint for `m[k]` when both m and k are
+ *  access-path shaped (var / field chain). Falls back to a generic counter
+ *  name for computed keys. */
+export function binderHintForMapAccess(m, k, ctx) {
+    const mHint = binderHintFor(m);
+    const kHint = binderHintFor(k);
+    if (mHint && kHint) {
+        // mHint is `_m_val`, kHint is `_k_val` — stitch into `_m_k_val`.
+        const mStem = mHint.replace(/_val$/, "");
+        const kStem = kHint.replace(/^_/, "").replace(/_val$/, "");
+        return freshName(`${mStem}_${kStem}_val`);
+    }
+    return freshOcBinder(ctx);
+}
+/** A "narrowable path" is a var or a chain of field accesses rooted at a var
+ *  — i.e., pure and structurally addressable, so transforms can substitute
+ *  occurrences inside a matched arm without worrying about re-evaluation. */
+export function isNarrowablePath(e) {
+    if (e.kind === "var")
+        return true;
+    if (e.kind === "field")
+        return isNarrowablePath(e.obj);
+    return false;
+}
+/** Detect `Array.isArray(<path>)` where `<path>` is a narrowable path whose
+ *  type is a synthesized array-union (discriminant `"__isArray__"`). */
+export function isArrayFact(call, ctx) {
+    if (call.kind !== "call")
+        return null;
+    if (call.fn.kind !== "field" || call.fn.field !== "isArray")
+        return null;
+    if (call.fn.obj.kind !== "var" || call.fn.obj.name !== "Array")
+        return null;
+    if (call.args.length !== 1)
+        return null;
+    const arg = call.args[0];
+    if (!isNarrowablePath(arg) || arg.ty.kind !== "user")
+        return null;
+    const decl = unionDeclOfTy(ctx.decls, arg.ty);
+    if (decl?.discriminant !== "__isArray__")
+        return null;
+    return { scrutinee: arg, typeName: arg.ty.name, variant: "ArrayBranch" };
+}
+/** Detect `typeof <path> === "string"` where `<path>`'s type is a synth array-
+ *  union (`U | T[]`) AND its `NonArrayBranch` payload `U` is itself `string`.
+ *  The runtime `=== "string"` test matches that branch only when `U` is string —
+ *  for any other non-array payload (`number | T[]`, …) it never holds, so we must
+ *  NOT narrow. Returns the `NonArrayBranch` variant; the dual of `Array.isArray`. */
+export function typeofStringFact(e, ctx) {
+    if (e.kind !== "binop" || e.op !== "===")
+        return null;
+    const tof = e.left.kind === "unop" && e.left.op === "typeof" ? e.left.expr
+        : e.right.kind === "unop" && e.right.op === "typeof" ? e.right.expr : null;
+    const lit = e.left.kind === "str" ? e.left.value : e.right.kind === "str" ? e.right.value : null;
+    if (!tof || lit !== "string")
+        return null;
+    if (!isNarrowablePath(tof) || tof.ty.kind !== "user")
+        return null;
+    const decl = unionDeclOfTy(ctx.decls, tof.ty);
+    if (decl?.discriminant !== "__isArray__")
+        return null;
+    const valTy = decl.variants?.find(v => v.name === "NonArrayBranch")?.fields.find(f => f.name === "val")?.type;
+    if (valTy?.kind !== "string")
+        return null; // guard: the non-array branch must actually be `string`
+    return { scrutinee: tof, typeName: tof.ty.name, variant: "NonArrayBranch" };
+}
+/** Leading `Array.isArray(path)` fact of an `&&` chain (positive form only — a
+ *  negated `!Array.isArray(...)` would narrow to the wrong variant for then-body
+ *  consumers, so those are left to the untouched-conditional path). */
+export function leadingIsArray(cond, ctx) {
+    return extractConjunct(cond, e => isArrayFact(e, ctx));
+}
+/** Detect `x.kind === "variant"`, `'key' in x`, or `Array.isArray(x)` (synth
+ *  array-union) as a positive discriminant check on a bare-var scrutinee. */
+export function variantFact(cond, ctx) {
+    // Pattern: x.discriminant === "variant"
+    if (cond.kind === "binop" && cond.op === "===" && cond.right.kind === "str" &&
+        cond.left.kind === "field" && cond.left.isDiscriminant &&
+        cond.left.obj.kind === "var" && cond.left.obj.ty.kind === "user") {
+        return { scrutinee: cond.left.obj, typeName: cond.left.obj.ty.name, variant: cond.right.value };
+    }
+    // Pattern: 'key' in x — narrows x to the unique variant containing `key`.
+    if (cond.kind === "binop" && cond.op === "in" &&
+        cond.left.kind === "str" && cond.right.kind === "var" &&
+        cond.right.ty.kind === "user") {
+        const key = cond.left.value;
+        const typeName = cond.right.ty.name;
+        const decl = unionDeclOfTy(ctx.decls, cond.right.ty);
+        if (decl?.variants) {
+            const matches = decl.variants.filter(v => v.fields.some(f => f.name === key));
+            if (matches.length === 1) {
+                return { scrutinee: cond.right, typeName, variant: matches[0].name };
+            }
+        }
+    }
+    // Pattern: Array.isArray(x) — narrows x to the ArrayBranch variant of a
+    // synthesized array-union (discriminant "__isArray__"). Statement-level
+    // discriminant chains (`if (Array.isArray(x)) {...} else if (...)`) still
+    // require a bare-var scrutinee since the existing var-name-keyed
+    // replacement machinery in transform.ts only handles that shape; path
+    // scrutinees (e.g. `m.content`) are handled exclusively by the
+    // conditional/expression tagMatch drivers.
+    const arrCheck = isArrayFact(cond, ctx);
+    if (arrCheck && arrCheck.scrutinee.kind === "var") {
+        return { scrutinee: arrCheck.scrutinee, typeName: arrCheck.typeName, variant: arrCheck.variant };
+    }
+    return null;
+}
+/** Detect `x.kind !== "variant"` (negative discriminant check) or
+ *  `!Array.isArray(x)` (synth array-union, narrows to NonArrayBranch). */
+export function negVariantFact(cond, ctx) {
+    if (cond.kind === "binop" && cond.op === "!==" && cond.right.kind === "str" &&
+        cond.left.kind === "field" && cond.left.isDiscriminant &&
+        cond.left.obj.kind === "var" && cond.left.obj.ty.kind === "user") {
+        return { scrutinee: cond.left.obj, typeName: cond.left.obj.ty.name, variant: cond.right.value };
+    }
+    // Pattern: !Array.isArray(x) — narrows x to the NonArrayBranch variant.
+    // Same var-scrutinee restriction as variantFact.
+    if (cond.kind === "unop" && cond.op === "!") {
+        const arrCheck = isArrayFact(cond.expr, ctx);
+        if (arrCheck && arrCheck.scrutinee.kind === "var") {
+            return { scrutinee: arrCheck.scrutinee, typeName: arrCheck.typeName, variant: "NonArrayBranch" };
+        }
+    }
+    return null;
+}
+// ── Materializers ───────────────────────────────────────────
+/** Reify a presence fact in statement position: the falsy gate (for
+ *  truthiness checks over falsy-capable inners) tests the bound value inside
+ *  the Some arm, routing falsy inners to `none`. */
+export function presentMatchStmts(f, some, none) {
+    return {
+        kind: "someMatch",
+        scrutinee: f.scrutinee, binderTy: f.innerTy,
+        binder: f.binder,
+        someBody: canBeFalsy(f) ? [{ kind: "if", cond: bound(f), then: some, else: none }] : some,
+        noneBody: none,
+    };
+}
+/** Reify a presence fact in expression position; same falsy gate. */
+export function presentMatchExpr(f, some, none, ty) {
+    return {
+        kind: "someMatch",
+        scrutinee: f.scrutinee, binderTy: f.innerTy,
+        binder: f.binder,
+        someBody: canBeFalsy(f) ? { kind: "conditional", cond: bound(f), then: some, else: none, ty } : some,
+        noneBody: none,
+        ty,
+    };
+}