stone-lang 0.1.0

package/frontend/types/types.js

@@ -0,0 +1,2046 @@
+/**
+ * Stone Type System
+ *
+ * This module defines the internal type representation for Stone's type system.
+ * Types are structural and support inference via unification.
+ *
+ * Key design principles:
+ * - Types are always optional (annotations are hints, not requirements)
+ * - Compile-time errors when annotated types don't match inferred types
+ * - No implicit coercion or broadcasting
+ */
+
+// ============================================================================
+// TYPE CONSTRUCTORS
+// ============================================================================
+
+/**
+ * Primitive types: Num, Bool, String, Unit
+ */
+export class PrimitiveType {
+  constructor(name) {
+    this.kind = "primitive";
+    this.name = name; // 'num' | 'bool' | 'string' | 'unit'
+  }
+
+  toString() {
+    return this.name;
+  }
+
+  equals(other) {
+    return other instanceof PrimitiveType && this.name === other.name;
+  }
+}
+
+// Singleton instances for primitive types (lowercase names)
+export const NUM = new PrimitiveType("num");
+export const BOOL = new PrimitiveType("bool");
+export const STRING = new PrimitiveType("string");
+export const UNIT = new PrimitiveType("unit");
+// Note: Complex numbers are now represented as records {re: num, im: num}
+// The "complex" primitive type is kept for backwards compatibility in type annotations
+
+// Backwards compatibility aliases
+export const INT = NUM;
+export const FLOAT = NUM;
+
+/**
+ * Function type: (T1, T2, ...) -> R
+ */
+export class FunctionType {
+  constructor(paramTypes, returnType, constraints = []) {
+    this.kind = "function";
+    this.paramTypes = paramTypes; // Array<Type>
+    this.returnType = returnType; // Type
+    this.constraints = constraints; // Array of deferred constraints (e.g., rank requirements)
+  }
+
+  toString() {
+    const params = this.paramTypes.map((t) => t.toString()).join(", ");
+    let str = `(${params}) -> ${this.returnType.toString()}`;
+    if (this.constraints.length > 0) {
+      const constraintStrs = this.constraints.map(c => {
+        if (c.type === 'rank') {
+          return `param${c.paramIndex}.rank=${c.requiredRank}`;
+        }
+        return JSON.stringify(c);
+      });
+      str += ` where [${constraintStrs.join(', ')}]`;
+    }
+    return str;
+  }
+
+  equals(other) {
+    if (!(other instanceof FunctionType)) return false;
+    if (this.paramTypes.length !== other.paramTypes.length) return false;
+    for (let i = 0; i < this.paramTypes.length; i++) {
+      if (!typeEquals(this.paramTypes[i], other.paramTypes[i])) return false;
+    }
+    return typeEquals(this.returnType, other.returnType);
+  }
+
+  /**
+   * Create a fresh copy of this function type with fresh type variables.
+   * This is used for polymorphic functions like print() where each call
+   * should get its own type variable instance.
+   *
+   * Important: Resolved TypeVariables are instantiated as their resolved type,
+   * preserving constraints (e.g., if a TypeVariable was constrained to FunctionType).
+   */
+  instantiate() {
+    const varMap = new Map();
+    const instantiateType = (type) => {
+      // Resolve TypeVariables first to preserve constraints
+      if (type instanceof TypeVariable) {
+        const resolved = type.resolve();
+        if (resolved !== type) {
+          // TypeVariable was constrained to a concrete type - instantiate that
+          return instantiateType(resolved);
+        }
+        // Still unresolved - create fresh TypeVariable
+        if (!varMap.has(type.id)) {
+          varMap.set(type.id, freshTypeVar());
+        }
+        return varMap.get(type.id);
+      }
+      if (type instanceof FunctionType) {
+        return new FunctionType(
+          type.paramTypes.map(instantiateType),
+          instantiateType(type.returnType),
+          type.constraints // Copy constraints
+        );
+      }
+      if (type instanceof ArrayType) {
+        return new ArrayType(instantiateType(type.elementType), type.rank);
+      }
+      if (type instanceof RecordType) {
+        const newFields = new Map();
+        for (const [k, v] of type.fields) {
+          newFields.set(k, instantiateType(v));
+        }
+        return new RecordType(newFields, type.open, type.explicit);
+      }
+      if (type instanceof DictionaryType) {
+        return new DictionaryType(
+          instantiateType(type.keyType),
+          instantiateType(type.valueType)
+        );
+      }
+      return type;
+    };
+    return new FunctionType(
+      this.paramTypes.map(instantiateType),
+      instantiateType(this.returnType),
+      this.constraints // Preserve constraints in instantiated type
+    );
+  }
+}
+
+/**
+ * Record type: { field1: T1, field2: T2, ... }
+ * All records are closed (exact fields required)
+ */
+export class RecordType {
+  constructor(fields, open = false, explicit = false, requiredFields = null) {
+    this.kind = "record";
+    this.fields = fields; // Map<string, Type>
+    // open = true means this record type is an inference constraint from field access
+    // and can be extended with additional fields during type inference
+    // open = false means this is a concrete record (from object literal or explicit type)
+    this.open = open;
+    this.explicit = explicit; // true if from destructuring
+    // requiredFields tracks type descriptor fields without defaults (for schema records)
+    // If null, this is a regular record. If a Set, this is a schema record where
+    // these fields cannot be accessed directly (they have no default value).
+    this.requiredFields = requiredFields; // Set<string> | null
+  }
+
+  toString() {
+    const fieldStrs = [];
+    for (const [name, type] of this.fields) {
+      fieldStrs.push(`${name}: ${type.toString()}`);
+    }
+    return `{ ${fieldStrs.join(", ")} }`;
+  }
+
+  equals(other) {
+    if (!(other instanceof RecordType)) return false;
+    if (this.fields.size !== other.fields.size) return false;
+    for (const [name, type] of this.fields) {
+      const otherType = other.fields.get(name);
+      if (!otherType || !typeEquals(type, otherType)) return false;
+    }
+    return true;
+  }
+}
+
+/**
+ * Dictionary type: {[K]: V}
+ * For homogeneous key-value maps with uniform value types
+ */
+export class DictionaryType {
+  constructor(keyType, valueType) {
+    this.kind = "dictionary";
+    this.keyType = keyType;   // Type (typically STRING)
+    this.valueType = valueType; // Type
+  }
+
+  toString() {
+    return `{[${this.keyType.toString()}]: ${this.valueType.toString()}}`;
+  }
+
+  equals(other) {
+    if (!(other instanceof DictionaryType)) return false;
+    return typeEquals(this.keyType, other.keyType) &&
+           typeEquals(this.valueType, other.valueType);
+  }
+}
+
+/**
+ * Promoted type: Type | converter(param) | converter2(param) | ...
+ * Wraps a target type with promotion metadata, allowing arguments of the
+ * converter's input type to be automatically converted to the target type.
+ *
+ * Supports multiple converters (tried in order during type checking).
+ *
+ * Example: `a: complex | to_complex(a)` means:
+ * - targetType: complex
+ * - converters: [{funcName: "to_complex", sourceType: num}]
+ * - paramRef: "a"
+ *
+ * Example with multiple converters: `p: Point | from_num(p) | from_arr(p)` means:
+ * - targetType: Point
+ * - converters: [{funcName: "from_num", sourceType: num}, {funcName: "from_arr", sourceType: array<num,1>}]
+ * - paramRef: "p"
+ */
+export class PromotedType {
+  constructor(targetType, converterFuncOrConverters, paramRef, sourceType = null) {
+    this.kind = "promoted";
+    this.targetType = targetType;    // The type after conversion
+    this.paramRef = paramRef;        // Parameter name reference (for validation)
+
+    // Support both old single-converter API and new multi-converter API
+    if (typeof converterFuncOrConverters === 'string') {
+      // Old API: single converter function name
+      this.converters = [{ funcName: converterFuncOrConverters, sourceType: sourceType }];
+      this.converterFunc = converterFuncOrConverters;
+      this.sourceType = sourceType;
+    } else if (Array.isArray(converterFuncOrConverters)) {
+      // New API: array of converter objects
+      this.converters = converterFuncOrConverters;
+      // Backwards compatibility
+      this.converterFunc = this.converters[0]?.funcName || null;
+      this.sourceType = this.converters[0]?.sourceType || null;
+    } else {
+      // Fallback
+      this.converters = [];
+      this.converterFunc = null;
+      this.sourceType = null;
+    }
+  }
+
+  toString() {
+    const converterStrs = this.converters.map(c => {
+      const sourceStr = c.sourceType ? ` (from ${c.sourceType.toString()})` : "";
+      return `${c.funcName}(${this.paramRef})${sourceStr}`;
+    });
+    return `${this.targetType.toString()} | ${converterStrs.join(" | ")}`;
+  }
+
+  equals(other) {
+    if (!(other instanceof PromotedType)) return false;
+    if (!typeEquals(this.targetType, other.targetType)) return false;
+    if (this.converters.length !== other.converters.length) return false;
+    for (let i = 0; i < this.converters.length; i++) {
+      if (this.converters[i].funcName !== other.converters[i].funcName) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Get the effective type for type checking purposes (the target type)
+   */
+  getEffectiveType() {
+    return this.targetType;
+  }
+
+  /**
+   * Find a converter that can accept the given source type.
+   * Returns the converter object or null if none match.
+   */
+  findConverterForType(sourceType) {
+    for (const converter of this.converters) {
+      if (converter.sourceType && typeEquals(converter.sourceType, sourceType)) {
+        return converter;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get all source types that this promoted type can accept.
+   */
+  getAllSourceTypes() {
+    return this.converters.map(c => c.sourceType).filter(Boolean);
+  }
+}
+
+/**
+ * Literal type: a single literal value used as a type
+ * Example: mode: "on" or level: 2
+ *
+ * Literal types are subtypes of their primitive kind:
+ * - "on" is a subtype of string
+ * - 42 is a subtype of num
+ *
+ * Only string and number literals are supported (no booleans).
+ */
+export class LiteralType {
+  constructor(value, primitiveKind) {
+    this.kind = "literal";
+    this.value = value;           // The literal value: "on", 42
+    this.primitiveKind = primitiveKind;  // 'string' | 'num'
+  }
+
+  toString() {
+    return this.primitiveKind === 'string' ? `"${this.value}"` : String(this.value);
+  }
+
+  equals(other) {
+    if (other instanceof LiteralType) {
+      return this.value === other.value && this.primitiveKind === other.primitiveKind;
+    }
+    return false;
+  }
+
+  /**
+   * Check if this literal type is compatible with another type.
+   * A literal type is compatible with:
+   * - The same literal type
+   * - A LiteralUnionType that includes this value
+   * - Its base primitive type (for general compatibility)
+   */
+  isCompatibleWith(other) {
+    if (other instanceof LiteralType) {
+      return this.value === other.value && this.primitiveKind === other.primitiveKind;
+    }
+    if (other instanceof LiteralUnionType) {
+      return other.primitiveKind === this.primitiveKind && other.values.includes(this.value);
+    }
+    if (other instanceof PrimitiveType) {
+      return other.name === this.primitiveKind;
+    }
+    return false;
+  }
+}
+
+/**
+ * Literal union type: a finite set of literal values
+ * Example: mode: "on" | "off" or level: 0 | 1 | 2
+ *
+ * All values must be of the same primitive kind.
+ */
+export class LiteralUnionType {
+  constructor(values, primitiveKind) {
+    this.kind = "literalUnion";
+    this.values = values;         // Array of literal values: ["on", "off"]
+    this.primitiveKind = primitiveKind;  // 'string' | 'num'
+  }
+
+  toString() {
+    const formatted = this.values.map(v =>
+      this.primitiveKind === 'string' ? `"${v}"` : String(v)
+    );
+    return formatted.join(" | ");
+  }
+
+  equals(other) {
+    if (!(other instanceof LiteralUnionType)) return false;
+    if (this.primitiveKind !== other.primitiveKind) return false;
+    if (this.values.length !== other.values.length) return false;
+    // Check same values (order-independent)
+    const thisSet = new Set(this.values);
+    return other.values.every(v => thisSet.has(v));
+  }
+
+  /**
+   * Check if a value is one of the allowed values
+   */
+  includes(value) {
+    return this.values.includes(value);
+  }
+
+  /**
+   * Check if another type is a subset of this literal union.
+   * Used for type compatibility checking.
+   */
+  isSupersetOf(other) {
+    if (other instanceof LiteralType) {
+      return other.primitiveKind === this.primitiveKind && this.values.includes(other.value);
+    }
+    if (other instanceof LiteralUnionType) {
+      if (other.primitiveKind !== this.primitiveKind) return false;
+      const thisSet = new Set(this.values);
+      return other.values.every(v => thisSet.has(v));
+    }
+    return false;
+  }
+}
+
+// ListType has been removed - Stone uses only typed arrays (array<T,R>)
+
+/**
+ * Array type: array<T, R>
+ * For dense, rectangular, contiguous numeric arrays
+ * @param elementType - The element type (typically int or float)
+ * @param rank - The number of dimensions (compile-time integer)
+ *
+ * Automatically normalizes nested numeric arrays:
+ * array<array<num,R1>,R2> -> array<num,R1+R2>
+ * array<array<complex,R1>,R2> -> array<complex,R1+R2>
+ */
+export class ArrayType {
+  constructor(elementType, rank) {
+    this.kind = "array";
+
+    // Normalize nested numeric/complex arrays
+    if (elementType instanceof ArrayType) {
+      // Get the base element type and total rank
+      let baseElem = elementType.elementType;
+      let totalRank = rank + elementType.rank;
+
+      // Keep unwrapping while we have nested ArrayTypes
+      while (baseElem instanceof ArrayType) {
+        totalRank += baseElem.rank;
+        baseElem = baseElem.elementType;
+      }
+
+      // Only normalize if base element is numeric (num or complex)
+      if (baseElem instanceof PrimitiveType &&
+          (baseElem.name === "num" || baseElem.name === "complex")) {
+        this.elementType = baseElem;
+        this.rank = totalRank;
+        return;
+      }
+    }
+
+    this.elementType = elementType;
+    this.rank = rank; // Integer >= 1
+  }
+
+  toString() {
+    return `array<${this.elementType.toString()}, ${this.rank}>`;
+  }
+
+  equals(other) {
+    return (
+      other instanceof ArrayType &&
+      this.rank === other.rank &&
+      typeEquals(this.elementType, other.elementType)
+    );
+  }
+}
+
+/**
+ * Union type: T | U
+ * Used for heterogeneous data and optional patterns
+ */
+export class UnionType {
+  constructor(types) {
+    this.kind = "union";
+    this.types = types; // Array<Type>
+  }
+
+  toString() {
+    return this.types.map((t) => t.toString()).join(" | ");
+  }
+
+  equals(other) {
+    if (!(other instanceof UnionType)) return false;
+    if (this.types.length !== other.types.length) return false;
+    // Union equality is order-independent
+    for (const t of this.types) {
+      if (!other.types.some((ot) => typeEquals(t, ot))) return false;
+    }
+    return true;
+  }
+}
+
+/**
+ * Type variable: for inference
+ * Represents an unknown type that will be resolved via unification
+ */
+export class TypeVariable {
+  static counter = 0;
+
+  constructor(id = null) {
+    this.kind = "typevar";
+    this.id = id !== null ? id : TypeVariable.counter++;
+    this.resolved = null; // Will be set during unification
+  }
+
+  toString() {
+    if (this.resolved) {
+      return this.resolved.toString();
+    }
+    return `T${this.id}`;
+  }
+
+  equals(other) {
+    if (this.resolved) {
+      return typeEquals(this.resolved, other);
+    }
+    return other instanceof TypeVariable && this.id === other.id;
+  }
+
+  /**
+   * Get the actual type, following resolution chain
+   */
+  resolve() {
+    if (this.resolved) {
+      if (this.resolved instanceof TypeVariable) {
+        return this.resolved.resolve();
+      }
+      return this.resolved;
+    }
+    return this;
+  }
+}
+
+// ============================================================================
+// TYPE UTILITIES
+// ============================================================================
+
+/**
+ * Normalize a type by resolving type variables and flattening nested numeric arrays.
+ * array<array<num,R1>,R2> -> array<num,R1+R2>
+ * array<array<complex,R1>,R2> -> array<complex,R1+R2>
+ *
+ * Handles both class-based types (ArrayType, etc.) and plain object types
+ * ({kind: "array", elem: ...}) used in overload resolution.
+ */
+export function normalizeType(type) {
+  if (!type) return type;
+
+  // Resolve type variables first
+  if (type instanceof TypeVariable) {
+    type = type.resolve();
+    if (type instanceof TypeVariable) {
+      return type; // Still unresolved
+    }
+  }
+
+  // Handle class-based ArrayType
+  if (type instanceof ArrayType) {
+    // Recursively normalize the element type
+    const normalizedElem = normalizeType(type.elementType);
+
+    // If element type is also an ArrayType with numeric/complex base, flatten
+    if (normalizedElem instanceof ArrayType) {
+      // Get the base element type
+      let baseElem = normalizedElem.elementType;
+      let totalRank = type.rank + normalizedElem.rank;
+
+      // Check if base is numeric or complex
+      if (baseElem instanceof PrimitiveType &&
+          (baseElem.name === "num" || baseElem.name === "complex")) {
+        return new ArrayType(baseElem, totalRank);
+      }
+    }
+
+    // If element changed after normalization, create new ArrayType
+    if (normalizedElem !== type.elementType) {
+      return new ArrayType(normalizedElem, type.rank);
+    }
+  }
+
+  // Handle plain object array types (used in overload resolution)
+  if (type.kind === "array" && type.elem) {
+    // Recursively normalize the element type
+    const normalizedElem = normalizeType(type.elem);
+
+    // If element is also an array with numeric/complex base, flatten
+    if (normalizedElem.kind === "array") {
+      let baseElem = normalizedElem.elem;
+      let totalRank = type.rank + normalizedElem.rank;
+
+      // Check if base is numeric or complex
+      if (baseElem.kind === "primitive" &&
+          (baseElem.name === "num" || baseElem.name === "complex")) {
+        return { kind: "array", elem: baseElem, rank: totalRank };
+      }
+    }
+
+    // If element changed after normalization, create new object
+    if (normalizedElem !== type.elem) {
+      return { kind: "array", elem: normalizedElem, rank: type.rank };
+    }
+  }
+
+  // Normalize FunctionType
+  if (type instanceof FunctionType) {
+    const normalizedParams = type.paramTypes.map(normalizeType);
+    const normalizedReturn = normalizeType(type.returnType);
+    const paramsChanged = normalizedParams.some((p, i) => p !== type.paramTypes[i]);
+    if (paramsChanged || normalizedReturn !== type.returnType) {
+      return new FunctionType(normalizedParams, normalizedReturn);
+    }
+  }
+
+  // Normalize RecordType
+  if (type instanceof RecordType) {
+    const normalizedFields = new Map();
+    let changed = false;
+    for (const [name, fieldType] of type.fields) {
+      const normalizedField = normalizeType(fieldType);
+      normalizedFields.set(name, normalizedField);
+      if (normalizedField !== fieldType) changed = true;
+    }
+    if (changed) {
+      return new RecordType(normalizedFields, type.open);
+    }
+  }
+
+  return type;
+}
+
+/**
+ * Check if two types are structurally equal
+ */
+export function typeEquals(t1, t2) {
+  // Guard against undefined
+  if (!t1 || !t2) return false;
+
+  // Handle type variables
+  if (t1 instanceof TypeVariable) {
+    t1 = t1.resolve();
+  }
+  if (t2 instanceof TypeVariable) {
+    t2 = t2.resolve();
+  }
+
+  // Same reference
+  if (t1 === t2) return true;
+
+  // Both type variables (unresolved)
+  if (t1 instanceof TypeVariable && t2 instanceof TypeVariable) {
+    return t1.id === t2.id;
+  }
+
+  // Different kinds
+  if (t1.kind !== t2.kind) return false;
+
+  // Delegate to type-specific equals
+  return t1.equals(t2);
+}
+
+/**
+ * Check if 'from' type is assignable to 'to' type.
+ * This considers literals as subtypes of their base primitives.
+ * LiteralType("on", "string") is assignable to string (primitive)
+ * LiteralType(5, "num") is assignable to num (primitive)
+ * LiteralType("on") is assignable to LiteralUnionType(["on", "off"])
+ * LiteralUnionType(["on"]) is assignable to LiteralUnionType(["on", "off"])
+ */
+export function isAssignableTo(from, to) {
+  // Guard against undefined
+  if (!from || !to) return false;
+
+  // Resolve type variables
+  if (from instanceof TypeVariable) {
+    from = from.resolve();
+  }
+  if (to instanceof TypeVariable) {
+    to = to.resolve();
+  }
+
+  // Exact equality
+  if (typeEquals(from, to)) return true;
+
+  // LiteralType is assignable to its base primitive
+  if (from instanceof LiteralType && to instanceof PrimitiveType) {
+    if (from.primitiveKind === "string" && to.name === "string") return true;
+    if (from.primitiveKind === "num" && to.name === "num") return true;
+  }
+
+  // LiteralUnionType is assignable to its base primitive
+  if (from instanceof LiteralUnionType && to instanceof PrimitiveType) {
+    if (from.primitiveKind === "string" && to.name === "string") return true;
+    if (from.primitiveKind === "num" && to.name === "num") return true;
+  }
+
+  // LiteralType is assignable to LiteralUnionType if the value is in the union
+  if (from instanceof LiteralType && to instanceof LiteralUnionType) {
+    if (from.primitiveKind === to.primitiveKind && to.values.includes(from.value)) {
+      return true;
+    }
+  }
+
+  // LiteralUnionType is assignable to LiteralUnionType if from is a subset of to
+  if (from instanceof LiteralUnionType && to instanceof LiteralUnionType) {
+    if (from.primitiveKind === to.primitiveKind) {
+      const toSet = new Set(to.values);
+      return from.values.every(v => toSet.has(v));
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if a type is numeric (num)
+ */
+export function isNumeric(type) {
+  if (type instanceof TypeVariable) {
+    type = type.resolve();
+  }
+  return type instanceof PrimitiveType && type.name === "num";
+}
+
+/**
+ * Check if a type is numeric or complex (for arithmetic operations)
+ * Recognizes both primitive "complex" and record {re: num, im: num}
+ */
+export function isNumericOrComplex(type) {
+  if (type instanceof TypeVariable) {
+    type = type.resolve();
+  }
+  if (type instanceof PrimitiveType) {
+    return type.name === "num" || type.name === "complex";
+  }
+  // Also recognize complex record type {re: num, im: num}
+  return isComplexRecord(type);
+}
+
+/**
+ * Check if a type is the complex record type {re: num, im: num}
+ */
+function isComplexRecord(type) {
+  if (!type || type.kind !== "record") return false;
+  const fields = type.fields;
+  if (!(fields instanceof Map)) return false;
+  if (fields.size !== 2) return false;
+  const reType = fields.get("re");
+  const imType = fields.get("im");
+  if (!reType || !imType) return false;
+  return (reType.kind === "primitive" && reType.name === "num" &&
+          imType.kind === "primitive" && imType.name === "num");
+}
+
+/**
+ * Check if a type is complex (primitive or record)
+ * Recognizes both primitive "complex" and record {re: num, im: num}
+ */
+export function isComplex(type) {
+  if (type instanceof TypeVariable) {
+    type = type.resolve();
+  }
+  if (type instanceof PrimitiveType && type.name === "complex") {
+    return true;
+  }
+  return isComplexRecord(type);
+}
+
+/**
+ * Check if a type is an array type
+ */
+export function isArrayType(type) {
+  if (type instanceof TypeVariable) {
+    type = type.resolve();
+  }
+  return type instanceof ArrayType;
+}
+
+// isListType has been removed - Stone uses only typed arrays
+
+/**
+ * Create a fresh type variable
+ */
+export function freshTypeVar() {
+  return new TypeVariable();
+}
+
+/**
+ * Flatten nested array types to a single multi-dimensional array
+ * e.g., array<array<num, 1>, 1> -> array<num, 2>
+ * Returns the original type if no flattening needed
+ */
+export function flattenNestedArrayType(t) {
+  if (t.kind !== "array") return t;
+
+  // Resolve the element type if it's a TypeVariable
+  let elemType = t.elementType;
+  if (elemType instanceof TypeVariable) {
+    elemType = elemType.resolve();
+  }
+
+  // If element type is also an array with concrete ranks, flatten
+  if (elemType.kind === "array" &&
+      typeof t.rank === "number" &&
+      typeof elemType.rank === "number") {
+    // Recursively flatten the inner array first
+    const flatInner = flattenNestedArrayType(elemType);
+    // Combine ranks: outer rank + inner (flattened) rank
+    const combinedRank = t.rank + flatInner.rank;
+    return new ArrayType(flatInner.elementType, combinedRank);
+  }
+
+  return t;
+}
+
+/**
+ * Attempt to unify two types
+ * Returns { success: true, substitution } or { success: false, error }
+ */
+export function unify(t1, t2) {
+  // Guard against undefined
+  if (!t1 || !t2) {
+    return { success: false, error: "Cannot unify undefined types" };
+  }
+
+  // Resolve type variables
+  if (t1 instanceof TypeVariable) {
+    t1 = t1.resolve();
+  }
+  if (t2 instanceof TypeVariable) {
+    t2 = t2.resolve();
+  }
+
+  // Same type
+  if (typeEquals(t1, t2)) {
+    return { success: true };
+  }
+
+  // Handle LiteralType and LiteralUnionType:
+  // - Literal types are subtypes of their primitive type
+  // - LiteralType("on") is assignable to STRING
+  // - STRING is NOT assignable to LiteralType("on") (strict compile-time checking)
+  // - Different literals can unify to their common primitive when types flow together (e.g., branches)
+  // Note: Skip this block if either type is PromotedType - let the PromotedType handler deal with it
+
+  if ((t1 instanceof LiteralType || t2 instanceof LiteralType ||
+      t1 instanceof LiteralUnionType || t2 instanceof LiteralUnionType) &&
+      !(t1 instanceof PromotedType) && !(t2 instanceof PromotedType)) {
+
+    // Exact literal match
+    if (t1 instanceof LiteralType && t2 instanceof LiteralType) {
+      if (t1.value === t2.value && t1.primitiveKind === t2.primitiveKind) {
+        return { success: true };
+      }
+      // Different literals of the same kind - create a union type
+      // This happens in branch unification (if/else returning different literals)
+      if (t1.primitiveKind === t2.primitiveKind) {
+        // Return the unified type as a LiteralUnionType containing both values
+        const unifiedType = new LiteralUnionType([t1.value, t2.value], t1.primitiveKind);
+        return { success: true, unifiedType };
+      }
+      return { success: false, error: `Type mismatch: expected ${formatType(t1)}, got ${formatType(t2)}` };
+    }
+
+    // Literal union matches
+    // When t1 is expected and t2 is actual, t2 must be a subset of t1
+    if (t1 instanceof LiteralUnionType && t2 instanceof LiteralUnionType) {
+      if (t1.primitiveKind === t2.primitiveKind) {
+        const t1Set = new Set(t1.values);
+        const t2Set = new Set(t2.values);
+        const t2IsSubsetOfT1 = t2.values.every(v => t1Set.has(v));
+        const t1IsSubsetOfT2 = t1.values.every(v => t2Set.has(v));
+
+        if (t2IsSubsetOfT1) {
+          return { success: true }; // t2 is subset of t1
+        }
+        if (t1IsSubsetOfT2) {
+          return { success: true }; // t1 is subset of t2 (symmetric for inference)
+        }
+        // Neither is subset - for branch unification return merged type
+        const mergedValues = [...new Set([...t1.values, ...t2.values])];
+        const unifiedType = new LiteralUnionType(mergedValues, t1.primitiveKind);
+        return { success: true, unifiedType };
+      }
+      return { success: false, error: `Type mismatch: expected ${formatType(t1)}, got ${formatType(t2)}` };
+    }
+
+    // Literal into literal union
+    if (t1 instanceof LiteralUnionType && t2 instanceof LiteralType) {
+      if (t1.primitiveKind === t2.primitiveKind) {
+        if (t1.values.includes(t2.value)) {
+          return { success: true }; // Literal is in the union - valid
+        }
+        // Literal not in union - for branch unification return expanded type
+        const unifiedType = new LiteralUnionType([...t1.values, t2.value], t1.primitiveKind);
+        return { success: true, unifiedType };
+      }
+      return { success: false, error: `Type mismatch: expected ${formatType(t1)}, got ${formatType(t2)}` };
+    }
+    if (t2 instanceof LiteralUnionType && t1 instanceof LiteralType) {
+      if (t2.primitiveKind === t1.primitiveKind) {
+        if (t2.values.includes(t1.value)) {
+          return { success: true }; // Literal is in the union - valid
+        }
+        // Literal not in union - for branch unification return expanded type
+        const unifiedType = new LiteralUnionType([...t2.values, t1.value], t2.primitiveKind);
+        return { success: true, unifiedType };
+      }
+      return { success: false, error: `Type mismatch: expected ${formatType(t2)}, got ${formatType(t1)}` };
+    }
+
+    // Literal -> Primitive (subtype relationship): a literal is assignable to its base primitive
+    if (t1 instanceof PrimitiveType && t2 instanceof LiteralType) {
+      if ((t1.name === "string" && t2.primitiveKind === "string") ||
+          (t1.name === "num" && t2.primitiveKind === "num")) {
+        return { success: true };
+      }
+    }
+    if (t1 instanceof PrimitiveType && t2 instanceof LiteralUnionType) {
+      if ((t1.name === "string" && t2.primitiveKind === "string") ||
+          (t1.name === "num" && t2.primitiveKind === "num")) {
+        return { success: true };
+      }
+    }
+
+    // Primitive -> Literal: NOT allowed (strict compile-time checking)
+    // A general string cannot satisfy a literal constraint
+    if (t2 instanceof PrimitiveType && t1 instanceof LiteralType) {
+      return { success: false, error: `Type mismatch: expected ${formatType(t1)}, got ${formatType(t2)}. A general ${t2.name} cannot satisfy a literal constraint.` };
+    }
+    if (t2 instanceof PrimitiveType && t1 instanceof LiteralUnionType) {
+      return { success: false, error: `Type mismatch: expected ${formatType(t1)}, got ${formatType(t2)}. A general ${t2.name} cannot satisfy a literal constraint.` };
+    }
+
+    // Other mismatches
+    return { success: false, error: `Type mismatch: expected ${formatType(t1)}, got ${formatType(t2)}` };
+  }
+
+  // Handle PromotedType: unify against target type or source types (multi-converter)
+  if (t1 instanceof PromotedType) {
+    // First try to unify with target type (no promotion needed)
+    const targetResult = unify(t1.targetType, t2);
+    if (targetResult.success) {
+      return { success: true, promoted: false };
+    }
+    // Then try each converter's source type (for multi-converter support)
+    for (const converter of t1.converters) {
+      if (converter.sourceType) {
+        const sourceResult = unify(converter.sourceType, t2);
+        if (sourceResult.success) {
+          return { success: true, promoted: true, converter: converter.funcName };
+        }
+      }
+    }
+    // Legacy: try single sourceType for backwards compatibility
+    if (t1.sourceType) {
+      const sourceResult = unify(t1.sourceType, t2);
+      if (sourceResult.success) {
+        return { success: true, promoted: true, converter: t1.converterFunc };
+      }
+    }
+    return { success: false, error: `Cannot match ${formatType(t2)} to ${formatType(t1)}` };
+  }
+  if (t2 instanceof PromotedType) {
+    // Reverse case - less common but handle symmetrically
+    const targetResult = unify(t1, t2.targetType);
+    if (targetResult.success) {
+      return { success: true };
+    }
+    // Try each converter's source type
+    for (const converter of t2.converters) {
+      if (converter.sourceType) {
+        const sourceResult = unify(t1, converter.sourceType);
+        if (sourceResult.success) {
+          return { success: true };
+        }
+      }
+    }
+    // Legacy: try single sourceType
+    if (t2.sourceType) {
+      const sourceResult = unify(t1, t2.sourceType);
+      if (sourceResult.success) {
+        return { success: true };
+      }
+    }
+    return { success: false, error: `Cannot match ${formatType(t1)} to ${formatType(t2)}` };
+  }
+
+  // Type variable on left - bind it
+  if (t1 instanceof TypeVariable) {
+    // Occurs check: prevent infinite types
+    if (occursIn(t1, t2)) {
+      return { success: false, error: `Infinite type: ${t1} occurs in ${t2}` };
+    }
+    t1.resolved = t2;
+    return { success: true };
+  }
+
+  // Type variable on right - bind it
+  if (t2 instanceof TypeVariable) {
+    if (occursIn(t2, t1)) {
+      return { success: false, error: `Infinite type: ${t2} occurs in ${t1}` };
+    }
+    t2.resolved = t1;
+    return { success: true };
+  }
+
+  // Special case: DictionaryType can unify with RecordType if all values match
+  // This allows: dict: {[string]: num} = {"a": 1, "b": 2}
+  if (t1.kind === "dictionary" && t2.kind === "record") {
+    // Check that all record field values match the dictionary value type
+    for (const [fieldName, fieldType] of t2.fields) {
+      const valueResult = unify(t1.valueType, fieldType);
+      if (!valueResult.success) {
+        return {
+          success: false,
+          error: `Field '${fieldName}' has type ${fieldType.toString()}, expected ${t1.valueType.toString()}`,
+        };
+      }
+    }
+    return { success: true };
+  }
+
+  // Special case: Flatten nested array types
+  // array<num, 2> should unify with array<array<num, 1>, 1>
+  // This handles matrix construction via push of rows
+  if (t1.kind === "array" && t2.kind === "array") {
+    const flat1 = flattenNestedArrayType(t1);
+    const flat2 = flattenNestedArrayType(t2);
+    // If flattening changed anything, retry unification with flattened types
+    if (flat1 !== t1 || flat2 !== t2) {
+      return unify(flat1, flat2);
+    }
+  }
+
+  // Different kinds
+  if (t1.kind !== t2.kind) {
+    return {
+      success: false,
+      error: `Type mismatch: expected ${t1.toString()}, got ${t2.toString()}`,
+    };
+  }
+
+  // Unify based on kind
+  switch (t1.kind) {
+    case "primitive":
+      if (t1.name !== t2.name) {
+        // Check if types are promotable (num -> complex)
+        if (canPromote(t1, t2).can || canPromote(t2, t1).can) {
+          return { success: true };
+        }
+        return {
+          success: false,
+          error: `Type mismatch: expected ${t1.name}, got ${t2.name}`,
+        };
+      }
+      return { success: true };
+
+    case "function":
+      if (t1.paramTypes.length !== t2.paramTypes.length) {
+        return {
+          success: false,
+          error: `Function arity mismatch: expected ${t1.paramTypes.length} params, got ${t2.paramTypes.length}`,
+        };
+      }
+      for (let i = 0; i < t1.paramTypes.length; i++) {
+        const result = unify(t1.paramTypes[i], t2.paramTypes[i]);
+        if (!result.success) return result;
+      }
+      return unify(t1.returnType, t2.returnType);
+
+    case "record":
+      // If either record is open (from inference), merge fields
+      // Otherwise require exact field match (closed records)
+      if (t1.open || t2.open) {
+        // Merge fields from both records into the one that should accumulate constraints
+        // The open record gets extended with fields from the other
+        const targetRecord = t1.open ? t1 : t2;
+        const sourceRecord = t1.open ? t2 : t1;
+
+        // Unify common fields
+        for (const [name, type] of sourceRecord.fields) {
+          const existingType = targetRecord.fields.get(name);
+          if (existingType) {
+            const result = unify(existingType, type);
+            if (!result.success) return result;
+          } else {
+            // Add new field from source to target
+            targetRecord.fields.set(name, type);
+          }
+        }
+        return { success: true };
+      }
+
+      // Both records are closed - must have exactly the same fields
+      if (t1.fields.size !== t2.fields.size) {
+        return { success: false, error: "Record field count mismatch" };
+      }
+      for (const [name, type] of t1.fields) {
+        const otherType = t2.fields.get(name);
+        if (!otherType) {
+          return { success: false, error: `Missing field: ${name}` };
+        }
+        const result = unify(type, otherType);
+        if (!result.success) return result;
+      }
+      return { success: true };
+
+    case "dictionary":
+      // Unify key types
+      const keyResult = unify(t1.keyType, t2.keyType);
+      if (!keyResult.success) {
+        return { success: false, error: `Dictionary key type mismatch: ${keyResult.error}` };
+      }
+      // Unify value types
+      const valueResult = unify(t1.valueType, t2.valueType);
+      if (!valueResult.success) {
+        return { success: false, error: `Dictionary value type mismatch: ${valueResult.error}` };
+      }
+      return { success: true };
+
+    case "list":
+      return unify(t1.elementType, t2.elementType);
+
+    case "array":
+      // Handle rank unification
+      let rank1 = t1.rank;
+      let rank2 = t2.rank;
+
+      // Helper to check if rank is a variable representation
+      const isRankVar = (r) => {
+        if (r instanceof TypeVariable) return true;
+        if (typeof r === 'object' && r !== null && r.var) return true;
+        return false;
+      };
+
+      // Helper to get resolved rank (for TypeVariable instances)
+      const resolveRank = (r) => {
+        if (r instanceof TypeVariable) {
+          const resolved = r.resolve();
+          if (resolved instanceof TypeVariable) return r; // Still variable
+          return resolved; // Resolved to a value
+        }
+        return r;
+      };
+
+      rank1 = resolveRank(rank1);
+      rank2 = resolveRank(rank2);
+
+      const rank1IsVar = isRankVar(rank1);
+      const rank2IsVar = isRankVar(rank2);
+
+      // Check if ranks can be unified
+      if (rank1IsVar && !rank2IsVar) {
+        // rank1 is variable, rank2 is concrete - bind/constrain rank1
+        if (rank1 instanceof TypeVariable) {
+          rank1.resolved = true;
+          rank1.resolvedTo = rank2;
+        }
+        // For { var: 'R' } format, we accept it (defer constraint)
+        // The actual binding should happen elsewhere
+      } else if (rank2IsVar && !rank1IsVar) {
+        // rank2 is variable, rank1 is concrete - bind/constrain rank2
+        if (rank2 instanceof TypeVariable) {
+          rank2.resolved = true;
+          rank2.resolvedTo = rank1;
+        }
+        // For { var: 'R' } format, we accept it (defer constraint)
+      } else if (rank1IsVar && rank2IsVar) {
+        // Both are variable - try to unify them
+        if (rank1 instanceof TypeVariable && rank2 instanceof TypeVariable) {
+          if (rank1.id !== rank2.id) {
+            rank1.resolved = true;
+            rank1.resolvedTo = rank2;
+          }
+        }
+        // For { var: 'R' } objects, we accept as compatible
+      } else if (rank1 !== rank2) {
+        // Both are concrete but different
+        return {
+          success: false,
+          error: `Array rank mismatch: expected rank ${rank1}, got rank ${rank2}`,
+        };
+      }
+      return unify(t1.elementType, t2.elementType);
+
+    case "union":
+      // Union unification is complex - for now, require exact match
+      if (t1.types.length !== t2.types.length) {
+        return { success: false, error: "Union type mismatch" };
+      }
+      // Try to match each type in t1 with one in t2
+      for (const ut1 of t1.types) {
+        let matched = false;
+        for (const ut2 of t2.types) {
+          const result = unify(ut1, ut2);
+          if (result.success) {
+            matched = true;
+            break;
+          }
+        }
+        if (!matched) {
+          return { success: false, error: "Union type mismatch" };
+        }
+      }
+      return { success: true };
+
+    default:
+      return { success: false, error: `Unknown type kind: ${t1.kind}` };
+  }
+}
+
+/**
+ * Check if a type variable occurs in a type (for occurs check)
+ */
+function occursIn(tvar, type) {
+  if (type instanceof TypeVariable) {
+    type = type.resolve();
+    if (type instanceof TypeVariable) {
+      return tvar.id === type.id;
+    }
+  }
+
+  switch (type.kind) {
+    case "primitive":
+      return false;
+    case "function":
+      return (
+        type.paramTypes.some((t) => occursIn(tvar, t)) ||
+        occursIn(tvar, type.returnType)
+      );
+    case "record":
+      for (const t of type.fields.values()) {
+        if (occursIn(tvar, t)) return true;
+      }
+      return false;
+    case "dictionary":
+      return occursIn(tvar, type.keyType) || occursIn(tvar, type.valueType);
+    case "list":
+      return occursIn(tvar, type.elementType);
+    case "array":
+      return occursIn(tvar, type.elementType);
+    case "union":
+      return type.types.some((t) => occursIn(tvar, t));
+    default:
+      return false;
+  }
+}
+
+/**
+ * Numeric promotion: num + num -> num
+ * Simplified since we only have one numeric type
+ */
+export function numericPromotion(t1, t2) {
+  if (t1 instanceof TypeVariable) t1 = t1.resolve();
+  if (t2 instanceof TypeVariable) t2 = t2.resolve();
+
+  if (!isNumeric(t1) || !isNumeric(t2)) {
+    return null; // Not numeric types
+  }
+
+  return NUM;
+}
+
+// ============================================================================
+// TYPE PARSING HELPERS
+// ============================================================================
+
+/**
+ * Parse a type name string into a Type
+ * Used for converting parsed type annotations to internal types
+ */
+export function parseTypeName(name) {
+  const lowered = name.toLowerCase();
+  switch (lowered) {
+    case "num":
+    case "int":      // backwards compatibility
+    case "float":    // backwards compatibility
+    case "number":   // convenience alias
+      return NUM;
+    case "bool":
+    case "boolean":
+      return BOOL;
+    case "string":
+      return STRING;
+    case "unit":
+    case "void":
+      return UNIT;
+    case "complex":
+      // Complex is now a record type {re: num, im: num}
+      // Return RecordType for class-based type system
+      const complexFields = new Map();
+      complexFields.set("re", NUM);
+      complexFields.set("im", NUM);
+      return new RecordType(complexFields, false);
+    case "array":
+      // Bare "array" type without generics - use fresh type variables for element type and rank
+      return new ArrayType(freshTypeVar(), null); // null rank = any rank
+    default:
+      return null; // Unknown type
+  }
+}
+
+/**
+ * Convert a parsed TypeAnnotation AST node to an internal Type
+ * @param {Object} annotation - TypeAnnotation AST node
+ * @param {Object} env - Optional type environment for looking up type aliases
+ */
+export function fromTypeAnnotation(annotation, env = null) {
+  if (!annotation) return freshTypeVar();
+
+  // Handle record types: { name: string, age: num }
+  if (annotation.kind === "record") {
+    const fields = new Map();
+    for (const field of annotation.details.fields) {
+      const fieldType = fromTypeAnnotation(field.type, env);
+      fields.set(field.name, fieldType);
+    }
+    return new RecordType(fields, annotation.details.open || false);
+  }
+
+  // Handle function types: (T1, T2) -> R
+  if (annotation.kind === "function") {
+    const paramTypes = annotation.details.paramTypes.map(t => fromTypeAnnotation(t, env));
+    const returnType = fromTypeAnnotation(annotation.details.returnType, env);
+    return new FunctionType(paramTypes, returnType);
+  }
+
+  // Handle dictionary types: {[K]: V}
+  if (annotation.kind === "dictionary") {
+    const keyType = fromTypeAnnotation(annotation.details.keyType, env);
+    const valueType = fromTypeAnnotation(annotation.details.valueType, env);
+    return new DictionaryType(keyType, valueType);
+  }
+
+  // Handle literal types: "on" or 42
+  if (annotation.kind === "literal") {
+    return new LiteralType(
+      annotation.details.value,
+      annotation.details.primitiveKind
+    );
+  }
+
+  // Handle literal union types: "on" | "off" or 0 | 1 | 2
+  if (annotation.kind === "literalUnion") {
+    return new LiteralUnionType(
+      annotation.details.values,
+      annotation.details.primitiveKind
+    );
+  }
+
+  // Handle promoted types: Type | converter(param) or Type | conv1(p) | conv2(p)
+  if (annotation.kind === "promoted") {
+    const targetType = fromTypeAnnotation(annotation.details.targetType, env);
+    const paramRef = annotation.details.paramRef;
+
+    // Check for new multi-converter format
+    if (annotation.details.converters) {
+      // Multi-converter format: converters is an array
+      const converters = annotation.details.converters.map(c => ({
+        funcName: c.funcName,
+        sourceType: null // Will be set during function definition validation
+      }));
+      return new PromotedType(targetType, converters, paramRef);
+    } else {
+      // Old single-converter format for backwards compatibility
+      const converterFunc = annotation.details.converterFunc;
+      return new PromotedType(targetType, converterFunc, paramRef);
+    }
+  }
+
+  const { baseType, genericParams } = annotation;
+
+  // Handle generic types
+  if (genericParams && genericParams.length > 0) {
+    const baseLower = baseType.toLowerCase();
+
+    if (baseLower === "array") {
+      if (genericParams.length !== 2) {
+        throw new Error("array type requires 2 parameters: array<T, R>");
+      }
+      const elemType = fromTypeAnnotation(genericParams[0], env);
+      const rank = genericParams[1]; // Should be a number
+      if (typeof rank !== "number") {
+        throw new Error("array rank must be a number");
+      }
+      return new ArrayType(elemType, rank);
+    }
+
+    // list<T> is deprecated - treat as array<T,1> for backwards compatibility
+    if (baseLower === "list") {
+      if (genericParams.length !== 1) {
+        throw new Error("list type requires 1 parameter: list<T>");
+      }
+      const elemType = fromTypeAnnotation(genericParams[0], env);
+      return new ArrayType(elemType, 1);
+    }
+  }
+
+  // IMPORTANT: Check schema variables FIRST (exact case match)
+  // This allows user-defined types like "Complex" to shadow primitive "complex"
+  // when the user explicitly defines a schema with that name
+  if (env && typeof env.lookup === "function") {
+    const varType = env.lookup(baseType);
+    if (varType instanceof RecordType) {
+      // When using a schema as a type annotation (e.g., parameter or return type),
+      // we want to refer to instances of that schema, not the schema itself.
+      // Create an "instance" type with the same fields but without requiredFields markers,
+      // so field access on results is allowed.
+      if (varType.requiredFields && varType.requiredFields.size > 0) {
+        return new RecordType(varType.fields, false, false, null);
+      }
+      return varType;
+    }
+  }
+
+  // Then try to look up as a type alias
+  if (env && typeof env.lookupTypeAlias === "function") {
+    const aliasType = env.lookupTypeAlias(baseType);
+    if (aliasType) {
+      return aliasType;
+    }
+  }
+
+  // Finally check primitive types (case-insensitive)
+  const primType = parseTypeName(baseType);
+  if (primType) {
+    return primType;
+  }
+
+  // Unknown type - return a type variable
+  return freshTypeVar();
+}
+
+// ============================================================================
+// TYPE STRING PARSING (for primitive signatures)
+// ============================================================================
+
+/**
+ * Parse a type string from primitive signatures into a structured type
+ * Handles: "num", "complex", "bool", "string", "object", "list", "array<num,R>", "array<num,2>"
+ *
+ * @param {string} str - Type string like "array<num,R>" or "num"
+ * @returns {Object} Structured type representation
+ */
+export function parseTypeString(str) {
+  str = str.trim();
+
+  // Handle array types: array<elem,rank>
+  if (str.startsWith("array<")) {
+    const inner = str.slice(6, -1); // Remove "array<" and ">"
+    const commaIdx = findTopLevelComma(inner);
+    if (commaIdx === -1) {
+      throw new Error(`Invalid array type: ${str}`);
+    }
+    const elemStr = inner.slice(0, commaIdx).trim();
+    const rankStr = inner.slice(commaIdx + 1).trim();
+
+    const elem = parseTypeString(elemStr);
+    const rank = rankStr === "R" ? { var: "R" } : parseInt(rankStr, 10);
+
+    return { kind: "array", elem, rank };
+  }
+
+  // Handle list types: list<elem> -> treat as array<elem,1> for backwards compatibility
+  if (str.startsWith("list<")) {
+    const inner = str.slice(5, -1); // Remove "list<" and ">"
+    const elem = parseTypeString(inner);
+    return { kind: "array", elem, rank: 1 };
+  }
+
+  // Handle primitive types
+  switch (str) {
+    case "num":
+      return { kind: "primitive", name: "num" };
+    case "complex":
+      // Complex is now a record type {re: num, im: num}
+      return {
+        kind: "record",
+        fields: new Map([
+          ["re", { kind: "primitive", name: "num" }],
+          ["im", { kind: "primitive", name: "num" }],
+        ]),
+        open: false,
+      };
+    case "bool":
+      return { kind: "primitive", name: "bool" };
+    case "string":
+      return { kind: "primitive", name: "string" };
+    case "unit":
+      return { kind: "primitive", name: "unit" };
+    case "object":
+    case "record":
+      // Generic object/record type - matches any record
+      return { kind: "record", fields: new Map(), open: true };
+    case "list":
+      // Generic list type - treat as array for backwards compatibility
+      return { kind: "array", elem: { kind: "primitive", name: "num" }, rank: 1, open: true };
+    case "any":
+      // Any type - matches any value
+      return { kind: "any" };
+    default:
+      // Single uppercase letters are type variables (T, U, V, etc.)
+      if (str.length === 1 && str >= "A" && str <= "Z") {
+        return { kind: "typevar", name: str };
+      }
+      throw new Error(`Unknown type: ${str}`);
+  }
+}
+
+/**
+ * Find the index of the top-level comma in a type string
+ * (not inside nested angle brackets)
+ */
+function findTopLevelComma(str) {
+  let depth = 0;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (ch === "<") depth++;
+    else if (ch === ">") depth--;
+    else if (ch === "," && depth === 0) return i;
+  }
+  return -1;
+}
+
+/**
+ * Convert a structured type back to a string for display
+ */
+export function typeToString(type) {
+  if (type.kind === "primitive") {
+    return type.name;
+  }
+  if (type.kind === "array") {
+    const elemStr = typeToString(type.elem);
+    const rankStr = typeof type.rank === "object" ? type.rank.var : type.rank;
+    return `array<${elemStr},${rankStr}>`;
+  }
+  return JSON.stringify(type);
+}
+
+/**
+ * Format a type for display in error messages
+ * Handles both class-based types and structured type objects
+ *
+ * @param {Object} type - Type to format (class or structured)
+ * @returns {string}
+ */
+export function formatType(type) {
+  if (!type) return "unknown";
+
+  // Class-based types have toString() method
+  if (typeof type.toString === "function" && type.constructor !== Object) {
+    return type.toString();
+  }
+
+  // Structured type objects
+  if (type.kind === "primitive") {
+    return type.name;
+  }
+
+  if (type.kind === "array") {
+    const elemStr = formatType(type.elem);
+    const rankStr = typeof type.rank === "object" ? type.rank.var : type.rank;
+    return `array<${elemStr},${rankStr}>`;
+  }
+
+  // DEPRECATED: list types are converted to array<T,1> at parse time
+  // This handler exists only for backward compatibility with old code
+  if (type.kind === "list") {
+    const elemStr = formatType(type.elem);
+    return `array<${elemStr},1>`;
+  }
+
+  if (type.kind === "function") {
+    const paramsStr = (type.params || []).map(formatType).join(", ");
+    const retStr = formatType(type.ret);
+    return `(${paramsStr}) -> ${retStr}`;
+  }
+
+  if (type.kind === "record") {
+    if (type.fields instanceof Map && type.fields.size > 0) {
+      const fieldStrs = [];
+      for (const [name, fieldType] of type.fields) {
+        fieldStrs.push(`${name}: ${formatType(fieldType)}`);
+      }
+      return `{ ${fieldStrs.join(", ")} }`;
+    }
+    return "{}";
+  }
+
+  if (type.kind === "dictionary") {
+    const keyStr = formatType(type.keyType);
+    const valueStr = formatType(type.valueType);
+    return `{[${keyStr}]: ${valueStr}}`;
+  }
+
+  if (type.kind === "union") {
+    return (type.types || []).map(formatType).join(" | ");
+  }
+
+  if (type.kind === "typevar") {
+    if (type.resolved) {
+      return formatType(type.resolved);
+    }
+    return `T${type.id ?? "?"}`;
+  }
+
+  if (type.kind === "unknown") {
+    return "unknown";
+  }
+
+  return type.kind || "unknown";
+}
+
+// ============================================================================
+// TYPE MATCHING (for overload resolution)
+// ============================================================================
+
+/**
+ * Match a pattern type against a concrete type
+ * Pattern may contain type variables (like R in array<num,R>)
+ *
+ * Returns structured result:
+ * - { success: true, bindings } - exact match
+ * - { success: false } - incompatible types
+ * - { deferred: true, constraint: {...}, bindings } - can match if constraint is satisfied
+ *
+ * @param {Object} pattern - Pattern type from signature
+ * @param {Object} concrete - Concrete type from runtime
+ * @param {Object} bindings - Existing bindings (mutated)
+ * @returns {Object} Match result with success/deferred status and bindings
+ */
+export function matchType(pattern, concrete, bindings = {}) {
+  // Guard against undefined
+  if (!pattern || !concrete) return { success: false };
+
+  // Any type - matches everything
+  if (pattern.kind === "any") {
+    return { success: true, bindings };
+  }
+
+  // Type variable - matches any type and binds
+  if (pattern.kind === "typevar") {
+    const varName = pattern.name;
+    if (varName in bindings) {
+      // Already bound - concrete must match the bound type
+      // For simplicity, we compare stringified types
+      if (JSON.stringify(bindings[varName]) !== JSON.stringify(concrete)) {
+        return { success: false };
+      }
+    } else {
+      // Bind the variable to the concrete type
+      bindings[varName] = concrete;
+    }
+    return { success: true, bindings };
+  }
+
+  // Literal type: "on", 42
+  if (pattern.kind === "literal") {
+    // Literal pattern must match exactly
+    if (concrete.kind === "literal") {
+      if (pattern.value === concrete.value && pattern.primitiveKind === concrete.primitiveKind) {
+        return { success: true, bindings };
+      }
+    }
+    return { success: false };
+  }
+
+  // Literal union type: "on" | "off"
+  if (pattern.kind === "literalUnion") {
+    // Concrete can be:
+    // - Same literalUnion (subset check)
+    // - A single literal that's in the union
+    if (concrete.kind === "literal") {
+      if (pattern.primitiveKind === concrete.primitiveKind &&
+          pattern.values.includes(concrete.value)) {
+        return { success: true, bindings };
+      }
+    }
+    if (concrete.kind === "literalUnion") {
+      // All concrete values must be in pattern values
+      if (pattern.primitiveKind === concrete.primitiveKind) {
+        const patternSet = new Set(pattern.values);
+        const allIncluded = concrete.values.every(v => patternSet.has(v));
+        if (allIncluded) {
+          return { success: true, bindings };
+        }
+      }
+    }
+    return { success: false };
+  }
+
+  // Primitive type
+  if (pattern.kind === "primitive") {
+    // Direct primitive match
+    if (concrete.kind === "primitive" && pattern.name === concrete.name) {
+      return { success: true, bindings };
+    }
+    // Special case: "complex" primitive matches {re: num, im: num} record
+    if (pattern.name === "complex" && isComplexRecord(concrete)) {
+      return { success: true, bindings };
+    }
+    // Subtype relationship: literal types are subtypes of their base primitive
+    // "on" (LiteralType) matches string (PrimitiveType) when string is the pattern
+    if (concrete.kind === "literal") {
+      if ((pattern.name === "string" && concrete.primitiveKind === "string") ||
+          (pattern.name === "num" && concrete.primitiveKind === "num")) {
+        return { success: true, bindings };
+      }
+    }
+    if (concrete.kind === "literalUnion") {
+      if ((pattern.name === "string" && concrete.primitiveKind === "string") ||
+          (pattern.name === "num" && concrete.primitiveKind === "num")) {
+        return { success: true, bindings };
+      }
+    }
+    return { success: false };
+  }
+
+  // Array type
+  if (pattern.kind === "array") {
+    if (concrete.kind !== "array") return { success: false };
+
+    // Match element type
+    const elemResult = matchType(pattern.elem, concrete.elem, bindings);
+    if (!elemResult.success && !elemResult.deferred) return { success: false };
+
+    const elemBindings = elemResult.bindings || bindings;
+    const deferredConstraints = elemResult.deferred && elemResult.constraints ? [...elemResult.constraints] : [];
+
+    // Match rank
+    if (typeof pattern.rank === "object" && pattern.rank.var) {
+      // Pattern has variable rank - can bind to any concrete rank
+      const varName = pattern.rank.var;
+      if (varName in elemBindings) {
+        // Already bound - check if concrete matches
+        const boundValue = elemBindings[varName];
+        if (typeof concrete.rank === "object" && concrete.rank.var) {
+          // Concrete has variable rank, pattern's variable is bound
+          if (typeof boundValue === "number") {
+            // Pattern bound to concrete, arg is variable - defer constraint
+            deferredConstraints.push({
+              type: 'rank',
+              rankVar: concrete.rank.var,
+              requiredRank: boundValue
+            });
+          } else if (typeof boundValue === "object" && boundValue.var) {
+            // Both are variable objects - check if same variable name
+            if (boundValue.var !== concrete.rank.var) {
+              // Different variable names - we need to unify them
+              // For now, defer a constraint that they must be equal
+              // This case is complex, treat as compatible for now
+            }
+          } else if (boundValue !== concrete.rank) {
+            // Unexpected case - fail
+            return { success: false };
+          }
+        } else if (typeof boundValue === "object" && boundValue.var) {
+          // Pattern bound to variable, concrete is a number
+          // Defer constraint: the bound variable must equal the concrete rank
+          deferredConstraints.push({
+            type: 'rank',
+            rankVar: boundValue.var,
+            requiredRank: concrete.rank
+          });
+        } else if (boundValue !== concrete.rank) {
+          // Both concrete values must match
+          return { success: false };
+        }
+      } else {
+        // Bind the variable
+        elemBindings[varName] = concrete.rank;
+      }
+    } else if (typeof concrete.rank === "object" && concrete.rank.var) {
+      // Concrete (argument) has variable rank, pattern has concrete rank
+      // This is the case where we need a deferred constraint
+      deferredConstraints.push({
+        type: 'rank',
+        rankVar: concrete.rank.var,
+        requiredRank: pattern.rank
+      });
+    } else {
+      // Both concrete - must match exactly
+      if (pattern.rank !== concrete.rank) return { success: false };
+    }
+
+    // Return with any collected deferred constraints
+    if (deferredConstraints.length > 0) {
+      return {
+        deferred: true,
+        constraints: deferredConstraints,
+        bindings: elemBindings
+      };
+    }
+    return { success: true, bindings: elemBindings };
+  }
+
+  // Record type (object) - all records are closed, must match exactly
+  if (pattern.kind === "record") {
+    if (concrete.kind !== "record") return { success: false };
+    // Check that concrete has all required fields
+    const deferredConstraints = [];
+    for (const [name, fieldType] of pattern.fields) {
+      const concreteFieldType = concrete.fields?.get?.(name);
+      if (!concreteFieldType) return { success: false };
+      const fieldResult = matchType(fieldType, concreteFieldType, bindings);
+      if (!fieldResult.success && !fieldResult.deferred) return { success: false };
+      bindings = fieldResult.bindings || bindings;
+      if (fieldResult.deferred && fieldResult.constraints) {
+        deferredConstraints.push(...fieldResult.constraints);
+      }
+    }
+    if (deferredConstraints.length > 0) {
+      return { deferred: true, constraints: deferredConstraints, bindings };
+    }
+    return { success: true, bindings };
+  }
+
+  // DEPRECATED: list type - now matches array<T,1> for backward compatibility
+  if (pattern.kind === "list") {
+    // List patterns match both list and array types (rank 1)
+    if (concrete.kind === "list") {
+      return matchType(pattern.elem, concrete.elem, bindings);
+    }
+    if (concrete.kind === "array" && concrete.rank === 1) {
+      return matchType(pattern.elem, concrete.elem, bindings);
+    }
+    return { success: false };
+  }
+
+  // Function type matching - supports bidirectional inference
+  // When concrete function has TypeVariable params, they get constrained by pattern params
+  if (pattern.kind === "function") {
+    if (concrete.kind !== "function") return { success: false };
+
+    // Parameter counts must match
+    if (!pattern.params || !concrete.params) return { success: false };
+    if (pattern.params.length !== concrete.params.length) return { success: false };
+
+    const deferredConstraints = [];
+    const typeVarUnifications = [];
+
+    // Match each parameter type (contravariant - pattern ← concrete)
+    // For higher-order functions, if concrete has TypeVar params, constrain them
+    for (let i = 0; i < pattern.params.length; i++) {
+      const patternParam = pattern.params[i];
+      const concreteParam = concrete.params[i];
+
+      // If concrete param is a TypeVariable, record unification with expected type
+      if (concreteParam.kind === "typevar" && !concreteParam.resolved) {
+        typeVarUnifications.push({
+          typeVarId: concreteParam.id,
+          targetType: patternParam
+        });
+        continue; // TypeVariable matches, will be constrained later
+      }
+
+      // Regular matching (pattern param should be satisfied by concrete param)
+      const paramResult = matchType(patternParam, concreteParam, bindings);
+      if (!paramResult.success && !paramResult.deferred) return { success: false };
+      bindings = paramResult.bindings || bindings;
+      if (paramResult.deferred && paramResult.constraints) {
+        deferredConstraints.push(...paramResult.constraints);
+      }
+    }
+
+    // Match return type (covariant - pattern ← concrete)
+    const retResult = matchType(pattern.ret, concrete.ret, bindings);
+    if (!retResult.success && !retResult.deferred) return { success: false };
+    bindings = retResult.bindings || bindings;
+    if (retResult.deferred && retResult.constraints) {
+      deferredConstraints.push(...retResult.constraints);
+    }
+
+    // Return with collected information
+    const result = { success: true, bindings };
+    if (deferredConstraints.length > 0) {
+      result.deferred = true;
+      result.constraints = deferredConstraints;
+    }
+    if (typeVarUnifications.length > 0) {
+      result.typeVarUnifications = typeVarUnifications;
+    }
+    return result;
+  }
+
+  return { success: false };
+}
+
+/**
+ * Simple match that returns bindings or null (for backward compatibility)
+ * Use this when you don't care about deferred constraints
+ */
+export function matchTypeSimple(pattern, concrete, bindings = {}) {
+  const result = matchType(pattern, concrete, bindings);
+  if (result.success) return result.bindings;
+  if (result.deferred) return result.bindings; // Accept deferred as success for simple cases
+  return null;
+}
+
+/**
+ * Substitute type variables in a type using bindings
+ *
+ * @param {Object} type - Type with possible variables
+ * @param {Object} bindings - Variable bindings
+ * @returns {Object} Substituted type
+ */
+export function substituteType(type, bindings) {
+  // Guard against undefined
+  if (!type) return { kind: "unknown" };
+
+  if (type.kind === "primitive") {
+    return type;
+  }
+
+  if (type.kind === "array") {
+    const elem = substituteType(type.elem, bindings);
+    let rank = type.rank;
+    if (typeof rank === "object" && rank.var && rank.var in bindings) {
+      rank = bindings[rank.var];
+    }
+    return { kind: "array", elem, rank };
+  }
+
+  return type;
+}
+
+// ============================================================================
+// TYPE PROMOTION
+// ============================================================================
+
+/**
+ * Check if a type can be promoted to another type.
+ * Supports both built-in promotions (num → complex) and user-defined
+ * promotions via PromotedType.
+ *
+ * @param {Object} from - Source type (argument type)
+ * @param {Object} to - Target type (parameter type, may be PromotedType)
+ * @returns {{can: boolean, converter: string|null}} Promotion result
+ *   - can: whether promotion is possible
+ *   - converter: converter function name (null for built-in promotion)
+ */
+export function canPromote(from, to) {
+  // Guard against undefined
+  if (!from || !to) return { can: false, converter: null };
+
+  // Handle LiteralType: no promotion possible, must match exactly
+  // (literal types are strictly compile-time checked)
+  if (to instanceof LiteralType) {
+    // from must be a LiteralType with the same value
+    if (from instanceof LiteralType &&
+        from.value === to.value &&
+        from.primitiveKind === to.primitiveKind) {
+      return { can: false, converter: null }; // Exact match, no promotion needed
+    }
+    return { can: false, converter: null };
+  }
+
+  // Handle LiteralUnionType: no promotion, just subset checking
+  if (to instanceof LiteralUnionType) {
+    // from must be a literal or literal union that's a subset
+    if (from instanceof LiteralType) {
+      if (from.primitiveKind === to.primitiveKind && to.values.includes(from.value)) {
+        return { can: false, converter: null }; // Subset match, no promotion
+      }
+    }
+    if (from instanceof LiteralUnionType) {
+      if (from.primitiveKind === to.primitiveKind) {
+        const toSet = new Set(to.values);
+        const isSubset = from.values.every(v => toSet.has(v));
+        if (isSubset) {
+          return { can: false, converter: null }; // Subset match, no promotion
+        }
+      }
+    }
+    return { can: false, converter: null };
+  }
+
+  // Handle PromotedType: check if from matches any converter's sourceType
+  if (to instanceof PromotedType) {
+    // First check if from matches the target type (no conversion needed)
+    // Use isAssignableTo to allow literals to match their base primitives
+    if (isAssignableTo(from, to.targetType)) {
+      return { can: false, converter: null }; // No promotion needed - assignable match
+    }
+
+    // Check each converter's sourceType (for multi-converter support)
+    // Use isAssignableTo to allow literals to match their base primitives
+    for (let i = 0; i < to.converters.length; i++) {
+      const converter = to.converters[i];
+      if (converter.sourceType && isAssignableTo(from, converter.sourceType)) {
+        return {
+          can: true,
+          converter: converter.funcName,
+          converterIndex: i
+        };
+      }
+    }
+
+    // Legacy: check single sourceType (backwards compatibility)
+    if (to.sourceType && isAssignableTo(from, to.sourceType)) {
+      return { can: true, converter: to.converterFunc };
+    }
+
+    return { can: false, converter: null };
+  }
+
+  // Built-in: num → complex (complex is now {re: num, im: num} record)
+  if (
+    from.kind === "primitive" &&
+    from.name === "num" &&
+    isComplexRecord(to)
+  ) {
+    return { can: true, converter: "to_complex" };
+  }
+
+  // Built-in: array<num,R> → array<complex,R> (with same rank)
+  // Complex element type is now a record
+  if (
+    from.kind === "array" &&
+    to.kind === "array" &&
+    from.elem?.kind === "primitive" &&
+    from.elem?.name === "num" &&
+    isComplexRecord(to.elem)
+  ) {
+    // Ranks must match (either both concrete and equal, or both variables)
+    if (typeof from.rank === "number" && typeof to.rank === "number") {
+      if (from.rank === to.rank) {
+        return { can: true, converter: "to_complex" };
+      }
+    }
+    return { can: false, converter: null };
+  }
+
+  return { can: false, converter: null };
+}
+
+/**
+ * Legacy wrapper for boolean-returning canPromote behavior.
+ * Used by existing code that expects a boolean.
+ */
+export function canPromoteBool(from, to) {
+  return canPromote(from, to).can;
+}
+
+/**
+ * Get the promotion cost between two types
+ * 0 = exact match
+ * 1 = promotable
+ * Infinity = not compatible
+ *
+ * @param {Object} from - Actual type
+ * @param {Object} to - Expected type (pattern)
+ * @param {Object} bindings - Type variable bindings
+ * @returns {number}
+ */
+export function promotionCost(from, to, bindings = {}) {
+  // Try exact match first
+  const matchResult = matchType(to, from, { ...bindings });
+  if (matchResult.success || matchResult.deferred) {
+    return 0;
+  }
+
+  // Try with promotion
+  const promoResult = canPromote(from, to);
+  if (promoResult.can) {
+    return 1;
+  }
+
+  return Infinity;
+}