@harmoniclabs/pebble 0.2.0 → 0.3.1

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

@@ -84,6 +84,18 @@ 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";
 }
 /**
  * Option templates intentionally omit `compilerVersion` — every caller must

package/dist/IR/toUPLC/CompilerOptions.js

@@ -1,6 +1,7 @@
 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,
@@ -39,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,
@@ -77,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
@@ -107,6 +111,7 @@ export function completeCompilerOptions(options, complete = defaultOptions) {
         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;

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

@@ -0,0 +1,169 @@
+/**
+ * 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 { IRApp } from "../../IRNodes/IRApp.js";
+import { IRCase } from "../../IRNodes/IRCase.js";
+import { IRError } from "../../IRNodes/IRError.js";
+import { IRFunc } from "../../IRNodes/IRFunc.js";
+import { IRHoisted } from "../../IRNodes/IRHoisted.js";
+import { IRLetted } from "../../IRNodes/IRLetted.js";
+import { IRNative } from "../../IRNodes/IRNative/index.js";
+import { IRNativeTag } from "../../IRNodes/IRNative/IRNativeTag.js";
+import { IRRecursive } from "../../IRNodes/IRRecursive.js";
+import { IRVar } from "../../IRNodes/IRVar.js";
+import { _modifyChildFromTo } from "../_internal/_modifyChildFromTo.js";
+function unwrap(t) {
+    while (t instanceof IRHoisted)
+        t = t.hoisted;
+    while (t instanceof IRLetted)
+        t = t.value;
+    return t;
+}
+export function introduceCaseForDualHeadTailAndReturnRoot(term) {
+    processNode(term);
+    return term;
+}
+function processNode(node) {
+    // Post-order: recurse into children first, then process this node.
+    for (const child of node.children())
+        processNode(child);
+    if (node instanceof IRFunc) {
+        // Avoid wrapping case-cons branches that the previous pass already
+        // optimized: if `node` is the cons continuation of an outer
+        // `IRCase(IRVar(L), [node, ...])`, then head(L)/tail(L) were
+        // already substituted; if any dual remains it's for a *different*
+        // list L', which we handle normally.
+        tryWrap(node);
+    }
+}
+function tryWrap(fn) {
+    while (true) {
+        const choice = findFirstDualHeadTailList(fn.body, new Set(fn.params));
+        if (choice === undefined)
+            return;
+        const listSym = choice;
+        const desc = listSym.description ?? "L";
+        const hSym = Symbol("h_" + desc);
+        const tSym = Symbol("t_" + desc);
+        // Substitute head(L)/tail(L) inside the current body (won't descend
+        // into nested scopes that re-bind L, h, or t — but we just minted
+        // h/t so they don't collide with anything).
+        substituteHeadTailInBody(fn.body, listSym, hSym, tSym);
+        // Wrap.
+        const oldBody = fn.body;
+        const consFn = new IRFunc([hSym, tSym], oldBody);
+        const wrapped = new IRCase(new IRVar(listSym), [consFn, new IRError()]);
+        fn.body = wrapped;
+    }
+}
+/**
+ * Scan `root` for free `headList(L)`/`tailList(L)` uses where `L` is NOT
+ * shadowed by an enclosing nested IRFunc/IRRecursive within `root`. Returns
+ * the first list symbol with at least one head AND one tail use.
+ */
+function findFirstDualHeadTailList(root, boundInOuterFunc) {
+    const heads = new Set();
+    const tails = new Set();
+    function walk(node, locallyBound) {
+        if (node instanceof IRFunc) {
+            const next = new Set(locallyBound);
+            for (const p of node.params)
+                next.add(p);
+            walk(node.body, next);
+            return;
+        }
+        if (node instanceof IRRecursive) {
+            const next = new Set(locallyBound);
+            next.add(node.name);
+            walk(node.body, next);
+            return;
+        }
+        if (node instanceof IRApp) {
+            const fn = unwrap(node.fn);
+            const arg = node.arg;
+            if (fn instanceof IRNative
+                && arg instanceof IRVar
+                && !locallyBound.has(arg.name)
+                && (fn.tag === IRNativeTag.headList
+                    || fn.tag === IRNativeTag.tailList)) {
+                (fn.tag === IRNativeTag.headList ? heads : tails).add(arg.name);
+                // do not descend further — this is a leaf for our purposes
+                return;
+            }
+            // generic descent
+        }
+        for (const c of node.children())
+            walk(c, locallyBound);
+    }
+    walk(root, boundInOuterFunc);
+    for (const sym of heads) {
+        if (tails.has(sym))
+            return sym;
+    }
+    return undefined;
+}
+/**
+ * In-place: replace every `IRApp(unwrap=headList, IRVar(L))` /
+ * `IRApp(unwrap=tailList, IRVar(L))` inside `root` with `IRVar(h)` /
+ * `IRVar(t)`. Stops descending into any nested IRFunc/IRRecursive that
+ * shadows `L`, `h`, or `t`.
+ */
+function substituteHeadTailInBody(root, listSym, hSym, tSym) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const t = stack.pop();
+        if (t instanceof IRFunc || t instanceof IRRecursive) {
+            const params = t instanceof IRFunc ? t.params : [t.name];
+            if (params.includes(listSym)
+                || params.includes(hSym)
+                || params.includes(tSym))
+                continue;
+        }
+        if (t instanceof IRApp) {
+            const fn = unwrap(t.fn);
+            const arg = t.arg;
+            if (fn instanceof IRNative
+                && arg instanceof IRVar
+                && arg.name === listSym
+                && (fn.tag === IRNativeTag.headList || fn.tag === IRNativeTag.tailList)) {
+                const newSym = fn.tag === IRNativeTag.headList ? hSym : tSym;
+                const parent = t.parent;
+                if (parent !== undefined) {
+                    _modifyChildFromTo(parent, t, new IRVar(newSym));
+                }
+                continue;
+            }
+        }
+        stack.push(...t.children());
+    }
+}

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

@@ -1,3 +1,2 @@
 import { IRTerm } from "../../IRTerm.js";
-export declare function __unsafe_clear_hoisted_cache(): void;
 export declare function replaceHoistedWithLetted(term: IRTerm): void;