@rcrsr/rill 0.16.0 → 0.18.0

package/dist/runtime/core/types/operations.js

@@ -0,0 +1,804 @@
+/**
+ * Type Structure Operations
+ *
+ * Structural comparison, matching, inference, and formatting functions
+ * extracted from values.ts. Provides `compareStructuredFields()` to
+ * deduplicate dict/tuple/ordered dispatch across structureEquals,
+ * structureMatches, and formatStructure.
+ *
+ * Import constraints:
+ * - Imports from ./structures.js, ./guards.js, ./registrations.js
+ * - Circular with registrations.ts (runtime-safe: no init-time cross-calls)
+ */
+import { RuntimeError } from '../../../types.js';
+import { isCallable as _isCallableGuard, isDict, isIterator, isOrdered, isStream, isTuple, isTypeValue, isVector, } from './guards.js';
+import { inferType as registryInferType, formatValue as registryFormatValue, deepEquals as registryDeepEquals, } from './registrations.js';
+/** isCallable guard widened to narrow to full RillCallable (not just CallableMarker) */
+const isCallable = _isCallableGuard;
+/**
+ * Shared dispatch for dict/tuple/ordered field comparison.
+ * Handles valueType check and field iteration across
+ * structureEquals, structureMatches, and formatStructure.
+ *
+ * Constraints:
+ * - Dict: keyed fields, sorted key comparison
+ * - Tuple: positional elements
+ * - Ordered: named positional fields
+ * - Recurses via caller-provided callbacks
+ *
+ * Callers validate that a.kind === b.kind before calling.
+ * Invalid kind values fall through to the final return.
+ */
+export function compareStructuredFields(a, b, callbacks, fallback) {
+    if (a.kind === 'dict') {
+        const aDict = a;
+        const bDict = b;
+        const aHasValue = aDict.valueType !== undefined;
+        const bHasValue = bDict.valueType !== undefined;
+        if (aHasValue || bHasValue) {
+            if (!aHasValue || !bHasValue)
+                return callbacks.onValueTypeMismatch();
+            return callbacks.onValueType(aDict.valueType, bDict.valueType);
+        }
+        if (aDict.fields === undefined && bDict.fields === undefined) {
+            return callbacks.onBothEmpty();
+        }
+        if (aDict.fields === undefined || bDict.fields === undefined) {
+            return callbacks.onFieldPresenceMismatch();
+        }
+        return callbacks.onDictFields(aDict.fields, bDict.fields);
+    }
+    if (a.kind === 'tuple') {
+        const aTuple = a;
+        const bTuple = b;
+        const aHasValue = aTuple.valueType !== undefined;
+        const bHasValue = bTuple.valueType !== undefined;
+        if (aHasValue || bHasValue) {
+            if (!aHasValue || !bHasValue)
+                return callbacks.onValueTypeMismatch();
+            return callbacks.onValueType(aTuple.valueType, bTuple.valueType);
+        }
+        if (aTuple.elements === undefined && bTuple.elements === undefined) {
+            return callbacks.onBothEmpty();
+        }
+        if (aTuple.elements === undefined || bTuple.elements === undefined) {
+            return callbacks.onFieldPresenceMismatch();
+        }
+        return callbacks.onTupleElements(aTuple.elements, bTuple.elements);
+    }
+    if (a.kind === 'ordered') {
+        const aOrd = a;
+        const bOrd = b;
+        const aHasValue = aOrd.valueType !== undefined;
+        const bHasValue = bOrd.valueType !== undefined;
+        if (aHasValue || bHasValue) {
+            if (!aHasValue || !bHasValue)
+                return callbacks.onValueTypeMismatch();
+            return callbacks.onValueType(aOrd.valueType, bOrd.valueType);
+        }
+        if (aOrd.fields === undefined && bOrd.fields === undefined) {
+            return callbacks.onBothEmpty();
+        }
+        if (aOrd.fields === undefined || bOrd.fields === undefined) {
+            return callbacks.onFieldPresenceMismatch();
+        }
+        return callbacks.onOrderedFields(aOrd.fields, bOrd.fields);
+    }
+    return fallback;
+}
+// ============================================================
+// PRIVATE HELPERS
+// ============================================================
+/**
+ * Normalize a TypeStructure that may use the legacy `.type` discriminator.
+ * During migration, some code constructs objects with `{ type: 'string' }`
+ * instead of `{ kind: 'string' }`. Converts legacy format on the fly.
+ */
+function normalizeStructure(ts) {
+    if (ts.kind !== undefined)
+        return ts;
+    const legacy = ts;
+    if (typeof legacy['type'] === 'string') {
+        return { ...legacy, kind: legacy['type'] };
+    }
+    return ts;
+}
+/** Format a RillValue as a rill literal for use in type signatures. */
+export function formatRillLiteral(value) {
+    if (typeof value === 'string') {
+        const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        return `"${escaped}"`;
+    }
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (value === null)
+        return 'null';
+    // List: bare bracket form [elem, ...]
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        return `[${value.map(formatRillLiteral).join(', ')}]`;
+    }
+    // Tuple: tuple[elem, ...]
+    if (isTuple(value)) {
+        return `tuple[${value.entries.map(formatRillLiteral).join(', ')}]`;
+    }
+    // Ordered: ordered[key: val, ...]
+    if (isOrdered(value)) {
+        const inner = value.entries
+            .map(([k, v]) => `${k}: ${formatRillLiteral(v)}`)
+            .join(', ');
+        return `ordered[${inner}]`;
+    }
+    // Non-literal compound types: fall through to display format
+    if (isVector(value) ||
+        isIterator(value) ||
+        isStream(value) ||
+        _isCallableGuard(value) ||
+        isTypeValue(value)) {
+        return registryFormatValue(value);
+    }
+    // Dict: bare bracket form [key: val, ...] or [:] for empty
+    if (typeof value === 'object' && value !== null) {
+        const keys = Object.keys(value);
+        if (keys.length === 0)
+            return '[:]';
+        const inner = keys
+            .map((k) => `${k}: ${formatRillLiteral(value[k])}`)
+            .join(', ');
+        return `[${inner}]`;
+    }
+    return registryFormatValue(value);
+}
+/**
+ * Compare sequential (positional) RillFieldDef arrays for structural equality.
+ * Shared by tuple elements and ordered fields. When `named` is true,
+ * compares field names in addition to types and defaults.
+ */
+function compareSequentialFields(aFields, bFields, named) {
+    if (aFields.length !== bFields.length)
+        return false;
+    for (let i = 0; i < aFields.length; i++) {
+        const aField = aFields[i];
+        const bField = bFields[i];
+        if (named && aField.name !== bField.name)
+            return false;
+        if (!structureEquals(aField.type, bField.type))
+            return false;
+        const aDefault = aField.defaultValue;
+        const bDefault = bField.defaultValue;
+        if (aDefault === undefined && bDefault === undefined)
+            continue;
+        if (aDefault === undefined || bDefault === undefined)
+            return false;
+        if (!registryDeepEquals(aDefault, bDefault))
+            return false;
+    }
+    return true;
+}
+// ============================================================
+// STRUCTURE EQUALS
+// ============================================================
+/** Equality callbacks for compareStructuredFields */
+const equalsCallbacks = {
+    onValueType: (aVT, bVT) => structureEquals(aVT, bVT),
+    onValueTypeMismatch: () => false,
+    onBothEmpty: () => true,
+    onFieldPresenceMismatch: () => false,
+    onDictFields(aFields, bFields) {
+        const aKeys = Object.keys(aFields).sort();
+        const bKeys = Object.keys(bFields).sort();
+        if (aKeys.length !== bKeys.length)
+            return false;
+        for (let i = 0; i < aKeys.length; i++) {
+            const key = aKeys[i];
+            if (key !== bKeys[i])
+                return false;
+            const aField = aFields[key];
+            const bField = bFields[key];
+            const aHasDefault = aField.defaultValue !== undefined;
+            const bHasDefault = bField.defaultValue !== undefined;
+            if (aHasDefault !== bHasDefault)
+                return false;
+            if (!structureEquals(aField.type, bField.type))
+                return false;
+            if (aHasDefault && bHasDefault) {
+                if (!registryDeepEquals(aField.defaultValue, bField.defaultValue))
+                    return false;
+            }
+        }
+        return true;
+    },
+    onTupleElements: (a, b) => compareSequentialFields(a, b, false),
+    onOrderedFields: (a, b) => compareSequentialFields(a, b, true),
+};
+/** Compare two structural types for equality. */
+export function structureEquals(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    // Leaf variants compare by kind alone
+    if (a.kind === 'number' ||
+        a.kind === 'string' ||
+        a.kind === 'bool' ||
+        a.kind === 'vector' ||
+        a.kind === 'type' ||
+        a.kind === 'any') {
+        return true;
+    }
+    if (a.kind === 'list' && b.kind === 'list') {
+        const aList = a;
+        const bList = b;
+        if (aList.element === undefined && bList.element === undefined)
+            return true;
+        if (aList.element === undefined || bList.element === undefined)
+            return false;
+        return structureEquals(aList.element, bList.element);
+    }
+    // Delegate dict/tuple/ordered to compareStructuredFields
+    if (a.kind === 'dict' || a.kind === 'tuple' || a.kind === 'ordered') {
+        return compareStructuredFields(a, b, equalsCallbacks, false);
+    }
+    if (a.kind === 'union' && b.kind === 'union') {
+        const aUnion = a;
+        const bUnion = b;
+        if (aUnion.members.length !== bUnion.members.length)
+            return false;
+        for (let i = 0; i < aUnion.members.length; i++) {
+            if (!structureEquals(aUnion.members[i], bUnion.members[i]))
+                return false;
+        }
+        return true;
+    }
+    if (a.kind === 'stream' && b.kind === 'stream') {
+        const aStream = a;
+        const bStream = b;
+        const chunkEq = aStream.chunk === undefined && bStream.chunk === undefined
+            ? true
+            : aStream.chunk !== undefined && bStream.chunk !== undefined
+                ? structureEquals(aStream.chunk, bStream.chunk)
+                : false;
+        if (!chunkEq)
+            return false;
+        const retEq = aStream.ret === undefined && bStream.ret === undefined
+            ? true
+            : aStream.ret !== undefined && bStream.ret !== undefined
+                ? structureEquals(aStream.ret, bStream.ret)
+                : false;
+        return retEq;
+    }
+    if (a.kind === 'closure' && b.kind === 'closure') {
+        const aCls = a;
+        const bCls = b;
+        if (aCls.params === undefined && bCls.params === undefined) {
+            // Both absent: compare ret
+        }
+        else if (aCls.params === undefined || bCls.params === undefined) {
+            return false;
+        }
+        else {
+            if (aCls.params.length !== bCls.params.length)
+                return false;
+            for (let i = 0; i < aCls.params.length; i++) {
+                const aParam = aCls.params[i];
+                const bParam = bCls.params[i];
+                if (aParam.name !== bParam.name)
+                    return false;
+                if (!structureEquals(aParam.type, bParam.type))
+                    return false;
+                const aDefault = aParam.defaultValue;
+                const bDefault = bParam.defaultValue;
+                if (aDefault === undefined && bDefault === undefined)
+                    continue;
+                if (aDefault === undefined || bDefault === undefined)
+                    return false;
+                if (!registryDeepEquals(aDefault, bDefault))
+                    return false;
+            }
+        }
+        if (aCls.ret === undefined && bCls.ret === undefined)
+            return true;
+        if (aCls.ret === undefined || bCls.ret === undefined)
+            return false;
+        return structureEquals(aCls.ret, bCls.ret);
+    }
+    return false;
+}
+// ============================================================
+// STRUCTURE MATCHES
+// ============================================================
+/**
+ * Create structureMatches callbacks that capture the runtime value.
+ * Dict checks keys against type fields. Tuple and ordered check
+ * entries against type elements/fields.
+ */
+function createMatchesCallbacks(value) {
+    return {
+        onValueType(valueType) {
+            // Uniform valueType: check all values match the type.
+            // Order matters: isOrdered/isTuple before isDict because
+            // ordered and tuple values also satisfy isDict.
+            if (isTuple(value)) {
+                return value.entries.every((v) => structureMatches(v, valueType));
+            }
+            if (isOrdered(value)) {
+                return value.entries.every(([, v]) => structureMatches(v, valueType));
+            }
+            if (isDict(value)) {
+                const vals = Object.values(value);
+                return vals.every((v) => structureMatches(v, valueType));
+            }
+            return false;
+        },
+        onValueTypeMismatch: () => false,
+        onBothEmpty: () => true,
+        onFieldPresenceMismatch: () => false,
+        onDictFields(fields) {
+            const dictKeys = Object.keys(fields);
+            if (dictKeys.length === 0)
+                return true;
+            const dict = value;
+            for (const key of dictKeys) {
+                if (!(key in dict)) {
+                    const field = fields[key];
+                    if (field.defaultValue !== undefined)
+                        continue;
+                    return false;
+                }
+                const field = fields[key];
+                if (!structureMatches(dict[key], field.type))
+                    return false;
+            }
+            return true;
+        },
+        onTupleElements(elements) {
+            if (!isTuple(value))
+                return false;
+            if (elements.length === 0)
+                return value.entries.length === 0;
+            if (value.entries.length > elements.length)
+                return false;
+            if (value.entries.length < elements.length) {
+                for (let i = value.entries.length; i < elements.length; i++) {
+                    const field = elements[i];
+                    if (field.defaultValue === undefined)
+                        return false;
+                }
+            }
+            for (let i = 0; i < value.entries.length; i++) {
+                if (!structureMatches(value.entries[i], elements[i].type))
+                    return false;
+            }
+            return true;
+        },
+        onOrderedFields(fields) {
+            if (!isOrdered(value))
+                return false;
+            if (fields.length === 0)
+                return value.entries.length === 0;
+            if (value.entries.length > fields.length)
+                return false;
+            if (value.entries.length < fields.length) {
+                for (let i = value.entries.length; i < fields.length; i++) {
+                    const field = fields[i];
+                    if (field.defaultValue === undefined)
+                        return false;
+                }
+            }
+            for (let i = 0; i < value.entries.length; i++) {
+                const field = fields[i];
+                const [actualName, actualValue] = value.entries[i];
+                if (actualName !== field.name)
+                    return false;
+                if (!structureMatches(actualValue, field.type))
+                    return false;
+            }
+            return true;
+        },
+    };
+}
+/**
+ * Check if a value matches a structural type descriptor.
+ * Used for runtime type checking (`:?` operator).
+ */
+export function structureMatches(value, type) {
+    type = normalizeStructure(type);
+    if (typeof value === 'undefined') {
+        throw new RuntimeError('RILL-R004', 'Cannot type-check non-value');
+    }
+    if (type.kind === 'any')
+        return true;
+    // Leaf primitive variants: match by inferred type name
+    if (type.kind === 'number' ||
+        type.kind === 'string' ||
+        type.kind === 'bool' ||
+        type.kind === 'vector' ||
+        type.kind === 'type') {
+        return registryInferType(value) === type.kind;
+    }
+    if (type.kind === 'list') {
+        const t = type;
+        if (!Array.isArray(value))
+            return false;
+        if (t.element === undefined)
+            return true;
+        if (t.element.kind === 'any')
+            return true;
+        return value.every((elem) => structureMatches(elem, t.element));
+    }
+    // Delegate dict/tuple/ordered to compareStructuredFields
+    if (type.kind === 'dict') {
+        if (!isDict(value) || isStream(value))
+            return false;
+        return compareStructuredFields(type, type, createMatchesCallbacks(value), false);
+    }
+    if (type.kind === 'tuple') {
+        if (!isTuple(value))
+            return false;
+        return compareStructuredFields(type, type, createMatchesCallbacks(value), false);
+    }
+    if (type.kind === 'ordered') {
+        if (!isOrdered(value))
+            return false;
+        return compareStructuredFields(type, type, createMatchesCallbacks(value), false);
+    }
+    if (type.kind === 'stream') {
+        if (!isStream(value))
+            return false;
+        const t = type;
+        if (t.chunk === undefined && t.ret === undefined)
+            return true;
+        const raw = value;
+        if (t.chunk !== undefined) {
+            const valueChunk = raw['__rill_stream_chunk_type'];
+            if (valueChunk !== undefined && !structureEquals(valueChunk, t.chunk))
+                return false;
+        }
+        if (t.ret !== undefined) {
+            const valueRet = raw['__rill_stream_ret_type'];
+            if (valueRet !== undefined && !structureEquals(valueRet, t.ret))
+                return false;
+        }
+        return true;
+    }
+    if (type.kind === 'closure') {
+        const t = type;
+        if (!isCallable(value))
+            return false;
+        if (t.params === undefined)
+            return true;
+        const valueParams = value.params ?? [];
+        if (valueParams.length !== t.params.length)
+            return false;
+        for (let i = 0; i < t.params.length; i++) {
+            const field = t.params[i];
+            const param = valueParams[i];
+            if (param.name !== field.name)
+                return false;
+            const paramType = param.type ?? { kind: 'any' };
+            if (!structureEquals(paramType, field.type))
+                return false;
+            // Directional default rules: value (superset) satisfies type (contract)
+            const valueHasDefault = param.defaultValue !== undefined;
+            const typeHasDefault = field.defaultValue !== undefined;
+            if (!valueHasDefault && typeHasDefault)
+                return false;
+            if (valueHasDefault && typeHasDefault) {
+                if (!registryDeepEquals(param.defaultValue, field.defaultValue))
+                    return false;
+            }
+            // value has default + type lacks → compatible (superset satisfies)
+            // neither has default → compatible
+        }
+        const retType = value.returnType.structure;
+        if (t.ret === undefined)
+            return true;
+        return structureEquals(retType, t.ret);
+    }
+    if (type.kind === 'union') {
+        const t = type;
+        return t.members.some((member) => structureMatches(value, member));
+    }
+    return false;
+}
+// ============================================================
+// FORMAT STRUCTURE
+// ============================================================
+/**
+ * Format callbacks for compareStructuredFields.
+ * Returns `null` for bare types (no fields, no valueType) so the caller
+ * can distinguish "fields: undefined" from "fields: {}".
+ */
+const formatCallbacks = {
+    onValueType(valueType) {
+        return formatStructure(valueType);
+    },
+    onValueTypeMismatch: () => null,
+    onBothEmpty: () => null,
+    onFieldPresenceMismatch: () => null,
+    onDictFields(fields) {
+        const parts = Object.keys(fields)
+            .sort()
+            .map((k) => {
+            const field = fields[k];
+            const base = `${k}: ${formatStructure(field.type)}`;
+            if (field.defaultValue === undefined)
+                return base;
+            return `${base} = ${formatRillLiteral(field.defaultValue)}`;
+        });
+        return parts.join(', ');
+    },
+    onTupleElements(elements) {
+        const parts = elements.map((field) => {
+            const base = formatStructure(field.type);
+            if (field.defaultValue === undefined)
+                return base;
+            return `${base} = ${formatRillLiteral(field.defaultValue)}`;
+        });
+        return parts.join(', ');
+    },
+    onOrderedFields(fields) {
+        const parts = fields.map((field) => {
+            const base = `${field.name}: ${formatStructure(field.type)}`;
+            if (field.defaultValue === undefined)
+                return base;
+            return `${base} = ${formatRillLiteral(field.defaultValue)}`;
+        });
+        return parts.join(', ');
+    },
+};
+/** Format a structural type descriptor as a human-readable string. */
+export function formatStructure(type) {
+    if (type.kind === 'any' ||
+        type.kind === 'number' ||
+        type.kind === 'string' ||
+        type.kind === 'bool' ||
+        type.kind === 'vector' ||
+        type.kind === 'type') {
+        return type.kind;
+    }
+    if (type.kind === 'list') {
+        const t = type;
+        if (t.element === undefined)
+            return 'list';
+        return `list(${formatStructure(t.element)})`;
+    }
+    // Delegate dict/tuple/ordered to compareStructuredFields
+    if (type.kind === 'dict' ||
+        type.kind === 'tuple' ||
+        type.kind === 'ordered') {
+        const inner = compareStructuredFields(type, type, formatCallbacks, null);
+        // Bare type (no fields, no valueType): null signals undefined fields
+        if (inner === null)
+            return type.kind;
+        return `${type.kind}(${inner})`;
+    }
+    if (type.kind === 'stream') {
+        const t = type;
+        if (t.chunk === undefined && t.ret === undefined)
+            return 'stream';
+        const chunkStr = t.chunk !== undefined ? formatStructure(t.chunk) : 'any';
+        const retStr = t.ret !== undefined ? `:${formatStructure(t.ret)}` : '';
+        return `stream(${chunkStr})${retStr}`;
+    }
+    if (type.kind === 'closure') {
+        const t = type;
+        if (t.params === undefined)
+            return 'closure';
+        const params = t.params
+            .map((field) => {
+            const base = `${field.name}: ${formatStructure(field.type)}`;
+            if (field.defaultValue === undefined)
+                return base;
+            return `${base} = ${formatRillLiteral(field.defaultValue)}`;
+        })
+            .join(', ');
+        const ret = t.ret !== undefined ? formatStructure(t.ret) : 'any';
+        return `|${params}| :${ret}`;
+    }
+    if (type.kind === 'union') {
+        const t = type;
+        return t.members.map(formatStructure).join('|');
+    }
+    return 'any';
+}
+// ============================================================
+// INFER STRUCTURE
+// ============================================================
+/** Build a closure param field definition from name, type, and optional default. */
+export function paramToFieldDef(name, type, defaultValue) {
+    const field = { name, type };
+    if (defaultValue !== undefined)
+        field.defaultValue = defaultValue;
+    return field;
+}
+/**
+ * Infer the element type for a homogeneous list.
+ * Empty arrays return { kind: 'any' }.
+ * Mixed types throw RILL-R002.
+ */
+export function inferElementType(elements) {
+    if (elements.length === 0)
+        return { kind: 'any' };
+    const firstElem = elements[0];
+    let accType = inferStructure(firstElem);
+    for (let i = 1; i < elements.length; i++) {
+        const elem = elements[i];
+        const elemType = inferStructure(elem);
+        const merged = commonType(accType, elemType);
+        if (merged === null) {
+            throw new RuntimeError('RILL-R002', `List elements must be the same type: expected ${formatStructure(accType)}, got ${formatStructure(elemType)} at index ${i}`);
+        }
+        accType = merged;
+    }
+    return accType;
+}
+/** Infer the structural type descriptor for any Rill value. */
+export function inferStructure(value) {
+    if (value === null || typeof value === 'string') {
+        return { kind: 'string' };
+    }
+    if (typeof value === 'number') {
+        return { kind: 'number' };
+    }
+    if (typeof value === 'boolean') {
+        return { kind: 'bool' };
+    }
+    if (isTypeValue(value)) {
+        return { kind: 'type' };
+    }
+    if (Array.isArray(value)) {
+        return { kind: 'list', element: inferElementType(value) };
+    }
+    if (isTuple(value)) {
+        return {
+            kind: 'tuple',
+            elements: value.entries.map((e) => ({
+                type: inferStructure(e),
+            })),
+        };
+    }
+    if (isOrdered(value)) {
+        return {
+            kind: 'ordered',
+            fields: value.entries.map(([k, v]) => ({
+                name: k,
+                type: inferStructure(v),
+            })),
+        };
+    }
+    if (isVector(value)) {
+        return { kind: 'vector' };
+    }
+    if (isStream(value)) {
+        const raw = value;
+        const chunk = raw['__rill_stream_chunk_type'];
+        const ret = raw['__rill_stream_ret_type'];
+        const result = {
+            kind: 'stream',
+        };
+        if (chunk !== undefined)
+            result.chunk = chunk;
+        if (ret !== undefined)
+            result.ret = ret;
+        return result;
+    }
+    if (isCallable(value)) {
+        const params = (value.params ?? []).map((p) => paramToFieldDef(p.name, p.type ?? { kind: 'any' }, p.defaultValue));
+        const ret = value.returnType.structure;
+        return { kind: 'closure', params, ret };
+    }
+    if (typeof value === 'object') {
+        const dict = value;
+        const fields = {};
+        for (const [k, v] of Object.entries(dict)) {
+            fields[k] = { type: inferStructure(v) };
+        }
+        return { kind: 'dict', fields };
+    }
+    throw new RuntimeError('RILL-R004', `Cannot infer structural type for ${registryFormatValue(value)}`);
+}
+// ============================================================
+// COMMON TYPE
+// ============================================================
+/**
+ * Merge uniform value types from two sides of the same compound type.
+ * Sub-case A: both carry valueType -> recurse commonType.
+ * Sub-case B: both carry structural fields -> extract value types, merge all.
+ * Returns the merged TypeStructure on success, undefined when no uniform merge applies.
+ */
+function mergeUniformValueType(aValue, bValue, aFields, bFields) {
+    // Sub-case A: both carry valueType
+    if (aValue !== undefined && bValue !== undefined) {
+        const merged = commonType(aValue, bValue);
+        if (merged !== null)
+            return merged;
+        return undefined;
+    }
+    // Sub-case B: both carry structural fields
+    if (aFields !== undefined && bFields !== undefined) {
+        const allTypes = [
+            ...aFields.map((f) => f.type),
+            ...bFields.map((f) => f.type),
+        ];
+        if (allTypes.length === 0)
+            return undefined;
+        let merged = allTypes[0];
+        for (let i = 1; i < allTypes.length; i++) {
+            const next = commonType(merged, allTypes[i]);
+            if (next === null)
+                return undefined;
+            merged = next;
+        }
+        return merged;
+    }
+    return undefined;
+}
+/**
+ * Return the most specific shared type for two TypeStructure values.
+ * Returns null when types are incompatible at the top level.
+ *
+ * Cascade priority:
+ * 1. Any-narrowing: if either side is `any`, return the other
+ * 2. Structural match: delegate to structureEquals; on true, return a
+ * 3. Recursive list: merge inner element types
+ * 3b. Uniform valueType: merge dict/tuple/ordered value types
+ * 4. Bare type fallback: same compound type but structural mismatch
+ * 5. Incompatible: different top-level types return null
+ */
+export function commonType(a, b) {
+    // 1. Any-narrowing
+    if (a.kind === 'any')
+        return b;
+    if (b.kind === 'any')
+        return a;
+    // 5. Incompatible top-level types (checked early to short-circuit)
+    if (a.kind !== b.kind)
+        return null;
+    // 2. Structural match
+    if (structureEquals(a, b))
+        return a;
+    // 3. Recursive list element merging
+    if (a.kind === 'list' && b.kind === 'list') {
+        const aList = a;
+        const bList = b;
+        if (aList.element !== undefined && bList.element !== undefined) {
+            const inner = commonType(aList.element, bList.element);
+            if (inner !== null)
+                return { kind: 'list', element: inner };
+        }
+        return { kind: 'list' };
+    }
+    // 3b. Uniform valueType merging for dict/tuple/ordered
+    if (a.kind === 'dict' && b.kind === 'dict') {
+        const aDict = a;
+        const bDict = b;
+        const merged = mergeUniformValueType(aDict.valueType, bDict.valueType, aDict.fields ? Object.values(aDict.fields) : undefined, bDict.fields ? Object.values(bDict.fields) : undefined);
+        if (merged !== undefined)
+            return { kind: 'dict', valueType: merged };
+    }
+    if (a.kind === 'tuple' && b.kind === 'tuple') {
+        const aTuple = a;
+        const bTuple = b;
+        const merged = mergeUniformValueType(aTuple.valueType, bTuple.valueType, aTuple.elements, bTuple.elements);
+        if (merged !== undefined)
+            return { kind: 'tuple', valueType: merged };
+    }
+    if (a.kind === 'ordered' && b.kind === 'ordered') {
+        const aOrd = a;
+        const bOrd = b;
+        const merged = mergeUniformValueType(aOrd.valueType, bOrd.valueType, aOrd.fields, bOrd.fields);
+        if (merged !== undefined)
+            return { kind: 'ordered', valueType: merged };
+    }
+    // 4. Bare type fallback for compound types.
+    if (a.kind === 'closure' ||
+        a.kind === 'dict' ||
+        a.kind === 'tuple' ||
+        a.kind === 'ordered' ||
+        a.kind === 'union') {
+        return { kind: a.kind };
+    }
+    return null;
+}