@harmoniclabs/pebble 0.1.10 → 0.2.0

package/dist/compiler/AstCompiler/internal/exprs/_compilePropAccessExpr.js

@@ -1,13 +1,17 @@
 import { OptionalPropAccessExpr, NonNullPropAccessExpr, DotPropAccessExpr } from "../../../../ast/nodes/expr/PropAccessExpr.js";
 import { NonNullExpr } from "../../../../ast/nodes/expr/unary/NonNullExpr.js";
 import { DiagnosticCode } from "../../../../diagnostics/diagnosticMessages.generated.js";
+import { TirCallExpr } from "../../../tir/expressions/TirCallExpr.js";
 import { TirCaseExpr, TirCaseMatcher } from "../../../tir/expressions/TirCaseExpr.js";
+import { TirNativeFunc } from "../../../tir/expressions/TirNativeFunc.js";
 import { TirPropAccessExpr } from "../../../tir/expressions/TirPropAccessExpr.js";
 import { TirVariableAccessExpr } from "../../../tir/expressions/TirVariableAccessExpr.js";
 import { TirNamedDeconstructVarDecl } from "../../../tir/statements/TirVarDecl/TirNamedDeconstructVarDecl.js";
 import { TirSimpleVarDecl } from "../../../tir/statements/TirVarDecl/TirSimpleVarDecl.js";
+import { TirUnConstrDataResultT } from "../../../tir/types/TirNativeType/index.js";
 import { getOptTypeArg } from "../../../tir/types/utils/getOptTypeArg.js";
 import { getPropAccessReturnType } from "../../utils/getPropAccessReturnType.js";
+import { tryResolveNamespaceChain } from "../../utils/resolveNamespaceChain.js";
 import { _compileExpr } from "./_compileExpr.js";
 import { _compileNonNullExpr } from "./_compileNonNullExpr.js";
 import { TirLitNamedObjExpr } from "../../../tir/expressions/litteral/TirLitNamedObjExpr.js";
@@ -91,10 +95,34 @@ export function _compileNonNullPropAccessExpr(ctx, expr, _typeHint) {
     return _compileDotPropAccessExpr(ctx, new DotPropAccessExpr(nonNullObjExpr, expr.prop, expr.range), _typeHint);
 }
 export function _compileDotPropAccessExpr(ctx, expr, _typeHint) {
+    // if the LHS is a (chain of) identifier(s) rooted at a namespace, resolve
+    // the entire dotted chain through namespaces.
+    const nsRes = tryResolveNamespaceChain(ctx, expr);
+    if (nsRes) {
+        if (nsRes.kind === "value")
+            return nsRes.expr;
+        if (nsRes.kind === "namespace")
+            return ctx.error(DiagnosticCode.Namespace_path_is_incomplete_expected_a_value_type_function_or_interface, expr.range);
+        // "incomplete" — diagnostic already emitted
+        return undefined;
+    }
     const objExpr = _compileExpr(ctx, expr.object, undefined);
     if (!objExpr)
         return undefined;
     const objType = objExpr.type;
+    // RawConstr (TirUnConstrDataResultT) field access lowers directly to
+    // fstPair / sndPair on the underlying pair(int, list(data)).
+    if (objType instanceof TirUnConstrDataResultT) {
+        if (expr.prop.text === "index") {
+            const fn = TirNativeFunc.unConstrDataResultIndex;
+            return new TirCallExpr(fn, [objExpr], fn.type.returnType, expr.range);
+        }
+        if (expr.prop.text === "fields") {
+            const fn = TirNativeFunc.unConstrDataResultFields;
+            return new TirCallExpr(fn, [objExpr], fn.type.returnType, expr.range);
+        }
+        return ctx.error(DiagnosticCode.Property_0_does_not_exist_on_type_1, expr.prop.range, expr.prop.text, "RawConstr");
+    }
     const returnType = getPropAccessReturnType(ctx, objType, expr.prop);
     if (!returnType)
         return ctx.error(DiagnosticCode.Property_0_does_not_exist_on_type_1, expr.prop.range, expr.prop.text, objType.toString());

package/dist/compiler/AstCompiler/internal/exprs/_compileVarAccessExpr.js

@@ -3,6 +3,8 @@ import { TirVariableAccessExpr } from "../../../tir/expressions/TirVariableAcces
 export function _compileVarAccessExpr(ctx, expr, typeHint) {
     const resolvedValue = ctx.scope.resolveValue(expr.text);
     if (!resolvedValue) {
+        if (ctx.scope.resolveNamespace(expr.text))
+            return ctx.error(DiagnosticCode.Namespace_path_is_incomplete_expected_a_value_type_function_or_interface, expr.range);
         console.trace(ctx.scope.allVariables(), expr.text);
         return ctx.error(DiagnosticCode._0_is_not_defined, expr.range, expr.text);
     }

package/dist/compiler/AstCompiler/internal/statements/_compileStatement.js

@@ -12,7 +12,7 @@ import { ForStmt } from "../../../../ast/nodes/statements/ForStmt.js";
 import { IfStmt } from "../../../../ast/nodes/statements/IfStmt.js";
 import { MatchStmt } from "../../../../ast/nodes/statements/MatchStmt.js";
 import { ReturnStmt } from "../../../../ast/nodes/statements/ReturnStmt.js";
-import { UsingStmt } from "../../../../ast/nodes/statements/UsingStmt.js";
+import { UsingAliasStmt, UsingStmt } from "../../../../ast/nodes/statements/UsingStmt.js";
 import { VarStmt } from "../../../../ast/nodes/statements/VarStmt.js";
 import { WhileStmt } from "../../../../ast/nodes/statements/WhileStmt.js";
 import { _compileAssertStmt } from "./_compileAssertStmt.js";
@@ -28,6 +28,7 @@ import { _compileIfStmt } from "./_compileIfStmt.js";
 import { _compileMatchStmt } from "./_compileMatchStmt.js";
 import { _compileReturnStmt } from "./_compileReturnStmt.js";
 import { _compileUsingStmt } from "./_compileUsingStmt.js";
+import { _compileUsingAliasStmt } from "./_compileUsingAliasStmt.js";
 import { _compileVarStmt } from "./_compileVarStmt.js";
 import { _compileWhileStmt } from "./_compileWhileStmt.js";
 /**
@@ -74,6 +75,8 @@ export function _compileStatement(ctx, stmt) {
     // if( stmt instanceof ExprStmt ) return _compileExprStmt( ctx, stmt );
     if (stmt instanceof UsingStmt)
         return _compileUsingStmt(ctx, stmt);
+    if (stmt instanceof UsingAliasStmt)
+        return _compileUsingAliasStmt(ctx, stmt);
     const tsEnsureExhautstiveCheck = stmt;
     console.error(stmt);
     throw new Error("unreachable::AstCompiler::_compileStatement");

package/dist/compiler/AstCompiler/internal/statements/_compileTestStmt.d.ts

@@ -1 +1,15 @@
-export {};
+import { TestStmt } from "../../../../ast/nodes/statements/TestStmt.js";
+import { AstCompilationCtx } from "../../AstCompilationCtx.js";
+/**
+ * Compiles a `test name( params? ) { body }` declaration.
+ *
+ * Synthesises a `function <tirFuncName>( params ): void { body }` and
+ * runs it through `_compileFuncExpr` so type-checking, scoping and
+ * later TIR-to-UPLC compilation work exactly like a user-defined function.
+ *
+ * Registers the resulting `TirFuncExpr` in `program.functions` and pushes
+ * a `TirTestStmt` referencing it onto `program.tests`.
+ *
+ * @returns `true` on success (test registered), `false` on failure (diagnostic emitted).
+ */
+export declare function _compileTestStmt(ctx: AstCompilationCtx, stmt: TestStmt, srcUid: string, sourceFile: string): boolean;

package/dist/compiler/AstCompiler/internal/statements/_compileTestStmt.js

@@ -1,32 +1,72 @@
-export {};
-/*
-export function _compileTestStmt(
-    ctx: AstCompilationCtx,
-    stmt: TestStmt
-): [ TirTestStmt ] | undefined
-{
-    if( ctx.functionCtx ) return ctx.error(
-        DiagnosticCode.A_test_statement_can_only_be_used_outside_a_function,
-        stmt.range
+import { Identifier } from "../../../../ast/nodes/common/Identifier.js";
+import { FuncExpr } from "../../../../ast/nodes/expr/functions/FuncExpr.js";
+import { ArrowKind } from "../../../../ast/nodes/expr/functions/ArrowKind.js";
+import { AstFuncType, AstVoidType } from "../../../../ast/nodes/types/AstNativeTypeExpr.js";
+import { CommonFlags } from "../../../../common.js";
+import { SimpleVarDecl } from "../../../../ast/nodes/statements/declarations/VarDecl/SimpleVarDecl.js";
+import { PEBBLE_INTERNAL_IDENTIFIER_PREFIX } from "../../../internalVar.js";
+import { TirTestStmt } from "../../../tir/statements/TirTestStmt.js";
+import { _compileFuncExpr } from "../exprs/_compileFuncExpr.js";
+import { TirIntT } from "../../../tir/types/TirNativeType/native/int.js";
+import { TirBoolT } from "../../../tir/types/TirNativeType/native/bool.js";
+import { getUnaliased } from "../../../tir/types/utils/getUnaliased.js";
+/**
+ * Compiles a `test name( params? ) { body }` declaration.
+ *
+ * Synthesises a `function <tirFuncName>( params ): void { body }` and
+ * runs it through `_compileFuncExpr` so type-checking, scoping and
+ * later TIR-to-UPLC compilation work exactly like a user-defined function.
+ *
+ * Registers the resulting `TirFuncExpr` in `program.functions` and pushes
+ * a `TirTestStmt` referencing it onto `program.tests`.
+ *
+ * @returns `true` on success (test registered), `false` on failure (diagnostic emitted).
+ */
+export function _compileTestStmt(ctx, stmt, srcUid, sourceFile) {
+    const program = ctx.program;
+    const astName = stmt.testName.text;
+    const tirFuncName = PEBBLE_INTERNAL_IDENTIFIER_PREFIX + "test_" + astName + "_" + srcUid;
+    // Lower each TestParam to a SimpleVarDecl for the synthesized FuncExpr.
+    // `viaExpr` is consumed later (fuzzer resolution); the wrapper function
+    // itself takes the same params a regular `function name( ... )` would.
+    const lowerParams = stmt.params.map(p => new SimpleVarDecl(p.name, p.type, undefined, // initExpr
+    CommonFlags.Const, p.range));
+    const sig = new AstFuncType(lowerParams, new AstVoidType(stmt.testName.range), stmt.range);
+    const astFuncExpr = new FuncExpr(new Identifier(tirFuncName, stmt.testName.range), CommonFlags.None, [], // typeParams
+    sig, stmt.body, ArrowKind.None, stmt.range);
+    const tirFuncExpr = _compileFuncExpr(ctx, astFuncExpr, undefined, // expectedFuncType
+    false // isMethod
     );
-
-    let tirBody = wrapManyStatements(
-        _compileStatement(
-            ctx.newBranchChildScope(),
-            stmt.body
-        ),
-        stmt.body.range
-    );
-    if( !tirBody ) return undefined;
-    if(!( tirBody instanceof TirBlockStmt))
-    {
-        tirBody = new TirBlockStmt( [ tirBody ], stmt.body.range );
-    }
-
-    return [ new TirTestStmt(
-        stmt.testName?.string,
-        tirBody as TirBlockStmt,
-        stmt.range
-    ) ];
+    if (!tirFuncExpr)
+        return false;
+    program.functions.set(tirFuncName, tirFuncExpr);
+    // Resolve per-parameter fuzzer info. This walks both the source-level
+    // `TestParam` array (which carries any `via` expressions) and the
+    // resolved TIR param types (taken from the compiled function).
+    const fuzzerInfos = stmt.params.map((astParam, idx) => {
+        // Phase 1: `via` is parsed but execution of user-defined fuzzers
+        // is not wired up. Type-checking the expression is also deferred
+        // until the stdlib `std.test.fuzz` namespace ships.
+        if (astParam.viaExpr) {
+            return { kind: "via_not_implemented" };
+        }
+        const tirParamType = tirFuncExpr.params[idx]?.type;
+        if (!tirParamType) {
+            return {
+                kind: "unsupported",
+                reason: `parameter '${astParam.name.text}' has no resolved type`
+            };
+        }
+        const unaliased = getUnaliased(tirParamType);
+        if (unaliased instanceof TirIntT)
+            return { kind: "primitive", primitive: "int" };
+        if (unaliased instanceof TirBoolT)
+            return { kind: "primitive", primitive: "bool" };
+        return {
+            kind: "unsupported",
+            reason: `parameter '${astParam.name.text}' of type '${tirParamType.toString()}' has no default fuzzer; specify one with 'via <expr>' (note: user-defined fuzzers via 'via' are not yet executable)`
+        };
+    });
+    program.tests.push(new TirTestStmt(astName, tirFuncName, sourceFile, stmt.range, fuzzerInfos));
+    return true;
 }
-//*/ 

package/dist/compiler/AstCompiler/internal/statements/_compileUsingAliasStmt.d.ts

@@ -0,0 +1,11 @@
+import { UsingAliasStmt } from "../../../../ast/nodes/statements/UsingStmt.js";
+import { AstCompilationCtx } from "../../AstCompilationCtx.js";
+/**
+ * `using <alias> = <NamespacePath>;`
+ *
+ * binds `<alias>` in the current scope as a namespace alias for the
+ * namespace at `<NamespacePath>`.
+ *
+ * compile-time only — no IR is emitted.
+ */
+export declare function _compileUsingAliasStmt(ctx: AstCompilationCtx, stmt: UsingAliasStmt): [] | undefined;

package/dist/compiler/AstCompiler/internal/statements/_compileUsingAliasStmt.js

@@ -0,0 +1,26 @@
+import { DiagnosticCode } from "../../../../diagnostics/diagnosticMessages.generated.js";
+import { resolveNamespacePath } from "../../utils/resolveNamespacePath.js";
+/**
+ * `using <alias> = <NamespacePath>;`
+ *
+ * binds `<alias>` in the current scope as a namespace alias for the
+ * namespace at `<NamespacePath>`.
+ *
+ * compile-time only — no IR is emitted.
+ */
+export function _compileUsingAliasStmt(ctx, stmt) {
+    const resolved = resolveNamespacePath(ctx, stmt.rhs);
+    if (!resolved) {
+        ctx.error(DiagnosticCode._0_is_not_a_namespace, stmt.rhs.range, stmt.rhs.segments[0].text);
+        return undefined;
+    }
+    const ok = ctx.scope.defineNamespace({
+        name: stmt.aliasName.text,
+        publicScope: resolved.namespace.publicScope
+    });
+    if (!ok) {
+        ctx.error(DiagnosticCode.Constructor_name_0_is_already_declared_in_this_scope, stmt.aliasName.range, stmt.aliasName.text);
+        return undefined;
+    }
+    return [];
+}

package/dist/compiler/AstCompiler/internal/statements/_compileUsingStmt.d.ts

@@ -1,11 +1,16 @@
 import { UsingStmt } from "../../../../ast/nodes/statements/UsingStmt.js";
 import { AstCompilationCtx } from "../../AstCompilationCtx.js";
 /**
- * `using` only introduces symbols in scope
+ * `using` only introduces symbols in scope.
  *
- * we don't represent `using` statements in the TIR
+ * we don't represent `using` statements in the TIR.
  *
- * @returns {[]} an empty array if successful compilation
+ * the RHS can be either:
+ *  - a struct type expression (legacy behavior, brings constructors into scope)
+ *  - a namespace path (new behavior, destructures the namespace's exported
+ *    members into the current scope)
+ *
+ * @returns {[]} an empty array if compilation succeeded
  * @returns {undefined} `undefined` if compilation failed
-**/
+ */
 export declare function _compileUsingStmt(ctx: AstCompilationCtx, stmt: UsingStmt): [] | undefined;

package/dist/compiler/AstCompiler/internal/statements/_compileUsingStmt.js

@@ -1,27 +1,55 @@
+import { UsingPath } from "../../../../ast/nodes/statements/UsingStmt.js";
 import { DiagnosticCode } from "../../../../diagnostics/diagnosticMessages.generated.js";
 import { getStructType } from "../../../tir/types/utils/canAssignTo.js";
+import { bindNamespaceMember, resolveNamespacePath } from "../../utils/resolveNamespacePath.js";
 import { _compileDataEncodedConcreteType } from "../types/_compileDataEncodedConcreteType.js";
 import { _compileSopEncodedConcreteType } from "../types/_compileSopEncodedConcreteType.js";
+import { AstNamedTypeExpr } from "../../../../ast/nodes/types/AstNamedTypeExpr.js";
 /**
- * `using` only introduces symbols in scope
+ * `using` only introduces symbols in scope.
  *
- * we don't represent `using` statements in the TIR
+ * we don't represent `using` statements in the TIR.
  *
- * @returns {[]} an empty array if successful compilation
+ * the RHS can be either:
+ *  - a struct type expression (legacy behavior, brings constructors into scope)
+ *  - a namespace path (new behavior, destructures the namespace's exported
+ *    members into the current scope)
+ *
+ * @returns {[]} an empty array if compilation succeeded
  * @returns {undefined} `undefined` if compilation failed
-**/
+ */
 export function _compileUsingStmt(ctx, stmt) {
-    stmt.constructorNames;
-    stmt.structTypeExpr;
-    stmt.range;
-    const structOrAliasType = (_compileSopEncodedConcreteType(ctx, stmt.structTypeExpr)
-        ?? _compileDataEncodedConcreteType(ctx, stmt.structTypeExpr));
+    const rhs = stmt.rhs;
+    if (rhs instanceof UsingPath) {
+        // namespace path. if the head is a namespace, destructure
+        // its public members; otherwise fall through to the struct path
+        // (this supports the single-identifier case where a name could
+        //  be either a struct or a namespace).
+        const ns = resolveNamespacePath(ctx, rhs);
+        if (ns) {
+            return _compileUsingNamespaceDestructure(ctx, stmt, ns.namespace);
+        }
+        // single-segment fallback: treat as a struct type ref
+        if (rhs.segments.length === 1) {
+            const ident = rhs.segments[0];
+            const fakeTypeExpr = new AstNamedTypeExpr(ident, [], ident.range);
+            return _compileUsingStructDestructure(ctx, stmt, fakeTypeExpr);
+        }
+        ctx.error(DiagnosticCode._0_is_not_a_namespace, rhs.range, rhs.segments[0].text);
+        return undefined;
+    }
+    // RHS is an AstTypeExpr (existing struct-destructure code path)
+    return _compileUsingStructDestructure(ctx, stmt, rhs);
+}
+function _compileUsingStructDestructure(ctx, stmt, rhs) {
+    const structOrAliasType = (_compileSopEncodedConcreteType(ctx, rhs)
+        ?? _compileDataEncodedConcreteType(ctx, rhs));
     if (!structOrAliasType)
         return undefined;
     // un-alias
     const structType = getStructType(structOrAliasType);
     if (!structType || !structType.isConcrete())
-        return ctx.error(DiagnosticCode.Type_0_does_not_have_constructors, stmt.structTypeExpr.range, structOrAliasType.toString());
+        return ctx.error(DiagnosticCode.Type_0_does_not_have_constructors, rhs.range, structOrAliasType.toString());
     const defCtorNames = structType.constructors.map(c => c.name);
     const sameStmtCtorNames = [];
     for (const stmtCtor of stmt.constructorNames) {
@@ -39,3 +67,16 @@ export function _compileUsingStmt(ctx, stmt) {
     }
     return [];
 }
+function _compileUsingNamespaceDestructure(ctx, stmt, ns) {
+    const seen = new Set();
+    for (const decl of stmt.constructorNames) {
+        const name = decl.constructorName;
+        if (seen.has(name.text))
+            return ctx.error(DiagnosticCode.Constructor_0_was_already_specified, name.range, name.text);
+        seen.add(name.text);
+        const ok = bindNamespaceMember(ctx, ns, name, decl.renamedConstructorName, ctx.scope);
+        if (!ok)
+            return undefined;
+    }
+    return [];
+}

package/dist/compiler/AstCompiler/internal/types/_compileDataEncodedConcreteType.js

@@ -46,11 +46,30 @@ export function _compileDataEncodedConcreteType(ctx, typeExpr, optionalsAsSop =
         return undefined; // no data encoding for function types
     if (typeExpr instanceof AstNamedTypeExpr) // struct, aliases and respective params
      {
+        // generic type parameters take precedence: `T` in a generic function
+        // body resolves directly to its TirTypeParam, leaving substitution
+        // to `monomorphizeGeneric` at call time.
+        const typeParam = ctx.scope.resolveTypeParam(typeExpr.name.text);
+        if (typeParam)
+            return typeParam;
         const possibleTirNames = ctx.scope.resolveType(typeExpr.name.text);
         if (!possibleTirNames)
             return ctx.error(DiagnosticCode._0_is_not_defined, typeExpr.name.range, typeExpr.name.text);
-        if (possibleTirNames.isGeneric)
-            throw new Error("not implemented: _compileDataEncodedConcreteType for generic types");
+        if (possibleTirNames.isGeneric) {
+            // Generic named type with explicit type-args, e.g. `List<int>` —
+            // compile each arg and apply the generic.
+            if (typeExpr.tyArgs.length === 0)
+                return ctx.error(DiagnosticCode._0_is_not_defined, typeExpr.name.range, typeExpr.name.text);
+            const compiledArgs = [];
+            for (const aExpr of typeExpr.tyArgs) {
+                const a = _compileDataEncodedConcreteType(ctx, aExpr, optionalsAsSop);
+                if (!a)
+                    return undefined;
+                compiledArgs.push(a);
+            }
+            const applied = ctx.program.getAppliedGeneric(possibleTirNames.dataTirName ?? possibleTirNames.sopTirName, compiledArgs);
+            return applied;
+        }
         if (typeof possibleTirNames.dataTirName !== "string")
             return undefined;
         return ctx.program.types.get(possibleTirNames.dataTirName);

package/dist/compiler/AstCompiler/internal/types/_compileSopEncodedConcreteType.js

@@ -44,11 +44,26 @@ export function _compileSopEncodedConcreteType(ctx, typeExpr) {
         return undefined; // no data encoding for function types
     if (typeExpr instanceof AstNamedTypeExpr) // struct, aliases and respective params
      {
+        // generic type parameters take precedence over named-type lookup
+        const typeParam = ctx.scope.resolveTypeParam(typeExpr.name.text);
+        if (typeParam)
+            return typeParam;
         const possibleTirNames = ctx.scope.resolveType(typeExpr.name.text);
         if (!possibleTirNames)
             return ctx.error(DiagnosticCode._0_is_not_defined, typeExpr.name.range, typeExpr.name.text);
-        if (possibleTirNames.isGeneric)
-            throw new Error("not implemented: _compileSopEncodedConcreteType for generic types");
+        if (possibleTirNames.isGeneric) {
+            if (typeExpr.tyArgs.length === 0)
+                return ctx.error(DiagnosticCode._0_is_not_defined, typeExpr.name.range, typeExpr.name.text);
+            const compiledArgs = [];
+            for (const aExpr of typeExpr.tyArgs) {
+                const a = _compileSopEncodedConcreteType(ctx, aExpr);
+                if (!a)
+                    return undefined;
+                compiledArgs.push(a);
+            }
+            const applied = ctx.program.getAppliedGeneric(possibleTirNames.sopTirName, compiledArgs);
+            return applied;
+        }
         if (typeof possibleTirNames.dataTirName !== "string")
             return undefined;
         return ctx.program.types.get(possibleTirNames.dataTirName);

package/dist/compiler/AstCompiler/scope/AstScope.d.ts

@@ -1,6 +1,7 @@
 import { AstFuncType } from "../../../ast/nodes/types/AstNativeTypeExpr.js";
-import { TypedProgram } from "../../tir/program/TypedProgram.js";
+import { TypedProgram, TypeParamConstraint } from "../../tir/program/TypedProgram.js";
 import { TirType } from "../../tir/types/TirType.js";
+import { TirTypeParam } from "../../tir/types/TirTypeParam.js";
 export interface ScopeInfos {
     isFunctionDeclScope: boolean;
     isMethodScope: boolean;
@@ -32,6 +33,29 @@ export interface IVariableInfos {
     name: string;
     type: TirType;
     isConstant: boolean;
+    /**
+     * If set, this binding is a placeholder for a generic function template.
+     * The actual TIR function does not exist yet; it must be instantiated
+     * at the call site by `monomorphizeGeneric` using the template stored in
+     * `TypedProgram.genericTemplates` under this name.
+     *
+     * `type` for a generic placeholder is the *un-substituted* TirFuncT —
+     * i.e. it may contain `TirTypeParam` nodes for each declared type param.
+     */
+    genericTemplateName?: string;
+}
+/**
+ * A namespace is a compile-time only construct that groups
+ * symbols (values, types, functions, interfaces, and nested
+ * namespaces) under a single name.
+ *
+ * Members of the namespace marked with `private` are NOT included
+ * in `publicScope`; they only live in the namespace's body-compilation
+ * scope and are unreachable from outside.
+ */
+export interface NamespaceSymbol {
+    name: string;
+    publicScope: AstScope;
 }
 export interface PossibleTirTypes {
     sopTirName: string;
@@ -81,6 +105,24 @@ export declare class AstScope {
      */
     readonly narrowings: Map<string, TirType>;
     readonly aviableConstructors: Map<string, IAvaiableConstructor>;
+    /**
+     * ast name -> namespace symbol
+     *
+     * namespaces are compile-time only; they do not emit IR
+     */
+    readonly namespaces: Map<string, NamespaceSymbol>;
+    /**
+     * Generic type parameters in scope, e.g. while compiling the signature
+     * (and later the body) of a generic function `function f<T>(...)`. These
+     * are NOT real types — they only mark positions that must be substituted
+     * by `monomorphizeGeneric` at each call site.
+     *
+     * When `_compileDataEncodedConcreteType` / `_compileSopEncodedConcreteType`
+     * encounter an `AstNamedTypeExpr` whose name is here, it returns the
+     * corresponding `TirTypeParam` directly instead of going through the
+     * regular `resolveType` path.
+     */
+    readonly typeParams: Map<string, TirTypeParam>;
     private _isReadonly;
     readonly infos: ScopeInfos;
     constructor(parent: AstScope | undefined, program: TypedProgram, infos: Partial<ScopeInfos>);
@@ -111,5 +153,32 @@ export declare class AstScope {
      */
     defineAviableConstructorIfValid(declaredName: string, originalName: string, structOrAliasType: TirType): boolean;
     inferStructTypeFromConstructorName(name: string): IAvaiableConstructor | undefined;
+    /** define a namespace in this scope; returns `false` if shadowed in current scope */
+    defineNamespace(ns: NamespaceSymbol): boolean;
+    /** resolve a namespace by walking the scope chain */
+    resolveNamespace(name: string): NamespaceSymbol | undefined;
+    /** define a generic type parameter in this scope; returns `false` if shadowed */
+    defineTypeParam(name: string, param: TirTypeParam): boolean;
+    /** resolve a generic type parameter by walking the scope chain */
+    resolveTypeParam(name: string): TirTypeParam | undefined;
+    /**
+     * Type-parameter constraints declared via `<T implements I>` syntax.
+     * Populated by `AstCompiler._registerGenericTemplate` for the function
+     * template's compilation scope. `resolveTypeParamConstraint` walks the
+     * parent chain like the other resolvers.
+     */
+    readonly typeParamConstraints: Map<string, TypeParamConstraint>;
+    defineTypeParamConstraint(name: string, constraint: TypeParamConstraint): boolean;
+    resolveTypeParamConstraint(name: string): TypeParamConstraint | undefined;
+    /**
+     * Walk the scope chain to resolve an interface by name. Returns the
+     * method-name -> AstFuncType signature map.
+     */
+    resolveInterface(name: string): Map<string, AstFuncType> | undefined;
+    /**
+     * `true` if `name` is bound in this scope (or any parent) under any kind.
+     * Used to detect shadowing across symbol categories when defining a new symbol.
+     */
+    hasAnySymbol(name: string): boolean;
     clone(): AstScope;
 }

package/dist/compiler/AstCompiler/scope/AstScope.js

@@ -59,6 +59,24 @@ export class AstScope {
      */
     narrowings = new Map();
     aviableConstructors = new Map();
+    /**
+     * ast name -> namespace symbol
+     *
+     * namespaces are compile-time only; they do not emit IR
+     */
+    namespaces = new Map();
+    /**
+     * Generic type parameters in scope, e.g. while compiling the signature
+     * (and later the body) of a generic function `function f<T>(...)`. These
+     * are NOT real types — they only mark positions that must be substituted
+     * by `monomorphizeGeneric` at each call site.
+     *
+     * When `_compileDataEncodedConcreteType` / `_compileSopEncodedConcreteType`
+     * encounter an `AstNamedTypeExpr` whose name is here, it returns the
+     * corresponding `TirTypeParam` directly instead of going through the
+     * regular `resolveType` path.
+     */
+    typeParams = new Map();
     _isReadonly = false;
     infos;
     constructor(parent, program, infos) {
@@ -202,6 +220,77 @@ export class AstScope {
         return (this.aviableConstructors.get(name)
             ?? this.parent?.inferStructTypeFromConstructorName(name));
     }
+    /** define a namespace in this scope; returns `false` if shadowed in current scope */
+    defineNamespace(ns) {
+        if (this._isReadonly)
+            return false;
+        if (invalidSymbolNames.has(ns.name))
+            return false;
+        if (this.namespaces.has(ns.name))
+            return false;
+        this.namespaces.set(ns.name, ns);
+        return true;
+    }
+    /** resolve a namespace by walking the scope chain */
+    resolveNamespace(name) {
+        return (this.namespaces.get(name)
+            ?? this.parent?.resolveNamespace(name));
+    }
+    /** define a generic type parameter in this scope; returns `false` if shadowed */
+    defineTypeParam(name, param) {
+        if (this._isReadonly)
+            return false;
+        if (this.typeParams.has(name))
+            return false;
+        this.typeParams.set(name, param);
+        return true;
+    }
+    /** resolve a generic type parameter by walking the scope chain */
+    resolveTypeParam(name) {
+        return (this.typeParams.get(name)
+            ?? this.parent?.resolveTypeParam(name));
+    }
+    /**
+     * Type-parameter constraints declared via `<T implements I>` syntax.
+     * Populated by `AstCompiler._registerGenericTemplate` for the function
+     * template's compilation scope. `resolveTypeParamConstraint` walks the
+     * parent chain like the other resolvers.
+     */
+    typeParamConstraints = new Map();
+    defineTypeParamConstraint(name, constraint) {
+        if (this._isReadonly)
+            return false;
+        if (this.typeParamConstraints.has(name))
+            return false;
+        this.typeParamConstraints.set(name, constraint);
+        return true;
+    }
+    resolveTypeParamConstraint(name) {
+        return (this.typeParamConstraints.get(name)
+            ?? this.parent?.resolveTypeParamConstraint(name));
+    }
+    /**
+     * Walk the scope chain to resolve an interface by name. Returns the
+     * method-name -> AstFuncType signature map.
+     */
+    resolveInterface(name) {
+        return (this.interfaces.get(name)
+            ?? this.parent?.resolveInterface(name));
+    }
+    /**
+     * `true` if `name` is bound in this scope (or any parent) under any kind.
+     * Used to detect shadowing across symbol categories when defining a new symbol.
+     */
+    hasAnySymbol(name) {
+        if (this.variables.has(name)
+            || this.types.has(name)
+            || this.functions.has(name)
+            || this.interfaces.has(name)
+            || this.namespaces.has(name)
+            || this.aviableConstructors.has(name))
+            return true;
+        return this.parent?.hasAnySymbol(name) ?? false;
+    }
     clone() {
         const cloned = new AstScope(this.parent, this.program, this.infos);
         for (const [key, value] of this.variables)
@@ -219,6 +308,8 @@ export class AstScope {
             });
         for (const [name, methods] of this.interfaces)
             cloned.interfaces.set(name, new Map(methods));
+        for (const [name, ns] of this.namespaces)
+            cloned.namespaces.set(name, ns);
         return cloned;
     }
 }