@elaraai/east 0.0.1-beta.9 → 1.0.0

package/dist/src/type_of_type.js

@@ -2,9 +2,8 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-import { ArrayType, BlobType, BooleanType, DateTimeType, FloatType, IntegerType, NullType, printType, RecursiveType, StringType, StructType, VariantType } from "./types.js";
+import { ArrayType, BlobType, BooleanType, DateTimeType, FloatType, IntegerType, NullType, NeverType, printType, RecursiveType, StringType, StructType, VariantType, RefType, SetType, DictType, FunctionType, AsyncFunctionType, VectorType, MatrixType, type_id_symbol, getTypeId, isPrimitiveType } from "./types.js";
 import { isVariant, variant } from "./containers/variant.js";
-import { equalFor } from "./comparison.js";
 /** The type of primitive literal values in IR.
  * Used to represent the values in ValueIR nodes.
  */
@@ -37,7 +36,7 @@ export const EastTypeType = RecursiveType(type => VariantType({
     "Dict": StructType({ key: type, value: type }),
     "Struct": ArrayType(StructType({ name: StringType, type: type })),
     "Variant": ArrayType(StructType({ name: StringType, type: type })),
-    "Recursive": IntegerType,
+    "Recursive": VariantType({ ref: IntegerType, wrapper: StructType({ id: IntegerType, inner: type }) }),
     "Function": StructType({
         inputs: ArrayType(type),
         output: type,
@@ -45,37 +44,47 @@ export const EastTypeType = RecursiveType(type => VariantType({
     "AsyncFunction": StructType({
         inputs: ArrayType(type),
         output: type,
-    })
+    }),
+    "Vector": type,
+    "Matrix": type,
 }));
-// Cache for memoizing toEastTypeValue results (top-level non-recursive calls only)
-const toEastTypeValueCache = new WeakMap();
+// Cache keyed by type_id. Only caches top-level (non-recursive-context) calls.
+// With type interning in types.ts, structurally identical EastType objects share
+// the same type_id, so this cache ensures identity-based dedup of EastTypeValues.
+const toEastTypeValueCache = new Map();
 export function toEastTypeValue(type, stack = [], is_recursive = false) {
     if (typeof type === "string") {
-        // Used for generics (type parameters)
         return type;
     }
     if (isVariant(type)) {
-        throw new Error(`Type is already an EastTypeValue`);
+        return type;
     }
-    // Memoization for top-level calls (empty stack, not in recursive context)
-    const isTopLevel = stack.length === 0 && !is_recursive;
-    if (isTopLevel) {
-        const cached = toEastTypeValueCache.get(type);
+    // Cache when no RecursiveType is on the stack. Inside a Recursive scope,
+    // results contain ref(id) values that must stay inside their enclosing wrapper.
+    // Outside, RecursiveTypes are fetched from cache as complete wrapper({id, inner}) values.
+    // This ensures ref(id) only appears inside wrapper inner types, never standalone.
+    const typeId = getTypeId(type);
+    const hasRecursiveOnStack = !isPrimitiveType(type) && stack.some((s) => s.type === "Recursive");
+    const canCache = typeId !== undefined && !hasRecursiveOnStack;
+    if (canCache) {
+        const cached = toEastTypeValueCache.get(typeId);
         if (cached !== undefined)
             return cached;
-        const result = toEastTypeValueImpl(type, stack, is_recursive);
-        toEastTypeValueCache.set(type, result);
-        return result;
     }
-    return toEastTypeValueImpl(type, stack, is_recursive);
-}
-function toEastTypeValueImpl(type, stack, is_recursive) {
-    if (is_recursive) {
-        const idx = stack.indexOf(type);
-        if (idx !== -1) {
-            return variant("Recursive", BigInt(stack.length - idx));
-        }
+    const result = toEastTypeValueImpl(type, stack, is_recursive);
+    // Always stamp the ETV with the type_id (needed for type table dedup via tidMap).
+    // Only cache the result when outside a recursive scope.
+    if (typeId !== undefined) {
+        result[type_id_symbol] = typeId;
+    }
+    if (canCache) {
+        toEastTypeValueCache.set(typeId, result);
     }
+    return result;
+}
+function toEastTypeValueImpl(type, stack, _is_recursive) {
+    // Note: self-reference detection for Recursive types is handled in the
+    // type.type === "Recursive" branch below (stack.indexOf check).
     if (type.type === "Never") {
         return variant("Never", null);
     }
@@ -140,7 +149,16 @@ function toEastTypeValueImpl(type, stack, is_recursive) {
         return ret;
     }
     else if (type.type === "Recursive") {
-        return toEastTypeValue(type.node, stack, true);
+        const tid = getTypeId(type);
+        // Self-reference: this RecursiveType is already on the stack.
+        if (stack.indexOf(type) !== -1) {
+            return variant("Recursive", variant("ref", BigInt(tid)));
+        }
+        // First encounter: push, recurse into inner, produce wrapper.
+        stack.push(type);
+        const inner = toEastTypeValueImpl(type.node, stack, false);
+        stack.pop();
+        return variant("Recursive", variant("wrapper", { id: BigInt(tid), inner }));
     }
     else if (type.type === "Function") {
         stack.push(type);
@@ -160,11 +178,120 @@ function toEastTypeValueImpl(type, stack, is_recursive) {
         stack.pop();
         return ret;
     }
+    else if (type.type === "Vector") {
+        stack.push(type);
+        const ret = variant("Vector", toEastTypeValue(type.element, stack, false));
+        stack.pop();
+        return ret;
+    }
+    else if (type.type === "Matrix") {
+        stack.push(type);
+        const ret = variant("Matrix", toEastTypeValue(type.element, stack, false));
+        stack.pop();
+        return ret;
+    }
     else {
         throw new Error(`Unknown type: ${printType(type)}`);
     }
 }
 export const EastTypeValueType = toEastTypeValue(EastTypeType);
+/**
+ * Inverse of {@link toEastTypeValue}: rebuild a static {@link EastType} from
+ * its runtime {@link EastTypeValue} variant form.
+ *
+ * @remarks
+ * Mirror of `toEastTypeValueImpl` in reverse. Used by callers who hold a
+ * runtime EastTypeValue (e.g. from a generic platform-fn impl factory) but
+ * need to invoke an EastType-only API like {@link PatchType}.
+ *
+ * Recursive types are reassembled via the `wrapper`/`ref` shape east emits:
+ * a `wrapper` carries `{id, inner}` (we recurse into `inner` and reconstruct
+ * the `RecursiveType`), and a `ref(id)` is a back-reference into an
+ * already-being-reconstructed scope.
+ *
+ * The conversion preserves type equality via east's interning: feeding the
+ * result back through {@link toEastTypeValue} produces the same identity as
+ * the input.
+ */
+export function fromEastTypeValue(t) {
+    const ctx = new Map();
+    return fromImpl(t, ctx);
+}
+function fromImpl(t, ctx) {
+    const tag = t.type;
+    if (tag === "Never")
+        return NeverType;
+    if (tag === "Null")
+        return NullType;
+    if (tag === "Boolean")
+        return BooleanType;
+    if (tag === "Integer")
+        return IntegerType;
+    if (tag === "Float")
+        return FloatType;
+    if (tag === "String")
+        return StringType;
+    if (tag === "DateTime")
+        return DateTimeType;
+    if (tag === "Blob")
+        return BlobType;
+    if (tag === "Ref")
+        return RefType(fromImpl(t.value, ctx));
+    if (tag === "Array")
+        return ArrayType(fromImpl(t.value, ctx));
+    if (tag === "Set")
+        return SetType(fromImpl(t.value, ctx));
+    if (tag === "Vector")
+        return VectorType(fromImpl(t.value, ctx));
+    if (tag === "Matrix")
+        return MatrixType(fromImpl(t.value, ctx));
+    if (tag === "Dict") {
+        const v = t.value;
+        return DictType(fromImpl(v.key, ctx), fromImpl(v.value, ctx));
+    }
+    if (tag === "Struct") {
+        const fields = t.value;
+        const obj = {};
+        for (const f of fields)
+            obj[f.name] = fromImpl(f.type, ctx);
+        return StructType(obj);
+    }
+    if (tag === "Variant") {
+        const cases = t.value;
+        const obj = {};
+        for (const c of cases)
+            obj[c.name] = fromImpl(c.type, ctx);
+        return VariantType(obj);
+    }
+    if (tag === "Function") {
+        const v = t.value;
+        return FunctionType(v.inputs.map(i => fromImpl(i, ctx)), fromImpl(v.output, ctx));
+    }
+    if (tag === "AsyncFunction") {
+        const v = t.value;
+        return AsyncFunctionType(v.inputs.map(i => fromImpl(i, ctx)), fromImpl(v.output, ctx));
+    }
+    if (tag === "Recursive") {
+        // Recursive carries either `wrapper({id, inner})` or `ref(id)`.
+        const inner = t.value;
+        if (inner.type === "ref") {
+            const id = inner.value;
+            const cached = ctx.get(id);
+            if (!cached)
+                throw new Error(`fromEastTypeValue: unresolved Recursive ref(${id})`);
+            return cached;
+        }
+        // wrapper — reconstruct the RecursiveType, registering its id in ctx
+        // before recursing so a back-ref inside the body resolves to it.
+        const w = inner.value;
+        const rec = RecursiveType(_self => {
+            ctx.set(w.id, _self);
+            return fromImpl(w.inner, ctx);
+        });
+        return rec;
+    }
+    throw new Error(`fromEastTypeValue: unhandled tag "${tag}"`);
+}
 /**
  * Compares two EastTypeValue instances for type equality.
  *
@@ -175,28 +302,146 @@ export const EastTypeValueType = toEastTypeValue(EastTypeType);
  * @remarks
  * This is the {@link EastTypeValue} version of {@link isTypeEqual}.
 */
-const isTypeValueEqualUncached = equalFor(EastTypeValueType);
-const isTypeValueEqualCache = new WeakMap();
+const isTypeValueEqualCache = new Map();
+/**
+ * Check structural equality of two EastTypeValues.
+ * Handles Recursive ref/wrapper equivalence: ref(N) and wrapper({id=N, inner})
+ * denote the same recursive type when N matches.
+ */
 export function isTypeValueEqual(t1, t2) {
     // Fast path: reference equality
     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;
+    // Recursive ref/wrapper equivalence: ref(N) and wrapper({id=N, inner})
+    // denote the same recursive type when ids match.
+    if (t1.type === "Recursive" && t2.type === "Recursive") {
+        const v1 = t1.value;
+        const v2 = t2.value;
+        const id1 = v1.type === "ref" ? v1.value : v1.type === "wrapper" ? v1.value.id : undefined;
+        const id2 = v2.type === "ref" ? v2.value : v2.type === "wrapper" ? v2.value.id : undefined;
+        if (id1 !== undefined && id2 !== undefined && id1 === id2)
+            return true;
+    }
     // Check cache
-    const innerCache = isTypeValueEqualCache.get(t1);
-    if (innerCache) {
-        const cached = innerCache.get(t2);
-        if (cached !== undefined)
-            return cached;
+    if (tid1 !== undefined && tid2 !== undefined) {
+        const innerCache = isTypeValueEqualCache.get(tid1);
+        if (innerCache) {
+            const cached = innerCache.get(tid2);
+            if (cached !== undefined)
+                return cached;
+        }
+        const result = isTypeValueEqualImpl(t1, t2);
+        let cache = isTypeValueEqualCache.get(tid1);
+        if (!cache) {
+            cache = new Map();
+            isTypeValueEqualCache.set(tid1, cache);
+        }
+        cache.set(tid2, result);
+        return result;
     }
-    const result = isTypeValueEqualUncached(t1, t2);
-    // Store in cache
-    let cache = isTypeValueEqualCache.get(t1);
-    if (!cache) {
-        cache = new WeakMap();
-        isTypeValueEqualCache.set(t1, cache);
+    return isTypeValueEqualImpl(t1, t2);
+}
+/** Structural comparison that uses isTypeValueEqual for children (handles ref/wrapper). */
+function isTypeValueEqualImpl(t1, t2) {
+    if (t1.type !== t2.type)
+        return false;
+    switch (t1.type) {
+        case "Never":
+        case "Null":
+        case "Boolean":
+        case "Integer":
+        case "Float":
+        case "String":
+        case "DateTime":
+        case "Blob":
+            return true;
+        case "Ref":
+        case "Array":
+        case "Vector":
+        case "Matrix":
+            return isTypeValueEqual(t1.value, t2.value);
+        case "Set":
+            return isTypeValueEqual(t1.value, t2.value);
+        case "Dict":
+            return isTypeValueEqual(t1.value.key, t2.value.key) &&
+                isTypeValueEqual(t1.value.value, t2.value.value);
+        case "Struct": {
+            const f1 = t1.value;
+            const f2 = t2.value;
+            if (f1.length !== f2.length)
+                return false;
+            for (let i = 0; i < f1.length; i++) {
+                if (f1[i].name !== f2[i].name)
+                    return false;
+                if (!isTypeValueEqual(f1[i].type, f2[i].type))
+                    return false;
+            }
+            return true;
+        }
+        case "Variant": {
+            const c1 = t1.value;
+            const c2 = t2.value;
+            if (c1.length !== c2.length)
+                return false;
+            for (let i = 0; i < c1.length; i++) {
+                if (c1[i].name !== c2[i].name)
+                    return false;
+                if (!isTypeValueEqual(c1[i].type, c2[i].type))
+                    return false;
+            }
+            return true;
+        }
+        case "Function":
+        case "AsyncFunction": {
+            const fn1 = t1.value;
+            const fn2 = t2.value;
+            if (fn1.inputs.length !== fn2.inputs.length)
+                return false;
+            for (let i = 0; i < fn1.inputs.length; i++) {
+                if (!isTypeValueEqual(fn1.inputs[i], fn2.inputs[i]))
+                    return false;
+            }
+            return isTypeValueEqual(fn1.output, fn2.output);
+        }
+        case "Recursive": {
+            const v1 = t1.value;
+            const v2 = t2.value;
+            const id1 = v1.type === "ref" ? v1.value : v1.type === "wrapper" ? v1.value.id : undefined;
+            const id2 = v2.type === "ref" ? v2.value : v2.type === "wrapper" ? v2.value.id : undefined;
+            // Same id → same recursive type (fast path, works within one process)
+            if (id1 !== undefined && id2 !== undefined && id1 === id2)
+                return true;
+            // Both refs with different ids → different recursive scopes
+            if (v1.type === "ref" && v2.type === "ref")
+                return false;
+            // Both wrappers with different ids: structural comparison (alpha-equivalence).
+            // Types from different processes have different ids for the same structure.
+            // Pre-seed cache so inner ref(id1) ≡ ref(id2) during recursion.
+            if (v1.type === "wrapper" && v2.type === "wrapper") {
+                const refT1 = { type: "Recursive", value: { type: "ref", value: id1 } };
+                const refT2 = { type: "Recursive", value: { type: "ref", value: id2 } };
+                const refTid1 = getTypeId(refT1);
+                const refTid2 = getTypeId(refT2);
+                if (refTid1 !== undefined && refTid2 !== undefined) {
+                    let c = isTypeValueEqualCache.get(refTid1);
+                    if (!c) {
+                        c = new Map();
+                        isTypeValueEqualCache.set(refTid1, c);
+                    }
+                    c.set(refTid2, true);
+                }
+                return isTypeValueEqual(v1.value.inner, v2.value.inner);
+            }
+            return false;
+        }
+        default:
+            return false;
     }
-    cache.set(t2, result);
-    return result;
 }
 /**
  * Checks if one EastTypeValue is a subtype of another.
@@ -216,7 +461,7 @@ export function isTypeValueEqual(t1, t2) {
  * - {@link FunctionType} and {@link AsyncFunctionType} use contravariant inputs and covariant outputs (and FunctionType is a subtype of AsyncFunctionType if their signatures match)
  */
 // Cache for memoizing isSubtypeValue results (top-level calls only)
-const isSubtypeValueCache = new WeakMap();
+const isSubtypeValueCache = new Map();
 export function isSubtypeValue(t1, t2, stack1 = [], stack2 = []) {
     // Handle string type parameters (used for generics)
     if (typeof t1 === "string" || typeof t2 === "string") {
@@ -225,54 +470,57 @@ export function isSubtypeValue(t1, t2, stack1 = [], stack2 = []) {
     // Fast path: reference equality (reflexivity - every type is subtype of itself)
     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;
     // Memoization for top-level calls (empty stacks)
     const isTopLevel = stack1.length === 0 && stack2.length === 0;
-    if (isTopLevel) {
-        const innerCache = isSubtypeValueCache.get(t1);
+    if (isTopLevel && tid1 !== undefined && tid2 !== undefined) {
+        const innerCache = isSubtypeValueCache.get(tid1);
         if (innerCache) {
-            const cached = innerCache.get(t2);
+            const cached = innerCache.get(tid2);
             if (cached !== undefined)
                 return cached;
         }
         const result = isSubtypeValueImpl(t1, t2, stack1, stack2);
-        // Store in cache
-        let cache = isSubtypeValueCache.get(t1);
+        let cache = isSubtypeValueCache.get(tid1);
         if (!cache) {
-            cache = new WeakMap();
-            isSubtypeValueCache.set(t1, cache);
+            cache = new Map();
+            isSubtypeValueCache.set(tid1, cache);
         }
-        cache.set(t2, result);
+        cache.set(tid2, result);
         return result;
     }
     return isSubtypeValueImpl(t1, t2, stack1, stack2);
 }
 function isSubtypeValueImpl(t1, t2, stack1, stack2) {
-    // Equi-recursive type subtyping: unfold recursive types when only one side is recursive
-    if (t1.type === "Recursive") {
-        if (t2.type === "Recursive") {
-            // Recursive types are invariant - heap allocations must match exactly
-            const r1 = stack1[stack1.length - Number(t1.value)];
-            if (r1 === undefined) {
-                throw new Error(`Invalid Recursive type reference: ${t1.value} at depth ${stack1.length}`);
-            }
-            const r2 = stack2[stack2.length - Number(t2.value)];
-            if (r2 === undefined) {
-                throw new Error(`Invalid Recursive type reference: ${t2.value} at depth ${stack2.length}`);
-            }
-            return isTypeValueEqual(r1, r2);
+    // Recursive wrappers: push inner to context map, recurse into inner type
+    if (t1.type === "Recursive" && t1.value.type === "wrapper") {
+        stack1.push(t1);
+        const result = isSubtypeValueImpl(t1.value.value.inner, t2, stack1, stack2);
+        stack1.pop();
+        return result;
+    }
+    if (t2.type === "Recursive" && t2.value.type === "wrapper") {
+        stack2.push(t2);
+        const result = isSubtypeValueImpl(t1, t2.value.value.inner, stack1, stack2);
+        stack2.pop();
+        return result;
+    }
+    // Equi-recursive type subtyping for self-references (id-based)
+    if (t1.type === "Recursive" && t1.value.type === "ref") {
+        if (t2.type === "Recursive" && t2.value.type === "ref") {
+            // Both are refs — they're equal if they reference the same type_id
+            return t1.value.value === t2.value.value;
         }
         else {
-            // Recursive cannot fit in non-recursive (infinite cannot fit in finite)
             return false;
         }
     }
-    else if (t2.type === "Recursive") {
-        // If the head is "on the stack" we can do head covariance by unfolding once
-        const r2 = stack2[stack2.length - Number(t2.value)];
-        if (r2 === undefined) {
-            throw new Error(`Invalid Recursive type reference: ${t2.value} at depth ${stack2.length}`);
-        }
-        return isSubtypeValue(t1, r2, stack1, stack2.slice(0, stack2.length - Number(t2.value)));
+    else if (t2.type === "Recursive" && t2.value.type === "ref") {
+        return false;
     }
     // Never is subtype of everything
     if (t1.type === "Never") {
@@ -301,6 +549,14 @@ function isSubtypeValueImpl(t1, t2, stack1, stack2) {
     if (t1.type === "Array" && t2.type === "Array") {
         return isTypeValueEqual(t1.value, t2.value);
     }
+    // Vector type - invariant (mutable)
+    if (t1.type === "Vector" && t2.type === "Vector") {
+        return isTypeValueEqual(t1.value, t2.value);
+    }
+    // Matrix type - invariant (mutable)
+    if (t1.type === "Matrix" && t2.type === "Matrix") {
+        return isTypeValueEqual(t1.value, t2.value);
+    }
     // Set type - invariant (mutable)
     if (t1.type === "Set" && t2.type === "Set") {
         return isTypeValueEqual(t1.value, t2.value);
@@ -405,24 +661,28 @@ function isSubtypeValueImpl(t1, t2, stack1, stack2) {
     return false;
 }
 // Cache for memoizing expandTypeValue results (top-level calls only)
-const expandTypeValueCache = new WeakMap();
+const expandTypeValueCache = new Map();
 /** Expand recursive types one level deeper, if necessary */
 export function expandTypeValue(type, root = type, depth = 0n) {
     // Fast path: primitive types cannot contain recursive references
     if (type.type === "Never" || type.type === "Null" || type.type === "Boolean" ||
         type.type === "Integer" || type.type === "Float" || type.type === "String" ||
-        type.type === "DateTime" || type.type === "Blob") {
+        type.type === "DateTime" || type.type === "Blob" ||
+        type.type === "Vector" || type.type === "Matrix") {
         return type;
     }
     // Memoization for top-level calls
     const isTopLevel = root === type && depth === 0n;
     if (isTopLevel) {
-        const cached = expandTypeValueCache.get(type);
-        if (cached !== undefined)
-            return cached;
-        const result = expandTypeValueImpl(type, root, depth);
-        expandTypeValueCache.set(type, result);
-        return result;
+        const tid = getTypeId(type);
+        if (tid !== undefined) {
+            const cached = expandTypeValueCache.get(tid);
+            if (cached !== undefined)
+                return cached;
+            const result = expandTypeValueImpl(type, root, depth);
+            expandTypeValueCache.set(tid, result);
+            return result;
+        }
     }
     return expandTypeValueImpl(type, root, depth);
 }
@@ -433,6 +693,12 @@ function expandTypeValueImpl(type, root, depth) {
     else if (type.type === "Array") {
         return variant("Array", expandTypeValue(type.value, root, depth + 1n));
     }
+    else if (type.type === "Vector") {
+        return variant("Vector", expandTypeValue(type.value, root, depth + 1n));
+    }
+    else if (type.type === "Matrix") {
+        return variant("Matrix", expandTypeValue(type.value, root, depth + 1n));
+    }
     else if (type.type === "Dict") {
         return variant("Dict", {
             key: type.value.key,
@@ -463,10 +729,14 @@ function expandTypeValueImpl(type, root, depth) {
             output: expandTypeValue(type.value.output, root, depth + 1n),
         });
     }
-    else if (type.type === "Recursive" && depth === type.value) {
-        // Unfold once
+    else if (type.type === "Recursive" && type.value.type === "ref" && depth === type.value.value) {
+        // Unfold once (self-reference at matching depth)
         return root;
     }
+    else if (type.type === "Recursive" && type.value.type === "wrapper") {
+        // Recursive wrapper: expand the inner type
+        return variant("Recursive", variant("wrapper", { id: type.value.value.id, inner: expandTypeValue(type.value.value.inner, root, depth) }));
+    }
     else {
         return type;
     }
@@ -486,7 +756,9 @@ export function isDataTypeValue(type, depth = 0) {
     // checked this type in the current path, so it's safe (would have returned
     // false already if it contained functions)
     if (type.type === "Recursive") {
-        return true;
+        if (type.value.type === "wrapper")
+            return isDataTypeValue(type.value.value.inner, depth);
+        return true; // Self-reference — already checked in current path
     }
     // Function types are not data types
     if (type.type === "Function" || type.type === "AsyncFunction") {
@@ -505,6 +777,9 @@ export function isDataTypeValue(type, depth = 0) {
     if (type.type === "Array") {
         return isDataTypeValue(type.value, depth + 1);
     }
+    if (type.type === "Vector" || type.type === "Matrix") {
+        return true;
+    }
     if (type.type === "Set") {
         // Set keys are checked at construction time to be immutable data types
         return true;