@elaraai/east 0.0.1-beta.9 → 1.0.0

package/dist/src/types.js

@@ -6,6 +6,58 @@ import { isRef } from "./containers/ref.js";
 import { SortedMap } from "./containers/sortedmap.js";
 import { SortedSet } from "./containers/sortedset.js";
 import { variant_symbol } from "./containers/variant.js";
+import { isMatrix } from "./containers/matrix.js";
+// =============================================================================
+// Type identity — every EastType gets a unique integer ID via a Symbol property.
+// This enables O(1) identity-based lookup across independently constructed
+// type objects that are structurally identical. Mirrors east-c's pointer interning.
+// =============================================================================
+export const type_id_symbol = Symbol.for("@elaraai/east/type_id");
+let _next_type_id = 0;
+/** Assign a unique type_id to an EastType. Called by every type constructor. */
+export function assignTypeId(type) {
+    type[type_id_symbol] = _next_type_id++;
+    return type;
+}
+/** Get the type_id of an EastType, EastTypeValue, or any stamped object. */
+export function getTypeId(type) {
+    return type?.[type_id_symbol];
+}
+// =============================================================================
+// Type interning — ensures structurally identical compound types share identity.
+// Mirrors east-c's pointer-based hash table interning.
+// Uses integer hashing of child type_ids for O(1) lookup with zero GC pressure.
+// =============================================================================
+function hashCombine(h, v) {
+    return ((h ^ v) * 0x01000193) | 0;
+}
+// Intern table: hash → type. On collision we chain (store array).
+const _intern = new Map();
+function internLookup(hash, verify) {
+    const entry = _intern.get(hash);
+    if (entry === undefined)
+        return undefined;
+    if (Array.isArray(entry)) {
+        for (const candidate of entry) {
+            if (verify(candidate))
+                return candidate;
+        }
+        return undefined;
+    }
+    return verify(entry) ? entry : undefined;
+}
+function internStore(hash, type) {
+    const existing = _intern.get(hash);
+    if (existing === undefined) {
+        _intern.set(hash, type);
+    }
+    else if (Array.isArray(existing)) {
+        existing.push(type);
+    }
+    else {
+        _intern.set(hash, [existing, type]);
+    }
+}
 /**
  * Error thrown when type operations encounter incompatible types.
  *
@@ -13,28 +65,52 @@ import { variant_symbol } from "./containers/variant.js";
  * Used by type union, intersection, and equality operations when types
  * cannot be combined or compared as requested.
  */
-class TypeMismatchError extends Error {
-    constructor(message, options) {
-        super(message, options);
+export class TypeMismatchError extends Error {
+    path;
+    reason;
+    constructor(reason, options) {
+        super(reason, options);
         this.name = "TypeMismatchError";
+        this.reason = reason;
+        this.path = [];
+    }
+    addPathSegment(segment) {
+        this.path.unshift(segment);
+        this.message = `at ${this.path.join("")}: ${this.reason}`;
+    }
+}
+function withPathSegment(segment, fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        if (err instanceof TypeMismatchError)
+            err.addPathSegment(segment);
+        throw err;
     }
 }
 /** Singleton instance of the Never type. */
-export const NeverType = { type: "Never" };
+export const NeverType = assignTypeId({ type: "Never" });
 /** Singleton instance of the Null type. */
-export const NullType = { type: "Null" };
+export const NullType = assignTypeId({ type: "Null" });
 /** Singleton instance of the Boolean type. */
-export const BooleanType = { type: "Boolean" };
+export const BooleanType = assignTypeId({ type: "Boolean" });
 /** Singleton instance of the Integer type. */
-export const IntegerType = { type: "Integer" };
+export const IntegerType = assignTypeId({ type: "Integer" });
 /** Singleton instance of the Float type. */
-export const FloatType = { type: "Float" };
+export const FloatType = assignTypeId({ type: "Float" });
 /** Singleton instance of the String type. */
-export const StringType = { type: "String" };
+export const StringType = assignTypeId({ type: "String" });
 /** Singleton instance of the DateTime type. */
-export const DateTimeType = { type: "DateTime" };
+export const DateTimeType = assignTypeId({ type: "DateTime" });
 /** Singleton instance of the Blob type. */
-export const BlobType = { type: "Blob" };
+export const BlobType = assignTypeId({ type: "Blob" });
+/** Returns true if the type is a primitive (no child types, no refs possible). */
+export function isPrimitiveType(type) {
+    const t = type.type;
+    return t === "Never" || t === "Null" || t === "Boolean" || t === "Integer" ||
+        t === "Float" || t === "String" || t === "DateTime" || t === "Blob";
+}
 /**
  * Constructs a reference (or cell) type with the specified element type.
  *
@@ -48,7 +124,13 @@ export const BlobType = { type: "Blob" };
  * @throws When the element type contains functions
  */
 export function RefType(type) {
-    return { type: "Ref", value: type };
+    const h = hashCombine(0x52, type?.[type_id_symbol] ?? 0);
+    const cached = internLookup(h, (c) => c.type === "Ref" && c.value === type);
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Ref", value: type });
+    internStore(h, result);
+    return result;
 }
 ;
 /**
@@ -60,7 +142,13 @@ export function RefType(type) {
  * @throws When the element type contains functions
  */
 export function ArrayType(type) {
-    return { type: "Array", value: type };
+    const h = hashCombine(0x41, type?.[type_id_symbol] ?? 0);
+    const cached = internLookup(h, (c) => c.type === "Array" && c.value === type);
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Array", value: type });
+    internStore(h, result);
+    return result;
 }
 ;
 /**
@@ -75,7 +163,13 @@ export function SetType(type) {
     if (typeof type !== "string" && !isImmutableType(type)) {
         throw new Error(`Set key type must be an immutable type, got ${printType(type)}`);
     }
-    return { type: "Set", key: type };
+    const h = hashCombine(0x53, type?.[type_id_symbol] ?? 0);
+    const cached = internLookup(h, (c) => c.type === "Set" && c.key === type);
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Set", key: type });
+    internStore(h, result);
+    return result;
 }
 ;
 /**
@@ -92,7 +186,14 @@ export function DictType(key, value) {
     if (typeof key !== "string" && !isImmutableType(key)) {
         throw new Error(`Dict key type must be an immutable type, got ${printType(key)}`);
     }
-    return { type: "Dict", key, value };
+    let h = hashCombine(0x44, key?.[type_id_symbol] ?? 0);
+    h = hashCombine(h, value?.[type_id_symbol] ?? 0);
+    const cached = internLookup(h, (c) => c.type === "Dict" && c.key === key && c.value === value);
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Dict", key, value });
+    internStore(h, result);
+    return result;
 }
 ;
 /**
@@ -103,7 +204,35 @@ export function DictType(key, value) {
  * @returns A Struct type
  */
 export function StructType(field_types) {
-    return { type: "Struct", fields: field_types };
+    // Intern: structurally identical struct types (same field order, same names,
+    // same child type_ids) share a single canonical object. This mirrors the
+    // existing interning for Array/Dict/Function etc. and is required for the
+    // beast2 v2 encoder to produce a canonical type table — otherwise calling
+    // StructType({ x: Int, y: Int }) twice would yield two distinct entries.
+    const keys = Object.keys(field_types);
+    let h = hashCombine(0x09, keys.length);
+    for (const k of keys) {
+        h = hashCombine(h, field_types[k]?.[type_id_symbol] ?? 0);
+    }
+    const cached = internLookup(h, (c) => {
+        if (c.type !== "Struct")
+            return false;
+        const ck = Object.keys(c.fields);
+        if (ck.length !== keys.length)
+            return false;
+        for (let i = 0; i < keys.length; i++) {
+            if (ck[i] !== keys[i])
+                return false;
+            if (c.fields[keys[i]] !== field_types[keys[i]])
+                return false;
+        }
+        return true;
+    });
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Struct", fields: field_types });
+    internStore(h, result);
+    return result;
 }
 ;
 /**
@@ -116,7 +245,33 @@ export function StructType(field_types) {
 export function VariantType(case_types) {
     // Cases are sorted alphabetically by their name
     const cases_sorted = Object.fromEntries(Object.entries(case_types).sort((x, y) => x[0] < y[0] ? -1 : x[0] === y[0] ? 0 : 1));
-    return { type: "Variant", cases: cases_sorted };
+    // Intern: match Struct. Hash is computed over the sorted keys so two calls
+    // with cases in different orders produce the same hash, and verify confirms
+    // identical names and child type_ids.
+    const keys = Object.keys(cases_sorted);
+    let h = hashCombine(0x08, keys.length);
+    for (const k of keys) {
+        h = hashCombine(h, cases_sorted[k]?.[type_id_symbol] ?? 0);
+    }
+    const cached = internLookup(h, (c) => {
+        if (c.type !== "Variant")
+            return false;
+        const ck = Object.keys(c.cases);
+        if (ck.length !== keys.length)
+            return false;
+        for (let i = 0; i < keys.length; i++) {
+            if (ck[i] !== keys[i])
+                return false;
+            if (c.cases[keys[i]] !== cases_sorted[keys[i]])
+                return false;
+        }
+        return true;
+    });
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Variant", cases: cases_sorted });
+    internStore(h, result);
+    return result;
 }
 ;
 /**
@@ -197,6 +352,9 @@ function validateNotMutuallyRecursive(type, allowedMarker) {
             t.inputs.forEach(input => check(input, allowed));
             check(t.output, allowed);
         }
+        else if (t.type === "Vector" || t.type === "Matrix") {
+            check(t.element, allowed);
+        }
         // Primitive types don't need recursion
     }
     check(type, true);
@@ -237,14 +395,24 @@ function validateNotMutuallyRecursive(type, allowedMarker) {
  * ```
  */
 export function RecursiveType(f) {
-    const ret = { type: "Recursive", node: undefined };
+    const ret = assignTypeId({ type: "Recursive", node: undefined });
     const type = f(ret);
     ret.node = type;
     // Validate SCC size 1 (no nested RecursiveTypes with cross-references)
     validateNotMutuallyRecursive(type, ret);
+    // Intern: if a structurally identical RecursiveType already exists, reuse it.
+    // This ensures two independently-created RecursiveTypes with the same structure
+    // share a single type_id, making id-based Recursive refs work correctly.
+    for (const existing of _recursiveIntern) {
+        if (isTypeEqual(existing, ret)) {
+            return existing;
+        }
+    }
+    _recursiveIntern.push(ret);
     return ret;
 }
 ;
+const _recursiveIntern = [];
 /**
  * Constructs a Function type with the specified input and output types.
  *
@@ -255,7 +423,17 @@ export function RecursiveType(f) {
  * @see {@link AsyncFunctionType} for asynchronous functions.
  */
 export function FunctionType(inputs, output) {
-    return { type: "Function", inputs, output };
+    let h = hashCombine(0x46, inputs.length);
+    for (const inp of inputs)
+        h = hashCombine(h, inp?.[type_id_symbol] ?? 0);
+    h = hashCombine(h, output?.[type_id_symbol] ?? 0);
+    const cached = internLookup(h, (c) => c.type === "Function" && c.inputs.length === inputs.length && c.output === output &&
+        c.inputs.every((inp, i) => inp === inputs[i]));
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Function", inputs, output });
+    internStore(h, result);
+    return result;
 }
 ;
 /**
@@ -268,7 +446,43 @@ export function FunctionType(inputs, output) {
  * @see {@link AsyncFunctionType} for asynchronous functions.
  */
 export function AsyncFunctionType(inputs, output) {
-    return { type: "AsyncFunction", inputs, output };
+    let h = hashCombine(0x61, inputs.length);
+    for (const inp of inputs)
+        h = hashCombine(h, inp?.[type_id_symbol] ?? 0);
+    h = hashCombine(h, output?.[type_id_symbol] ?? 0);
+    const cached = internLookup(h, (c) => c.type === "AsyncFunction" && c.inputs.length === inputs.length && c.output === output &&
+        c.inputs.every((inp, i) => inp === inputs[i]));
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "AsyncFunction", inputs, output });
+    internStore(h, result);
+    return result;
+}
+;
+export function VectorType(element) {
+    if (typeof element !== "string" && element.type !== "Float" && element.type !== "Integer" && element.type !== "Boolean") {
+        throw new Error(`Vector element type must be Float, Integer, or Boolean, got ${printType(element)}`);
+    }
+    const h = hashCombine(0x56, element?.[type_id_symbol] ?? 0);
+    const cached = internLookup(h, (c) => c.type === "Vector" && c.element === element);
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Vector", element });
+    internStore(h, result);
+    return result;
+}
+;
+export function MatrixType(element) {
+    if (typeof element !== "string" && element.type !== "Float" && element.type !== "Integer" && element.type !== "Boolean") {
+        throw new Error(`Matrix element type must be Float, Integer, or Boolean, got ${printType(element)}`);
+    }
+    const h = hashCombine(0x4d, element?.[type_id_symbol] ?? 0);
+    const cached = internLookup(h, (c) => c.type === "Matrix" && c.element === element);
+    if (cached)
+        return cached;
+    const result = assignTypeId({ type: "Matrix", element });
+    internStore(h, result);
+    return result;
 }
 ;
 /**
@@ -319,6 +533,9 @@ export function isDataType(type, recursive_type) {
     else if (type.type === "Recursive") {
         return type.node === recursive_type ? true : isDataType(type.node, type);
     }
+    else if (type.type === "Vector" || type.type === "Matrix") {
+        return true;
+    }
     else if (type.type === "Function") {
         return false;
     }
@@ -361,6 +578,9 @@ export function isImmutableType(type, recursive_type) {
         // Dict are mutable
         return false;
     }
+    else if (type.type === "Vector" || type.type === "Matrix") {
+        return false;
+    }
     else if (type.type === "Struct") {
         for (const field_type of Object.values(type.fields)) {
             if (!isImmutableType(field_type, recursive_type)) {
@@ -424,6 +644,9 @@ export function EastTypeOf(value) {
     if (value instanceof Date) {
         return DateTimeType;
     }
+    else if (value instanceof Uint8ClampedArray) {
+        return VectorType(BooleanType);
+    }
     else if (value instanceof Uint8Array) {
         return BlobType;
     }
@@ -472,28 +695,32 @@ export function EastTypeOf(value) {
  * For {@link RecursiveType}, uses cycle tracking to handle recursive references.
  */
 // Cache for memoizing isTypeEqual results (top-level calls only)
-const typeEqualCache = new WeakMap();
+const typeEqualCache = new Map();
 export function isTypeEqual(t1, t2, r1 = t1, r2 = t2) {
     // Fast path: reference equality
     if (t1 === t2)
         return true;
+    // Fast path: type_id equality (interned types with same id are structurally equal)
+    const tid1 = getTypeId(t1);
+    const tid2 = getTypeId(t2);
+    if (tid1 !== undefined && tid1 === tid2)
+        return true;
     // Memoization for top-level calls only (r1/r2 are just for internal cycle detection)
     const isTopLevel = r1 === t1 && r2 === t2;
-    if (isTopLevel) {
-        const innerCache = typeEqualCache.get(t1);
+    if (isTopLevel && tid1 !== undefined && tid2 !== undefined) {
+        const innerCache = typeEqualCache.get(tid1);
         if (innerCache) {
-            const cached = innerCache.get(t2);
+            const cached = innerCache.get(tid2);
             if (cached !== undefined)
                 return cached;
         }
         const result = isTypeEqualImpl(t1, t2, r1, r2);
-        // Store result in cache
-        let cache = typeEqualCache.get(t1);
+        let cache = typeEqualCache.get(tid1);
         if (!cache) {
-            cache = new WeakMap();
-            typeEqualCache.set(t1, cache);
+            cache = new Map();
+            typeEqualCache.set(tid1, cache);
         }
-        cache.set(t2, result);
+        cache.set(tid2, result);
         return result;
     }
     return isTypeEqualImpl(t1, t2, r1, r2);
@@ -576,6 +803,22 @@ function isTypeEqualImpl(t1, t2, r1, r2) {
             return false;
         }
     }
+    else if (t1.type === "Vector") {
+        if (t2.type === "Vector") {
+            return isTypeEqual(t1.element, t2.element, r1, r2);
+        }
+        else {
+            return false;
+        }
+    }
+    else if (t1.type === "Matrix") {
+        if (t2.type === "Matrix") {
+            return isTypeEqual(t1.element, t2.element, r1, r2);
+        }
+        else {
+            return false;
+        }
+    }
     else if (t1.type === "Struct") {
         if (t2.type === "Struct") {
             const e1 = Object.entries(t1.fields);
@@ -766,6 +1009,26 @@ export function isValueOf(value, type, node_type, nodes_visited) {
         ;
         return isValueOf(value.value, t, node_type, nodes_visited);
     }
+    else if (type.type === "Vector") {
+        if (type.element.type === "Float")
+            return value instanceof Float64Array;
+        if (type.element.type === "Integer")
+            return value instanceof BigInt64Array;
+        if (type.element.type === "Boolean")
+            return value instanceof Uint8ClampedArray;
+        return false;
+    }
+    else if (type.type === "Matrix") {
+        if (!isMatrix(value))
+            return false;
+        if (type.element.type === "Float")
+            return value.data instanceof Float64Array;
+        if (type.element.type === "Integer")
+            return value.data instanceof BigInt64Array;
+        if (type.element.type === "Boolean")
+            return value.data instanceof Uint8ClampedArray;
+        return false;
+    }
     else if (type.type === "Recursive") {
         if (node_type === type.node) {
             if (nodes_visited.has(value)) {
@@ -866,14 +1129,21 @@ export function printType(type, stack = []) {
         stack.pop();
         return ret;
     }
+    else if (type.type === "Vector") {
+        return `.Vector ${printType(type.element, stack)}`;
+    }
+    else if (type.type === "Matrix") {
+        return `.Matrix ${printType(type.element, stack)}`;
+    }
     else if (type.type === "Recursive") {
-        // TODO update for our new recursive type representation
-        const idx = stack.indexOf(type.node);
+        const idx = stack.indexOf(type);
         if (idx !== -1) {
-            // Recursive reference
-            return `.Recursive ${stack.length - idx}`;
+            return `.Recursive .ref ${getTypeId(type)}`;
         }
-        return printType(type.node, stack);
+        stack.push(type);
+        const inner = printType(type.node, stack);
+        stack.pop();
+        return `.Recursive .wrapper (id=${getTypeId(type)}, inner=${inner})`;
     }
     else if (type.type === "Function") {
         // Note: functions can't be inside recursive types
@@ -893,6 +1163,140 @@ export function printType(type, stack = []) {
         throw new Error(`Unknown type encountered during type printing: ${type.type}`);
     }
 }
+/**
+ * Converts an East type to a truncated string representation for error messages.
+ *
+ * @param type - The {@link EastType} to print
+ * @param maxDepth - Maximum depth to recurse into compound types (default 1)
+ * @param maxFields - Maximum number of fields/cases to show before truncating (default 3)
+ * @param stack - Internal parameter for tracking recursive types
+ * @returns A human-readable, truncated string representation of the type
+ *
+ * @remarks
+ * Like {@link printType} but truncates large types for readable error messages.
+ * At depth 0, compound types show summary form (e.g., `.Struct [N fields]`).
+ * Shows first `maxFields` entries then `... and N more`.
+ */
+export function printTypeSummary(type, maxDepth = 1, maxFields = 3, stack = []) {
+    if (type.type === "Never") {
+        return ".Never";
+    }
+    else if (type.type === "Null") {
+        return ".Null";
+    }
+    else if (type.type === "Boolean") {
+        return ".Boolean";
+    }
+    else if (type.type === "Integer") {
+        return ".Integer";
+    }
+    else if (type.type === "Float") {
+        return ".Float";
+    }
+    else if (type.type === "String") {
+        return ".String";
+    }
+    else if (type.type === "DateTime") {
+        return ".DateTime";
+    }
+    else if (type.type === "Blob") {
+        return ".Blob";
+    }
+    else if (type.type === "Ref") {
+        if (maxDepth <= 0)
+            return ".Ref ...";
+        stack.push(type);
+        const ret = `.Ref ${printTypeSummary(type.value, maxDepth - 1, maxFields, stack)}`;
+        stack.pop();
+        return ret;
+    }
+    else if (type.type === "Array") {
+        if (maxDepth <= 0)
+            return ".Array ...";
+        stack.push(type);
+        const ret = `.Array ${printTypeSummary(type.value, maxDepth - 1, maxFields, stack)}`;
+        stack.pop();
+        return ret;
+    }
+    else if (type.type === "Set") {
+        if (maxDepth <= 0)
+            return ".Set ...";
+        stack.push(type);
+        const ret = `.Set ${printTypeSummary(type.key, maxDepth - 1, maxFields, stack)}`;
+        stack.pop();
+        return ret;
+    }
+    else if (type.type === "Dict") {
+        if (maxDepth <= 0)
+            return ".Dict ...";
+        stack.push(type);
+        const ret = `.Dict (key=${printTypeSummary(type.key, maxDepth - 1, maxFields, stack)}, value=${printTypeSummary(type.value, maxDepth - 1, maxFields, stack)})`;
+        stack.pop();
+        return ret;
+    }
+    else if (type.type === "Struct") {
+        const entries = Object.entries(type.fields);
+        if (maxDepth <= 0)
+            return `.Struct [${entries.length} fields]`;
+        stack.push(type);
+        const shown = entries.slice(0, maxFields).map(([k, t]) => `(name=${JSON.stringify(k)}, type=${printTypeSummary(t, maxDepth - 1, maxFields, stack)})`);
+        stack.pop();
+        const remaining = entries.length - maxFields;
+        if (remaining > 0) {
+            return `.Struct [${shown.join(", ")}, ... and ${remaining} more]`;
+        }
+        return `.Struct [${shown.join(", ")}]`;
+    }
+    else if (type.type === "Variant") {
+        const entries = Object.entries(type.cases);
+        if (maxDepth <= 0) {
+            return `.Variant (${entries.map(([k]) => k).join(" | ")})`;
+        }
+        stack.push(type);
+        const shown = entries.slice(0, maxFields).map(([k, t]) => `(name=${JSON.stringify(k)}, type=${printTypeSummary(t, maxDepth - 1, maxFields, stack)})`);
+        stack.pop();
+        const remaining = entries.length - maxFields;
+        if (remaining > 0) {
+            return `.Variant [${shown.join(", ")}, ... and ${remaining} more]`;
+        }
+        return `.Variant [${shown.join(", ")}]`;
+    }
+    else if (type.type === "Vector") {
+        return `.Vector ${printTypeSummary(type.element, maxDepth, maxFields, stack)}`;
+    }
+    else if (type.type === "Matrix") {
+        return `.Matrix ${printTypeSummary(type.element, maxDepth, maxFields, stack)}`;
+    }
+    else if (type.type === "Recursive") {
+        const idx = stack.indexOf(type);
+        if (idx !== -1) {
+            return `.Recursive .ref ${getTypeId(type)}`;
+        }
+        stack.push(type);
+        const inner = printTypeSummary(type.node, maxDepth, maxFields, stack);
+        stack.pop();
+        return `.Recursive .wrapper (id=${getTypeId(type)}, inner=${inner})`;
+    }
+    else if (type.type === "Function") {
+        if (maxDepth <= 0)
+            return `.Function ...`;
+        stack.push(type);
+        const ret = `.Function (inputs=[${type.inputs.map(t => printTypeSummary(t, maxDepth - 1, maxFields, stack)).join(", ")}], output=${printTypeSummary(type.output, maxDepth - 1, maxFields, stack)})`;
+        stack.pop();
+        return ret;
+    }
+    else if (type.type === "AsyncFunction") {
+        if (maxDepth <= 0)
+            return `.AsyncFunction ...`;
+        stack.push(type);
+        const ret = `.AsyncFunction (inputs=[${type.inputs.map(t => printTypeSummary(t, maxDepth - 1, maxFields, stack)).join(", ")}], output=${printTypeSummary(type.output, maxDepth - 1, maxFields, stack)})`;
+        stack.pop();
+        return ret;
+    }
+    else {
+        throw new Error(`Unknown type encountered during type printing: ${type.type}`);
+    }
+}
 /**
  * Checks if one East type is a subtype of another.
  *
@@ -908,27 +1312,34 @@ export function printType(type, stack = []) {
  * - {@link FunctionType} uses contravariant inputs and covariant outputs
  */
 // Cache for memoizing isSubtype results
-const isSubtypeCache = new WeakMap();
+const isSubtypeCache = new Map();
 export function isSubtype(t1, t2) {
     // Fast path: reference equality (reflexivity)
     if (t1 === t2)
         return true;
+    // Fast path: type_id equality
+    const tid1 = getTypeId(t1);
+    const tid2 = getTypeId(t2);
+    if (tid1 !== undefined && tid1 === tid2)
+        return true;
     // Check cache
-    const innerCache = isSubtypeCache.get(t1);
-    if (innerCache) {
-        const cached = innerCache.get(t2);
-        if (cached !== undefined)
-            return cached;
-    }
-    const result = isSubtypeImpl(t1, t2);
-    // Store in cache
-    let cache = isSubtypeCache.get(t1);
-    if (!cache) {
-        cache = new WeakMap();
-        isSubtypeCache.set(t1, cache);
-    }
-    cache.set(t2, result);
-    return result;
+    if (tid1 !== undefined && tid2 !== undefined) {
+        const innerCache = isSubtypeCache.get(tid1);
+        if (innerCache) {
+            const cached = innerCache.get(tid2);
+            if (cached !== undefined)
+                return cached;
+        }
+        const result = isSubtypeImpl(t1, t2);
+        let cache = isSubtypeCache.get(tid1);
+        if (!cache) {
+            cache = new Map();
+            isSubtypeCache.set(tid1, cache);
+        }
+        cache.set(tid2, result);
+        return result;
+    }
+    return isSubtypeImpl(t1, t2);
 }
 function isSubtypeImpl(t1, t2) {
     // Equi-recursive type subtyping: unfold recursive types when only one side is recursive
@@ -988,6 +1399,22 @@ function isSubtypeImpl(t1, t2) {
             return false;
         }
     }
+    else if (t1.type === "Vector") {
+        if (t2.type === "Vector") {
+            return isTypeEqual(t1.element, t2.element);
+        }
+        else {
+            return false;
+        }
+    }
+    else if (t1.type === "Matrix") {
+        if (t2.type === "Matrix") {
+            return isTypeEqual(t1.element, t2.element);
+        }
+        else {
+            return false;
+        }
+    }
     else if (t1.type === "Set") {
         if (t2.type === "Set") {
             return isTypeEqual(t1.key, t2.key);
@@ -1074,6 +1501,8 @@ function isSubtypeImpl(t1, t2) {
  * Error messages include the full type path for debugging.
  */
 export function TypeUnion(t1, t2) {
+    if (t1 === t2)
+        return t1;
     // TODO this is broken for recursive types (need to do cycle tracking in tandem with TypeEqual/TypeIntersect)
     try {
         if (t1.type === "Never") {
@@ -1093,7 +1522,7 @@ export function TypeUnion(t1, t2) {
                 if (isSubtype(t2, t1.node)) {
                     return t1;
                 }
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t2.type === "Recursive") {
@@ -1101,38 +1530,54 @@ export function TypeUnion(t1, t2) {
             if (isSubtype(t1, t2.node)) {
                 return t2;
             }
-            throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+            throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
         }
         else if (t1.type === "Ref") {
             if (t2.type === "Ref") {
-                return RefType(TypeEqual(t1.value, t2.value));
+                return RefType(withPathSegment("[ref]", () => TypeEqual(t1.value, t2.value)));
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Array") {
             if (t2.type === "Array") {
-                return ArrayType(TypeEqual(t1.value, t2.value));
+                return ArrayType(withPathSegment("[element]", () => TypeEqual(t1.value, t2.value)));
+            }
+            else {
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
+            }
+        }
+        else if (t1.type === "Vector") {
+            if (t2.type === "Vector") {
+                return VectorType(withPathSegment("[element]", () => TypeEqual(t1.element, t2.element)));
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
+            }
+        }
+        else if (t1.type === "Matrix") {
+            if (t2.type === "Matrix") {
+                return MatrixType(withPathSegment("[element]", () => TypeEqual(t1.element, t2.element)));
+            }
+            else {
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Set") {
             if (t2.type === "Set") {
-                return SetType(TypeEqual(t1.key, t2.key));
+                return SetType(withPathSegment("[key]", () => TypeEqual(t1.key, t2.key)));
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Dict") {
             if (t2.type === "Dict") {
-                return DictType(TypeEqual(t1.key, t2.key), TypeEqual(t1.value, t2.value));
+                return DictType(withPathSegment("[key]", () => TypeEqual(t1.key, t2.key)), withPathSegment("[value]", () => TypeEqual(t1.value, t2.value)));
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Struct") {
@@ -1140,20 +1585,20 @@ export function TypeUnion(t1, t2) {
                 const e1 = Object.entries(t1.fields);
                 const e2 = Object.entries(t2.fields);
                 if (e1.length !== e2.length)
-                    throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: structs contain different number of fields`);
+                    throw new TypeMismatchError(`structs contain different number of fields (${e1.length} vs ${e2.length})`);
                 let i = 0;
                 const e = {};
                 for (const [k1, f1] of e1) {
                     const [k2, f2] = e2[i];
                     if (k1 !== k2)
-                        throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: struct field ${i} has mismatched names ${printIdentifier(k1)} and ${printIdentifier(k2)}`);
-                    e[k1] = TypeUnion(f1, f2);
+                        throw new TypeMismatchError(`struct field ${i} has mismatched names ${printIdentifier(k1)} and ${printIdentifier(k2)}`);
+                    e[k1] = withPathSegment(`.${k1}`, () => TypeUnion(f1, f2));
                     i += 1;
                 }
                 return StructType(e);
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Variant") {
@@ -1165,7 +1610,7 @@ export function TypeUnion(t1, t2) {
                         cases[k1] = f1;
                     }
                     else {
-                        cases[k1] = TypeUnion(f1, f2);
+                        cases[k1] = withPathSegment(`.${k1}`, () => TypeUnion(f1, f2));
                     }
                 }
                 for (const [k2, f2] of Object.entries(t2.cases)) {
@@ -1177,41 +1622,41 @@ export function TypeUnion(t1, t2) {
                 return VariantType(cases);
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Function") {
             if (t2.type === "Function") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return FunctionType(t1.inputs.map((t, i) => TypeIntersect(t, t2.inputs[i])), TypeUnion(t1.output, t2.output));
+                return FunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeIntersect(t, t2.inputs[i]))), withPathSegment("[output]", () => TypeUnion(t1.output, t2.output)));
             }
             else if (t2.type === "AsyncFunction") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return AsyncFunctionType(t1.inputs.map((t, i) => TypeIntersect(t, t2.inputs[i])), TypeUnion(t1.output, t2.output));
+                return AsyncFunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeIntersect(t, t2.inputs[i]))), withPathSegment("[output]", () => TypeUnion(t1.output, t2.output)));
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "AsyncFunction") {
             if (t2.type === "Function") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return AsyncFunctionType(t1.inputs.map((t, i) => TypeIntersect(t, t2.inputs[i])), TypeUnion(t1.output, t2.output));
+                return AsyncFunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeIntersect(t, t2.inputs[i]))), withPathSegment("[output]", () => TypeUnion(t1.output, t2.output)));
             }
             else if (t2.type === "AsyncFunction") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return AsyncFunctionType(t1.inputs.map((t, i) => TypeIntersect(t, t2.inputs[i])), TypeUnion(t1.output, t2.output));
+                return AsyncFunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeIntersect(t, t2.inputs[i]))), withPathSegment("[output]", () => TypeUnion(t1.output, t2.output)));
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else {
@@ -1219,7 +1664,7 @@ export function TypeUnion(t1, t2) {
                 return t1;
             }
             else {
-                throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
     }
@@ -1227,7 +1672,7 @@ export function TypeUnion(t1, t2) {
         if (cause instanceof TypeMismatchError) {
             throw cause; // Don't wrap our own errors - they already have the full path
         }
-        throw new TypeMismatchError(`Cannot union ${printType(t1)} with ${printType(t2)}`, { cause });
+        throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}`, { cause });
     }
 }
 /**
@@ -1245,6 +1690,8 @@ export function TypeUnion(t1, t2) {
  * For {@link VariantType}, returns {@link NeverType} if no common cases exist.
  */
 export function TypeIntersect(t1, t2) {
+    if (t1 === t2)
+        return t1;
     // TODO this is broken for recursive types (need to do cycle tracking in tandem with TypeEqual/TypeUnion)
     try {
         if (t1.type === "Never") {
@@ -1263,7 +1710,7 @@ export function TypeIntersect(t1, t2) {
                 if (isSubtype(t2, t1.node)) {
                     return t2;
                 }
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t2.type === "Recursive") {
@@ -1271,38 +1718,54 @@ export function TypeIntersect(t1, t2) {
             if (isSubtype(t1, t2.node)) {
                 return t1;
             }
-            throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+            throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
         }
         else if (t1.type === "Ref") {
             if (t2.type === "Ref") {
-                return RefType(TypeEqual(t1.value, t2.value));
+                return RefType(withPathSegment("[ref]", () => TypeEqual(t1.value, t2.value)));
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Array") {
             if (t2.type === "Array") {
-                return ArrayType(TypeEqual(t1.value, t2.value));
+                return ArrayType(withPathSegment("[element]", () => TypeEqual(t1.value, t2.value)));
+            }
+            else {
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
+            }
+        }
+        else if (t1.type === "Vector") {
+            if (t2.type === "Vector") {
+                return VectorType(withPathSegment("[element]", () => TypeEqual(t1.element, t2.element)));
+            }
+            else {
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
+            }
+        }
+        else if (t1.type === "Matrix") {
+            if (t2.type === "Matrix") {
+                return MatrixType(withPathSegment("[element]", () => TypeEqual(t1.element, t2.element)));
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Set") {
             if (t2.type === "Set") {
-                return SetType(TypeEqual(t1.key, t2.key));
+                return SetType(withPathSegment("[key]", () => TypeEqual(t1.key, t2.key)));
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Dict") {
             if (t2.type === "Dict") {
-                return DictType(TypeEqual(t1.key, t2.key), TypeEqual(t1.value, t2.value));
+                return DictType(withPathSegment("[key]", () => TypeEqual(t1.key, t2.key)), withPathSegment("[value]", () => TypeEqual(t1.value, t2.value)));
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Struct") {
@@ -1310,20 +1773,20 @@ export function TypeIntersect(t1, t2) {
                 const e1 = Object.entries(t1.fields);
                 const e2 = Object.entries(t2.fields);
                 if (e1.length !== e2.length)
-                    throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: structs contain different number of fields`);
+                    throw new TypeMismatchError(`structs contain different number of fields (${e1.length} vs ${e2.length})`);
                 let i = 0;
                 const e = {};
                 for (const [k1, f1] of e1) {
                     const [k2, f2] = e2[i];
                     if (k1 !== k2)
-                        throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: struct field ${i} has mismatched names ${printIdentifier(k1)} and ${printIdentifier(k2)}`);
-                    e[k1] = TypeIntersect(f1, f2);
+                        throw new TypeMismatchError(`struct field ${i} has mismatched names ${printIdentifier(k1)} and ${printIdentifier(k2)}`);
+                    e[k1] = withPathSegment(`.${k1}`, () => TypeIntersect(f1, f2));
                     i += 1;
                 }
                 return StructType(e);
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Variant") {
@@ -1333,51 +1796,51 @@ export function TypeIntersect(t1, t2) {
                 for (const [k1, f1] of Object.entries(t1.cases)) {
                     const f2 = t2.cases[k1];
                     if (f2 !== undefined) {
-                        cases[k1] = TypeIntersect(f1, f2);
+                        cases[k1] = withPathSegment(`.${k1}`, () => TypeIntersect(f1, f2));
                         empty = false;
                     }
                 }
                 if (empty) {
-                    throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: variants have no overlapping cases`);
+                    throw new TypeMismatchError(`variants have no overlapping cases`);
                 }
                 return VariantType(cases);
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Function") {
             if (t2.type === "Function") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return FunctionType(t1.inputs.map((t, i) => TypeUnion(t, t2.inputs[i])), TypeIntersect(t1.output, t2.output));
+                return FunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeUnion(t, t2.inputs[i]))), withPathSegment("[output]", () => TypeIntersect(t1.output, t2.output)));
             }
             else if (t2.type === "AsyncFunction") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return FunctionType(t1.inputs.map((t, i) => TypeUnion(t, t2.inputs[i])), TypeIntersect(t1.output, t2.output));
+                return FunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeUnion(t, t2.inputs[i]))), withPathSegment("[output]", () => TypeIntersect(t1.output, t2.output)));
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "AsyncFunction") {
             if (t2.type === "Function") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return FunctionType(t1.inputs.map((t, i) => TypeUnion(t, t2.inputs[i])), TypeIntersect(t1.output, t2.output));
+                return FunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeUnion(t, t2.inputs[i]))), withPathSegment("[output]", () => TypeIntersect(t1.output, t2.output)));
             }
             else if (t2.type === "AsyncFunction") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return AsyncFunctionType(t1.inputs.map((t, i) => TypeUnion(t, t2.inputs[i])), TypeIntersect(t1.output, t2.output));
+                return AsyncFunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeUnion(t, t2.inputs[i]))), withPathSegment("[output]", () => TypeIntersect(t1.output, t2.output)));
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else {
@@ -1385,7 +1848,7 @@ export function TypeIntersect(t1, t2) {
                 return t1;
             }
             else {
-                throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
     }
@@ -1393,7 +1856,7 @@ export function TypeIntersect(t1, t2) {
         if (cause instanceof TypeMismatchError) {
             throw cause; // Don't wrap our own errors - they already have the full path
         }
-        throw new TypeMismatchError(`Cannot intersect ${printType(t1)} with ${printType(t2)}`, { cause });
+        throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}`, { cause });
     }
 }
 /**
@@ -1414,38 +1877,56 @@ export function TypeIntersect(t1, t2) {
  * Unlike {@link isTypeEqual}, this throws rather than returning a boolean.
  */
 export function TypeEqual(t1, t2, r1 = t1, r2 = t2) {
+    if (t1 === t2)
+        return t1;
     // TODO this is broken for recursive types (need to do cycle tracking in tandem with TypeUnion/TypeIntersect)
     try {
         if (t1.type === "Ref") {
             if (t2.type === "Ref") {
-                return RefType(TypeEqual(t1.value, t2.value, r1, r2));
+                return RefType(withPathSegment("[ref]", () => TypeEqual(t1.value, t2.value, r1, r2)));
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Array") {
             if (t2.type === "Array") {
-                return ArrayType(TypeEqual(t1.value, t2.value, r1, r2));
+                return ArrayType(withPathSegment("[element]", () => TypeEqual(t1.value, t2.value, r1, r2)));
+            }
+            else {
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
+            }
+        }
+        else if (t1.type === "Vector") {
+            if (t2.type === "Vector") {
+                return VectorType(withPathSegment("[element]", () => TypeEqual(t1.element, t2.element, r1, r2)));
+            }
+            else {
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
+            }
+        }
+        else if (t1.type === "Matrix") {
+            if (t2.type === "Matrix") {
+                return MatrixType(withPathSegment("[element]", () => TypeEqual(t1.element, t2.element, r1, r2)));
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Set") {
             if (t2.type === "Set") {
-                return SetType(TypeEqual(t1.key, t2.key, r1, r2));
+                return SetType(withPathSegment("[key]", () => TypeEqual(t1.key, t2.key, r1, r2)));
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Dict") {
             if (t2.type === "Dict") {
-                return DictType(TypeEqual(t1.key, t2.key, r1, r2), TypeEqual(t1.value, t2.value, r1, r2));
+                return DictType(withPathSegment("[key]", () => TypeEqual(t1.key, t2.key, r1, r2)), withPathSegment("[value]", () => TypeEqual(t1.value, t2.value, r1, r2)));
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Struct") {
@@ -1453,20 +1934,20 @@ export function TypeEqual(t1, t2, r1 = t1, r2 = t2) {
                 const e1 = Object.entries(t1.fields);
                 const e2 = Object.entries(t2.fields);
                 if (e1.length !== e2.length)
-                    throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: structs contain different number of fields`);
+                    throw new TypeMismatchError(`structs contain different number of fields (${e1.length} vs ${e2.length})`);
                 let i = 0;
                 const e = {};
                 for (const [k1, f1] of e1) {
                     const [k2, f2] = e2[i];
                     if (k1 !== k2)
-                        throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: struct field ${i} has mismatched names ${printIdentifier(k1)} and ${printIdentifier(k2)}`);
-                    e[k1] = TypeEqual(f1, f2, r1, r2);
+                        throw new TypeMismatchError(`struct field ${i} has mismatched names ${printIdentifier(k1)} and ${printIdentifier(k2)}`);
+                    e[k1] = withPathSegment(`.${k1}`, () => TypeEqual(f1, f2, r1, r2));
                     i += 1;
                 }
                 return StructType(e);
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Variant") {
@@ -1474,27 +1955,37 @@ export function TypeEqual(t1, t2, r1 = t1, r2 = t2) {
             if (t2.type === "Variant") {
                 const e1 = Object.entries(t1.cases);
                 const e2 = Object.entries(t2.cases);
-                if (e1.length !== e2.length)
-                    throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: variants contain different number of cases`);
+                if (e1.length !== e2.length) {
+                    let msg = `variants contain different number of cases (${e1.length} vs ${e2.length})`;
+                    const names1 = new Set(e1.map(([k]) => k));
+                    const names2 = new Set(e2.map(([k]) => k));
+                    const onlyIn1 = e1.map(([k]) => k).filter(k => !names2.has(k));
+                    const onlyIn2 = e2.map(([k]) => k).filter(k => !names1.has(k));
+                    if (onlyIn1.length > 0)
+                        msg += `; only in expected: ${onlyIn1.join(", ")}`;
+                    if (onlyIn2.length > 0)
+                        msg += `; only in actual: ${onlyIn2.join(", ")}`;
+                    throw new TypeMismatchError(msg);
+                }
                 let i = 0;
                 const e = {};
                 for (const [k1, f1] of e1) {
                     const [k2, f2] = e2[i];
                     if (k1 !== k2) {
                         if (k1 < k2) {
-                            throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: variant case ${k1} is not present in both variants`);
+                            throw new TypeMismatchError(`variant case ${k1} is not present in both variants`);
                         }
                         else {
-                            throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: variant case ${k2} is not present in both variants`);
+                            throw new TypeMismatchError(`variant case ${k2} is not present in both variants`);
                         }
                     }
-                    e[k1] = TypeEqual(f1, f2, r1, r2);
+                    e[k1] = withPathSegment(`.${k1}`, () => TypeEqual(f1, f2, r1, r2));
                     i += 1;
                 }
                 return VariantType(e);
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Recursive") {
@@ -1504,39 +1995,39 @@ export function TypeEqual(t1, t2, r1 = t1, r2 = t2) {
                         return t1; // both are references to the same recursive type
                     }
                     else {
-                        throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: recursive types do not match`);
+                        throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: recursive types do not match`);
                     }
                 }
                 else if (t2.node === r2) {
-                    throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: recursive types do not match`);
+                    throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: recursive types do not match`);
                 }
                 // this is the root of a new recursive type - assert the node types are equal
                 return RecursiveType(() => TypeEqual(t1.node, t2.node, t1.node, t2.node));
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Function") {
             if (t2.type === "Function") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return FunctionType(t1.inputs.map((t, i) => TypeEqual(t, t2.inputs[i], r1, r2)), TypeEqual(t1.output, t2.output, r1, r2));
+                return FunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeEqual(t, t2.inputs[i], r1, r2))), withPathSegment("[output]", () => TypeEqual(t1.output, t2.output, r1, r2)));
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "AsyncFunction") {
             if (t2.type === "AsyncFunction") {
                 if (t1.inputs.length !== t2.inputs.length) {
-                    throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: functions take different number of arguments`);
+                    throw new TypeMismatchError(`functions take different number of arguments (${t1.inputs.length} vs ${t2.inputs.length})`);
                 }
-                return AsyncFunctionType(t1.inputs.map((t, i) => TypeEqual(t, t2.inputs[i], r1, r2)), TypeEqual(t1.output, t2.output, r1, r2));
+                return AsyncFunctionType(t1.inputs.map((t, i) => withPathSegment(`[input ${i}]`, () => TypeEqual(t, t2.inputs[i], r1, r2))), withPathSegment("[output]", () => TypeEqual(t1.output, t2.output, r1, r2)));
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else {
@@ -1544,7 +2035,7 @@ export function TypeEqual(t1, t2, r1 = t1, r2 = t2) {
                 return t1;
             }
             else {
-                throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
     }
@@ -1552,7 +2043,7 @@ export function TypeEqual(t1, t2, r1 = t1, r2 = t2) {
         if (cause instanceof TypeMismatchError) {
             throw cause; // Don't wrap our own errors - they already have the full path
         }
-        throw new TypeMismatchError(`${printType(t1)} is not equal to ${printType(t2)}`, { cause });
+        throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}`, { cause });
     }
 }
 /**
@@ -1577,41 +2068,57 @@ export function TypeWiden(t1, t2) {
             return t1;
         }
         else if (t1.type === "Recursive") {
-            throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: recursive types not supported`);
+            throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: recursive types not supported`);
         }
         else if (t2.type === "Recursive") {
-            throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: recursive types not supported`);
+            throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: recursive types not supported`);
         }
         else if (t1.type === "Ref") {
             if (t2.type === "Ref") {
-                return RefType(TypeWiden(t1.value, t2.value));
+                return RefType(withPathSegment("[ref]", () => TypeWiden(t1.value, t2.value)));
             }
             else {
-                throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Array") {
             if (t2.type === "Array") {
-                return ArrayType(TypeWiden(t1.value, t2.value));
+                return ArrayType(withPathSegment("[element]", () => TypeWiden(t1.value, t2.value)));
+            }
+            else {
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
+            }
+        }
+        else if (t1.type === "Vector") {
+            if (t2.type === "Vector") {
+                return VectorType(withPathSegment("[element]", () => TypeEqual(t1.element, t2.element)));
+            }
+            else {
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
+            }
+        }
+        else if (t1.type === "Matrix") {
+            if (t2.type === "Matrix") {
+                return MatrixType(withPathSegment("[element]", () => TypeEqual(t1.element, t2.element)));
             }
             else {
-                throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Set") {
             if (t2.type === "Set") {
-                return SetType(TypeWiden(t1.key, t2.key));
+                return SetType(withPathSegment("[key]", () => TypeWiden(t1.key, t2.key)));
             }
             else {
-                throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Dict") {
             if (t2.type === "Dict") {
-                return DictType(TypeWiden(t1.key, t2.key), TypeWiden(t1.value, t2.value));
+                return DictType(withPathSegment("[key]", () => TypeWiden(t1.key, t2.key)), withPathSegment("[value]", () => TypeWiden(t1.value, t2.value)));
             }
             else {
-                throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Struct") {
@@ -1619,20 +2126,20 @@ export function TypeWiden(t1, t2) {
                 const e1 = Object.entries(t1.fields);
                 const e2 = Object.entries(t2.fields);
                 if (e1.length !== e2.length)
-                    throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: structs contain different number of fields`);
+                    throw new TypeMismatchError(`structs contain different number of fields (${e1.length} vs ${e2.length})`);
                 let i = 0;
                 const e = {};
                 for (const [k1, f1] of e1) {
                     const [k2, f2] = e2[i];
                     if (k1 !== k2)
-                        throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: struct field ${i} has mismatched names ${printIdentifier(k1)} and ${printIdentifier(k2)}`);
-                    e[k1] = TypeWiden(f1, f2);
+                        throw new TypeMismatchError(`struct field ${i} has mismatched names ${printIdentifier(k1)} and ${printIdentifier(k2)}`);
+                    e[k1] = withPathSegment(`.${k1}`, () => TypeWiden(f1, f2));
                     i += 1;
                 }
                 return StructType(e);
             }
             else {
-                throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Variant") {
@@ -1644,7 +2151,7 @@ export function TypeWiden(t1, t2) {
                         cases[k1] = f1;
                     }
                     else {
-                        cases[k1] = TypeWiden(f1, f2);
+                        cases[k1] = withPathSegment(`.${k1}`, () => TypeWiden(f1, f2));
                     }
                 }
                 for (const [k2, f2] of Object.entries(t2.cases)) {
@@ -1656,21 +2163,21 @@ export function TypeWiden(t1, t2) {
                 return VariantType(cases);
             }
             else {
-                throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
         else if (t1.type === "Function") {
-            throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: functions not supported`);
+            throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: functions not supported`);
         }
         else if (t1.type === "AsyncFunction") {
-            throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: functions not supported`);
+            throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: functions not supported`);
         }
         else {
             if (t1.type === t2.type) {
                 return t1;
             }
             else {
-                throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}: incompatible types`);
+                throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}: incompatible types`);
             }
         }
     }
@@ -1678,7 +2185,7 @@ export function TypeWiden(t1, t2) {
         if (cause instanceof TypeMismatchError) {
             throw cause; // Don't wrap our own errors - they already have the full path
         }
-        throw new TypeMismatchError(`Cannot widen ${printType(t1)} with ${printType(t2)}`, { cause });
+        throw new TypeMismatchError(`expected ${printTypeSummary(t1)} but got ${printTypeSummary(t2)}`, { cause });
     }
 }
 /**