@harmoniclabs/pebble 0.1.10 → 0.3.0

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

package/dist/compiler/AstCompiler/utils/getPropAccessReturnType.js

@@ -1,13 +1,16 @@
 import { TirAliasType } from "../../tir/types/TirAliasType.js";
 import { isTirStructType } from "../../tir/types/TirStructType.js";
+import { TirEnumType } from "../../tir/types/TirEnumType.js";
 import { TirTypeParam } from "../../tir/types/TirTypeParam.js";
 import { int_t, bytes_t, bool_t, string_t } from "../../tir/program/stdScope/stdScope.js";
-import { TirUnConstrDataResultT, TirPairDataT } from "../../tir/types/TirNativeType/index.js";
+import { TirBlsG1T, TirBlsG2T, TirMlResultT, TirUnConstrDataResultT, TirPairDataT } from "../../tir/types/TirNativeType/index.js";
 import { TirBoolT } from "../../tir/types/TirNativeType/native/bool.js";
 import { TirBytesT } from "../../tir/types/TirNativeType/native/bytes.js";
 import { TirDataT } from "../../tir/types/TirNativeType/native/data.js";
 import { TirFuncT } from "../../tir/types/TirNativeType/native/function.js";
 import { TirIntT } from "../../tir/types/TirNativeType/native/int.js";
+import { TirArrayT } from "../../tir/types/TirNativeType/native/array.js";
+import { TirValueT } from "../../tir/types/TirNativeType/native/value.js";
 import { TirLinearMapT } from "../../tir/types/TirNativeType/native/linearMap.js";
 import { TirLinearMapEntryT } from "../../tir/types/TirNativeType/native/linearMapEntry.js";
 import { TirListT } from "../../tir/types/TirNativeType/native/list.js";
@@ -27,6 +30,24 @@ export function getPropAccessReturnType(ctx, objType, propId) {
         objType = objType.aliased;
     }
     // if( objType instanceof TirAliasType ) return findPropInImpls( objType.impls, propName ) ?? getPropAccessReturnType( objType.aliased, propId );
+    // Universal `.show()` — every (built-in) type implementing the Show
+    // interface has signature `(): bytes`. Struct types fall through to
+    // `getStructPropAccessReturnType`, which checks user-declared
+    // `type X implements Show { ... }` impls first; if absent, the
+    // expressify-time fallback emits a TirShowExpr that auto-derives via
+    // `_showIR` (e.g. for data-encoded structs).
+    if (propName === "show") {
+        if (objType instanceof TirVoidT
+            || objType instanceof TirBoolT
+            || objType instanceof TirIntT
+            || objType instanceof TirBytesT
+            || objType instanceof TirStringT
+            || objType instanceof TirDataT
+            || objType instanceof TirListT
+            || objType instanceof TirLinearMapT
+            || isTirOptType(objType))
+            return new TirFuncT([], bytes_t);
+    }
     if (isTirStructType(objType))
         return getStructPropAccessReturnType(ctx, objType, propName);
     if (objType instanceof TirVoidT)
@@ -60,6 +81,20 @@ export function getPropAccessReturnType(ctx, objType, propId) {
         return undefined;
     if (objType instanceof TirPairDataT)
         return undefined;
+    if (objType instanceof TirBlsG1T)
+        return undefined;
+    if (objType instanceof TirBlsG2T)
+        return undefined;
+    if (objType instanceof TirMlResultT)
+        return undefined;
+    // Native Value / Array<T> — methods are reached through prelude/std
+    // aliases, not via direct prop-access on the native type.
+    if (objType instanceof TirValueT)
+        return undefined;
+    if (objType instanceof TirArrayT)
+        return undefined;
+    if (objType instanceof TirEnumType)
+        return undefined;
     const tsEnsureExhaustiveCheck = objType;
     console.error(objType);
     throw new Error("unreachable::getPropAccessReturnType");

package/dist/compiler/AstCompiler/utils/monomorphizeGeneric.d.ts

@@ -0,0 +1,36 @@
+import { SourceRange } from "../../../ast/Source/SourceRange.js";
+import { GenericTemplate } from "../../tir/program/TypedProgram.js";
+import { TirFuncT } from "../../tir/types/TirNativeType/native/function.js";
+import { TirType } from "../../tir/types/TirType.js";
+import { AstCompilationCtx } from "../AstCompilationCtx.js";
+export interface MonomorphizationResult {
+    /** the canonical TIR function name registered in `program.functions` */
+    tirFuncName: string;
+    /** the substituted concrete TirFuncT (no remaining type params) */
+    concreteFuncType: TirFuncT;
+}
+/**
+ * Returns a deterministic instance key for memoization & function-table naming.
+ */
+export declare function buildMonomorphizationKey(templateCanonicalName: string, typeArgs: TirType[]): string;
+/**
+ * Instantiate a generic function template with the given concrete type
+ * arguments, producing (and caching) a fresh concrete TIR function.
+ *
+ * The strategy is "desugar to a concrete function during AST→TIR":
+ *
+ * 1. Build a child scope on the template's defining scope where each type
+ *    parameter name resolves as a type alias for its concrete type. When the
+ *    cloned FuncExpr is re-compiled, every `AstNamedTypeExpr` mentioning a
+ *    type parameter resolves to its concrete TIR type.
+ * 2. Construct a fresh `FuncExpr` reusing the template's body & signature but
+ *    with `typeParams = []` (so the "not implemented: generic functions"
+ *    guard in `_compileFuncExpr` does not trip) and a unique instance name.
+ * 3. Compile via `_compileFuncExpr` and register the resulting `TirFuncExpr`
+ *    in `program.functions` under the instance name.
+ *
+ * Results are memoized per `(template, type-args)` tuple — repeated calls
+ * with the same type arguments return the same instance and do not
+ * re-compile.
+ */
+export declare function monomorphizeGeneric(ctx: AstCompilationCtx, template: GenericTemplate, typeArgs: TirType[], callRange: SourceRange): MonomorphizationResult | undefined;

package/dist/compiler/AstCompiler/utils/monomorphizeGeneric.js

@@ -0,0 +1,123 @@
+import { FuncExpr } from "../../../ast/nodes/expr/functions/FuncExpr.js";
+import { Identifier } from "../../../ast/nodes/common/Identifier.js";
+import { ArrowKind } from "../../../ast/nodes/expr/functions/ArrowKind.js";
+import { DiagnosticCode } from "../../../diagnostics/diagnosticMessages.generated.js";
+import { substituteTypeParams } from "../../tir/types/utils/substituteTypeParams.js";
+import { AstCompilationCtx } from "../AstCompilationCtx.js";
+import { _compileFuncExpr } from "../internal/exprs/_compileFuncExpr.js";
+/**
+ * Returns a deterministic instance key for memoization & function-table naming.
+ */
+export function buildMonomorphizationKey(templateCanonicalName, typeArgs) {
+    return templateCanonicalName + "$$" + typeArgs.map(t => t.toConcreteTirTypeName()).join("$$");
+}
+/**
+ * Instantiate a generic function template with the given concrete type
+ * arguments, producing (and caching) a fresh concrete TIR function.
+ *
+ * The strategy is "desugar to a concrete function during AST→TIR":
+ *
+ * 1. Build a child scope on the template's defining scope where each type
+ *    parameter name resolves as a type alias for its concrete type. When the
+ *    cloned FuncExpr is re-compiled, every `AstNamedTypeExpr` mentioning a
+ *    type parameter resolves to its concrete TIR type.
+ * 2. Construct a fresh `FuncExpr` reusing the template's body & signature but
+ *    with `typeParams = []` (so the "not implemented: generic functions"
+ *    guard in `_compileFuncExpr` does not trip) and a unique instance name.
+ * 3. Compile via `_compileFuncExpr` and register the resulting `TirFuncExpr`
+ *    in `program.functions` under the instance name.
+ *
+ * Results are memoized per `(template, type-args)` tuple — repeated calls
+ * with the same type arguments return the same instance and do not
+ * re-compile.
+ */
+export function monomorphizeGeneric(ctx, template, typeArgs, callRange) {
+    const program = ctx.program;
+    if (typeArgs.length !== template.typeParams.length) {
+        ctx.error(DiagnosticCode.Expected_0_type_arguments_but_got_1, callRange, String(template.typeParams.length), String(typeArgs.length));
+        return undefined;
+    }
+    // Build the substitution env for substituteTypeParams
+    const subst = new Map();
+    for (let i = 0; i < template.typeParams.length; i++) {
+        subst.set(template.typeParams[i].symbol, typeArgs[i]);
+    }
+    // Compute concrete signature up-front (used by callers to type the call expr)
+    const concreteFuncType = substituteTypeParams(template.placeholderFuncType, subst);
+    // Memo key & cache hit
+    const instanceName = buildMonomorphizationKey(template.canonicalTirName, typeArgs);
+    const cached = program.monomorphizationCache.get(instanceName);
+    if (typeof cached === "string") {
+        return { tirFuncName: cached, concreteFuncType };
+    }
+    // Native template path: skip AST cloning entirely.
+    if (template.kind === "native") {
+        const tirFunc = template.instantiate(typeArgs);
+        program.functions.set(instanceName, tirFunc);
+        program.monomorphizationCache.set(instanceName, instanceName);
+        return { tirFuncName: instanceName, concreteFuncType };
+    }
+    // Cycle detection: polymorphic recursion (same template + same type args
+    // re-entering before the first compile finished) is impossible because
+    // recursion at the same type-args hits the memo cache below. Recursion at
+    // *different* type-args is allowed and produces a separate instance.
+    if (program.monomorphizationInFlight.has(instanceName)) {
+        // intentionally rare path; surface as a Not_implemented diagnostic
+        ctx.error(DiagnosticCode.Not_implemented_0, callRange, "mutually-recursive monomorphization for " + instanceName);
+        return undefined;
+    }
+    program.monomorphizationInFlight.add(instanceName);
+    // Pre-register memo so recursive same-args call resolves to the same name
+    program.monomorphizationCache.set(instanceName, instanceName);
+    try {
+        // Build child scope where each type-param name aliases its concrete type
+        const monoScope = template.definingScope.newChildScope({
+            ...template.definingScope.infos,
+            isFunctionDeclScope: false,
+            isMethodScope: false
+        });
+        for (let i = 0; i < template.typeParams.length; i++) {
+            const tparam = template.typeParams[i];
+            const concrete = typeArgs[i];
+            const concreteKey = concrete.toConcreteTirTypeName();
+            if (!program.types.has(concreteKey)) {
+                program.types.set(concreteKey, concrete);
+            }
+            monoScope.defineUnambigousType(tparam.name, concreteKey, concrete.hasDataEncoding(), new Map() // no methods on a bare type alias
+            );
+        }
+        // Register the instance in the parent (defining) scope under the
+        // instance name so the body's own recursive `id(...)` call (which
+        // resolves through the parent chain) sees a concrete value of the
+        // already-substituted type. Without this, recursive calls would
+        // re-trigger the generic placeholder path and infinite-loop the
+        // monomorphizer.
+        // Use the mono scope (not the defining scope) so the entry is local
+        // to this instantiation.
+        monoScope.defineValue({
+            name: instanceName,
+            type: concreteFuncType,
+            isConstant: true,
+        });
+        const cloneExpr = new FuncExpr(new Identifier(instanceName, template.astFuncExpr.name.range), template.astFuncExpr.flags, [], // intentionally empty: this clone is the monomorphized concrete fn
+        template.astFuncExpr.signature, template.astFuncExpr.body, template.astFuncExpr.arrowKind ?? ArrowKind.None, template.astFuncExpr.range);
+        // Pre-seed program.functions with the concrete signature so
+        // `_compileFuncExpr` picks it up via `program.functions.get(...).sig()`.
+        // We will replace this with the real TirFuncExpr after compile.
+        // (placeholder is not strictly required; _compileFuncExpr falls back to
+        //  inferring from the signature if not present — leaving this out for
+        //  simplicity)
+        const monoCtx = AstCompilationCtx.fromScope(program, monoScope);
+        const tirFuncExpr = _compileFuncExpr(monoCtx, cloneExpr, undefined, false // isMethod
+        );
+        if (!tirFuncExpr) {
+            program.monomorphizationCache.delete(instanceName);
+            return undefined;
+        }
+        program.functions.set(instanceName, tirFuncExpr);
+        return { tirFuncName: instanceName, concreteFuncType };
+    }
+    finally {
+        program.monomorphizationInFlight.delete(instanceName);
+    }
+}

package/dist/compiler/AstCompiler/utils/resolveNamespaceChain.d.ts

@@ -0,0 +1,28 @@
+import { PebbleExpr } from "../../../ast/nodes/expr/PebbleExpr.js";
+import { TirExpr } from "../../tir/expressions/TirExpr.js";
+import { AstCompilationCtx } from "../AstCompilationCtx.js";
+import { NamespaceSymbol } from "../scope/AstScope.js";
+export type NamespaceChainResolution = {
+    kind: "namespace";
+    namespace: NamespaceSymbol;
+} | {
+    kind: "value";
+    expr: TirExpr;
+}
+/** the chain points to a non-value (type / interface / nested ns
+ *  used in non-expression position). callers should typically error. */
+ | {
+    kind: "incomplete";
+} | undefined;
+/**
+ * if `expr` is `Identifier` or a chain of `DotPropAccessExpr` ending in an
+ * `Identifier`, AND the head identifier resolves to a namespace in scope,
+ * walks the chain through namespace `publicScope`s and returns the resolved
+ * member. otherwise returns `undefined` so the caller can fall back to
+ * normal value/property-access compilation.
+ *
+ * the resolution does NOT emit diagnostics on plain "not a namespace"
+ * outcomes — those are silent failures so the caller can choose another
+ * resolution strategy.
+ */
+export declare function tryResolveNamespaceChain(ctx: AstCompilationCtx, expr: PebbleExpr): NamespaceChainResolution;

package/dist/compiler/AstCompiler/utils/resolveNamespaceChain.js

@@ -0,0 +1,95 @@
+import { Identifier } from "../../../ast/nodes/common/Identifier.js";
+import { DotPropAccessExpr } from "../../../ast/nodes/expr/PropAccessExpr.js";
+import { DiagnosticCode } from "../../../diagnostics/diagnosticMessages.generated.js";
+import { TirVariableAccessExpr } from "../../tir/expressions/TirVariableAccessExpr.js";
+/**
+ * if `expr` is `Identifier` or a chain of `DotPropAccessExpr` ending in an
+ * `Identifier`, AND the head identifier resolves to a namespace in scope,
+ * walks the chain through namespace `publicScope`s and returns the resolved
+ * member. otherwise returns `undefined` so the caller can fall back to
+ * normal value/property-access compilation.
+ *
+ * the resolution does NOT emit diagnostics on plain "not a namespace"
+ * outcomes — those are silent failures so the caller can choose another
+ * resolution strategy.
+ */
+export function tryResolveNamespaceChain(ctx, expr) {
+    const segments = _collectChainSegments(expr);
+    if (!segments)
+        return undefined;
+    const head = ctx.scope.resolveNamespace(segments[0].text);
+    if (!head)
+        return undefined;
+    // head is a namespace; from here on, any failure emits a diagnostic
+    let current = head;
+    for (let i = 1; i < segments.length; i++) {
+        const seg = segments[i];
+        const name = seg.text;
+        const pub = current.publicScope;
+        const nested = pub.namespaces.get(name);
+        if (nested) {
+            current = nested;
+            continue;
+        }
+        const variable = pub.variables.get(name);
+        if (variable) {
+            // last segment must end here; if not, the chain is invalid
+            if (i !== segments.length - 1) {
+                ctx.error(DiagnosticCode.Property_0_does_not_exist_on_type_1, seg.range, segments[i + 1].text, variable.type.toString());
+                return { kind: "incomplete" };
+            }
+            return {
+                kind: "value",
+                expr: new TirVariableAccessExpr({ variableInfos: variable, isDefinedOutsideFuncScope: true }, seg.range)
+            };
+        }
+        const tirFuncName = pub.functions.get(name);
+        if (tirFuncName) {
+            if (i !== segments.length - 1) {
+                // function-typed member can't be further dotted
+                ctx.error(DiagnosticCode.Namespace_path_is_incomplete_expected_a_value_type_function_or_interface, seg.range);
+                return { kind: "incomplete" };
+            }
+            const funcExpr = pub.program.functions.get(tirFuncName);
+            if (!funcExpr) {
+                ctx.error(DiagnosticCode.Namespace_0_has_no_exported_member_1, seg.range, current.name, name);
+                return { kind: "incomplete" };
+            }
+            return {
+                kind: "value",
+                expr: new TirVariableAccessExpr({
+                    variableInfos: {
+                        isConstant: true,
+                        name: tirFuncName,
+                        type: funcExpr.type,
+                    },
+                    isDefinedOutsideFuncScope: true,
+                }, seg.range)
+            };
+        }
+        // not a namespace, not a value, not a function — likely a type or
+        // interface. either way it can't be used as a value here.
+        if (pub.types.has(name) || pub.interfaces.has(name)) {
+            ctx.error(DiagnosticCode.Namespace_path_is_incomplete_expected_a_value_type_function_or_interface, seg.range);
+            return { kind: "incomplete" };
+        }
+        ctx.error(DiagnosticCode.Namespace_0_has_no_exported_member_1, seg.range, current.name, name);
+        return { kind: "incomplete" };
+    }
+    // chain consumed entirely as namespaces (no leaf member)
+    return { kind: "namespace", namespace: current };
+}
+function _collectChainSegments(expr) {
+    if (expr instanceof Identifier)
+        return [expr];
+    if (expr instanceof DotPropAccessExpr) {
+        const inner = _collectChainSegments(expr.object);
+        if (!inner)
+            return undefined;
+        inner.push(expr.prop);
+        return inner;
+    }
+    // anything other than a plain dotted-identifier chain disqualifies
+    // namespace resolution.
+    return undefined;
+}

package/dist/compiler/AstCompiler/utils/resolveNamespacePath.d.ts

@@ -0,0 +1,37 @@
+import { Identifier } from "../../../ast/nodes/common/Identifier.js";
+import { UsingPath } from "../../../ast/nodes/statements/UsingStmt.js";
+import { AstScope, NamespaceSymbol } from "../scope/AstScope.js";
+import { AstCompilationCtx } from "../AstCompilationCtx.js";
+export interface ResolvedNamespacePath {
+    /** the namespace the path resolves to */
+    namespace: NamespaceSymbol;
+    /** the chain of resolved namespaces (one per segment of the path) */
+    chain: NamespaceSymbol[];
+}
+/**
+ * walks a dotted namespace path against the given scope.
+ *
+ * - returns the final `NamespaceSymbol` if every segment resolves to a namespace.
+ * - if the first segment is not a namespace, returns `undefined`
+ *   (no diagnostic emitted; the caller can fall back to a different
+ *   resolution strategy, e.g. struct lookup).
+ * - if a later segment is missing or is not a namespace, emits a
+ *   diagnostic and returns `undefined`.
+ */
+export declare function resolveNamespacePath(ctx: AstCompilationCtx, path: UsingPath): ResolvedNamespacePath | undefined;
+/**
+ * looks up a member name in a namespace's public scope.
+ *
+ * the member can be any of:
+ *   - a value (variable)
+ *   - a function
+ *   - a type
+ *   - an interface
+ *   - a nested namespace
+ *
+ * binds the resolved member into `target` (under either `originalName`
+ * or `aliasName` if provided). emits a diagnostic and returns `false`
+ * if no such member is exported, or if a conflicting binding already
+ * exists in `target`.
+ */
+export declare function bindNamespaceMember(ctx: AstCompilationCtx, ns: NamespaceSymbol, originalName: Identifier, aliasName: Identifier | undefined, target: AstScope): boolean;