kopscript 0.11.1 → 0.13.0

package/dist/checker.js

@@ -56,11 +56,13 @@ export class Checker {
         this.functions = new Map();
         this.externValues = new Map();
         this.namedTypes = new Map();
-        // className/interfaceName -> its type parameter's name (e.g. "Box" -> "T"),
-        // for every generic class/interface — populated up front, before any type
-        // resolution runs, specifically so a forward reference (class A's field
-        // referencing generic class B, declared later in the same file) still
-        // resolves B's genericity correctly. See resolveType/validateGenericArity.
+        // className/interfaceName -> its type parameters' names, in declared order
+        // (e.g. "Pair" -> ["K", "V"]), for every generic class/interface —
+        // populated up front, before any type resolution runs, specifically so a
+        // forward reference (class A's field referencing generic class B, declared
+        // later in the same file) still resolves B's genericity correctly. Also
+        // doubles as the arity table (its length is how many type arguments a
+        // reference to that name must supply). See resolveType/validateGenericArity.
         this.genericTypeParams = new Map();
         this.importedNames = new Set();
         this.rawContents = new Map();
@@ -73,13 +75,13 @@ export class Checker {
         }
         for (const [name, info] of this.imports.classes) {
             this.classes.set(name, info);
-            if (info.typeParam)
-                this.genericTypeParams.set(name, info.typeParam);
+            if (info.typeParams.length > 0)
+                this.genericTypeParams.set(name, info.typeParams);
         }
         for (const [name, info] of this.imports.interfaces) {
             this.interfaces.set(name, info);
-            if (info.typeParam)
-                this.genericTypeParams.set(name, info.typeParam);
+            if (info.typeParams.length > 0)
+                this.genericTypeParams.set(name, info.typeParams);
         }
         for (const [name, info] of this.imports.enums)
             this.enums.set(name, info);
@@ -109,14 +111,14 @@ export class Checker {
         for (const c of externClassDecls)
             this.namedTypes.set(c.name, "class");
         for (const c of classDecls)
-            if (c.typeParam)
-                this.genericTypeParams.set(c.name, c.typeParam);
+            if (c.typeParams.length > 0)
+                this.genericTypeParams.set(c.name, c.typeParams.map((p) => p.name));
         for (const i of interfaceDecls)
-            if (i.typeParam)
-                this.genericTypeParams.set(i.name, i.typeParam);
+            if (i.typeParams.length > 0)
+                this.genericTypeParams.set(i.name, i.typeParams.map((p) => p.name));
         for (const c of externClassDecls)
-            if (c.typeParam)
-                this.genericTypeParams.set(c.name, c.typeParam);
+            if (c.typeParams.length > 0)
+                this.genericTypeParams.set(c.name, c.typeParams.map((p) => p.name));
         for (const e of enumDecls)
             this.registerEnum(e);
         for (const i of interfaceDecls)
@@ -172,11 +174,11 @@ export class Checker {
         });
     }
     registerExternClass(decl) {
-        // Same withTypeParamInScope treatment registerClass gives a real class's
-        // signature (fields/methods/ctor params) — an extern class's own `T`
-        // needs to resolve the same way while its declared members are being
-        // resolved, e.g. `state<T> Value;` in an `extern class FormField<T>`.
-        const { fields, staticFields, methods, staticMethods, ownCtorParams } = this.withTypeParamInScope(decl.typeParam, () => {
+        // Same withTypeParamsInScope treatment registerClass gives a real class's
+        // signature (fields/methods/ctor params) — an extern class's own type
+        // params need to resolve the same way while its declared members are
+        // being resolved, e.g. `state<T> Value;` in an `extern class FormField<T>`.
+        const { fields, staticFields, methods, staticMethods, ownCtorParams } = this.withTypeParamsInScope(decl.typeParams, () => {
             const fields = new Map();
             const staticFields = new Map();
             for (const p of decl.properties) {
@@ -200,9 +202,11 @@ export class Checker {
         });
         this.classes.set(decl.name, {
             name: decl.name,
-            typeParam: decl.typeParam,
+            typeParams: decl.typeParams.map((p) => p.name),
             superclass: null,
+            superclassTypeArgs: null,
             interfaces: [],
+            interfaceTypeArgs: new Map(),
             fields,
             methods,
             staticFields,
@@ -341,8 +345,9 @@ export class Checker {
         });
         if (!resolved) {
             const name = node.kind === "NamedType" ? node.name : "[]";
-            if (name !== "[]" && this.genericTypeParams.has(name) && !node.typeArgs) {
-                this.diagnostics.error("KS4007", `Generic type '${name}' requires a type argument (e.g. '${name}<T>')`, line, col);
+            const declaredParams = this.genericTypeParams.get(name);
+            if (name !== "[]" && declaredParams && !node.typeArgs) {
+                this.diagnostics.error("KS4007", `Generic type '${name}' requires ${this.describeArity(declaredParams)} (e.g. '${name}<${declaredParams.join(", ")}>')`, line, col);
             }
             else {
                 this.diagnostics.error("KS4008", `Unknown type '${name}'`, line, col);
@@ -378,74 +383,137 @@ export class Checker {
                 return;
             case "class":
             case "interface": {
-                const isGeneric = this.genericTypeParams.has(type.name);
-                if (isGeneric && !type.typeArg) {
-                    this.diagnostics.error("KS4009", `Generic type '${type.name}' requires a type argument (e.g. '${type.name}<T>')`, line, col);
+                const declaredParams = this.genericTypeParams.get(type.name);
+                const suppliedCount = type.typeArgs?.length ?? 0;
+                if (declaredParams && suppliedCount === 0) {
+                    this.diagnostics.error("KS4009", `Generic type '${type.name}' requires ${this.describeArity(declaredParams)} (e.g. '${type.name}<${declaredParams.join(", ")}>')`, line, col);
                 }
-                else if (!isGeneric && type.typeArg) {
+                else if (!declaredParams && suppliedCount > 0) {
                     this.diagnostics.error("KS4010", `Type '${type.name}' is not generic — it doesn't take a type argument`, line, col);
                 }
-                if (type.typeArg)
-                    this.validateGenericArity(type.typeArg, line, col);
+                else if (declaredParams && suppliedCount > 0 && suppliedCount !== declaredParams.length) {
+                    this.diagnostics.error("KS4090", `Type '${type.name}' expects ${this.describeArity(declaredParams)}, got ${suppliedCount}`, line, col);
+                }
+                type.typeArgs?.forEach((a) => this.validateGenericArity(a, line, col));
                 return;
             }
             default:
                 return;
         }
     }
-    // Temporarily makes `name` (a class/interface's own type parameter, e.g.
-    // "T") resolve as a TypeParamType, for the duration of `fn` — used only
-    // while registering that class/interface's own declaration (fields,
-    // methods, ctor params), so `T Value;` resolves correctly. Scoped this
-    // narrowly (set, run, delete/restore) rather than left in `namedTypes`
-    // permanently, since it's only ever meaningful inside that one
-    // declaration's own body.
-    withTypeParamInScope(typeParam, fn) {
-        if (!typeParam)
+    describeArity(params) {
+        return params.length === 1 ? "a type argument" : `${params.length} type arguments`;
+    }
+    // Temporarily makes each of `typeParams` (a class/interface/function's own
+    // type parameters, e.g. ["K", "V"]) resolve as a TypeParamType, for the
+    // duration of `fn` — used only while registering that declaration's own
+    // signature (fields, methods, ctor/function params), so `T Value;`/`K
+    // key;` resolve correctly. Scoped this narrowly (set, run, delete/
+    // restore) rather than left in `namedTypes` permanently, since it's only
+    // ever meaningful inside that one declaration's own body.
+    withTypeParamsInScope(typeParams, fn) {
+        if (typeParams.length === 0)
             return fn();
-        const previous = this.namedTypes.get(typeParam);
-        this.namedTypes.set(typeParam, "typeParam");
+        const previous = typeParams.map((p) => this.namedTypes.get(p.name));
+        for (const p of typeParams)
+            this.namedTypes.set(p.name, "typeParam");
         try {
             return fn();
         }
         finally {
-            if (previous === undefined)
-                this.namedTypes.delete(typeParam);
-            else
-                this.namedTypes.set(typeParam, previous);
-        }
-    }
-    // Replaces every occurrence of the class/interface's own type parameter
-    // (by name) inside `type` with `arg` — the substitution step that turns
-    // Box<T>'s abstractly-stored field type `T` into `number` when someone
-    // actually asks about `Box<number>.Value`. A type with no occurrence of
-    // `paramName` anywhere in it is returned unchanged (including every
-    // non-generic type, the overwhelming majority).
-    substituteTypeParam(type, paramName, arg) {
+            typeParams.forEach((p, i) => {
+                const prev = previous[i];
+                if (prev === undefined)
+                    this.namedTypes.delete(p.name);
+                else
+                    this.namedTypes.set(p.name, prev);
+            });
+        }
+    }
+    // Replaces every occurrence of a type parameter named in `bindings`
+    // (mapping name -> concrete Type) inside `type` — the substitution step
+    // that turns Pair<K, V>'s abstractly-stored field type `K` into `number`
+    // when someone actually asks about `Pair<number, string>.First`. A type
+    // with none of `bindings`' names occurring anywhere in it is returned
+    // unchanged (including every non-generic type, the overwhelming majority).
+    substituteTypeParams(type, bindings) {
         switch (type.kind) {
             case "typeParam":
-                return type.name === paramName ? arg : type;
+                return bindings.get(type.name) ?? type;
             case "array":
-                return T.arrayOf(this.substituteTypeParam(type.element, paramName, arg));
+                return T.arrayOf(this.substituteTypeParams(type.element, bindings));
             case "nullable":
-                return T.nullableOf(this.substituteTypeParam(type.inner, paramName, arg));
+                return T.nullableOf(this.substituteTypeParams(type.inner, bindings));
             case "task":
-                return T.taskType(this.substituteTypeParam(type.resultType, paramName, arg));
+                return T.taskType(this.substituteTypeParams(type.resultType, bindings));
             case "state":
-                return T.stateType(this.substituteTypeParam(type.valueType, paramName, arg));
+                return T.stateType(this.substituteTypeParams(type.valueType, bindings));
             case "function":
-                return T.functionType(type.params.map((p) => this.substituteTypeParam(p, paramName, arg)), this.substituteTypeParam(type.returnType, paramName, arg));
-            // A nested generic's own type argument can itself mention the outer
-            // T (`Box<T[]>`'s field being List<T> — a v1 corner case, but cheap
-            // to handle correctly): substitute inside it too.
+                return T.functionType(type.params.map((p) => this.substituteTypeParams(p, bindings)), this.substituteTypeParams(type.returnType, bindings));
+            // A nested generic's own type arguments can themselves mention an
+            // outer type param (`Pair<K, V>`'s field being List<K> — a v1 corner
+            // case, but cheap to handle correctly): substitute inside each.
             case "class":
-                return type.typeArg ? T.classType(type.name, this.substituteTypeParam(type.typeArg, paramName, arg)) : type;
+                return type.typeArgs ? T.classType(type.name, type.typeArgs.map((a) => this.substituteTypeParams(a, bindings))) : type;
             case "interface":
-                return type.typeArg ? T.interfaceType(type.name, this.substituteTypeParam(type.typeArg, paramName, arg)) : type;
+                return type.typeArgs ? T.interfaceType(type.name, type.typeArgs.map((a) => this.substituteTypeParams(a, bindings))) : type;
             default:
                 return type;
         }
     }
+    // Builds the bindings map for a generic reference (a `ClassType`/
+    // `InterfaceType`'s own `typeArgs`, zipped against its declared
+    // `typeParams`) — the "own bindings" every member-lookup/conformance
+    // check starts from. Null when the reference isn't actually generic
+    // (no declared params) or carries no type arguments (an arity error
+    // already diagnosed elsewhere — see validateGenericArity).
+    ownBindings(typeParams, typeArgs) {
+        if (typeParams.length === 0 || !typeArgs)
+            return null;
+        return new Map(typeParams.map((name, i) => [name, typeArgs[i]]));
+    }
+    // Maps `typeParams` to themselves, as abstract TypeParamTypes — used when
+    // resolving a base-list/interface type argument that may reference the
+    // *declaring* class/interface's own (still-abstract) type parameter,
+    // rather than a concrete instantiation (see checkInterfaceConformance and
+    // the base(...) call check in checkClassBodyInner).
+    identityBindings(typeParams) {
+        return new Map(typeParams.map((name) => [name, T.typeParamType(name)]));
+    }
+    // One step of substitution composition, walking from a class/interface
+    // ("owner") to one of its own generic base-list entries. `baseArgs` are
+    // the type arguments `owner` supplied to `baseName` in its own base list
+    // — still in `owner`'s own type-param-name space (may reference `owner`'s
+    // own type parameters, not yet concrete). `ownerBindings` is `owner`'s
+    // current bindings at the point of this lookup. Returns `baseName`'s own
+    // bindings map (its declared type-param names -> resolved types), ready
+    // for the next composition step or a final substituteTypeParams call.
+    composeBaseBindings(baseName, baseArgs, ownerBindings) {
+        const baseParams = this.genericTypeParams.get(baseName) ?? [];
+        const resolvedArgs = baseArgs.map((t) => this.substituteTypeParams(t, ownerBindings));
+        return new Map(baseParams.map((name, i) => [name, resolvedArgs[i]]));
+    }
+    // Starting from `className` with its own bindings (from ownBindings,
+    // above — empty if non-generic or no type arguments), walks up the
+    // superclass chain composing each generic link's stored
+    // superclassTypeArgs, until it reaches `targetOwner` (the ancestor that
+    // actually declared the member being resolved — see lookupField/
+    // lookupMethod/etc.'s `owner` result). Returns the bindings in
+    // `targetOwner`'s own type-param-name space. A non-generic link along the
+    // way (superclassTypeArgs null) resets to empty bindings, same as today's
+    // behavior of never substituting through a non-generic ancestor.
+    bindingsAtAncestor(className, ownBindings, targetOwner) {
+        let current = className;
+        let bindings = ownBindings;
+        while (current !== targetOwner) {
+            const info = this.classes.get(current);
+            if (!info || !info.superclass)
+                return bindings;
+            bindings = info.superclassTypeArgs ? this.composeBaseBindings(info.superclass, info.superclassTypeArgs, bindings) : new Map();
+            current = info.superclass;
+        }
+        return bindings;
+    }
     registerEnum(decl) {
         const members = new Map();
         decl.members.forEach((name, index) => {
@@ -459,29 +527,32 @@ export class Checker {
         this.recordHover(decl.line, decl.col, `enum ${decl.name}`);
     }
     registerInterface(decl) {
-        const methods = this.withTypeParamInScope(decl.typeParam, () => decl.methods.map((m) => {
-            const params = m.params.map((p) => this.resolveType(p.type, m.line, m.col));
-            const returnType = this.resolveType(m.returnType, m.line, m.col);
-            this.recordHover(m.nameLine, m.nameCol, `${m.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
-            return { name: m.name, params, returnType };
-        }));
-        const bases = [];
-        for (const baseName of decl.baseList) {
-            if (this.namedTypes.get(baseName) !== "interface") {
-                this.diagnostics.error("KS4012", `Interface '${decl.name}' can only extend other interfaces (unknown interface '${baseName}')`, decl.line, decl.col);
-                continue;
-            }
-            // v1 generics can't appear in a base list at all — only as a
-            // standalone type (field/param/return/local, `new Box<T>()`). A
-            // class/interface always implements/extends a *bare* name.
-            if (this.genericTypeParams.has(baseName)) {
-                this.diagnostics.error("KS4013", `Interface '${decl.name}' cannot extend generic interface '${baseName}' — not supported in v1`, decl.line, decl.col);
-                continue;
+        const genericBaseCount = { count: 0 };
+        const { methods, bases, baseTypeArgs } = this.withTypeParamsInScope(decl.typeParams, () => {
+            const methods = decl.methods.map((m) => {
+                const params = m.params.map((p) => this.resolveType(p.type, m.line, m.col));
+                const returnType = this.resolveType(m.returnType, m.line, m.col);
+                this.recordHover(m.nameLine, m.nameCol, `${m.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
+                return { name: m.name, params, returnType };
+            });
+            const bases = [];
+            const baseTypeArgs = new Map();
+            for (const entry of decl.baseList) {
+                if (this.namedTypes.get(entry.name) !== "interface") {
+                    this.diagnostics.error("KS4012", `Interface '${decl.name}' can only extend other interfaces (unknown interface '${entry.name}')`, decl.line, decl.col);
+                    continue;
+                }
+                bases.push(entry.name);
+                if (entry.typeArgs || this.genericTypeParams.has(entry.name)) {
+                    const resolved = this.resolveBaseTypeArgs(decl.name, entry.name, entry.typeArgs, decl.line, decl.col, genericBaseCount);
+                    if (resolved)
+                        baseTypeArgs.set(entry.name, resolved);
+                }
             }
-            bases.push(baseName);
-        }
-        this.interfaces.set(decl.name, { name: decl.name, typeParam: decl.typeParam, bases, methods });
-        this.recordHover(decl.line, decl.col, decl.typeParam ? `interface ${decl.name}<${decl.typeParam}>` : `interface ${decl.name}`);
+            return { methods, bases, baseTypeArgs };
+        });
+        this.interfaces.set(decl.name, { name: decl.name, typeParams: decl.typeParams.map((p) => p.name), bases, baseTypeArgs, methods });
+        this.recordHover(decl.line, decl.col, decl.typeParams.length > 0 ? `interface ${decl.name}<${decl.typeParams.map((p) => p.name).join(", ")}>` : `interface ${decl.name}`);
     }
     checkInterfaceHierarchy(decl) {
         const info = this.interfaces.get(decl.name);
@@ -504,16 +575,31 @@ export class Checker {
         }
     }
     // All methods required to satisfy an interface: its own plus every
-    // transitively-inherited parent interface's (cycle-safe).
-    collectInterfaceMethods(interfaceName, seen = new Set()) {
+    // transitively-inherited parent interface's (cycle-safe). `bindings` maps
+    // `interfaceName`'s own type-param names to resolved types (from
+    // ownBindings, at the root call — see its two call sites) — every
+    // returned signature is substituted through it, and a generic base link
+    // along the way (`interface IDerived<T> : IBase<T>`) composes its own
+    // stored baseTypeArgs through `bindings` before recursing, so a signature
+    // inherited from several generic-base links up still resolves correctly.
+    collectInterfaceMethods(interfaceName, bindings = new Map(), seen = new Set()) {
         if (seen.has(interfaceName))
             return [];
         seen.add(interfaceName);
         const info = this.interfaces.get(interfaceName);
         if (!info)
             return [];
-        const inherited = info.bases.flatMap((b) => this.collectInterfaceMethods(b, seen));
-        return [...inherited, ...info.methods];
+        const inherited = info.bases.flatMap((b) => {
+            const baseArgs = info.baseTypeArgs.get(b);
+            const baseBindings = baseArgs ? this.composeBaseBindings(b, baseArgs, bindings) : new Map();
+            return this.collectInterfaceMethods(b, baseBindings, seen);
+        });
+        const ownMethods = info.methods.map((m) => ({
+            name: m.name,
+            params: m.params.map((p) => this.substituteTypeParams(p, bindings)),
+            returnType: this.substituteTypeParams(m.returnType, bindings),
+        }));
+        return [...inherited, ...ownMethods];
     }
     interfaceExtends(sub, sup) {
         if (sub === sup)
@@ -524,8 +610,9 @@ export class Checker {
         return info.bases.some((b) => this.interfaceExtends(b, sup));
     }
     registerClass(decl) {
-        this.recordHover(decl.line, decl.col, decl.typeParam ? `class ${decl.name}<${decl.typeParam}>` : `class ${decl.name}`);
-        const { fields, staticFields, methods, staticMethods, ownCtorParams } = this.withTypeParamInScope(decl.typeParam, () => {
+        this.recordHover(decl.line, decl.col, decl.typeParams.length > 0 ? `class ${decl.name}<${decl.typeParams.map((p) => p.name).join(", ")}>` : `class ${decl.name}`);
+        const genericBaseCount = { count: 0 };
+        const { fields, staticFields, methods, staticMethods, ownCtorParams, superclass, superclassTypeArgs, interfaces, interfaceTypeArgs } = this.withTypeParamsInScope(decl.typeParams, () => {
             const fields = new Map();
             const staticFields = new Map();
             for (const f of decl.fields) {
@@ -554,39 +641,46 @@ export class Checker {
             const ownCtorParams = decl.constructor
                 ? decl.constructor.params.map((p) => this.resolveType(p.type, decl.constructor.line, decl.constructor.col))
                 : null;
-            return { fields, staticFields, methods, staticMethods, ownCtorParams };
-        });
-        let superclass = null;
-        const interfaces = [];
-        for (const baseName of decl.baseList) {
-            // v1 generics can't appear in a base list at all — only as a
-            // standalone type (field/param/return/local, `new Box<T>()`). A
-            // class always extends/implements a *bare* name.
-            if (this.genericTypeParams.has(baseName)) {
-                this.diagnostics.error("KS4015", `Class '${decl.name}' cannot extend/implement generic type '${baseName}' — not supported in v1`, decl.line, decl.col);
-                continue;
-            }
-            const kind = this.namedTypes.get(baseName);
-            if (kind === "class") {
-                if (superclass !== null) {
-                    this.diagnostics.error("KS4016", `Class '${decl.name}' cannot extend multiple classes ('${superclass}' and '${baseName}')`, decl.line, decl.col);
+            // Base-list resolution runs in this same scope — so `Box<T>` in
+            // `class Container<T> : Box<T>` resolves its inner `T` as
+            // Container's own type parameter, exactly like a field type would.
+            let superclass = null;
+            let superclassTypeArgs = null;
+            const interfaces = [];
+            const interfaceTypeArgs = new Map();
+            for (const entry of decl.baseList) {
+                const kind = this.namedTypes.get(entry.name);
+                if (kind === "class") {
+                    if (superclass !== null) {
+                        this.diagnostics.error("KS4016", `Class '${decl.name}' cannot extend multiple classes ('${superclass}' and '${entry.name}')`, decl.line, decl.col);
+                        continue;
+                    }
+                    superclass = entry.name;
+                    if (entry.typeArgs || this.genericTypeParams.has(entry.name)) {
+                        superclassTypeArgs = this.resolveBaseTypeArgs(decl.name, entry.name, entry.typeArgs, decl.line, decl.col, genericBaseCount);
+                    }
+                }
+                else if (kind === "interface") {
+                    interfaces.push(entry.name);
+                    if (entry.typeArgs || this.genericTypeParams.has(entry.name)) {
+                        const resolved = this.resolveBaseTypeArgs(decl.name, entry.name, entry.typeArgs, decl.line, decl.col, genericBaseCount);
+                        if (resolved)
+                            interfaceTypeArgs.set(entry.name, resolved);
+                    }
                 }
                 else {
-                    superclass = baseName;
+                    this.diagnostics.error("KS4017", `Unknown base class or interface '${entry.name}'`, decl.line, decl.col);
                 }
             }
-            else if (kind === "interface") {
-                interfaces.push(baseName);
-            }
-            else {
-                this.diagnostics.error("KS4017", `Unknown base class or interface '${baseName}'`, decl.line, decl.col);
-            }
-        }
+            return { fields, staticFields, methods, staticMethods, ownCtorParams, superclass, superclassTypeArgs, interfaces, interfaceTypeArgs };
+        });
         this.classes.set(decl.name, {
             name: decl.name,
-            typeParam: decl.typeParam,
+            typeParams: decl.typeParams.map((p) => p.name),
             superclass,
+            superclassTypeArgs,
             interfaces,
+            interfaceTypeArgs,
             fields,
             methods,
             staticFields,
@@ -594,6 +688,35 @@ export class Checker {
             ownCtorParams,
         });
     }
+    // Resolves a base-list entry's own type arguments against `baseName`'s
+    // declared arity — `typeArgNodes` is null when the entry was written bare
+    // (`: Box`, not `: Box<number>`). Must be called from inside the
+    // declaring class/interface's own withTypeParamsInScope, so a type
+    // argument that references the declaring type's own parameter (`Box<T>`
+    // in `class Container<T> : Box<T>`) resolves correctly. `genericBaseCount`
+    // is a shared mutable counter across one declaration's whole base list,
+    // enforcing v1's "at most one generic entry per base list" cut.
+    resolveBaseTypeArgs(declName, baseName, typeArgNodes, declLine, declCol, genericBaseCount) {
+        const declaredParams = this.genericTypeParams.get(baseName);
+        if (!declaredParams) {
+            if (typeArgNodes)
+                this.diagnostics.error("KS4092", `'${baseName}' is not generic — it doesn't take a type argument`, declLine, declCol);
+            return null;
+        }
+        if (!typeArgNodes) {
+            this.diagnostics.error("KS4093", `Generic base '${baseName}' requires ${this.describeArity(declaredParams)} (e.g. '${baseName}<${declaredParams.join(", ")}>')`, declLine, declCol);
+            return null;
+        }
+        if (typeArgNodes.length !== declaredParams.length) {
+            this.diagnostics.error("KS4094", `Generic base '${baseName}' expects ${this.describeArity(declaredParams)}, got ${typeArgNodes.length}`, declLine, declCol);
+            return null;
+        }
+        genericBaseCount.count++;
+        if (genericBaseCount.count > 1) {
+            this.diagnostics.error("KS4095", `'${declName}' has more than one generic entry in its base list — v1 supports at most one`, declLine, declCol);
+        }
+        return typeArgNodes.map((a) => this.resolveType(a, declLine, declCol));
+    }
     checkClassHierarchy(decl) {
         const info = this.classes.get(decl.name);
         this.checkBaseCall(decl, info);
@@ -671,10 +794,19 @@ export class Checker {
     }
     checkInterfaceConformance(decl) {
         const classInfo = this.classes.get(decl.name);
+        // This is a conformance check against the class's own *declared*
+        // (still-abstract) signatures, not an instantiated use site, so a
+        // generic interface arg that references the class's own type param
+        // (`IContainer<T>` in `class Container<T> : IContainer<T>`) should
+        // compose down to that same abstract TypeParamType, matching how the
+        // class's own methods are stored — see identityBindings.
+        const selfBindings = this.identityBindings(classInfo.typeParams);
         for (const ifaceName of classInfo.interfaces) {
             if (!this.interfaces.has(ifaceName))
                 continue; // already reported as an unknown base type
-            for (const sig of this.collectInterfaceMethods(ifaceName)) {
+            const ifaceArgs = classInfo.interfaceTypeArgs.get(ifaceName);
+            const bindings = ifaceArgs ? this.composeBaseBindings(ifaceName, ifaceArgs, selfBindings) : new Map();
+            for (const sig of this.collectInterfaceMethods(ifaceName, bindings)) {
                 const found = this.lookupMethod(decl.name, sig.name);
                 if (!found) {
                     this.diagnostics.error("KS4026", `Class '${decl.name}' does not implement method '${sig.name}' required by interface '${ifaceName}'`, decl.line, decl.col);
@@ -825,11 +957,11 @@ export class Checker {
     // only ever arises from an arity error already diagnosed at the
     // reference site — see validateGenericArity).
     typeArgsMatch(a, b) {
-        if (!a.typeArg && !b.typeArg)
+        if (!a.typeArgs && !b.typeArgs)
             return true;
-        if (!a.typeArg || !b.typeArg)
+        if (!a.typeArgs || !b.typeArgs || a.typeArgs.length !== b.typeArgs.length)
             return false;
-        return T.typesEqual(a.typeArg, b.typeArg);
+        return a.typeArgs.every((t, i) => T.typesEqual(t, b.typeArgs[i]));
     }
     // ---------- top-level ----------
     // Validates that `isAsync` and the declared return type agree — `async`
@@ -867,12 +999,12 @@ export class Checker {
     }
     checkClassBody(decl) {
         // Constructor/method *bodies* run in this same scope registerClass used
-        // for the *signatures* (see withTypeParamInScope) — without it, `T`
+        // for the *signatures* (see withTypeParamsInScope) — without it, `T`
         // resolves everywhere in a generic class's declared field/param/return
         // types but not inside a method body itself (a local `T x = ...;`, or a
         // lambda parameter typed `T`), which would make the type parameter
         // usable only at the class's boundary and not inside its own logic.
-        this.withTypeParamInScope(decl.typeParam, () => this.checkClassBodyInner(decl));
+        this.withTypeParamsInScope(decl.typeParams, () => this.checkClassBodyInner(decl));
     }
     checkClassBodyInner(decl) {
         const info = this.classes.get(decl.name);
@@ -883,7 +1015,18 @@ export class Checker {
             // params but no `this` — matching real base()/super() semantics,
             // which must run before `this` becomes available.
             if (decl.constructor.baseArgs && info.superclass) {
-                const baseCtorParams = this.lookupCtorParams(info.superclass);
+                // One step from `decl` to its immediate superclass (Container's own
+                // type params, still abstract, composed through whatever it
+                // supplied Box in its base list — see identityBindings), then
+                // however many further steps lookupCtorParams' own `owner` implies
+                // (Box itself has no constructor of its own, inherits its
+                // superclass's) via bindingsAtAncestor.
+                const superBindings = info.superclassTypeArgs
+                    ? this.composeBaseBindings(info.superclass, info.superclassTypeArgs, this.identityBindings(info.typeParams))
+                    : new Map();
+                const { params: rawBaseCtorParams, owner: baseCtorOwner } = this.lookupCtorParams(info.superclass);
+                const baseCtorBindings = this.bindingsAtAncestor(info.superclass, superBindings, baseCtorOwner);
+                const baseCtorParams = rawBaseCtorParams.map((p) => this.substituteTypeParams(p, baseCtorBindings));
                 const baseCtx = { returnType: T.VOID, currentClass: info, inConstructor: false, loopDepth: 0, isAsync: false };
                 if (decl.constructor.baseArgs.length !== baseCtorParams.length) {
                     this.diagnostics.error("KS4032", `Expected ${baseCtorParams.length} base constructor argument(s), got ${decl.constructor.baseArgs.length}`, decl.constructor.line, decl.constructor.col);
@@ -1461,31 +1604,40 @@ export class Checker {
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
-        let typeArg;
-        if (info.typeParam && !expr.typeArgs) {
-            this.diagnostics.error("KS4069", `Generic class '${expr.className}' requires a type argument (e.g. 'new ${expr.className}<T>(...)')`, expr.line, expr.col);
+        let typeArgs;
+        if (info.typeParams.length > 0 && !expr.typeArgs) {
+            this.diagnostics.error("KS4069", `Generic class '${expr.className}' requires ${this.describeArity(info.typeParams)} (e.g. 'new ${expr.className}<${info.typeParams.join(", ")}>(...)')`, expr.line, expr.col);
             // Abstractly-typed (T-containing) ctor params, un-substitutable
-            // without a real type argument, would otherwise cascade into a
+            // without real type arguments, would otherwise cascade into a
             // confusing "expected 'T'" error on every argument — one clear error
             // beats that pile-on.
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
-        if (!info.typeParam && expr.typeArgs) {
+        if (info.typeParams.length === 0 && expr.typeArgs) {
             this.diagnostics.error("KS4070", `Class '${expr.className}' is not generic — it doesn't take a type argument`, expr.line, expr.col);
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
-        if (info.typeParam && expr.typeArgs) {
-            typeArg = this.resolveType(expr.typeArgs[0], expr.line, expr.col);
-        }
-        this.recordHover(expr.line, expr.col, typeArg ? `class ${expr.className}<${T.typeToString(typeArg)}>` : `class ${expr.className}`);
-        let ctorParams = this.lookupCtorParams(expr.className);
-        if (info.typeParam && typeArg) {
-            const paramName = info.typeParam;
-            const arg = typeArg;
-            ctorParams = ctorParams.map((p) => this.substituteTypeParam(p, paramName, arg));
-        }
+        if (info.typeParams.length > 0 && expr.typeArgs) {
+            if (expr.typeArgs.length !== info.typeParams.length) {
+                this.diagnostics.error("KS4091", `Generic class '${expr.className}' expects ${this.describeArity(info.typeParams)}, got ${expr.typeArgs.length}`, expr.line, expr.col);
+                expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+                return T.UNKNOWN;
+            }
+            typeArgs = expr.typeArgs.map((a) => this.resolveType(a, expr.line, expr.col));
+        }
+        this.recordHover(expr.line, expr.col, typeArgs ? `class ${expr.className}<${typeArgs.map(T.typeToString).join(", ")}>` : `class ${expr.className}`);
+        // The constructor being called may be inherited from a generic
+        // ancestor several base-list links up (e.g. `new NumberBox(5)` where
+        // `NumberBox : Box<number>` has no constructor of its own) — compose
+        // bindings all the way to whichever class's own constructor
+        // lookupCtorParams actually found (bindingsAtAncestor is a no-op single
+        // step when it's expr.className's own, the common case).
+        const { params: rawCtorParams, owner: ctorOwner } = this.lookupCtorParams(expr.className);
+        const ownCtorBindings = this.ownBindings(info.typeParams, typeArgs) ?? new Map();
+        const ctorBindings = this.bindingsAtAncestor(expr.className, ownCtorBindings, ctorOwner);
+        const ctorParams = rawCtorParams.map((p) => this.substituteTypeParams(p, ctorBindings));
         if (expr.args.length !== ctorParams.length) {
             this.diagnostics.error("KS4071", `Expected ${ctorParams.length} constructor argument(s), got ${expr.args.length}`, expr.line, expr.col);
         }
@@ -1496,19 +1648,25 @@ export class Checker {
                 this.diagnostics.error("KS4072", `Constructor argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
             }
         });
-        return T.classType(expr.className, typeArg);
-    }
+        return T.classType(expr.className, typeArgs);
+    }
+    // `owner` is which class up the chain actually declared the constructor
+    // being inherited (itself, or the nearest ancestor with one) — needed so
+    // a caller can compose the right type-parameter bindings when that
+    // ancestor is a generic base (see bindingsAtAncestor). `params` is stored
+    // abstractly in `owner`'s own type-param-name space, same as a field or
+    // method's type would be.
     lookupCtorParams(className) {
         let current = className;
         while (current) {
             const info = this.classes.get(current);
             if (!info)
-                return [];
+                return { params: [], owner: className };
             if (info.ownCtorParams !== null)
-                return info.ownCtorParams;
+                return { params: info.ownCtorParams, owner: current };
             current = info.superclass;
         }
-        return [];
+        return { params: [], owner: className };
     }
     // Array stdlib with a fixed (non-polymorphic) signature, given the
     // array's own element type — everything except Map, which checkCall
@@ -1646,12 +1804,14 @@ export class Checker {
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "class") {
-            // v1 has no generic inheritance (a generic class's base list can only
-            // name non-generic types), so a member found on a generic instance
-            // was always declared directly on that same class — substituting by
-            // its own type parameter, not some ancestor's, is always correct.
-            const paramName = objectType.typeArg ? this.genericTypeParams.get(objectType.name) : undefined;
-            const substitute = (type) => (paramName && objectType.typeArg ? this.substituteTypeParam(type, paramName, objectType.typeArg) : type);
+            // A member found on an *ancestor* (owner !== objectType.name — v1 now
+            // supports a generic superclass, see registerClass/
+            // bindingsAtAncestor) needs bindings composed through however many
+            // generic base links separate objectType from that ancestor, not just
+            // objectType's own type arguments — bindingsAtAncestor does that walk
+            // (a no-op single step when owner IS objectType.name, the common
+            // case, same result as before this existed).
+            const ownBindings = this.ownBindings(this.genericTypeParams.get(objectType.name) ?? [], objectType.typeArgs) ?? new Map();
             const field = this.lookupField(objectType.name, expr.property);
             if (field) {
                 this.checkAccessibility(field.info.visibility, field.owner, ctx, expr.property, expr.line, expr.col);
@@ -1661,28 +1821,32 @@ export class Checker {
                         this.diagnostics.error("KS4082", `'${expr.property}' has no setter and can only be assigned within ${field.owner}'s constructor`, expr.line, expr.col);
                     }
                 }
-                return { type: substitute(field.info.type), methodInfo: null };
+                const bindings = this.bindingsAtAncestor(objectType.name, ownBindings, field.owner);
+                return { type: this.substituteTypeParams(field.info.type, bindings), methodInfo: null };
             }
             const method = this.lookupMethod(objectType.name, expr.property);
             if (method) {
                 this.checkAccessibility(method.info.visibility, method.owner, ctx, expr.property, expr.line, expr.col);
-                const info = paramName ? { ...method.info, params: method.info.params.map(substitute), returnType: substitute(method.info.returnType) } : method.info;
+                const bindings = this.bindingsAtAncestor(objectType.name, ownBindings, method.owner);
+                const info = {
+                    ...method.info,
+                    params: method.info.params.map((p) => this.substituteTypeParams(p, bindings)),
+                    returnType: this.substituteTypeParams(method.info.returnType, bindings),
+                };
                 return { type: info.returnType, methodInfo: info };
             }
             this.diagnostics.error("KS4083", `Class '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "interface") {
-            const sig = this.collectInterfaceMethods(objectType.name).find((m) => m.name === expr.property);
+            // collectInterfaceMethods itself now substitutes through `bindings` —
+            // including across a generic base-interface link — so passing
+            // objectType's own bindings once at the root is enough; no separate
+            // re-substitution needed here (see its own header comment).
+            const ownBindings = this.ownBindings(this.genericTypeParams.get(objectType.name) ?? [], objectType.typeArgs) ?? new Map();
+            const sig = this.collectInterfaceMethods(objectType.name, ownBindings).find((m) => m.name === expr.property);
             if (sig) {
-                // v1 has no generic interface inheritance either (same restriction
-                // as classes — see registerInterface), so a signature found here
-                // was always declared directly on this same interface.
-                const paramName = objectType.typeArg ? this.genericTypeParams.get(objectType.name) : undefined;
-                const substitute = (type) => (paramName && objectType.typeArg ? this.substituteTypeParam(type, paramName, objectType.typeArg) : type);
-                const params = sig.params.map(substitute);
-                const returnType = substitute(sig.returnType);
-                return { type: returnType, methodInfo: { params, returnType, visibility: "public", isVirtual: false, isOverride: false } };
+                return { type: sig.returnType, methodInfo: { params: sig.params, returnType: sig.returnType, visibility: "public", isVirtual: false, isOverride: false } };
             }
             this.diagnostics.error("KS4084", `Interface '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };