@harmoniclabs/pebble 0.1.10 → 0.2.0

package/dist/IR/IRNodes/IRConst.js

@@ -11,7 +11,7 @@ import { TirDataStructType, TirSoPStructType } from "../../compiler/tir/types/Ti
 import { getListTypeArg } from "../../compiler/tir/types/utils/getListTypeArg.js";
 import { TirTypeParam } from "../../compiler/tir/types/TirTypeParam.js";
 import { constT, isPair, UPLCConst } from "@harmoniclabs/uplc";
-import { TirPairDataT, TirUnConstrDataResultT } from "../../compiler/tir/types/TirNativeType/index.js";
+import { TirBlsG1T, TirBlsG2T, TirMlResultT, TirPairDataT, TirUnConstrDataResultT } from "../../compiler/tir/types/TirNativeType/index.js";
 import { TirBoolT } from "../../compiler/tir/types/TirNativeType/native/bool.js";
 import { TirBytesT } from "../../compiler/tir/types/TirNativeType/native/bytes.js";
 import { TirDataT } from "../../compiler/tir/types/TirNativeType/native/data.js";
@@ -169,6 +169,11 @@ function isValueAssignableToType(value, type) {
     }
     if (type instanceof TirLinearMapEntryT)
         return isIRConstPair(value);
+    // BLS / ML-result values can't appear as constants in user Pebble code
+    if (type instanceof TirBlsG1T
+        || type instanceof TirBlsG2T
+        || type instanceof TirMlResultT)
+        return false;
     const tsEnsureExsaustiveCheck = type;
     return false;
 }
@@ -221,7 +226,10 @@ function serializeIRConstValue(value, type) {
         || type instanceof TirSopOptT
         || type instanceof TirLinearMapEntryT
         || type instanceof TirSoPStructType
-        || type instanceof TirTypeParam)
+        || type instanceof TirTypeParam
+        || type instanceof TirBlsG1T
+        || type instanceof TirBlsG2T
+        || type instanceof TirMlResultT)
         throw new Error("invalid uplc const type");
     const tsEnsureExsaustiveCheck = type;
     throw new Error("unreachable");
@@ -280,7 +288,10 @@ export function tirTypeToUplcType(t) {
         || t instanceof TirFuncT
         || t instanceof TirSopOptT
         || t instanceof TirSoPStructType
-        || t instanceof TirTypeParam)
+        || t instanceof TirTypeParam
+        || t instanceof TirBlsG1T
+        || t instanceof TirBlsG2T
+        || t instanceof TirMlResultT)
         throw new Error("invalid uplc const type");
     const tsEnsureExsaustiveCheck = t;
     throw new Error("tirTypeToUplcType: unreachable");

package/dist/IR/IRNodes/IRNative/index.js

@@ -8,7 +8,7 @@ import { getUnaliased } from "../../../compiler/tir/types/utils/getUnaliased.js"
 import { TirDataStructType } from "../../../compiler/tir/types/TirStructType.js";
 import { TirAliasType } from "../../../compiler/tir/types/TirAliasType.js";
 import { getListTypeArg } from "../../../compiler/tir/types/utils/getListTypeArg.js";
-import { TirPairDataT, TirUnConstrDataResultT } from "../../../compiler/tir/types/TirNativeType/index.js";
+import { TirBlsG1T, TirBlsG2T, TirMlResultT, TirPairDataT, TirUnConstrDataResultT } from "../../../compiler/tir/types/TirNativeType/index.js";
 import { TirBoolT } from "../../../compiler/tir/types/TirNativeType/native/bool.js";
 import { TirBytesT } from "../../../compiler/tir/types/TirNativeType/native/bytes.js";
 import { TirDataT } from "../../../compiler/tir/types/TirNativeType/native/data.js";
@@ -249,6 +249,10 @@ export class IRNative {
             return getEqUnConstr();
         if (type instanceof TirVoidT)
             return getEqVoid();
+        if (type instanceof TirBlsG1T
+            || type instanceof TirBlsG2T
+            || type instanceof TirMlResultT)
+            throw new Error("invalid type for std equality");
         const tsEnsureExsaustiveCheck = type;
         throw new Error("invalid type for std equality");
     }

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
      */
@@ -76,10 +85,16 @@ export interface CompilerOptions {
      **/
     addMarker: boolean;
 }
-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,7 @@
 import { isObject } from "@harmoniclabs/obj-utils";
 import { defaultUplcVersion, UPLCVersion } from "@harmoniclabs/uplc";
+import { COMPILER_VERSION } from "../../version.generated.js";
+export { COMPILER_VERSION };
 export const productionUplcOptimizations = Object.freeze({
     groupApplications: true,
     inlineSingleUse: true,
@@ -99,7 +101,9 @@ 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),

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;
+    }
+}

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

@@ -1,10 +1,12 @@
 import { SourceRange } from "../../Source/SourceRange.js";
-import { LitStrExpr } from "../expr/litteral/LitStrExpr.js";
+import { Identifier } from "../common/Identifier.js";
 import { HasSourceRange } from "../HasSourceRange.js";
 import { BlockStmt } from "./BlockStmt.js";
+import { TestParam } from "./TestParam.js";
 export declare class TestStmt implements HasSourceRange {
-    readonly testName: LitStrExpr | undefined;
+    readonly testName: Identifier;
+    readonly params: TestParam[];
     readonly body: BlockStmt;
     readonly range: SourceRange;
-    constructor(testName: LitStrExpr | undefined, body: BlockStmt, range: SourceRange);
+    constructor(testName: Identifier, params: TestParam[], body: BlockStmt, range: SourceRange);
 }

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

@@ -1,9 +1,11 @@
 export class TestStmt {
     testName;
+    params;
     body;
     range;
-    constructor(testName, body, range) {
+    constructor(testName, params, body, range) {
         this.testName = testName;
+        this.params = params;
         this.body = body;
         this.range = range;
     }

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

@@ -2,11 +2,30 @@ import { SourceRange } from "../../Source/SourceRange.js";
 import { Identifier } from "../common/Identifier.js";
 import { HasSourceRange } from "../HasSourceRange.js";
 import { AstTypeExpr } from "../types/AstTypeExpr.js";
+/**
+ * dotted chain of identifiers used as the RHS of a `using` statement
+ * to refer to a namespace path (e.g. `std.builtins`).
+ */
+export declare class UsingPath implements HasSourceRange {
+    readonly segments: Identifier[];
+    readonly range: SourceRange;
+    constructor(segments: Identifier[], range: SourceRange);
+}
+export type UsingRhs = AstTypeExpr | UsingPath;
+/**
+ * `using { a, b: renamed } = <rhs>;`
+ *
+ * `<rhs>` may be either a struct type expression (existing behavior,
+ * bringing constructors into scope) or a namespace path (new behavior,
+ * destructuring the namespace's exported members into scope).
+ */
 export declare class UsingStmt implements HasSourceRange {
     readonly constructorNames: UsingStmtDeclaredConstructor[];
-    readonly structTypeExpr: AstTypeExpr;
+    readonly rhs: UsingRhs;
     readonly range: SourceRange;
-    constructor(constructorNames: UsingStmtDeclaredConstructor[], structTypeExpr: AstTypeExpr, range: SourceRange);
+    constructor(constructorNames: UsingStmtDeclaredConstructor[], rhs: UsingRhs, range: SourceRange);
+    /** legacy accessor for code paths still expecting `structTypeExpr` */
+    get structTypeExpr(): UsingRhs;
 }
 export declare class UsingStmtDeclaredConstructor implements HasSourceRange {
     readonly constructorName: Identifier;
@@ -14,3 +33,14 @@ export declare class UsingStmtDeclaredConstructor implements HasSourceRange {
     readonly range: SourceRange;
     constructor(constructorName: Identifier, renamedConstructorName: Identifier | undefined, range: SourceRange);
 }
+/**
+ * `using <aliasName> = <rhs>;`
+ *
+ * binds `aliasName` as a local alias for the namespace identified by `rhs`.
+ */
+export declare class UsingAliasStmt implements HasSourceRange {
+    readonly aliasName: Identifier;
+    readonly rhs: UsingPath;
+    readonly range: SourceRange;
+    constructor(aliasName: Identifier, rhs: UsingPath, range: SourceRange);
+}

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

@@ -1,12 +1,33 @@
+/**
+ * dotted chain of identifiers used as the RHS of a `using` statement
+ * to refer to a namespace path (e.g. `std.builtins`).
+ */
+export class UsingPath {
+    segments;
+    range;
+    constructor(segments, range) {
+        this.segments = segments;
+        this.range = range;
+    }
+}
+/**
+ * `using { a, b: renamed } = <rhs>;`
+ *
+ * `<rhs>` may be either a struct type expression (existing behavior,
+ * bringing constructors into scope) or a namespace path (new behavior,
+ * destructuring the namespace's exported members into scope).
+ */
 export class UsingStmt {
     constructorNames;
-    structTypeExpr;
+    rhs;
     range;
-    constructor(constructorNames, structTypeExpr, range) {
+    constructor(constructorNames, rhs, range) {
         this.constructorNames = constructorNames;
-        this.structTypeExpr = structTypeExpr;
+        this.rhs = rhs;
         this.range = range;
     }
+    /** legacy accessor for code paths still expecting `structTypeExpr` */
+    get structTypeExpr() { return this.rhs; }
 }
 export class UsingStmtDeclaredConstructor {
     constructorName;
@@ -18,3 +39,18 @@ export class UsingStmtDeclaredConstructor {
         this.range = range;
     }
 }
+/**
+ * `using <aliasName> = <rhs>;`
+ *
+ * binds `aliasName` as a local alias for the namespace identified by `rhs`.
+ */
+export class UsingAliasStmt {
+    aliasName;
+    rhs;
+    range;
+    constructor(aliasName, rhs, range) {
+        this.aliasName = aliasName;
+        this.rhs = rhs;
+        this.range = range;
+    }
+}

package/dist/ast/nodes/statements/declarations/NamespaceDecl.d.ts

@@ -0,0 +1,21 @@
+import { SourceRange } from "../../../Source/SourceRange.js";
+import { Identifier } from "../../common/Identifier.js";
+import { HasSourceRange } from "../../HasSourceRange.js";
+import { VarStmt } from "../VarStmt.js";
+import { FuncDecl } from "./FuncDecl.js";
+import { InterfaceDecl } from "./InterfaceDecl.js";
+import { PebbleTypeDecl } from "./PebbleTypeDecl.js";
+export type NamespaceMemberStmt = VarStmt | FuncDecl | PebbleTypeDecl | InterfaceDecl | NamespaceDecl;
+export declare function isNamespaceMemberStmt(thing: any): thing is NamespaceMemberStmt;
+export declare class NamespaceMember implements HasSourceRange {
+    readonly isPrivate: boolean;
+    readonly stmt: NamespaceMemberStmt;
+    readonly range: SourceRange;
+    constructor(isPrivate: boolean, stmt: NamespaceMemberStmt, range: SourceRange);
+}
+export declare class NamespaceDecl implements HasSourceRange {
+    readonly name: Identifier;
+    readonly members: NamespaceMember[];
+    readonly range: SourceRange;
+    constructor(name: Identifier, members: NamespaceMember[], range: SourceRange);
+}