@harmoniclabs/pebble 0.1.10 → 0.3.0

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

@@ -1,6 +1,7 @@
 import { TirBoolT, TirIntT } from "../../../compiler/tir/types/TirNativeType/index.js";
 import { equalIrHash } from "../../IRHash.js";
 import { _ir_apps } from "../../IRNodes/IRApp.js";
+import { IRCase } from "../../IRNodes/IRCase.js";
 import { IRConst } from "../../IRNodes/IRConst.js";
 import { IRFunc } from "../../IRNodes/IRFunc.js";
 import { IRHoisted } from "../../IRNodes/IRHoisted.js";
@@ -125,8 +126,14 @@ export function rewriteNativesAppliedToConstantsAndReturnRoot(term) {
                     if (isListLength(eqZeroArgFunc)
                         && eqZeroArgArgs.length === 1) {
                         const listTerm = eqZeroArgArgs[0];
-                        // replace with isNullList
-                        const newTerm = _ir_apps(IRNative.strictChooseList, listTerm, thenArg, elseArg);
+                        // if( list.length() === 0 ) thenArg else elseArg
+                        //   →  case list of cons _h _t -> elseArg ; nil -> thenArg
+                        const dh = Symbol("_h");
+                        const dt = Symbol("_t");
+                        const newTerm = new IRCase(listTerm, [
+                            new IRFunc([dh, dt], elseArg),
+                            thenArg
+                        ]);
                         modifyTermAndPushToReprocess(current, newTerm);
                         continue;
                     }
@@ -137,8 +144,14 @@ export function rewriteNativesAppliedToConstantsAndReturnRoot(term) {
                 else if (isNullList(condFunc)
                     && condArgs.length === 1) {
                     const listTerm = condArgs[0];
-                    // replace with isListLength
-                    const newTerm = _ir_apps(IRNative.strictChooseList, listTerm, thenArg, elseArg);
+                    // if( nullList(list) ) thenArg else elseArg
+                    //   →  case list of cons _h _t -> elseArg ; nil -> thenArg
+                    const dh = Symbol("_h");
+                    const dt = Symbol("_t");
+                    const newTerm = new IRCase(listTerm, [
+                        new IRFunc([dh, dt], elseArg),
+                        thenArg
+                    ]);
                     modifyTermAndPushToReprocess(current, newTerm);
                     continue;
                 } // if( x.isEmpty() )
@@ -227,6 +240,24 @@ export function rewriteNativesAppliedToConstantsAndReturnRoot(term) {
                     continue;
                 }
             }
+            else if (tag === IRNativeTag.strictChooseList
+                && restArgs.length === 2) {
+                // strictChooseList list caseNil caseCons
+                //   →  case list of (λ_h _t → caseCons) | caseNil
+                // IRCase branches are naturally lazy, so wrapping caseNil/
+                // caseCons in delay/force is unnecessary at the call site.
+                const listTerm = fstArg;
+                const caseNil = restArgs[0];
+                const caseCons = restArgs[1];
+                const dh = Symbol("_h");
+                const dt = Symbol("_t");
+                const newTerm = new IRCase(listTerm, [
+                    new IRFunc([dh, dt], caseCons),
+                    caseNil
+                ]);
+                modifyTermAndPushToReprocess(current, newTerm);
+                continue;
+            }
         }
         // only optimizations if first argument is constant after this point
         if (!(fstArg instanceof IRConst)) {
@@ -254,7 +285,7 @@ function isDropList(term) {
             term = term.value;
     }
     return (term instanceof IRNative
-        && term.tag === IRNativeTag._dropList);
+        && term.tag === IRNativeTag.dropList);
 }
 function isId(term) {
     while (term instanceof IRHoisted

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

@@ -0,0 +1,35 @@
+/**
+ * Case-over-Const lowering pass.
+ *
+ * The UPLC `Case` term accepts a constant scrutinee and reinterprets it
+ * as a tag-untagged constructor (bool → 0/1, int N → N, unit → 0,
+ * pair → constr 0 [fst, snd], list → constr 1 [] for `[]` or
+ * constr 0 [head, tail] for cons).
+ *
+ * This pass replaces canonical `strictIfThenElse(cond, then, else)`
+ * sequences with the equivalent `IRCase(cond, [else, then])` form. The
+ * machine resolves bool=false → constr 0, bool=true → constr 1.
+ * This subsumes the strict boolean helpers (`_not`, `_strictAnd`,
+ * `_strictOr`) whose hoisted bodies are themselves `strictIfThenElse`
+ * triple-apps — they get lowered inside their hoisted definitions.
+ *
+ * It also replaces the LAZY pattern emitted by `_ir_lazyIfThenElse`:
+ *
+ *     IRForced( strictIfThenElse cond (delay t) (delay e) )
+ *
+ * — which is how `&&`, `||` and pebble `if/else` are encoded today —
+ * with `IRCase(cond, [e, t])`. Branches under `Case` are naturally
+ * lazy, so the surrounding `force`/`delay` indirection is dropped.
+ *
+ * It also prunes trailing IRError continuations: a missing branch is
+ * semantically equivalent to an evaluation-failure branch, so dropping a
+ * trailing `IRError` reduces script size while preserving meaning.
+ *
+ * NOTE: `getApplicationTerms` sees through both raw `IRApp` chains AND
+ * the case-constr-app encoding produced earlier in `performUplc…`
+ * (i.e. `IRCase(IRConstr(0, [args]), [func])`). We therefore check the
+ * app-pattern *before* the IRCase trailing-error pruning so that a case
+ * that's really a function call gets unwrapped first.
+ */
+import { IRTerm } from "../../IRTerm.js";
+export declare function rewriteToCaseOverConstAndReturnRoot(term: IRTerm): IRTerm;

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

@@ -0,0 +1,169 @@
+/**
+ * Case-over-Const lowering pass.
+ *
+ * The UPLC `Case` term accepts a constant scrutinee and reinterprets it
+ * as a tag-untagged constructor (bool → 0/1, int N → N, unit → 0,
+ * pair → constr 0 [fst, snd], list → constr 1 [] for `[]` or
+ * constr 0 [head, tail] for cons).
+ *
+ * This pass replaces canonical `strictIfThenElse(cond, then, else)`
+ * sequences with the equivalent `IRCase(cond, [else, then])` form. The
+ * machine resolves bool=false → constr 0, bool=true → constr 1.
+ * This subsumes the strict boolean helpers (`_not`, `_strictAnd`,
+ * `_strictOr`) whose hoisted bodies are themselves `strictIfThenElse`
+ * triple-apps — they get lowered inside their hoisted definitions.
+ *
+ * It also replaces the LAZY pattern emitted by `_ir_lazyIfThenElse`:
+ *
+ *     IRForced( strictIfThenElse cond (delay t) (delay e) )
+ *
+ * — which is how `&&`, `||` and pebble `if/else` are encoded today —
+ * with `IRCase(cond, [e, t])`. Branches under `Case` are naturally
+ * lazy, so the surrounding `force`/`delay` indirection is dropped.
+ *
+ * It also prunes trailing IRError continuations: a missing branch is
+ * semantically equivalent to an evaluation-failure branch, so dropping a
+ * trailing `IRError` reduces script size while preserving meaning.
+ *
+ * NOTE: `getApplicationTerms` sees through both raw `IRApp` chains AND
+ * the case-constr-app encoding produced earlier in `performUplc…`
+ * (i.e. `IRCase(IRConstr(0, [args]), [func])`). We therefore check the
+ * app-pattern *before* the IRCase trailing-error pruning so that a case
+ * that's really a function call gets unwrapped first.
+ */
+import { IRCase } from "../../IRNodes/IRCase.js";
+import { IRDelayed } from "../../IRNodes/IRDelayed.js";
+import { IRError } from "../../IRNodes/IRError.js";
+import { IRForced } from "../../IRNodes/IRForced.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 { IRFunc } from "../../IRNodes/IRFunc.js";
+import { _modifyChildFromTo } from "../_internal/_modifyChildFromTo.js";
+import { getApplicationTerms } from "../utils/getApplicationTerms.js";
+/**
+ * `_makeAllNegativeNativesHoisted` wraps every `IRNative` reference in
+ * an `IRHoisted` (despite the name, it touches positive tags too), and
+ * subsequent sharing passes may further wrap in `IRLetted`. Unwrap so
+ * the pattern detector can see the underlying native tag.
+ */
+function unwrapToNative(t) {
+    while (t instanceof IRHoisted)
+        t = t.hoisted;
+    while (t instanceof IRLetted)
+        t = t.value;
+    return t;
+}
+export function rewriteToCaseOverConstAndReturnRoot(term) {
+    const stack = [term];
+    function modifyTermAndPushToReprocess(current, newTerm) {
+        const parent = current.parent;
+        if (parent) {
+            _modifyChildFromTo(parent, current, newTerm);
+        }
+        else {
+            term = newTerm;
+            term.parent = undefined;
+        }
+        stack.unshift(newTerm);
+    }
+    while (stack.length > 0) {
+        const current = stack.pop();
+        // LAZY pattern emitted by `_ir_lazyIfThenElse`:
+        //   force( strictIfThenElse cond (delay t) (delay e) )
+        // Rewrite to a bare `case cond [e, t]` (Case branches are lazy).
+        if (current instanceof IRForced) {
+            const innerApp = getApplicationTerms(current.forced);
+            const innerFunc = innerApp ? unwrapToNative(innerApp.func) : undefined;
+            if (innerApp
+                && innerFunc instanceof IRNative
+                && innerFunc.tag === IRNativeTag.strictIfThenElse
+                && innerApp.args.length === 3
+                && innerApp.args[1] instanceof IRDelayed
+                && innerApp.args[2] instanceof IRDelayed) {
+                const cond = innerApp.args[0];
+                const tBranch = innerApp.args[1].delayed;
+                const eBranch = innerApp.args[2].delayed;
+                const newTerm = new IRCase(cond, [eBranch, tBranch]);
+                modifyTermAndPushToReprocess(current, newTerm);
+                continue;
+            }
+            // `IRForced(IRCase(s, [b0, b1, …]))` where every branch is
+            // either `IRDelayed(v)` or `IRFunc(params, IRDelayed(v))` can
+            // be simplified by stripping the force/delay pair: case
+            // branches are naturally lazy in UPLC `case`. The
+            // wrap typically comes from `_ir_lazyIfThenElse` lowering an
+            // `if/else` whose condition then got rewritten to a list-case
+            // (e.g. `if(nullList(L)) ...`) — the outer force is left
+            // dangling around the resulting IRCase.
+            if (current.forced instanceof IRCase) {
+                const caseTerm = current.forced;
+                const conts = caseTerm.continuations;
+                const stripped = [];
+                let allOk = true;
+                for (let i = 0; i < conts.length; i++) {
+                    const c = conts[i];
+                    if (c instanceof IRDelayed) {
+                        stripped.push(c.delayed);
+                    }
+                    else if (c instanceof IRFunc
+                        && c.body instanceof IRDelayed) {
+                        stripped.push(new IRFunc(c.params.slice(), c.body.delayed));
+                    }
+                    else {
+                        allOk = false;
+                        break;
+                    }
+                }
+                if (allOk) {
+                    const newCase = new IRCase(caseTerm.constrTerm.clone(), stripped);
+                    modifyTermAndPushToReprocess(current, newCase);
+                    continue;
+                }
+            }
+            stack.unshift(...current.children());
+            continue;
+        }
+        // Application-pattern rewrites (raw IRApp chain OR case-constr-app
+        // encoding produced by `performUplcOptimizationsAndReturnRoot`).
+        const appTerms = getApplicationTerms(current);
+        if (appTerms) {
+            const { func, args } = appTerms;
+            const unwrappedFunc = unwrapToNative(func);
+            // strictIfThenElse cond then else  →  case cond [else, then]
+            if (unwrappedFunc instanceof IRNative
+                && unwrappedFunc.tag === IRNativeTag.strictIfThenElse
+                && args.length === 3) {
+                const [cond, thenBranch, elseBranch] = args;
+                const newTerm = new IRCase(cond, [elseBranch, thenBranch]);
+                modifyTermAndPushToReprocess(current, newTerm);
+                continue;
+            }
+            // No app-pattern match — but if the node is itself an IRCase
+            // (a case-constr-app encoding), we still want trailing-error
+            // pruning on the original case, so don't `continue` yet.
+            if (!(current instanceof IRCase)) {
+                stack.unshift(...current.children());
+                continue;
+            }
+        }
+        // Trailing-error pruning on any IRCase node we encounter.
+        if (current instanceof IRCase) {
+            const conts = current.continuations;
+            let lastNonError = conts.length;
+            while (lastNonError > 0 && conts[lastNonError - 1] instanceof IRError) {
+                lastNonError--;
+            }
+            if (lastNonError < conts.length && lastNonError > 0) {
+                const pruned = new IRCase(current.constrTerm.clone(), Array.from({ length: lastNonError }, (_, i) => conts[i].clone()));
+                modifyTermAndPushToReprocess(current, pruned);
+                continue;
+            }
+            stack.unshift(...current.children());
+            continue;
+        }
+        stack.unshift(...current.children());
+    }
+    return term;
+}

package/dist/IR/tree_utils/_ir_caseList.d.ts

@@ -0,0 +1,15 @@
+import { IRCase } from "../IRNodes/IRCase.js";
+import type { IRTerm } from "../IRTerm.js";
+/**
+ * case list of
+ *   h::t -> caseCons   (h, t are bound only if `consParams` is provided)
+ *   []   -> caseNil
+ *
+ * Lowers to UPLC `Case`. Branches are naturally lazy, so callers
+ * should pass plain (un-delayed) expressions — no `force` is needed around
+ * the result.
+ */
+export declare function _ir_caseList(listTerm: IRTerm, caseNil: IRTerm, caseCons: IRTerm, consParams?: {
+    head: symbol;
+    tail: symbol;
+}): IRCase;

package/dist/IR/tree_utils/_ir_caseList.js

@@ -0,0 +1,19 @@
+import { IRCase } from "../IRNodes/IRCase.js";
+import { IRFunc } from "../IRNodes/IRFunc.js";
+/**
+ * case list of
+ *   h::t -> caseCons   (h, t are bound only if `consParams` is provided)
+ *   []   -> caseNil
+ *
+ * Lowers to UPLC `Case`. Branches are naturally lazy, so callers
+ * should pass plain (un-delayed) expressions — no `force` is needed around
+ * the result.
+ */
+export function _ir_caseList(listTerm, caseNil, caseCons, consParams) {
+    const h = consParams?.head ?? Symbol("_caseList_h");
+    const t = consParams?.tail ?? Symbol("_caseList_t");
+    return new IRCase(listTerm, [
+        new IRFunc([h, t], caseCons),
+        caseNil
+    ]);
+}

package/dist/IR/tree_utils/bytesToHex.d.ts

@@ -0,0 +1,8 @@
+import { IRHoisted } from "../IRNodes/IRHoisted.js";
+/**
+ * Hoisted IR term: `bytes -> bytes`
+ *
+ * Converts a bytestring to its lowercase hex (`0-9a-f`) UTF-8 encoding.
+ * 1-byte input becomes 2 bytes; 32-byte input (e.g. a hash) becomes 64 bytes.
+ */
+export declare const hoisted_bytesToHex: IRHoisted;

package/dist/IR/tree_utils/bytesToHex.js

@@ -0,0 +1,69 @@
+import { _ir_apps } from "../IRNodes/IRApp.js";
+import { IRConst } from "../IRNodes/IRConst.js";
+import { IRFunc } from "../IRNodes/IRFunc.js";
+import { IRHoisted } from "../IRNodes/IRHoisted.js";
+import { IRNative } from "../IRNodes/IRNative/index.js";
+import { IRRecursive } from "../IRNodes/IRRecursive.js";
+import { IRSelfCall } from "../IRNodes/IRSelfCall.js";
+import { IRVar } from "../IRNodes/IRVar.js";
+import { _ir_lazyIfThenElse } from "./_ir_lazyIfThenElse.js";
+// hexChar(n) = if n < 10 then n + 48 else n + 87   // '0' = 48, 'a' = 97 = 87+10
+// goAt(bs, len, i) = if i >= len then ""
+//                    else cons(hexChar(b/16), cons(hexChar(b%16), goAt(bs, len, i+1)))
+//                    where b = indexByteString(bs, i)
+// bytesToHex(bs) = goAt(bs, lengthOfByteString(bs), 0)
+const emptyBs = IRConst.bytes(new Uint8Array(0));
+const hexCharSym = Symbol("hexChar_n");
+const hoisted_hexChar = new IRHoisted(new IRFunc([hexCharSym], _ir_lazyIfThenElse(
+// n < 10
+_ir_apps(IRNative.lessThanInteger, new IRVar(hexCharSym), IRConst.int(10)), 
+// then n + 48
+_ir_apps(IRNative.addInteger, new IRVar(hexCharSym), IRConst.int(48)), 
+// else n + 87
+_ir_apps(IRNative.addInteger, new IRVar(hexCharSym), IRConst.int(87)))));
+hoisted_hexChar.hash;
+// Iteration over the bytes of `bs` from offset 0 to len (passed in as args).
+// We avoid re-computing length on each step.
+//
+//   self(bs, len, i) =
+//       if i >= len then ""
+//       else
+//           let b = indexByteString(bs, i)
+//           cons( hexChar( quotient(b, 16) ),
+//             cons( hexChar( mod(b, 16) ),
+//               self(bs, len, i + 1)))
+const self_sym = Symbol("bytesToHex_self");
+const bs_sym = Symbol("bytesToHex_bs");
+const len_sym = Symbol("bytesToHex_len");
+const i_sym = Symbol("bytesToHex_i");
+const b_sym = Symbol("bytesToHex_b");
+const hoisted_bytesToHex_loop = new IRHoisted(new IRRecursive(self_sym, new IRFunc([bs_sym, len_sym, i_sym], _ir_lazyIfThenElse(
+// i >= len  <=> NOT (i < len)
+_ir_apps(IRNative.lessThanInteger, new IRVar(i_sym), new IRVar(len_sym)), 
+// then: process byte at i and recurse
+(() => {
+    // let b = indexByteString(bs, i)
+    const b = _ir_apps(IRNative.indexByteString, new IRVar(bs_sym), new IRVar(i_sym));
+    // The IR currently doesn't have a direct `let` form here; we
+    // emit b twice. The optimiser hoists common sub-expressions
+    // when they're cheap; for the byte-at-index access this is
+    // acceptable (two cheap builtin calls each iteration).
+    const high = _ir_apps(hoisted_hexChar.clone(), _ir_apps(IRNative.quotientInteger, b, IRConst.int(16)));
+    const lowB = _ir_apps(IRNative.indexByteString, new IRVar(bs_sym), new IRVar(i_sym));
+    const low = _ir_apps(hoisted_hexChar.clone(), _ir_apps(IRNative.modInteger, lowB, IRConst.int(16)));
+    return _ir_apps(IRNative.consByteString, high, _ir_apps(IRNative.consByteString, low, 
+    // self(bs, len, i + 1)
+    _ir_apps(new IRSelfCall(self_sym), new IRVar(bs_sym), new IRVar(len_sym), _ir_apps(IRNative.addInteger, new IRVar(i_sym), IRConst.int(1)))));
+})(), 
+// else: empty bytes
+emptyBs.clone()))));
+hoisted_bytesToHex_loop.hash;
+const outer_bs_sym = Symbol("bytesToHex_outer_bs");
+/**
+ * Hoisted IR term: `bytes -> bytes`
+ *
+ * Converts a bytestring to its lowercase hex (`0-9a-f`) UTF-8 encoding.
+ * 1-byte input becomes 2 bytes; 32-byte input (e.g. a hash) becomes 64 bytes.
+ */
+export const hoisted_bytesToHex = new IRHoisted(new IRFunc([outer_bs_sym], _ir_apps(hoisted_bytesToHex_loop.clone(), new IRVar(outer_bs_sym), _ir_apps(IRNative.lengthOfByteString, new IRVar(outer_bs_sym)), IRConst.int(0))));
+hoisted_bytesToHex.hash;

package/dist/ast/nodes/expr/functions/FuncExpr.d.ts

@@ -3,20 +3,34 @@ import { SourceRange } from "../../../Source/SourceRange.js";
 import { Identifier } from "../../common/Identifier.js";
 import { HasSourceRange } from "../../HasSourceRange.js";
 import { BlockStmt } from "../../statements/BlockStmt.js";
+import { AstTypeExpr } from "../../types/AstTypeExpr.js";
 import { AstFuncType } from "../../types/AstNativeTypeExpr.js";
 import { PebbleExpr } from "../PebbleExpr.js";
 import { ArrowKind } from "./ArrowKind.js";
+/**
+ * A declared type parameter on a function declaration. Optionally constrained
+ * to an interface via `<T implements I>` syntax — when set, every concrete
+ * instantiation of the generic function must provide a type that implements
+ * `I`, and the compiler threads an implicit `I`-dictionary argument through
+ * the function body (see `monomorphizeGeneric`).
+ */
+export declare class TypeParamDecl implements HasSourceRange {
+    readonly name: Identifier;
+    readonly constraint: AstTypeExpr | undefined;
+    readonly range: SourceRange;
+    constructor(name: Identifier, constraint: AstTypeExpr | undefined, range: SourceRange);
+}
 /**
  * a litteral function value
 **/
 export declare class FuncExpr implements HasSourceRange {
     readonly name: Identifier;
     readonly flags: CommonFlags;
-    readonly typeParams: Identifier[];
+    readonly typeParams: TypeParamDecl[];
     readonly signature: AstFuncType;
     body: BlockStmt | PebbleExpr;
     readonly arrowKind: ArrowKind;
     readonly range: SourceRange;
-    constructor(name: Identifier, flags: CommonFlags, typeParams: Identifier[], signature: AstFuncType, body: BlockStmt | PebbleExpr, arrowKind: ArrowKind, range: SourceRange);
+    constructor(name: Identifier, flags: CommonFlags, typeParams: TypeParamDecl[], signature: AstFuncType, body: BlockStmt | PebbleExpr, arrowKind: ArrowKind, range: SourceRange);
     bodyBlockStmt(): BlockStmt;
 }

package/dist/ast/nodes/expr/functions/FuncExpr.js

@@ -1,5 +1,22 @@
 import { BlockStmt } from "../../statements/BlockStmt.js";
 import { ReturnStmt } from "../../statements/ReturnStmt.js";
+/**
+ * A declared type parameter on a function declaration. Optionally constrained
+ * to an interface via `<T implements I>` syntax — when set, every concrete
+ * instantiation of the generic function must provide a type that implements
+ * `I`, and the compiler threads an implicit `I`-dictionary argument through
+ * the function body (see `monomorphizeGeneric`).
+ */
+export class TypeParamDecl {
+    name;
+    constraint;
+    range;
+    constructor(name, constraint, range) {
+        this.name = name;
+        this.constraint = constraint;
+        this.range = range;
+    }
+}
 /**
  * a litteral function value
 **/

package/dist/ast/nodes/expr/litteral/LitteralExpr.d.ts

@@ -11,5 +11,6 @@ import { LitThisExpr } from "./LitThisExpr.js";
 import { LitTrueExpr } from "./LitTrueExpr.js";
 import { LitUndefExpr } from "./LitUndefExpr.js";
 import { LitVoidExpr } from "./LitVoidExpr.js";
-export type LitteralExpr = LitVoidExpr | LitUndefExpr | LitTrueExpr | LitFalseExpr | LitThisExpr | LitContextExpr | LitArrExpr | LitObjExpr | LitNamedObjExpr | LitStrExpr | LitIntExpr | LitHexBytesExpr | LitFailExpr;
+import { TemplateStrExpr } from "./TemplateStrExpr.js";
+export type LitteralExpr = LitVoidExpr | LitUndefExpr | LitTrueExpr | LitFalseExpr | LitThisExpr | LitContextExpr | LitArrExpr | LitObjExpr | LitNamedObjExpr | LitStrExpr | TemplateStrExpr | LitIntExpr | LitHexBytesExpr | LitFailExpr;
 export declare function isLitteralExpr(thing: any): thing is LitteralExpr;

package/dist/ast/nodes/expr/litteral/LitteralExpr.js

@@ -11,6 +11,7 @@ import { LitThisExpr } from "./LitThisExpr.js";
 import { LitTrueExpr } from "./LitTrueExpr.js";
 import { LitUndefExpr } from "./LitUndefExpr.js";
 import { LitVoidExpr } from "./LitVoidExpr.js";
+import { TemplateStrExpr } from "./TemplateStrExpr.js";
 export function isLitteralExpr(thing) {
     return (thing instanceof LitVoidExpr
         || thing instanceof LitUndefExpr
@@ -22,6 +23,7 @@ export function isLitteralExpr(thing) {
         || thing instanceof LitObjExpr
         || thing instanceof LitNamedObjExpr
         || thing instanceof LitStrExpr
+        || thing instanceof TemplateStrExpr
         || thing instanceof LitIntExpr
         || thing instanceof LitHexBytesExpr
         || thing instanceof LitFailExpr);

package/dist/ast/nodes/expr/litteral/TemplateStrExpr.d.ts

@@ -0,0 +1,30 @@
+import { SourceRange } from "../../../Source/SourceRange.js";
+import { HasSourceRange } from "../../HasSourceRange.js";
+import { PebbleExpr } from "../PebbleExpr.js";
+/**
+ * A template string literal: backtick-delimited text with `${expr}`
+ * interpolation slots — e.g. `` `hello ${name}, count is ${n}` ``.
+ *
+ * Stored as alternating literal text fragments and interpolated expressions.
+ * For a template with N interpolations, `parts.length === N + 1`.
+ *
+ * Compilation produces a chain of UTF-8 byte concatenations:
+ *
+ *   parts[0]_bytes
+ *     ++ show-or-passthrough( exprs[0] )
+ *     ++ parts[1]_bytes
+ *     ++ show-or-passthrough( exprs[1] )
+ *     ++ ...
+ *     ++ parts[N]_bytes
+ *
+ * For each interpolated expression: if its type is `bytes` it is passed
+ * through verbatim (assumed to already be valid UTF-8 — same convention as
+ * `trace`); otherwise the compiler implicitly inserts `.show()` via the
+ * built-in Show interface dispatch.
+ */
+export declare class TemplateStrExpr implements HasSourceRange {
+    readonly parts: string[];
+    readonly exprs: PebbleExpr[];
+    readonly range: SourceRange;
+    constructor(parts: string[], exprs: PebbleExpr[], range: SourceRange);
+}

package/dist/ast/nodes/expr/litteral/TemplateStrExpr.js

@@ -0,0 +1,35 @@
+/**
+ * A template string literal: backtick-delimited text with `${expr}`
+ * interpolation slots — e.g. `` `hello ${name}, count is ${n}` ``.
+ *
+ * Stored as alternating literal text fragments and interpolated expressions.
+ * For a template with N interpolations, `parts.length === N + 1`.
+ *
+ * Compilation produces a chain of UTF-8 byte concatenations:
+ *
+ *   parts[0]_bytes
+ *     ++ show-or-passthrough( exprs[0] )
+ *     ++ parts[1]_bytes
+ *     ++ show-or-passthrough( exprs[1] )
+ *     ++ ...
+ *     ++ parts[N]_bytes
+ *
+ * For each interpolated expression: if its type is `bytes` it is passed
+ * through verbatim (assumed to already be valid UTF-8 — same convention as
+ * `trace`); otherwise the compiler implicitly inserts `.show()` via the
+ * built-in Show interface dispatch.
+ */
+export class TemplateStrExpr {
+    parts;
+    exprs;
+    range;
+    constructor(parts, exprs, range) {
+        this.parts = parts;
+        this.exprs = exprs;
+        this.range = range;
+        if (parts.length !== exprs.length + 1) {
+            throw new Error(`TemplateStrExpr: parts.length (${parts.length}) must equal ` +
+                `exprs.length + 1 (${exprs.length + 1})`);
+        }
+    }
+}

package/dist/ast/nodes/statements/ExportStmt.d.ts

@@ -1,13 +1,13 @@
 import { SourceRange } from "../../Source/SourceRange.js";
 import { HasSourceRange } from "../HasSourceRange.js";
-import { BodyStmt } from "./PebbleStmt.js";
+import { BodyStmt, TopLevelStmt } from "./PebbleStmt.js";
 /**
  * ```ts
  * export <PebbleStmt>
  * ```
  */
 export declare class ExportStmt implements HasSourceRange {
-    readonly stmt: BodyStmt;
+    readonly stmt: BodyStmt | TopLevelStmt;
     readonly range: SourceRange;
-    constructor(stmt: BodyStmt, range: SourceRange);
+    constructor(stmt: BodyStmt | TopLevelStmt, range: SourceRange);
 }

package/dist/ast/nodes/statements/PebbleStmt.d.ts

@@ -19,13 +19,14 @@ import { TestStmt } from "./TestStmt.js";
 import { VarStmt } from "./VarStmt.js";
 import { WhileStmt } from "./WhileStmt.js";
 import { AssignmentStmt } from "./AssignmentStmt.js";
-import { UsingStmt } from "./UsingStmt.js";
+import { UsingAliasStmt, UsingStmt } from "./UsingStmt.js";
 import { FuncDecl } from "./declarations/FuncDecl.js";
 import { ExportStmt } from "./ExportStmt.js";
 import { InterfaceDecl } from "./declarations/InterfaceDecl.js";
 import { ContractDecl } from "./declarations/ContractDecl.js";
+import { NamespaceDecl } from "./declarations/NamespaceDecl.js";
 import { TraceStmt } from "./TraceStmt.js";
-export type TopLevelStmt = EmptyStmt | VarStmt | PebbleTypeDecl | InterfaceDecl | FuncDecl | TestStmt | ExportStmt | ExportStarStmt | ExportImportStmt | ImportStmt | ImportStarStmt | TypeImplementsStmt | UsingStmt | ContractDecl;
+export type TopLevelStmt = EmptyStmt | VarStmt | PebbleTypeDecl | InterfaceDecl | FuncDecl | TestStmt | ExportStmt | ExportStarStmt | ExportImportStmt | ImportStmt | ImportStarStmt | TypeImplementsStmt | UsingStmt | UsingAliasStmt | NamespaceDecl | ContractDecl;
 export declare function isTopLevelStmt(stmt: any): stmt is TopLevelStmt;
-export type BodyStmt = IfStmt | VarStmt | ForStmt | ForOfStmt | WhileStmt | ReturnStmt | BlockStmt | BreakStmt | ContinueStmt | EmptyStmt | FailStmt | AssertStmt | TraceStmt | MatchStmt | AssignmentStmt | UsingStmt;
+export type BodyStmt = IfStmt | VarStmt | ForStmt | ForOfStmt | WhileStmt | ReturnStmt | BlockStmt | BreakStmt | ContinueStmt | EmptyStmt | FailStmt | AssertStmt | TraceStmt | MatchStmt | AssignmentStmt | UsingStmt | UsingAliasStmt;
 export declare function isBodyStmt(stmt: any): stmt is BodyStmt;

package/dist/ast/nodes/statements/PebbleStmt.js

@@ -22,10 +22,11 @@ import { WhileStmt } from "./WhileStmt.js";
 import { isAssignmentStmt } from "./AssignmentStmt.js";
 import { IncrStmt } from "./IncrStmt.js";
 import { DecrStmt } from "./DecrStmt.js";
-import { UsingStmt } from "./UsingStmt.js";
+import { UsingAliasStmt, UsingStmt } from "./UsingStmt.js";
 import { FuncDecl } from "./declarations/FuncDecl.js";
 import { ExportStmt } from "./ExportStmt.js";
 import { ContractDecl } from "./declarations/ContractDecl.js";
+import { NamespaceDecl } from "./declarations/NamespaceDecl.js";
 import { TraceStmt } from "./TraceStmt.js";
 export function isTopLevelStmt(stmt) {
     return (stmt instanceof EmptyStmt
@@ -40,6 +41,8 @@ export function isTopLevelStmt(stmt) {
         || stmt instanceof ImportStarStmt
         || stmt instanceof TypeImplementsStmt
         || stmt instanceof UsingStmt
+        || stmt instanceof UsingAliasStmt
+        || stmt instanceof NamespaceDecl
         || stmt instanceof ContractDecl);
 }
 export function isBodyStmt(stmt) {
@@ -62,5 +65,6 @@ export function isBodyStmt(stmt) {
         // || stmt instanceof ExprStmt
         || stmt instanceof IncrStmt
         || stmt instanceof DecrStmt
-        || stmt instanceof UsingStmt);
+        || stmt instanceof UsingStmt
+        || stmt instanceof UsingAliasStmt);
 }

package/dist/ast/nodes/statements/TestParam.d.ts

@@ -0,0 +1,18 @@
+import { SourceRange } from "../../Source/SourceRange.js";
+import { Identifier } from "../common/Identifier.js";
+import { PebbleExpr } from "../expr/PebbleExpr.js";
+import { AstTypeExpr } from "../types/AstTypeExpr.js";
+import { HasSourceRange } from "../HasSourceRange.js";
+/**
+ * A parameter of a `test` declaration: `<name>: <type> ( via <expr> )?`.
+ *
+ * This is intentionally a separate node from `SimpleVarDecl` / `VarDecl` so the
+ * `via` keyword cannot leak into function/method/contract parameter grammar.
+ */
+export declare class TestParam implements HasSourceRange {
+    readonly name: Identifier;
+    readonly type: AstTypeExpr;
+    readonly viaExpr: PebbleExpr | undefined;
+    readonly range: SourceRange;
+    constructor(name: Identifier, type: AstTypeExpr, viaExpr: PebbleExpr | undefined, range: SourceRange);
+}

package/dist/ast/nodes/statements/TestParam.js

@@ -0,0 +1,18 @@
+/**
+ * A parameter of a `test` declaration: `<name>: <type> ( via <expr> )?`.
+ *
+ * This is intentionally a separate node from `SimpleVarDecl` / `VarDecl` so the
+ * `via` keyword cannot leak into function/method/contract parameter grammar.
+ */
+export class TestParam {
+    name;
+    type;
+    viaExpr;
+    range;
+    constructor(name, type, viaExpr, range) {
+        this.name = name;
+        this.type = type;
+        this.viaExpr = viaExpr;
+        this.range = range;
+    }
+}