@harmoniclabs/pebble 0.1.10 → 0.3.0

package/dist/IR/IRNodes/utils/hashVarSym.js

@@ -1,36 +1,30 @@
-// HASH GENERATOR
 import { fromHex } from "@harmoniclabs/uint8array-utils";
-const MAX_SAFE_INTEGER = Number(globalThis.Number?.MAX_SAFE_INTEGER ?? ((2 ** 53) - 1));
-const MIN_SAFE_INTEGER = Number(globalThis.Number?.MIN_SAFE_INTEGER ?? -MAX_SAFE_INTEGER);
-const _sym_to_hash = new Map();
-const _hash_to_sym = new Map();
-let _next_hash = MIN_SAFE_INTEGER;
-const unusedHashes = [];
-function _collectUnusedHashes() {
-    for (const [h, s] of _hash_to_sym) {
-        if (!_sym_to_hash.has(s)) {
-            _hash_to_sym.delete(h);
-            unusedHashes.push(h);
-        }
-    }
-}
-export function __VERY_UNSAFE_FORGET_VAR_SYM_HASHES_ONLY_USE_AT_END_OF_UPLC_COMPILATION() {
-    _hash_to_sym.clear();
-    unusedHashes.length = 0;
-    _next_hash = MIN_SAFE_INTEGER;
-}
+/**
+ * Stable per-symbol bytes used as the preimage contribution of an
+ * `IRVar` / self-reference when hashing.
+ *
+ * Each distinct symbol is assigned a unique 8-byte id the first time it
+ * is hashed; subsequent calls for the same symbol return the same bytes.
+ * This makes hashing a pure function of the (symbol-identity) content,
+ * so a term's hash is stable for the life of the process — exactly what
+ * content-addressed `IRHash` requires.
+ *
+ * No global state needs resetting:
+ *  - the map is a `WeakMap`, so a symbol's entry is collected once the
+ *    symbol itself is unreachable (no unbounded growth);
+ *  - the counter is monotonic and never rewinds, so a symbol can never
+ *    be reassigned a colliding id (the bug that the old reset-based
+ *    scheme introduced).
+ */
+// `any` key: non-registered symbols are valid WeakMap keys at runtime
+// (ES2023 / Node 20+), but older `lib` typings don't model symbol keys.
+const _sym_to_bytes = new WeakMap();
+let _next_id = 0n;
 export function hashVarSym(s) {
-    const limitReached = _next_hash >= MAX_SAFE_INTEGER;
-    if (_next_hash % 0xffff === 0
-        || limitReached)
-        _collectUnusedHashes();
-    if (limitReached
-        && unusedHashes.length <= 0)
-        throw new Error("ran out of IR hashes");
-    const result_hash = unusedHashes.shift() ?? _next_hash++;
-    _sym_to_hash.set(s, result_hash);
-    _hash_to_sym.set(result_hash, s);
-    return fromHex((BigInt(result_hash) + BigInt(MAX_SAFE_INTEGER))
-        .toString(16)
-        .padStart(16, "0"));
+    let bytes = _sym_to_bytes.get(s);
+    if (bytes !== undefined)
+        return bytes;
+    bytes = fromHex((_next_id++).toString(16).padStart(16, "0"));
+    _sym_to_bytes.set(s, bytes);
+    return bytes;
 }

package/dist/IR/toUPLC/CompilerOptions.d.ts

@@ -1,4 +1,6 @@
 import { UPLCVersion } from "@harmoniclabs/uplc";
+import { COMPILER_VERSION } from "../../version.generated.js";
+export { COMPILER_VERSION };
 export interface CompilerUplcOptimizations {
     /**
      *
@@ -21,6 +23,13 @@ export declare const defaultUplcOptimizations: CompilerUplcOptimizations;
 export declare function isDebugUplcOptimizations(options?: Partial<CompilerUplcOptimizations>): boolean;
 export declare function completeUplcOptimizations(options: Partial<CompilerUplcOptimizations>, complete?: CompilerUplcOptimizations): CompilerUplcOptimizations;
 export interface CompilerOptions {
+    /**
+     * npm-style semver range that the running compiler version must satisfy.
+     * Required since `@harmoniclabs/pebble@0.2.0` — the `Compiler` throws
+     * when this field is missing or when the running compiler version does
+     * not satisfy the range.
+     */
+    compilerVersion: string;
     /**
      * path to the entry file
      */
@@ -75,11 +84,29 @@ export interface CompilerOptions {
      *
      **/
     addMarker: boolean;
+    /**
+     * Controls the default Data encoding for single-constructor shortcut
+     * struct declarations (`struct Foo { x: int }`).
+     *
+     * - `"default"`: shortcut single-constructor structs are encoded as
+     *   `constrData(0, fields)` (backwards-compatible). Use the explicit
+     *   `untagged` keyword to opt a specific struct in to the minimal form.
+     * - `"minimal"`: shortcut single-constructor structs are encoded as
+     *   `listData(fields)` (smaller / cheaper). The explicit `untagged`
+     *   keyword still forces minimal regardless.
+     */
+    encodingStrategy: "default" | "minimal";
 }
-export declare const extremeOptions: CompilerOptions;
-export declare const productionOptions: CompilerOptions;
-export declare const debugOptions: CompilerOptions;
-export declare const defaultOptions: CompilerOptions;
-export declare const testOptions: CompilerOptions;
-export declare const defulatCompilerOptions: CompilerOptions;
-export declare function completeCompilerOptions(options: Partial<CompilerOptions>, complete?: CompilerOptions): CompilerOptions;
+/**
+ * Option templates intentionally omit `compilerVersion` — every caller must
+ * set it explicitly so a missing `compilerVersion` always surfaces as an
+ * error from the `Compiler` constructor.
+ */
+export type CompilerDefaults = Omit<CompilerOptions, "compilerVersion">;
+export declare const extremeOptions: CompilerDefaults;
+export declare const productionOptions: CompilerDefaults;
+export declare const debugOptions: CompilerDefaults;
+export declare const defaultOptions: CompilerDefaults;
+export declare const testOptions: CompilerDefaults;
+export declare const defulatCompilerOptions: CompilerDefaults;
+export declare function completeCompilerOptions(options: Partial<CompilerOptions>, complete?: Partial<CompilerOptions>): CompilerOptions;

package/dist/IR/toUPLC/CompilerOptions.js

@@ -1,5 +1,8 @@
 import { isObject } from "@harmoniclabs/obj-utils";
-import { defaultUplcVersion, UPLCVersion } from "@harmoniclabs/uplc";
+import { UPLCVersion } from "@harmoniclabs/uplc";
+import { COMPILER_VERSION } from "../../version.generated.js";
+const defaultTargetUplcVersion = new UPLCVersion(1, 1, 0);
+export { COMPILER_VERSION };
 export const productionUplcOptimizations = Object.freeze({
     groupApplications: true,
     inlineSingleUse: true,
@@ -37,33 +40,36 @@ export const extremeOptions = Object.freeze({
     root: ".",
     outDir: "./out",
     silent: false,
-    targetUplcVersion: defaultUplcVersion,
+    targetUplcVersion: defaultTargetUplcVersion,
     removeTraces: true,
     delayHoists: true,
     uplcOptimizations: productionUplcOptimizations,
-    addMarker: true
+    addMarker: true,
+    encodingStrategy: "minimal"
 });
 export const productionOptions = Object.freeze({
     entry: "./src/index.pebble",
     root: ".",
     outDir: "./out",
     silent: false,
-    targetUplcVersion: defaultUplcVersion,
+    targetUplcVersion: defaultTargetUplcVersion,
     removeTraces: true,
     delayHoists: true,
     uplcOptimizations: productionUplcOptimizations,
-    addMarker: true
+    addMarker: true,
+    encodingStrategy: "default"
 });
 export const debugOptions = Object.freeze({
     entry: "./src/index.pebble",
     root: ".",
     outDir: "./out",
     silent: false,
-    targetUplcVersion: defaultUplcVersion,
+    targetUplcVersion: defaultTargetUplcVersion,
     removeTraces: false,
     delayHoists: false,
     uplcOptimizations: debugUplcOptimizations,
-    addMarker: false
+    addMarker: false,
+    encodingStrategy: "default"
 });
 export const defaultOptions = Object.freeze({
     ...productionOptions,
@@ -75,7 +81,7 @@ export const testOptions = Object.freeze({
 });
 export const defulatCompilerOptions = defaultOptions;
 export function completeCompilerOptions(options, complete = defaultOptions) {
-    let targetUplcVersion = options.targetUplcVersion instanceof UPLCVersion ? complete.targetUplcVersion : defaultUplcVersion;
+    let targetUplcVersion = options.targetUplcVersion instanceof UPLCVersion ? complete.targetUplcVersion : defaultTargetUplcVersion;
     complete = {
         ...defaultOptions,
         ...complete
@@ -99,10 +105,13 @@ export function completeCompilerOptions(options, complete = defaultOptions) {
     // console.log( "completeUplcOptimizations( uplcOptimizations )",completeUplcOptimizations( uplcOptimizations ))
     return {
         ...complete,
-        targetUplcVersion,
+        // forward compilerVersion verbatim — no fallback; Compiler throws if missing/invalid
+        compilerVersion: options.compilerVersion ?? complete.compilerVersion,
+        targetUplcVersion: targetUplcVersion,
         removeTraces: options.removeTraces ?? complete.removeTraces,
         delayHoists: options.delayHoists ?? complete.delayHoists,
         uplcOptimizations: completeUplcOptimizations(uplcOptimizations),
-        addMarker: options.addMarker ?? complete.addMarker
+        addMarker: options.addMarker ?? complete.addMarker,
+        encodingStrategy: options.encodingStrategy ?? complete.encodingStrategy ?? "default"
     };
 }

package/dist/IR/toUPLC/compileIRToUPLC.js

@@ -16,6 +16,10 @@ import { IRCase, IRConstr, IRFunc, IRNative } from "../IRNodes/index.js";
 import { replaceForcedNativesWithHoisted } from "./subRoutines/replaceForcedNativesWithHoisted.js";
 import { performUplcOptimizationsAndReturnRoot } from "./subRoutines/performUplcOptimizationsAndReturnRoot/performUplcOptimizationsAndReturnRoot.js";
 import { rewriteNativesAppliedToConstantsAndReturnRoot } from "./subRoutines/rewriteNativesAppliedToConstantsAndReturnRoot.js";
+import { rewriteToCaseOverConstAndReturnRoot } from "./subRoutines/rewriteToCaseOverConstAndReturnRoot.js";
+import { rewriteHeadTailInCaseConsAndReturnRoot } from "./subRoutines/rewriteHeadTailInCaseConsAndReturnRoot.js";
+import { introduceCaseForDualHeadTailAndReturnRoot } from "./subRoutines/introduceCaseForDualHeadTailAndReturnRoot.js";
+import { inlineSingleUseLetBindingsAndReturnRoot } from "./subRoutines/inlineSingleUseLetBindingsAndReturnRoot.js";
 import { _debug_assertClosedIR } from "../utils/index.js";
 import { ToUplcCtx } from "./ctx/ToUplcCtx.js";
 import { removeUnusedVarsAndReturnRoot } from "./subRoutines/removeUnusuedVarsAndReturnRoot/removeUnusuedVarsAndReturnRoot.js";
@@ -57,6 +61,29 @@ export function compileIRToUPLC(term, paritalOptions = defaultOptions) {
     term = replaceNativesAndReturnRoot(term);
     // re-call rewrite to optimize introduced hoisted
     term = rewriteNativesAppliedToConstantsAndReturnRoot(term);
+    // Lower `strictIfThenElse` triple-apps to `IRCase` BEFORE
+    // `replaceForcedNativesWithHoisted` would otherwise hoist
+    // `(force ifThenElse)` into a shared variable that's no longer
+    // pattern-matchable as a native. (`strictChooseList` is already
+    // lowered to `IRCase` unconditionally by the earlier
+    // `rewriteNativesAppliedToConstantsAndReturnRoot` pass.)
+    term = rewriteToCaseOverConstAndReturnRoot(term);
+    // Inside `case L of cons h t -> body`, replace any `headList(L)` /
+    // `tailList(L)` calls within `body` with `h` / `t`. Drop the now-dead
+    // `h`/`t` bindings via a fresh unused-vars sweep.
+    term = rewriteHeadTailInCaseConsAndReturnRoot(term);
+    term = removeUnusedVarsAndReturnRoot(term);
+    // For every IRFunc body where the same list L is accessed via BOTH
+    // `headList(L)` and `tailList(L)`, wrap the body in
+    // `case L of cons h t -> body' | nil -> error` and substitute the two
+    // builtin calls with `h` / `t`. Empirically (bench.headTailVsCase):
+    // one case dispatch costs ~128K CPU vs ~160K for two builtin calls,
+    // and only ~9 bytes vs ~16. The previous head/tail-in-case-cons pass
+    // can then make a second sweep to substitute any further internal
+    // references the new case introduced.
+    term = introduceCaseForDualHeadTailAndReturnRoot(term);
+    term = rewriteHeadTailInCaseConsAndReturnRoot(term);
+    term = removeUnusedVarsAndReturnRoot(term);
     // debugAsserts && _debug_assertions( term );
     // unwrap top level letted and hoisted;
     // some natives may be converted to hoisted;
@@ -144,12 +171,21 @@ export function compileIRToUPLC(term, paritalOptions = defaultOptions) {
     //     somethingWasInlined = inlineResult.somethingWasInlined;
     // }
     term = removeUnusedVarsAndReturnRoot(term);
+    // After `handleLettedAndReturnRoot` lowers `IRLetted` into the
+    // `IRApp(IRFunc([p], body), value)` shape, this is the first point
+    // where the let-as-application pattern is syntactically visible.
+    // Run the inliner here (NOT earlier, where lets are still IRLetted
+    // nodes the inliner doesn't recognize). Single-use uses trapped
+    // inside nested closures are skipped — see the pass for details.
+    term = inlineSingleUseLetBindingsAndReturnRoot(term);
+    term = removeUnusedVarsAndReturnRoot(term);
     term = performUplcOptimizationsAndReturnRoot(term, options);
+    // Rewrite strictIfThenElse into IRCase-over-Const, and prune
+    // trailing IRError continuations from any IRCase.
+    term = rewriteToCaseOverConstAndReturnRoot(term);
     term = ensureProperlyForcedBuiltinsAndReturnRoot(term);
     if (options.addMarker &&
-        options.targetUplcVersion.major >= 1 &&
-        options.targetUplcVersion.minor >= 1 &&
-        options.targetUplcVersion.patch >= 0) {
+        options.targetUplcVersion.isV3Friendly()) {
         term = new IRCase(new IRConstr(0, []), [
             term,
             // never evaluated

package/dist/IR/toUPLC/subRoutines/inlineSingleUseLetBindingsAndReturnRoot.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Inline single-use let-bindings of the shape `((λp. body) value)`:
+ *
+ *   - If `body` references `p` exactly once AND that reference is NOT
+ *     trapped inside a nested closure (IRFunc/IRRecursive) within
+ *     `body`, replace the entire app with `body[p := value]`. The
+ *     nested-closure guard is critical: a use that's syntactically
+ *     "once" inside a recursive body is actually evaluated once per
+ *     iteration, and inlining there would move per-iteration work to a
+ *     value the caller currently evaluates once.
+ *   - If `body` references `p` zero times, drop the let and replace
+ *     the app with `body`.
+ *
+ * IRCase continuations are themselves IRFunc nodes (case-cons branches
+ * take h/t lambdas), but the case dispatches each continuation AT MOST
+ * ONCE per case eval, so they don't count as "trapping" closures — we
+ * treat IRFunc reached *as a direct case continuation* as transparent.
+ *
+ * If `body` uses `p` two or more times we don't inline either (would
+ * duplicate the term in the output).
+ */
+import { IRTerm } from "../../IRTerm.js";
+export declare function inlineSingleUseLetBindingsAndReturnRoot(term: IRTerm): IRTerm;

package/dist/IR/toUPLC/subRoutines/inlineSingleUseLetBindingsAndReturnRoot.js

@@ -0,0 +1,263 @@
+/**
+ * Inline single-use let-bindings of the shape `((λp. body) value)`:
+ *
+ *   - If `body` references `p` exactly once AND that reference is NOT
+ *     trapped inside a nested closure (IRFunc/IRRecursive) within
+ *     `body`, replace the entire app with `body[p := value]`. The
+ *     nested-closure guard is critical: a use that's syntactically
+ *     "once" inside a recursive body is actually evaluated once per
+ *     iteration, and inlining there would move per-iteration work to a
+ *     value the caller currently evaluates once.
+ *   - If `body` references `p` zero times, drop the let and replace
+ *     the app with `body`.
+ *
+ * IRCase continuations are themselves IRFunc nodes (case-cons branches
+ * take h/t lambdas), but the case dispatches each continuation AT MOST
+ * ONCE per case eval, so they don't count as "trapping" closures — we
+ * treat IRFunc reached *as a direct case continuation* as transparent.
+ *
+ * If `body` uses `p` two or more times we don't inline either (would
+ * duplicate the term in the output).
+ */
+import { IRApp } from "../../IRNodes/IRApp.js";
+import { IRCase } from "../../IRNodes/IRCase.js";
+import { IRConst } from "../../IRNodes/IRConst.js";
+import { IRDelayed } from "../../IRNodes/IRDelayed.js";
+import { IRFunc } from "../../IRNodes/IRFunc.js";
+import { IRHoisted } from "../../IRNodes/IRHoisted.js";
+import { IRLetted } from "../../IRNodes/IRLetted.js";
+import { IRRecursive } from "../../IRNodes/IRRecursive.js";
+import { IRVar } from "../../IRNodes/IRVar.js";
+import { _modifyChildFromTo } from "../_internal/_modifyChildFromTo.js";
+export function inlineSingleUseLetBindingsAndReturnRoot(term) {
+    // Iterate until a full pass finds nothing to rewrite. Each rewrite
+    // restarts the walk from the (possibly new) root because the tree
+    // shape near the rewrite changes and may expose further candidates.
+    let didChange = true;
+    while (didChange) {
+        didChange = false;
+        const stack = [term];
+        outer: while (stack.length > 0) {
+            const t = stack.pop();
+            if (t instanceof IRApp
+                && t.fn instanceof IRFunc
+                && t.fn.params.length === 1) {
+                const fn = t.fn;
+                const p = fn.params[0];
+                const value = t.arg;
+                // Beta-reduce when the argument is itself just a
+                // variable access. Replacing every `IRVar(p)` with
+                // `IRVar(x)` costs the same per access (a single env
+                // lookup either way) and saves the surrounding
+                // `(λp. …) x` lambda + application. Always safe,
+                // regardless of how many times `p` is used and
+                // regardless of whether the uses sit inside a recursive
+                // body — there's no work to multiply.
+                if (value instanceof IRVar) {
+                    const newBody = substituteAllVar(fn.body, p, value);
+                    term = replaceWithBody(term, t, newBody);
+                    didChange = true;
+                    break outer;
+                }
+                const stats = countVarUses(fn.body, p);
+                if (stats.count === 0) {
+                    // Dead let — replace with body, dropping the value.
+                    term = replaceWithBody(term, t, fn.body);
+                    didChange = true;
+                    break outer;
+                }
+                if (stats.count === 1 && !stats.trapped) {
+                    substituteVar(fn.body, p, value);
+                    term = replaceWithBody(term, t, fn.body);
+                    didChange = true;
+                    break outer;
+                }
+                // Trapped single use: the lone occurrence sits inside a
+                // nested closure (recursive body or non-case lambda).
+                // Inlining a COMPUTATION there would duplicate the
+                // per-iteration work, but a syntactic VALUE (closure /
+                // constant / var / delay) only pays its (essentially
+                // zero) construction cost — the same as a fresh lookup.
+                // Pebble also stores recursive helpers as open-recursion
+                // lambdas whose body references their own binding name;
+                // inlining such a lambda would orphan that self-ref, so
+                // also require that the value has no free `IRVar(p)`.
+                if (stats.count === 1
+                    && stats.trapped
+                    && isSyntacticValue(value)
+                    && !containsFreeVar(value, p)) {
+                    substituteVar(fn.body, p, value);
+                    term = replaceWithBody(term, t, fn.body);
+                    didChange = true;
+                    break outer;
+                }
+                // count >= 2, or trapped-with-computational-value → leave alone
+            }
+            stack.push(...t.children());
+        }
+    }
+    return term;
+}
+/** Returns true if `term` contains a free `IRVar(p)` reference. A
+ * binding inside `term` that re-uses `p`'s symbol shadows it (these
+ * are rare given fresh-symbol minting, but the check is cheap). */
+function containsFreeVar(term, p) {
+    const stack = [term];
+    while (stack.length > 0) {
+        const t = stack.pop();
+        if (t instanceof IRVar && t.name === p)
+            return true;
+        if (t instanceof IRFunc && t.params.includes(p))
+            continue;
+        if (t instanceof IRRecursive && t.name === p)
+            continue;
+        stack.push(...t.children());
+    }
+    return false;
+}
+/**
+ * A "syntactic value" is a term whose evaluation does no work beyond
+ * binding/closure construction — duplicating it across a recursive
+ * boundary doesn't multiply runtime cost. Specifically:
+ *
+ *   - `IRFunc` / `IRRecursive` — closure values; per-construction is
+ *     ~zero cost, and the body only runs when the closure is applied
+ *     (which happens at the use-site frequency either way).
+ *   - `IRConst` — literal value.
+ *   - `IRVar` — already just an environment lookup.
+ *   - `IRDelayed` — produces a thunk; the inner term only runs on
+ *     force, at the use-site frequency.
+ *
+ * NOTE: `IRNative` is deliberately NOT included. While a bare native
+ * reference is itself cheap, in Pebble's pipeline `hoistForcedNatives`
+ * specifically wraps each forced builtin (e.g. `headList`,
+ * `tailList`, `ifThenElse`) once at the top via `(λvar. …) IRNative`,
+ * so that the runtime `force` happens once and is shared. Inlining
+ * the `IRNative` back into a recursive body undoes that sharing —
+ * the resulting compiled UPLC re-issues the force per iteration.
+ * `IRHoisted`/`IRLetted` are transparent wrappers: we unwrap to check
+ * the inner term.
+ */
+function isSyntacticValue(t) {
+    while (t instanceof IRHoisted)
+        t = t.hoisted;
+    while (t instanceof IRLetted)
+        t = t.value;
+    return (t instanceof IRFunc
+        || t instanceof IRRecursive
+        || t instanceof IRConst
+        || t instanceof IRVar
+        || t instanceof IRDelayed);
+}
+function replaceWithBody(root, app, body) {
+    const parent = app.parent;
+    if (parent === undefined) {
+        body.parent = undefined;
+        return body;
+    }
+    _modifyChildFromTo(parent, app, body);
+    return root;
+}
+/** Count IRVar(p) references in `body` accurately. Caps at 2 — we
+ * only care about 0/1/many — but ALWAYS walks the whole tree, so we
+ * correctly distinguish "1 trapped use" from "1 trapped + 1 more".
+ */
+function countVarUses(body, p) {
+    let count = 0;
+    let firstUseTrapped = false;
+    const stack = [{ node: body, trapped: false }];
+    while (stack.length > 0) {
+        const { node: t, trapped } = stack.pop();
+        if (t instanceof IRVar) {
+            if (t.name === p) {
+                if (count === 0)
+                    firstUseTrapped = trapped;
+                count++;
+                if (count >= 2)
+                    return { count: 2, trapped: false };
+            }
+            continue;
+        }
+        // Symbols are minted fresh on each binder, so shadowing is rare,
+        // but the guard is cheap and protects against any reuse.
+        if (t instanceof IRFunc && t.params.includes(p))
+            continue;
+        if (t instanceof IRRecursive && t.name === p)
+            continue;
+        // Determine the trap state for descending into this node:
+        //   - IRRecursive always traps (loop introduces multi-eval).
+        //   - IRFunc traps EXCEPT when it's a direct case continuation
+        //     (`IRCase(_, […, this IRFunc, …])`): the case dispatches
+        //     it at most once per case eval, so it's transparent.
+        let childTrapped = trapped;
+        if (t instanceof IRRecursive)
+            childTrapped = true;
+        else if (t instanceof IRFunc) {
+            const parent = t.parent;
+            const isCaseContinuation = parent instanceof IRCase
+                // direct continuation array membership
+                && Array.from(parent.continuations).includes(t);
+            if (!isCaseContinuation)
+                childTrapped = true;
+        }
+        for (const c of t.children())
+            stack.push({ node: c, trapped: childTrapped });
+    }
+    return { count: count, trapped: firstUseTrapped };
+}
+/**
+ * Replace EVERY `IRVar(p)` inside `body` with a fresh clone of
+ * `replacement`. Used for the var-arg beta-reduction: substituting one
+ * variable name for another anywhere it appears.
+ *
+ * Returns the (possibly new) body. If `body` itself is `IRVar(p)`,
+ * returns a fresh clone of `replacement` — the caller is responsible
+ * for wiring it into the parent.
+ */
+function substituteAllVar(body, p, replacement) {
+    if (body instanceof IRVar && body.name === p) {
+        return replacement.clone();
+    }
+    const stack = [body];
+    while (stack.length > 0) {
+        const t = stack.pop();
+        // Don't descend into scopes that shadow p (unique-symbol
+        // invariant makes this rare, but the guard is cheap).
+        if (t instanceof IRFunc && t.params.includes(p))
+            continue;
+        if (t instanceof IRRecursive && t.name === p)
+            continue;
+        // Snapshot children before mutating (children() returns a fresh
+        // array, so the loop is stable across modifications).
+        const children = t.children();
+        for (const child of children) {
+            if (child instanceof IRVar && child.name === p) {
+                // `t` must be a parent term because we got `child` from
+                // `t.children()`. Cast to satisfy the type checker.
+                _modifyChildFromTo(t, child, replacement.clone());
+            }
+            else {
+                stack.push(child);
+            }
+        }
+    }
+    return body;
+}
+/** Replace the (single) IRVar(p) inside `body` with `replacement`. */
+function substituteVar(body, p, replacement) {
+    const stack = [body];
+    while (stack.length > 0) {
+        const t = stack.pop();
+        if (t instanceof IRVar && t.name === p) {
+            const parent = t.parent;
+            if (parent !== undefined)
+                _modifyChildFromTo(parent, t, replacement);
+            return;
+        }
+        if (t instanceof IRFunc && t.params.includes(p))
+            continue;
+        if (t instanceof IRRecursive && t.name === p)
+            continue;
+        stack.push(...t.children());
+    }
+}

package/dist/IR/toUPLC/subRoutines/introduceCaseForDualHeadTailAndReturnRoot.d.ts

@@ -0,0 +1,35 @@
+/**
+ * When the same list `L` is used for BOTH `headList(L)` and `tailList(L)`
+ * within a single function body, those two builtin calls can be replaced
+ * by a single `case L of cons h t -> body[h/headList(L), t/tailList(L)] |
+ * nil -> error`. The trade-off (measured in `bench.headTailVsCase`):
+ *
+ *   - one `headList` (or `tailList`) builtin call: 112,100 CPU / 800 mem
+ *   - one `case L of cons h t -> h | nil -> error`: 128,100 CPU / 900 mem
+ *
+ * So for a single access the builtin wins; for dual access the case wins
+ * by a single dispatch (~96K CPU / 700 mem).
+ *
+ * This pass walks every `IRFunc` body bottom-up. For each body, it scans
+ * the top-level (without descending into nested `IRFunc`/`IRRecursive`,
+ * because nested scopes are processed independently). If a free list var
+ * `L` has both a `headList(L)` and a `tailList(L)` use in the body, the
+ * body is wrapped with `IRCase(IRVar(L), [IRFunc([h, t], body'), IRError])`
+ * — where `body'` has those calls replaced with `IRVar(h)` / `IRVar(t)`.
+ *
+ * Notes:
+ *   - We only act on `IRFunc` bodies that are NOT immediate continuations
+ *     of an `IRCase` whose scrutinee is `IRVar(L)` for the same L — that
+ *     case-cons branch already binds head/tail and the prior
+ *     `rewriteHeadTailInCaseConsAndReturnRoot` pass has already done the
+ *     substitution. Wrapping again would be a no-op constructor pair.
+ *   - The nil branch is `IRError`. Original code that calls `headList` or
+ *     `tailList` on a nil list errors at evaluation; the new code errors
+ *     at the case dispatch — same observable behavior whenever either
+ *     call is actually reached.
+ *   - The pass iterates: after introducing a case for L, the (now
+ *     substituted) body might still contain a different L' with dual
+ *     head/tail uses — handled by re-scanning until no more pairs.
+ */
+import { IRTerm } from "../../IRTerm.js";
+export declare function introduceCaseForDualHeadTailAndReturnRoot(term: IRTerm): IRTerm;