kopscript 0.13.0 → 0.15.0

package/LLM.md

@@ -75,9 +75,10 @@ below). No circular `using` (compile error).
 **Does not exist**: `any`/`unknown` as a writable annotation, a `let`/`var` keyword (see
 Declarations below — there isn't one), type inference for declarations (every
 local/`const`/param/field/return type is written out explicitly), union types, tuples,
-structural/duck typing (all typing is nominal). Generics exist but are deliberately
-scoped down — see the Generics section for exactly what's NOT supported there (multiple
-type parameters, constraints, generic functions, generic inheritance).
+structural/duck typing (all typing is nominal). Generics exist and cover multiple type
+parameters, single-interface constraints, generic inheritance, and free generic functions
+— see the Generics section for exactly what's still NOT supported there (variance,
+multiple constraints per parameter, generic methods).
 
 ## Declarations
 
@@ -303,9 +304,10 @@ class Pair<K, V> {
 Pair<number, string> p = new Pair<number, string>(1, "a");
 ```
 
-One or more unconstrained, invariant type parameters per class/interface (real *or*
-`extern` — see the `extern` section below), comma-separated: `<T>`, `<K, V>`, `<A, B, C>`,
-however many the declaration needs.
+One or more invariant type parameters per class/interface (real *or* `extern` — see the
+`extern` section below), comma-separated: `<T>`, `<K, V>`, `<A, B, C>`, however many the
+declaration needs — each optionally constrained to a single interface: `<T : IComparable>`,
+`<K : IHashable, V>` (mixing constrained and unconstrained params is fine).
 Erased at codegen (JS has no generics either; `Box<number>` and `Box<string>` both
 compile to the exact same plain `class Box`), so there's no runtime cost and no way to
 inspect a type parameter at runtime.
@@ -322,10 +324,30 @@ inspect a type parameter at runtime.
 - Nesting works: `Box<Box<number>>`, `Box<number[]>`, `Box<number>?`, `Box<number>?[]`,
   `Pair<number, Pair<string, bool>>`.
 - Inside the class/interface's own body, each type parameter is fully abstract — you can
-  store it, return it, pass it around, but (unconstrained) you **cannot call any member on
-  a bare type-parameter value** (`this.value.Foo()` where `value: T` is a compile error:
-  "Cannot access member 'Foo' on type 'T'"). This is correct, not a bug — same as an
-  unconstrained type parameter in C#/Java/TypeScript.
+  store it, return it, pass it around, but an **unconstrained** parameter (no `: IFoo`)
+  means you **cannot call any member on a bare type-parameter value** (`this.value.Foo()`
+  where `value: T` is a compile error: "Cannot access member 'Foo' on type 'T'"). This is
+  correct, not a bug — same as an unconstrained type parameter in C#/Java/TypeScript.
+
+**Constraints**: `<T : IComparable>` lifts the "no member calls" restriction — a member
+call on a constrained `T` resolves against the constraint interface's own signature:
+```ks
+interface IComparable { number CompareTo(); }
+class Box<T : IComparable> {
+  public T Value;
+  constructor(T v) { this.Value = v; }
+  public number Compare() { return this.Value.CompareTo(); } // legal — T : IComparable
+}
+Box<Money> b = new Box<Money>(new Money(5));   // Money must implement IComparable
+```
+A type argument satisfies a constraint by implementing the interface directly, through an
+ancestor (`classImplementsInterface` walks the whole superclass chain), or — inside another
+generic body — by already being an equally- or more-constrained type parameter of its own
+(`class Wrapper<T : IComparable> { Box<T> MakeBox(T v) { return new Box<T>(v); } }` is
+legal without ever naming a concrete type). Checked everywhere a type argument is bound: on
+`new`, on a bare generic type reference, and on a generic base in a base list.
+**v1 limit**: at most one constraint per parameter (`T : IFoo, IBar` isn't supported), and
+the constraint must be an interface, never a class.
 
 **Generic inheritance**: a class/interface base list CAN name a generic base, with its own
 type arguments, in either direction:
@@ -345,12 +367,30 @@ implemented/extended interface — never more than one) — `class Foo<T> : Box<
 IContainer<T>` is a compile error ("has more than one generic entry in its base list") even
 though either half alone would work.
 
+**Generic functions**: only free/top-level functions, never a method inside a class (a
+method still only ever uses its enclosing class's own type parameters):
+```ks
+T Identity<T>(T x) { return x; }
+number n = Identity(5);       // T inferred as number, from the argument
+string s = Identity("hi");    // T inferred as string, independently
+```
+**No explicit type argument at a call site** — `Identity<number>(5)` isn't valid syntax;
+`T` is always inferred from the actual argument types by structurally unifying each
+declared (possibly abstract) parameter type against its argument's real type — including
+through a nested generic type (`T Unwrap<T>(Box<T> b)` infers `T` from `Box<number>`) or a
+lambda argument's own explicit parameter type (`void UseCallback<T>((T) => void cb)` infers
+`T` from `(number n) => ...`). This is a real grammar constraint, not a missing feature:
+`new Box<number>(...)` disambiguates `<` from a comparison only because `new` is a distinct
+keyword context — a bare call has no such anchor, so `f<T>(x)` would be genuinely ambiguous
+with a chained `<`/`>` comparison. If no argument determines a declared type parameter, or
+two arguments would bind it to conflicting types, that's a compile error naming the
+parameter, not a syntax feature to reach for. A constrained type parameter (`T :
+IComparable`) works exactly like it does on a class — the inferred type must satisfy it,
+checked after inference succeeds.
+
 **Does not exist (v1 scope cuts, each deliberate)**:
-- **Generic functions.** `T Identity<T>(T x)` doesn't parse — only classes and interfaces
-  take type parameters, not free functions/methods themselves (a method *inside* a
-  generic class can use that class's own type parameters freely, same as any other member).
-- **Constraints.** No `T : IComparable` — a type parameter is always fully unconstrained,
-  which is why you can't call members on a bare one (see above).
+- **Generic methods.** A class method can't introduce its own new type parameter beyond
+  its enclosing class's (generic functions are free-function-only — see above).
 - **Variance.** No `out`/`in`/covariance/contravariance — see invariance above.
 
 ## Nullable types — `T?`
@@ -428,13 +468,14 @@ KopScript-declared name exactly. Extern class members use real JS member names v
 (camelCase, no rename mechanism). No inheritance modeling between two `extern class`
 declarations — each stands alone.
 
-`extern class` can carry type parameters (`extern class Box<T> { constructor(T v); T Value
-{ get; } } from "some-package";`) — identical rules to a real generic class (see "Generics"
-above: one or more unconstrained invariant parameters, erased, generic inheritance
-included), so a generic type from another package instantiates and type-checks exactly
-like a local one (`Box<number>`, arity/invariance errors included) — and a real KopScript
-class can extend a generic `extern class` with a concrete or threaded-through type
-argument, same as extending a real generic base.
+`extern class` can carry type parameters, optionally constrained (`extern class Box<T :
+IComparable> { constructor(T v); T Value { get; } } from "some-package";`) — identical
+rules to a real generic class (see "Generics" above: invariant, erased, generic
+inheritance and constraints both included), so a generic type from another package
+instantiates and type-checks exactly like a local one (`Box<number>`, arity/invariance/
+constraint errors included) — and a real KopScript class can extend a generic `extern
+class` with a concrete or threaded-through type argument, same as extending a real generic
+base.
 
 **Never write `async` on an extern function/method signature** — declare its return type
 as `task`/`task<T>` directly (`task<string> text();`, not `async task<string> text();`).
@@ -521,10 +562,11 @@ Locals/params: **camelCase**. This is convention, not enforced by the compiler.
 
 ## Does not exist (don't reach for these)
 
-Generics beyond one or more unconstrained type parameters and single-generic-base
-inheritance (no `T : IFoo` constraints, no generic functions, no variance, no more than one
-generic entry per base list — see Generics above for what *is* supported) ·
-`any`/`unknown` annotations ·
+Generics beyond one or more type parameters (each with at most one interface constraint),
+single-generic-base inheritance, and free (never method-level) generic functions with
+inference-only call sites (no `T : IFoo, IBar` multi-constraints, no explicit
+`Identity<number>(5)` type arguments, no variance, no more than one generic entry per base
+list — see Generics above for what *is* supported) · `any`/`unknown` annotations ·
 a `let`/`var` keyword (locals are just `Type name = value;`) · decorators/annotations ·
 reflection · type inference on declarations · ternary expression · union/tuple types ·
 **object-literal syntax** (`{ key: value }` as a value — this doesn't exist *anywhere* in
@@ -559,9 +601,12 @@ Real, observed cases where a plausible-looking guess was wrong — not hypotheti
   dedicated rewriter, `qualifyThis`, specifically because this isn't automatic.)
 - **No `let`/`var`, ever.** Every local is `Type name = value;` — writing `let x = 5;` or a
   bare `const x = 5;` (missing the type) is a parse error, not a lenient inferred form.
-- **No generic functions.** `T Identity<T>(T x) { return x; }` doesn't parse — only classes
-  and interfaces take `<T>`. Don't reach for this even though every mainstream generic
-  language supports it.
+- **No explicit type argument at a generic function call site.** `Identity<number>(5)`
+  doesn't parse — a bare call has no keyword like `new` to disambiguate `<` from a
+  comparison, so type arguments are always inferred from the actual arguments instead.
+  Just call `Identity(5)`; if inference can't determine a type parameter, restructure the
+  call (e.g. an argument that actually mentions the type) rather than reaching for explicit
+  syntax that isn't there.
 - **Early-return doesn't narrow a nullable type.** `if (x == null) { return; } print(x.Length);`
   still errors on `x.Length` — narrowing is scope-based (an `if`/`else` block), not
   control-flow/reachability-based. Wrap the rest of the logic in the `if (x != null) { ... }`

package/README.md

@@ -22,9 +22,11 @@ LLM's context, as opposed to this README's narrative explanation.
   explicit `virtual`/`override` dispatch (methods are sealed unless marked `virtual`), and a full
   `public`/`protected`/`private` access model enforced at compile time.
 - **Strongly typed**: every declaration is explicitly typed and checked at compile time.
-- **Generics**: one or more unconstrained, invariant type parameters on classes and
-  interfaces (`class Box<T> { public T Value; }`, `class Pair<K, V> { ... }`) — erased at
-  codegen with zero runtime cost, the same way `task<T>`/`state<T>` already are.
+- **Generics**: one or more invariant type parameters on classes, interfaces, and free
+  functions (`class Box<T> { public T Value; }`, `T Identity<T>(T x) { return x; }`), each
+  optionally constrained to an interface (`class Box<T : IComparable> { ... }`), plus
+  generic inheritance (`class IntBox : Box<number> { }`) — erased at codegen with zero
+  runtime cost, the same way `task<T>`/`state<T>` already are.
 - **Nullable types with compiler-enforced null-checking**: `T?` (`string?`, `Dog?`,
   `number[]?`) — a `T?` can't be used where a `T` is expected without an `if (x != null)`
   check first (checked statically, not just at runtime), and comparing a value that can
@@ -253,16 +255,29 @@ compile to the identical plain `class Box`, so there's no runtime cost.
 Still a deliberately small slice of generics, not a scaled-down promise of more later
 inside v1:
 
-- **Invariant, unconstrained.** No `T : ISomething` (constraints) — and because a type
-  parameter is fully unconstrained, you can't call any member on a bare `T`/`K`/`V` value
-  inside the generic class's own body (that's correct behavior, the same restriction
-  C#/Java/TypeScript put on an unconstrained parameter, not a bug). Invariant means
-  `Box<Dog>` is **not** assignable to `Box<Animal>` even though `Dog : Animal`, and
-  `Pair<number, string>` is not assignable to `Pair<string, number>` — every slot must
-  match exactly, in order.
-- **No generic functions.** `T Identity<T>(T x)` isn't supported — only classes and
-  interfaces take type parameters. A method *inside* a generic class can still use that
-  class's own type parameters freely; it's just not introducing one of its own.
+- **Invariant.** `Box<Dog>` is **not** assignable to `Box<Animal>` even though `Dog :
+  Animal`, and `Pair<number, string>` is not assignable to `Pair<string, number>` — every
+  slot must match exactly, in order.
+
+By default a type parameter is fully unconstrained, so you can't call any member on a bare
+`T`/`K`/`V` value inside the generic class's own body — the same restriction C#/Java/
+TypeScript put on an unconstrained parameter, not a bug. A single optional `: IFoo`
+constraint per parameter lifts that:
+
+```ks
+interface IComparable { number CompareTo(); }
+class Box<T : IComparable> {
+  public T Value;
+  constructor(T v) { this.Value = v; }
+  public number Compare() { return this.Value.CompareTo(); } // legal — T is constrained
+}
+Box<Money> b = new Box<Money>(new Money(5));   // Money must implement IComparable
+```
+
+The constraint must be an interface (never a class), and a type argument satisfies it by
+implementing it directly, through an ancestor, or (inside another generic body) by already
+being an equally-or-more-constrained type parameter of its own. **v1 limit**: at most one
+constraint per parameter — `T : IFoo, IBar` isn't supported.
 
 A class or interface *can* extend/implement a generic base, type arguments and all:
 
@@ -281,6 +296,24 @@ down. **v1 limit**: at most one generic entry across a whole base list (the supe
 one implemented interface — not several at once) — `class Foo<T> : Box<T>, IContainer<T>`
 is a compile error even though each half would work alone.
 
+**Free functions can be generic too** — only free/top-level functions, not class methods
+(a method inside a class still only uses its enclosing class's own type parameters, never
+introduces a new one):
+
+```ks
+T Identity<T>(T x) { return x; }
+number n = Identity(5);       // T = number, inferred from the argument
+string s = Identity("hi");    // T = string, independently
+```
+
+**No explicit type argument at the call site** — `Identity<number>(5)` isn't valid syntax;
+`T` is always inferred from the actual argument types. This is a real grammar constraint,
+not a missing feature: `new Box<number>(...)` can disambiguate `<` from a comparison only
+because `new` is a distinct keyword context — a bare call has no such anchor, so
+`f<T>(x)` would be genuinely ambiguous with a chained `<`/`>` comparison. If inference
+can't pin down a type parameter from the arguments given, that's a compile error naming the
+unresolved parameter, not a syntax feature to reach for.
+
 See `LLM.md`'s "Generics" section for the exhaustive rules if you're generating code
 against this — nested generics (`Box<Box<number>>`, `Box<number>?[]`, `Pair<number,
 Pair<string, bool>>`) and generic interfaces used as standalone parameter types both work
@@ -383,11 +416,12 @@ consumes `Component`/`Router` themselves via `extern class ... from "kopular/...
 proving `extern` works as a real cross-*package* boundary, not just for describing DOM
 globals within a single project.
 
-An `extern class` can carry its own type parameter(s), `extern class Box<T> { ... }` or
-`extern class Pair<K, V> { ... }` — exactly the same rules as a real generic class (see
-"Generics" above: invariant, unconstrained, erased, and a real class can extend it as a
-generic base), so a generic type from another package (e.g. Kopular's `FormField<T>`) can
-be described and instantiated generically, not just per concrete type:
+An `extern class` can carry its own type parameter(s), optionally constrained —
+`extern class Box<T> { ... }`, `extern class Pair<K, V> { ... }`, `extern class Box<T :
+IComparable> { ... }` — exactly the same rules as a real generic class (see "Generics"
+above: invariant, erased, and a real class can extend it as a generic base), so a generic
+type from another package (e.g. Kopular's `FormField<T>`) can be described and
+instantiated generically, not just per concrete type:
 
 ```ks
 extern class Box<T> {
@@ -873,13 +907,13 @@ into your extensions folder).
 
 ## Status
 
-This is a v1 / hobby-project scope. Nullable types (`T?`) and generics (a single
-unconstrained, invariant type parameter on classes/interfaces) have both shipped — see
-above for both. What generics deliberately doesn't cover: multiple type parameters
-(`Map<K, V>`), constraints (`T : IFoo`), generic functions, generic inheritance, and
-variance — each a real, separable extension rather than a v1 oversight. Also not yet
-supported: static auto-properties, interface properties (methods only), and nested
-functions/classes.
+This is a v1 / hobby-project scope. Nullable types (`T?`) and generics (multiple type
+parameters, single-interface constraints, generic inheritance, and free generic functions)
+have all shipped — see above for the full "Generics" section. What generics still
+deliberately doesn't cover: variance, multiple constraints per parameter, generic methods
+(only free functions), and more than one generic entry per base list — each a real,
+separable extension rather than a v1 oversight. Also not yet supported: static
+auto-properties, interface properties (methods only), and nested functions/classes.
 
 `async`/`await`, `task<T>`, and `try`/`catch`/`finally`/`throw` are now in place (see the
 language tour above) — the ceiling that's left is what's *inside* those: no async lambdas,

package/dist/checker.js

@@ -64,6 +64,19 @@ export class Checker {
         // 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();
+        // Same shape/population sites as genericTypeParams, but each entry is a
+        // parallel array of that generic's per-parameter constraint interface
+        // name (or null if unconstrained) — e.g. "Pair" -> [null, "IHashable"]
+        // for `class Pair<K, V : IHashable>`. See resolveBaseTypeArgs/checkNew/
+        // checkConstraintSatisfied.
+        this.genericTypeParamConstraints = new Map();
+        // The constraint interface (or null) for every type parameter *currently
+        // in scope* while checking a generic declaration's own body — set/
+        // restored by withTypeParamsInScope alongside namedTypes, so a bare `T`
+        // value's member access (`this.value.Foo()`) can resolve Foo against the
+        // constraint's own signature instead of always erroring (see
+        // checkMemberInner's "typeParam" branch).
+        this.activeConstraints = new Map();
         this.importedNames = new Set();
         this.rawContents = new Map();
         this.hoverEntries = [];
@@ -75,13 +88,17 @@ export class Checker {
         }
         for (const [name, info] of this.imports.classes) {
             this.classes.set(name, info);
-            if (info.typeParams.length > 0)
+            if (info.typeParams.length > 0) {
                 this.genericTypeParams.set(name, info.typeParams);
+                this.genericTypeParamConstraints.set(name, info.typeParamConstraints);
+            }
         }
         for (const [name, info] of this.imports.interfaces) {
             this.interfaces.set(name, info);
-            if (info.typeParams.length > 0)
+            if (info.typeParams.length > 0) {
                 this.genericTypeParams.set(name, info.typeParams);
+                this.genericTypeParamConstraints.set(name, info.typeParamConstraints);
+            }
         }
         for (const [name, info] of this.imports.enums)
             this.enums.set(name, info);
@@ -110,15 +127,24 @@ export class Checker {
             this.namedTypes.set(e.name, "enum");
         for (const c of externClassDecls)
             this.namedTypes.set(c.name, "class");
-        for (const c of classDecls)
-            if (c.typeParams.length > 0)
-                this.genericTypeParams.set(c.name, c.typeParams.map((p) => p.name));
-        for (const i of interfaceDecls)
-            if (i.typeParams.length > 0)
-                this.genericTypeParams.set(i.name, i.typeParams.map((p) => p.name));
-        for (const c of externClassDecls)
-            if (c.typeParams.length > 0)
-                this.genericTypeParams.set(c.name, c.typeParams.map((p) => p.name));
+        for (const c of classDecls) {
+            if (c.typeParams.length === 0)
+                continue;
+            this.genericTypeParams.set(c.name, c.typeParams.map((p) => p.name));
+            this.genericTypeParamConstraints.set(c.name, c.typeParams.map((p) => p.constraint));
+        }
+        for (const i of interfaceDecls) {
+            if (i.typeParams.length === 0)
+                continue;
+            this.genericTypeParams.set(i.name, i.typeParams.map((p) => p.name));
+            this.genericTypeParamConstraints.set(i.name, i.typeParams.map((p) => p.constraint));
+        }
+        for (const c of externClassDecls) {
+            if (c.typeParams.length === 0)
+                continue;
+            this.genericTypeParams.set(c.name, c.typeParams.map((p) => p.name));
+            this.genericTypeParamConstraints.set(c.name, c.typeParams.map((p) => p.constraint));
+        }
         for (const e of enumDecls)
             this.registerEnum(e);
         for (const i of interfaceDecls)
@@ -168,7 +194,12 @@ export class Checker {
             this.checkClassBody(c);
     }
     registerExternFunction(decl) {
+        // extern functions never take a type parameter of their own in v1 —
+        // generic functions (see registerFunction) are a real-function-only
+        // feature; an extern binding always describes a concrete signature.
         this.functions.set(decl.name, {
+            typeParams: [],
+            typeParamConstraints: [],
             params: decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col)),
             returnType: this.resolveType(decl.returnType, decl.line, decl.col),
         });
@@ -203,6 +234,7 @@ export class Checker {
         this.classes.set(decl.name, {
             name: decl.name,
             typeParams: decl.typeParams.map((p) => p.name),
+            typeParamConstraints: decl.typeParams.map((p) => p.constraint),
             superclass: null,
             superclassTypeArgs: null,
             interfaces: [],
@@ -394,6 +426,14 @@ export class Checker {
                 else if (declaredParams && suppliedCount > 0 && suppliedCount !== declaredParams.length) {
                     this.diagnostics.error("KS4090", `Type '${type.name}' expects ${this.describeArity(declaredParams)}, got ${suppliedCount}`, line, col);
                 }
+                else if (declaredParams && suppliedCount === declaredParams.length) {
+                    const constraints = this.genericTypeParamConstraints.get(type.name);
+                    type.typeArgs.forEach((arg, i) => {
+                        const constraint = constraints?.[i];
+                        if (constraint)
+                            this.checkConstraintSatisfied(arg, constraint, declaredParams[i], line, col);
+                    });
+                }
                 type.typeArgs?.forEach((a) => this.validateGenericArity(a, line, col));
                 return;
             }
@@ -415,8 +455,11 @@ export class Checker {
         if (typeParams.length === 0)
             return fn();
         const previous = typeParams.map((p) => this.namedTypes.get(p.name));
-        for (const p of typeParams)
+        const previousConstraints = typeParams.map((p) => this.activeConstraints.get(p.name));
+        for (const p of typeParams) {
             this.namedTypes.set(p.name, "typeParam");
+            this.activeConstraints.set(p.name, p.constraint);
+        }
         try {
             return fn();
         }
@@ -427,6 +470,11 @@ export class Checker {
                     this.namedTypes.delete(p.name);
                 else
                     this.namedTypes.set(p.name, prev);
+                const prevConstraint = previousConstraints[i];
+                if (prevConstraint === undefined)
+                    this.activeConstraints.delete(p.name);
+                else
+                    this.activeConstraints.set(p.name, prevConstraint);
             });
         }
     }
@@ -461,6 +509,68 @@ export class Checker {
                 return type;
         }
     }
+    // The reverse of substituteTypeParams: derives bindings *from* matching a
+    // generic function's declared (abstract) parameter type against one real
+    // argument's actual (concrete) type, instead of substituting bindings
+    // *into* a type. Structural unification, same recursive shape as
+    // substituteTypeParams/typesEqual — whenever `declared` is a TypeParamType
+    // for one of `typeParamNames`, records `bindings.set(name, actual)` the
+    // first time it's seen; a later argument that would bind the same name to
+    // a genuinely different type is recorded in `conflicts` instead of
+    // silently overwriting (see checkGenericFunctionCall's own error for
+    // that). A structural mismatch elsewhere (e.g. declared is `T[]` but
+    // actual isn't an array at all) simply infers nothing from that
+    // position — the normal post-substitution assignability check catches
+    // the real type error afterward, with a clearer message than unification
+    // failing silently here would give.
+    inferTypeParamBindings(declared, actual, typeParamNames, bindings, conflicts) {
+        if (declared.kind === "typeParam" && typeParamNames.has(declared.name)) {
+            const existing = bindings.get(declared.name);
+            if (existing) {
+                if (!T.typesEqual(existing, actual))
+                    conflicts.set(declared.name, actual);
+            }
+            else {
+                bindings.set(declared.name, actual);
+            }
+            return;
+        }
+        if (declared.kind === "array" && actual.kind === "array") {
+            this.inferTypeParamBindings(declared.element, actual.element, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "nullable") {
+            const actualInner = actual.kind === "nullable" ? actual.inner : actual;
+            this.inferTypeParamBindings(declared.inner, actualInner, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "task" && actual.kind === "task") {
+            this.inferTypeParamBindings(declared.resultType, actual.resultType, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "state" && actual.kind === "state") {
+            this.inferTypeParamBindings(declared.valueType, actual.valueType, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if ((declared.kind === "class" || declared.kind === "interface") && declared.kind === actual.kind && declared.name === actual.name) {
+            const declaredArgs = declared.typeArgs ?? [];
+            const actualArgs = actual.typeArgs ?? [];
+            declaredArgs.forEach((d, i) => {
+                if (actualArgs[i])
+                    this.inferTypeParamBindings(d, actualArgs[i], typeParamNames, bindings, conflicts);
+            });
+            return;
+        }
+        if (declared.kind === "function" && actual.kind === "function") {
+            declared.params.forEach((d, i) => {
+                if (actual.params[i])
+                    this.inferTypeParamBindings(d, actual.params[i], typeParamNames, bindings, conflicts);
+            });
+            this.inferTypeParamBindings(declared.returnType, actual.returnType, typeParamNames, bindings, conflicts);
+        }
+        // Anything else (primitive/enum/void/unknown, or a structural
+        // mismatch) has nothing to unify — no-op.
+    }
     // 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
@@ -551,7 +661,14 @@ export class Checker {
             }
             return { methods, bases, baseTypeArgs };
         });
-        this.interfaces.set(decl.name, { name: decl.name, typeParams: decl.typeParams.map((p) => p.name), bases, baseTypeArgs, methods });
+        this.interfaces.set(decl.name, {
+            name: decl.name,
+            typeParams: decl.typeParams.map((p) => p.name),
+            typeParamConstraints: decl.typeParams.map((p) => p.constraint),
+            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) {
@@ -677,6 +794,7 @@ export class Checker {
         this.classes.set(decl.name, {
             name: decl.name,
             typeParams: decl.typeParams.map((p) => p.name),
+            typeParamConstraints: decl.typeParams.map((p) => p.constraint),
             superclass,
             superclassTypeArgs,
             interfaces,
@@ -715,7 +833,15 @@ export class Checker {
         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));
+        const resolvedArgs = typeArgNodes.map((a) => this.resolveType(a, declLine, declCol));
+        const constraints = this.genericTypeParamConstraints.get(baseName);
+        const declaredParamNames = this.genericTypeParams.get(baseName);
+        resolvedArgs.forEach((arg, i) => {
+            const constraint = constraints?.[i];
+            if (constraint)
+                this.checkConstraintSatisfied(arg, constraint, declaredParamNames[i], declLine, declCol);
+        });
+        return resolvedArgs;
     }
     checkClassHierarchy(decl) {
         const info = this.classes.get(decl.name);
@@ -820,10 +946,18 @@ export class Checker {
         }
     }
     registerFunction(decl) {
-        const params = decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col));
-        const returnType = this.resolveType(decl.returnType, decl.line, decl.col);
-        this.functions.set(decl.name, { params, returnType });
-        this.recordHover(decl.line, decl.col, `function ${decl.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
+        const { params, returnType } = this.withTypeParamsInScope(decl.typeParams, () => ({
+            params: decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col)),
+            returnType: this.resolveType(decl.returnType, decl.line, decl.col),
+        }));
+        this.functions.set(decl.name, {
+            typeParams: decl.typeParams.map((p) => p.name),
+            typeParamConstraints: decl.typeParams.map((p) => p.constraint),
+            params,
+            returnType,
+        });
+        const nameWithTypeParam = decl.typeParams.length > 0 ? `${decl.name}<${decl.typeParams.map((p) => p.name).join(", ")}>` : decl.name;
+        this.recordHover(decl.line, decl.col, `function ${nameWithTypeParam}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
     }
     isSubclass(sub, sup) {
         let current = sub;
@@ -846,6 +980,38 @@ export class Checker {
         }
         return false;
     }
+    // Checks that `argType` (bound to type parameter `paramName`, declared
+    // `paramName : constraintInterfaceName`) actually satisfies the
+    // constraint: a class implementing the interface (possibly via an
+    // ancestor — classImplementsInterface already walks the chain), the
+    // interface itself (or one extending it), or a currently-in-scope type
+    // parameter whose own constraint already extends this one (so a
+    // constrained T can be threaded into another equally-constrained slot,
+    // e.g. `class Wrapper<T : IComparable> { void F(Box<T> b) { ... } }`
+    // passing Wrapper's own T to a `Box<T : IComparable>`). Anything else —
+    // a primitive, an array, an unconstrained type parameter, an unrelated
+    // class — is a compile error.
+    checkConstraintSatisfied(argType, constraintInterfaceName, paramName, line, col) {
+        if (argType.kind === "unknown")
+            return; // an earlier error already reported; don't cascade
+        let satisfied;
+        if (argType.kind === "class") {
+            satisfied = this.classImplementsInterface(argType.name, constraintInterfaceName);
+        }
+        else if (argType.kind === "interface") {
+            satisfied = this.interfaceExtends(argType.name, constraintInterfaceName);
+        }
+        else if (argType.kind === "typeParam") {
+            const ownConstraint = this.activeConstraints.get(argType.name);
+            satisfied = !!ownConstraint && this.interfaceExtends(ownConstraint, constraintInterfaceName);
+        }
+        else {
+            satisfied = false;
+        }
+        if (!satisfied) {
+            this.diagnostics.error("KS4096", `Type argument '${T.typeToString(argType)}' does not satisfy constraint '${constraintInterfaceName}' for type parameter '${paramName}'`, line, col);
+        }
+    }
     lookupField(className, fieldName) {
         let current = className;
         while (current) {
@@ -991,11 +1157,17 @@ export class Checker {
         this.checkStatement(stmt, scope, { returnType: T.VOID, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: true });
     }
     checkFunctionBody(decl, parentScope) {
-        const info = this.functions.get(decl.name);
-        const scope = parentScope.child();
-        decl.params.forEach((p, i) => scope.declare(p.name, info.params[i], false));
-        const returnType = this.resolveBodyReturnType(info.returnType, decl.isAsync, decl.line, decl.col);
-        this.checkBlock(decl.body, scope, { returnType, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: decl.isAsync });
+        // Same withTypeParamsInScope treatment checkClassBody gives a generic
+        // class's own method bodies — without it, a generic function's type
+        // parameter would resolve in its declared signature but not inside a
+        // local declaration/lambda written in its own body.
+        this.withTypeParamsInScope(decl.typeParams, () => {
+            const info = this.functions.get(decl.name);
+            const scope = parentScope.child();
+            decl.params.forEach((p, i) => scope.declare(p.name, info.params[i], false));
+            const returnType = this.resolveBodyReturnType(info.returnType, decl.isAsync, decl.line, decl.col);
+            this.checkBlock(decl.body, scope, { returnType, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: decl.isAsync });
+        });
     }
     checkClassBody(decl) {
         // Constructor/method *bodies* run in this same scope registerClass used
@@ -1535,6 +1707,9 @@ export class Checker {
                 return T.UNKNOWN;
             }
             this.recordHover(expr.callee.line, expr.callee.col, `function ${expr.callee.name}(${info.params.map(T.typeToString).join(", ")}): ${T.typeToString(info.returnType)}`);
+            if (info.typeParams.length > 0) {
+                return this.checkGenericFunctionCall(expr, expr.callee.name, info, scope, ctx);
+            }
             this.checkArgs(expr, info.params, scope, ctx);
             return info.returnType;
         }
@@ -1587,6 +1762,50 @@ export class Checker {
             }
         });
     }
+    // A generic function call has no explicit type-argument syntax (see
+    // README's "Generics" — a real grammar-ambiguity reason, `f<T>(x)` is
+    // indistinguishable from a chained comparison with no keyword like `new`
+    // to disambiguate it), so every type parameter is inferred from the
+    // actual argument types instead. Checks argument count first (an arity
+    // mismatch would make inference itself meaningless), infers bindings by
+    // unifying each declared (abstract) parameter type against its actual
+    // argument's real type (see inferTypeParamBindings), then re-runs the
+    // normal assignability check with the now-concrete substituted parameter
+    // types — catching anything structural unification alone wouldn't (e.g.
+    // an argument assignable to, but not identical to, its inferred slot).
+    checkGenericFunctionCall(expr, functionName, info, scope, ctx) {
+        if (expr.args.length !== info.params.length) {
+            this.diagnostics.error("KS4098", `Expected ${info.params.length} argument(s), got ${expr.args.length}`, expr.line, expr.col);
+            expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+            return T.UNKNOWN;
+        }
+        const actualArgTypes = expr.args.map((a) => this.checkExpression(a, scope, ctx));
+        const typeParamNames = new Set(info.typeParams);
+        const bindings = new Map();
+        const conflicts = new Map();
+        info.params.forEach((declared, i) => this.inferTypeParamBindings(declared, actualArgTypes[i], typeParamNames, bindings, conflicts));
+        for (const [name, conflictingType] of conflicts) {
+            this.diagnostics.error("KS4099", `Type parameter '${name}' inferred as both '${T.typeToString(bindings.get(name))}' and '${T.typeToString(conflictingType)}' from different arguments — conflicting types`, expr.line, expr.col);
+        }
+        const unresolved = info.typeParams.filter((name) => !bindings.has(name));
+        if (unresolved.length > 0) {
+            this.diagnostics.error("KS4100", `Cannot infer type parameter${unresolved.length === 1 ? "" : "s"} '${unresolved.join("', '")}' for '${functionName}' — no argument determines ${unresolved.length === 1 ? "it" : "them"}`, expr.line, expr.col);
+            return T.UNKNOWN;
+        }
+        info.typeParams.forEach((name, i) => {
+            const constraint = info.typeParamConstraints[i];
+            if (constraint)
+                this.checkConstraintSatisfied(bindings.get(name), constraint, name, expr.line, expr.col);
+        });
+        const substitutedParams = info.params.map((p) => this.substituteTypeParams(p, bindings));
+        expr.args.forEach((arg, i) => {
+            const expected = substitutedParams[i];
+            if (!this.isAssignableType(actualArgTypes[i], expected)) {
+                this.diagnostics.error("KS4101", `Argument ${i + 1} has type '${T.typeToString(actualArgTypes[i])}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
+            }
+        });
+        return this.substituteTypeParams(info.returnType, bindings);
+    }
     checkNew(expr, scope, ctx) {
         if (this.interfaces.has(expr.className)) {
             this.diagnostics.error("KS4066", `Cannot instantiate interface '${expr.className}'`, expr.line, expr.col);
@@ -1626,6 +1845,12 @@ export class Checker {
                 return T.UNKNOWN;
             }
             typeArgs = expr.typeArgs.map((a) => this.resolveType(a, expr.line, expr.col));
+            const constraints = this.genericTypeParamConstraints.get(expr.className);
+            typeArgs.forEach((arg, i) => {
+                const constraint = constraints?.[i];
+                if (constraint)
+                    this.checkConstraintSatisfied(arg, constraint, info.typeParams[i], 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
@@ -1851,6 +2076,22 @@ export class Checker {
             this.diagnostics.error("KS4084", `Interface '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }
+        // A bare type-parameter receiver (`this.value.Foo()` where `value: T`)
+        // — resolves against the constraint interface's own signature if `T`
+        // is constrained; an unconstrained `T` falls through to the generic
+        // "cannot access member" error below, unchanged from before constraints
+        // existed (see README/LLM.md's own documented restriction).
+        if (objectType.kind === "typeParam") {
+            const constraintName = this.activeConstraints.get(objectType.name);
+            if (constraintName) {
+                const sig = this.collectInterfaceMethods(constraintName).find((m) => m.name === expr.property);
+                if (sig) {
+                    return { type: sig.returnType, methodInfo: { params: sig.params, returnType: sig.returnType, visibility: "public", isVirtual: false, isOverride: false } };
+                }
+                this.diagnostics.error("KS4097", `Interface '${constraintName}' (the constraint on type parameter '${objectType.name}') has no member '${expr.property}'`, expr.line, expr.col);
+                return { type: T.UNKNOWN, methodInfo: null };
+            }
+        }
         if (objectType.kind !== "unknown") {
             this.diagnostics.error("KS4085", `Cannot access member '${expr.property}' on type '${T.typeToString(objectType)}'`, expr.line, expr.col);
         }

package/dist/parser.js

@@ -198,14 +198,24 @@ export class Parser {
         const type = this.parseType();
         const nameTok = this.consume(TokenKind.Identifier, "Expected name");
         const name = nameTok.lexeme;
+        // `T Identity<T>(T x) { ... }` — a free function's own type-param list,
+        // between its name and `(`. Only meaningful for the function branch
+        // below; a local/top-level variable declaration never has `<` right
+        // after its name, so trying this first costs nothing in that case
+        // (parseTypeParamList returns immediately without consuming anything
+        // when `<` isn't there).
+        const typeParams = this.parseTypeParamList();
         if (this.check(TokenKind.LParen)) {
             const params = this.parseParamList();
             const body = this.parseBlock();
-            return { kind: "FunctionDecl", isExported, isAsync, name, params, returnType: type, body, line: start.line, col: start.col };
+            return { kind: "FunctionDecl", isExported, isAsync, name, typeParams, params, returnType: type, body, line: start.line, col: start.col };
         }
         if (isAsync) {
             this.diagnostics.error("KS2006", "'async' cannot modify a variable declaration", start.line, start.col);
         }
+        if (typeParams.length > 0) {
+            this.diagnostics.error("KS2023", "A type parameter list is only allowed on a function declaration", start.line, start.col);
+        }
         this.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
         this.consume(TokenKind.Semicolon, "Expected ';' after variable declaration");
@@ -243,17 +253,21 @@ export class Parser {
         this.consume(TokenKind.RParen, "Expected ')' after parameters");
         return params;
     }
-    // `<K, V>` right after a class/interface name — one or more type
-    // parameters, comma-separated. Empty array if absent, the overwhelmingly
-    // common case. Constraint syntax (`<T : IFoo>`) isn't parsed yet — every
-    // entry's `constraint` is always null for now (see AST.TypeParamDecl).
+    // `<K : IHashable, V>` right after a class/interface/function name — one
+    // or more type parameters, comma-separated, each with an optional
+    // `: InterfaceName` constraint. Empty array if absent, the overwhelmingly
+    // common case.
     parseTypeParamList() {
         if (!this.match(TokenKind.Lt))
             return [];
         const params = [];
         do {
             const nameTok = this.consume(TokenKind.Identifier, "Expected a type parameter name");
-            params.push({ name: nameTok.lexeme, constraint: null, line: nameTok.line, col: nameTok.col });
+            let constraint = null;
+            if (this.match(TokenKind.Colon)) {
+                constraint = this.consume(TokenKind.Identifier, "Expected a constraint interface name after ':'").lexeme;
+            }
+            params.push({ name: nameTok.lexeme, constraint, line: nameTok.line, col: nameTok.col });
         } while (this.match(TokenKind.Comma));
         this.consume(TokenKind.Gt, "Expected '>' after type parameter list");
         return params;

package/dist/printer.js

@@ -121,6 +121,12 @@ export class Printer {
     printBaseListEntry(entry) {
         return entry.typeArgs ? `${entry.name}<${entry.typeArgs.map((t) => this.printType(t)).join(", ")}>` : entry.name;
     }
+    printTypeParamName(decl) {
+        if (decl.typeParams.length === 0)
+            return decl.name;
+        const params = decl.typeParams.map((p) => (p.constraint ? `${p.name} : ${p.constraint}` : p.name)).join(", ");
+        return `${decl.name}<${params}>`;
+    }
     // ---------- top-level declarations ----------
     printStatement(stmt, indent) {
         const pad = indentStr(indent);
@@ -202,7 +208,8 @@ export class Printer {
     printFunction(decl, indent) {
         const pad = indentStr(indent);
         const prefix = `${decl.isExported ? "" : "private "}${decl.isAsync ? "async " : ""}`;
-        return `${pad}${prefix}${this.printType(decl.returnType)} ${decl.name}(${this.printParams(decl.params)}) ${this.printBlock(decl.body, indent).trimStart()}`;
+        const nameWithTypeParam = this.printTypeParamName(decl);
+        return `${pad}${prefix}${this.printType(decl.returnType)} ${nameWithTypeParam}(${this.printParams(decl.params)}) ${this.printBlock(decl.body, indent).trimStart()}`;
     }
     // Canonical member order: fields, then properties, then the constructor,
     // then methods — regardless of how the original source interleaved them.
@@ -215,7 +222,7 @@ export class Printer {
     printClass(decl, indent) {
         const pad = indentStr(indent);
         const memberPad = indentStr(indent + 1);
-        const nameWithTypeParam = decl.typeParams.length > 0 ? `${decl.name}<${decl.typeParams.map((p) => p.name).join(", ")}>` : decl.name;
+        const nameWithTypeParam = this.printTypeParamName(decl);
         const header = decl.baseList.length > 0 ? `class ${nameWithTypeParam} : ${decl.baseList.map((b) => this.printBaseListEntry(b)).join(", ")} {` : `class ${nameWithTypeParam} {`;
         const prefix = decl.isExported ? "" : "private ";
         const memberParts = [];
@@ -253,7 +260,7 @@ export class Printer {
     printInterface(decl, indent) {
         const pad = indentStr(indent);
         const memberPad = indentStr(indent + 1);
-        const nameWithTypeParam = decl.typeParams.length > 0 ? `${decl.name}<${decl.typeParams.map((p) => p.name).join(", ")}>` : decl.name;
+        const nameWithTypeParam = this.printTypeParamName(decl);
         const header = decl.baseList.length > 0 ? `interface ${nameWithTypeParam} : ${decl.baseList.map((b) => this.printBaseListEntry(b)).join(", ")} {` : `interface ${nameWithTypeParam} {`;
         const prefix = decl.isExported ? "" : "private ";
         if (decl.methods.length === 0)
@@ -282,7 +289,7 @@ export class Printer {
         const pad = indentStr(indent);
         const memberPad = indentStr(indent + 1);
         const prefix = decl.isExported ? "" : "private ";
-        const nameWithTypeParam = decl.typeParams.length > 0 ? `${decl.name}<${decl.typeParams.map((p) => p.name).join(", ")}>` : decl.name;
+        const nameWithTypeParam = this.printTypeParamName(decl);
         const lines = [];
         if (decl.hasConstructor)
             lines.push(`${memberPad}constructor(${this.printParams(decl.ctorParams)});`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript, with generics and nullable types",
   "type": "module",
   "license": "MIT",