@rcrsr/rill 0.16.0 → 0.18.0

package/dist/runtime/core/callable.js

@@ -21,14 +21,13 @@
  */
 import { RuntimeError } from '../../types.js';
 import { astEquals } from './equals.js';
-import { formatValue, formatStructuralType, inferType, isOrdered, createOrdered, deepCopyRillValue, isTuple, paramToFieldDef, structuralTypeEquals, structuralTypeMatches, anyTypeValue, hasCollectionFields, emptyForType, } from './values.js';
-/** Type guard for any callable */
-export function isCallable(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        '__type' in value &&
-        value.__type === 'callable');
-}
+import { isCallable as _isCallableGuard, isDict, isOrdered, isTuple, } from './types/guards.js';
+import { formatValue, inferType } from './types/registrations.js';
+import { formatStructure, paramToFieldDef, structureEquals, structureMatches, } from './types/operations.js';
+import { createOrdered, copyValue, emptyForType, } from './types/constructors.js';
+import { anyTypeValue, hasCollectionFields } from './values.js';
+/** Type guard for any callable (delegates to types/guards.ts) */
+export const isCallable = _isCallableGuard;
 /** Type guard for script callable */
 export function isScriptCallable(value) {
     return isCallable(value) && value.kind === 'script';
@@ -61,14 +60,37 @@ export function callable(fn, isProperty = false) {
         isProperty,
     };
 }
-/** Type guard for dict (plain object, not array, not callable, not tuple) */
-export function isDict(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        !Array.isArray(value) &&
-        !isCallable(value) &&
-        !isTuple(value));
+/**
+ * Convert a RillFunction to an ApplicationCallable.
+ *
+ * Validates the input and produces a callable value accepted by the loader.
+ * Pure function with no side effects.
+ *
+ * @param def - Host function definition to convert
+ * @returns ApplicationCallable with __type, kind, isProperty, and preserved annotations
+ */
+export function toCallable(def, isProperty = false) {
+    if (def == null) {
+        throw new TypeError('RillFunction cannot be null or undefined');
+    }
+    if (typeof def.fn !== 'function') {
+        throw new TypeError('RillFunction.fn must be a function');
+    }
+    if (!Array.isArray(def.params)) {
+        throw new TypeError('RillFunction.params must be an array');
+    }
+    return {
+        __type: 'callable',
+        kind: 'application',
+        isProperty,
+        fn: def.fn,
+        params: def.params,
+        returnType: def.returnType,
+        annotations: def.annotations ?? {},
+    };
 }
+// isDict imported from ./types/guards.js and re-exported
+export { isDict };
 /** Format a callable for display */
 export function formatCallable(callable) {
     if (callable.kind === 'script') {
@@ -116,14 +138,14 @@ export function callableEquals(a, b, valueEquals = (x, y) => formatValue(x) ===
             return false;
         if (ap.name !== bp.name)
             return false;
-        // Compare type via structuralTypeEquals; absent type (any-typed) matches absent type
+        // Compare type via structureEquals; absent type (any-typed) matches absent type
         if (ap.type === undefined && bp.type !== undefined)
             return false;
         if (ap.type !== undefined && bp.type === undefined)
             return false;
         if (ap.type !== undefined &&
             bp.type !== undefined &&
-            !structuralTypeEquals(ap.type, bp.type))
+            !structureEquals(ap.type, bp.type))
             return false;
         if (!valueEquals(ap.defaultValue ?? null, bp.defaultValue ?? null)) {
             return false;
@@ -146,24 +168,24 @@ export function callableEquals(a, b, valueEquals = (x, y) => formatValue(x) ===
     return true;
 }
 /**
- * Build a RillType closure variant from a closure's parameter list.
+ * Build a TypeStructure closure variant from a closure's parameter list.
  *
  * Called at closure creation time to build the structural type for `$fn.^input`.
  * - Typed params use param.type directly when present
- * - Untyped params (type: undefined) map to { type: 'any' }
- * - Return type is always { type: 'any' }
+ * - Untyped params (type: undefined) map to { kind: 'any' }
+ * - Return type is always { kind: 'any' }
  *
  * No validation: parser already validates type names.
  *
  * @param params - Closure parameter definitions (RillParam[])
- * @returns Frozen RillType with closure variant
+ * @returns Frozen TypeStructure with closure variant
  */
 export function paramsToStructuralType(params) {
-    const closureParams = params.map((param) => paramToFieldDef(param.name, param.type ?? { type: 'any' }, param.defaultValue));
+    const closureParams = params.map((param) => paramToFieldDef(param.name, param.type ?? { kind: 'any' }, param.defaultValue));
     return Object.freeze({
-        type: 'closure',
+        kind: 'closure',
         params: closureParams,
-        ret: { type: 'any' },
+        ret: { kind: 'any' },
     });
 }
 /**
@@ -182,10 +204,10 @@ export function validateDefaultValueType(param, _functionName) {
     // Skip validation when type is undefined (any-typed, all defaults valid)
     if (param.type === undefined)
         return;
-    if (!structuralTypeMatches(param.defaultValue, param.type)) {
+    if (!structureMatches(param.defaultValue, param.type)) {
         const actualType = inferType(param.defaultValue);
-        const expectedType = formatStructuralType(param.type);
-        throw new Error(`Invalid defaultValue for parameter '${param.name}': expected ${expectedType}, got ${actualType}`);
+        const expectedType = formatStructure(param.type);
+        throw new RuntimeError('RILL-R077', `Invalid defaultValue for parameter '${param.name}': expected ${expectedType}, got ${actualType}`);
     }
 }
 /**
@@ -198,16 +220,17 @@ export function validateDefaultValueType(param, _functionName) {
  * Pure function: no class context, no evaluator, no side effects.
  */
 export function hydrateFieldDefaults(value, type) {
-    if (type.type === 'dict' && type.fields && isDict(value)) {
+    if (type.kind === 'dict' && type.fields && isDict(value)) {
+        const t = type;
         const dictValue = value;
         // Seed with all input entries so extra keys survive (structural match allows extras)
         const result = { ...dictValue };
-        for (const [fieldName, fieldDef] of Object.entries(type.fields)) {
+        for (const [fieldName, fieldDef] of Object.entries(t.fields)) {
             if (fieldName in dictValue) {
                 result[fieldName] = hydrateFieldDefaults(dictValue[fieldName], fieldDef.type);
             }
             else if (fieldDef.defaultValue !== undefined) {
-                result[fieldName] = hydrateFieldDefaults(deepCopyRillValue(fieldDef.defaultValue), fieldDef.type);
+                result[fieldName] = hydrateFieldDefaults(copyValue(fieldDef.defaultValue), fieldDef.type);
             }
             else if (hasCollectionFields(fieldDef.type)) {
                 result[fieldName] = hydrateFieldDefaults(emptyForType(fieldDef.type), fieldDef.type);
@@ -216,11 +239,14 @@ export function hydrateFieldDefaults(value, type) {
         }
         return result;
     }
-    if (type.type === 'ordered' && type.fields && isOrdered(value)) {
+    if (type.kind === 'ordered' &&
+        type.fields &&
+        isOrdered(value)) {
+        const t = type;
         const lookup = new Map(value.entries.map(([k, v]) => [k, v]));
-        const fieldNames = new Set(type.fields.map((f) => f.name ?? ''));
+        const fieldNames = new Set(t.fields.map((f) => f.name ?? ''));
         const resultEntries = [];
-        for (const field of type.fields) {
+        for (const field of t.fields) {
             const name = field.name ?? '';
             if (lookup.has(name)) {
                 resultEntries.push([
@@ -231,7 +257,7 @@ export function hydrateFieldDefaults(value, type) {
             else if (field.defaultValue !== undefined) {
                 resultEntries.push([
                     name,
-                    hydrateFieldDefaults(deepCopyRillValue(field.defaultValue), field.type),
+                    hydrateFieldDefaults(copyValue(field.defaultValue), field.type),
                 ]);
             }
             else if (hasCollectionFields(field.type)) {
@@ -250,7 +276,9 @@ export function hydrateFieldDefaults(value, type) {
         }
         return createOrdered(resultEntries);
     }
-    if (type.type === 'tuple' && type.elements && isTuple(value)) {
+    if (type.kind === 'tuple' &&
+        type.elements &&
+        isTuple(value)) {
         const elements = type.elements;
         const entries = value.entries;
         // All fields present: recurse into nested types for present positions
@@ -270,7 +298,7 @@ export function hydrateFieldDefaults(value, type) {
                 resultEntries.push(hydrateFieldDefaults(entries[i], el.type));
             }
             else if (el.defaultValue !== undefined) {
-                resultEntries.push(hydrateFieldDefaults(deepCopyRillValue(el.defaultValue), el.type));
+                resultEntries.push(hydrateFieldDefaults(copyValue(el.defaultValue), el.type));
             }
             else if (hasCollectionFields(el.type)) {
                 resultEntries.push(hydrateFieldDefaults(emptyForType(el.type), el.type));
@@ -327,6 +355,11 @@ export function marshalArgs(args, params, options) {
             if (param.defaultValue !== undefined) {
                 value = param.defaultValue;
             }
+            else if (param.type !== undefined && hasCollectionFields(param.type)) {
+                // Collection-typed param with field-level defaults: synthesize empty
+                // collection so Stage 2.5 (hydrateFieldDefaults) can fill in defaults
+                value = emptyForType(param.type);
+            }
             else {
                 // Stage 2: Missing required parameter
                 throw new RuntimeError('RILL-R044', `Missing argument for parameter '${param.name}'`, location, {
@@ -341,8 +374,8 @@ export function marshalArgs(args, params, options) {
         }
         // Stage 3: Type check when param.type is defined
         if (param.type !== undefined) {
-            if (!structuralTypeMatches(value, param.type)) {
-                const expectedType = formatStructuralType(param.type);
+            if (!structureMatches(value, param.type)) {
+                const expectedType = formatStructure(param.type);
                 const actualType = inferType(value);
                 throw new RuntimeError('RILL-R001', `Parameter type mismatch: ${param.name} expects ${expectedType}, got ${actualType}`, location, {
                     functionName,

package/dist/runtime/core/context.d.ts

@@ -4,20 +4,9 @@
  * Creates and configures the runtime context for script execution.
  * Public API for host applications.
  */
-import type { RuntimeContext, RuntimeOptions } from './types.js';
-import { type RillValue } from './values.js';
-import { type RillFunction } from './callable.js';
+import type { RuntimeContext, RuntimeOptions } from './types/runtime.js';
+import type { RillValue } from './types/structures.js';
 export declare const UNVALIDATED_METHOD_PARAMS: Set<string>;
-export declare const UNVALIDATED_METHOD_RECEIVERS: Set<string>;
-/**
- * Build a ReadonlyMap of frozen ApplicationCallable dicts from an array of
- * [typeName, methods] pairs. Accepts pairs (not a plain object) so the same
- * typeName can appear more than once — duplicate method names across entries
- * for the same type trigger an Error (EC-6).
- *
- * Re-exported from the public barrel index for host integration use.
- */
-export declare function buildTypeMethodDicts(pairs: Array<[string, Record<string, RillFunction>]>): ReadonlyMap<string, Readonly<Record<string, RillValue>>>;
 /**
  * Create a runtime context for script execution.
  * This is the main entry point for configuring the Rill runtime.

package/dist/runtime/core/context.js

@@ -5,9 +5,10 @@
  * Public API for host applications.
  */
 import { RuntimeError } from '../../types.js';
-import { BUILTIN_FUNCTIONS, BUILTIN_METHODS } from '../ext/builtins.js';
-import { bindDictCallables } from './types.js';
-import { inferType } from './values.js';
+import { BUILTIN_FUNCTIONS } from '../ext/builtins.js';
+import { BUILT_IN_TYPES } from './types/registrations.js';
+import { bindDictCallables } from './types/runtime.js';
+import { inferType } from './types/registrations.js';
 import { callable, validateDefaultValueType, } from './callable.js';
 // Built-in functions that are genuinely variadic and must skip arg validation.
 // log: tests call log("msg", extraValue) — extra args are silently ignored.
@@ -17,69 +18,23 @@ const UNTYPED_BUILTINS = new Set(['log', 'chain']);
 // messages expected by protected language tests. Generic marshalArgs
 // must not fire before the method body's own check.
 export const UNVALIDATED_METHOD_PARAMS = new Set(['has', 'has_any', 'has_all']);
-// Built-in methods that perform their own receiver type checking with specific
-// error messages. Generic RILL-R003 must not fire before the method body runs.
-// Mirrors the old flat-structure convention of receiverTypes: [].
-export const UNVALIDATED_METHOD_RECEIVERS = new Set([
-    'head',
-    'tail',
-    'first',
-    'at',
-    'eq',
-    'ne',
-    'keys',
-    'values',
-    'entries',
-    'has',
-    'has_any',
-    'has_all',
-    'dimensions',
-    'model',
-    'similarity',
-    'dot',
-    'distance',
-    'norm',
-    'normalize',
-]);
 /**
- * Build a ReadonlyMap of frozen ApplicationCallable dicts from an array of
- * [typeName, methods] pairs. Accepts pairs (not a plain object) so the same
- * typeName can appear more than once — duplicate method names across entries
- * for the same type trigger an Error (EC-6).
- *
- * Re-exported from the public barrel index for host integration use.
+ * Derive the set of method names that handle their own receiver type checking.
+ * Collects names from methods where skipReceiverValidation is true.
+ * Methods without the flag default to standard RILL-R003 receiver validation.
  */
-export function buildTypeMethodDicts(pairs) {
-    const registry = new Map();
-    const result = new Map();
-    for (const [typeName, methods] of pairs) {
-        const seen = registry.get(typeName) ?? new Set();
-        registry.set(typeName, seen);
-        const existing = result.get(typeName) ?? {};
-        const dict = { ...existing };
-        for (const [name, fn] of Object.entries(methods)) {
-            if (seen.has(name)) {
-                throw new Error(`Duplicate method '${name}' on type '${typeName}'`);
+function deriveUnvalidatedMethodReceivers(registrations) {
+    const bypass = new Set();
+    for (const reg of registrations) {
+        for (const [name, method] of Object.entries(reg.methods)) {
+            if (method.skipReceiverValidation) {
+                bypass.add(name);
             }
-            seen.add(name);
-            const appCallable = {
-                __type: 'callable',
-                kind: 'application',
-                params: fn.params,
-                returnType: fn.returnType,
-                annotations: fn.annotations ?? {},
-                isProperty: false,
-                fn: fn.fn,
-            };
-            dict[name] = appCallable;
         }
-        result.set(typeName, Object.freeze(dict));
     }
-    return result;
+    return Object.freeze(bypass);
 }
 const BUILTIN_FN_CACHE = new Map();
-const BUILTIN_METHOD_PARAMS_CACHE = new Map();
-const BUILTIN_METHOD_RECEIVER_TYPES_CACHE = new Map();
 function initBuiltinCaches() {
     for (const [name, entry] of Object.entries(BUILTIN_FUNCTIONS)) {
         if (UNTYPED_BUILTINS.has(name)) {
@@ -94,21 +49,6 @@ function initBuiltinCaches() {
         };
         BUILTIN_FN_CACHE.set(name, { appCallable: typedCallable });
     }
-    for (const [typeName, methods] of Object.entries(BUILTIN_METHODS)) {
-        for (const [name, impl] of Object.entries(methods)) {
-            // Accumulate receiver types across all type groups for this method name.
-            // Skip methods that perform their own receiver type checking.
-            if (!UNVALIDATED_METHOD_RECEIVERS.has(name)) {
-                const existing = BUILTIN_METHOD_RECEIVER_TYPES_CACHE.get(name);
-                BUILTIN_METHOD_RECEIVER_TYPES_CACHE.set(name, existing !== undefined ? [...existing, typeName] : [typeName]);
-            }
-            if (!UNVALIDATED_METHOD_PARAMS.has(name)) {
-                if (impl.params.length > 0) {
-                    BUILTIN_METHOD_PARAMS_CACHE.set(name, impl.params);
-                }
-            }
-        }
-    }
 }
 // Initialise once at module load.
 initBuiltinCaches();
@@ -153,7 +93,7 @@ export function createRuntimeContext(options = {}) {
                 if (description === undefined ||
                     typeof description !== 'string' ||
                     description.trim().length === 0) {
-                    throw new Error(`Function '${name}' requires description (requireDescriptions enabled)`);
+                    throw new RuntimeError('RILL-R069', `Function '${name}' requires description (requireDescriptions enabled)`);
                 }
                 // Check parameter descriptions (EC-11)
                 for (const param of params) {
@@ -161,7 +101,7 @@ export function createRuntimeContext(options = {}) {
                     if (paramDesc === undefined ||
                         typeof paramDesc !== 'string' ||
                         paramDesc.trim().length === 0) {
-                        throw new Error(`Parameter '${param.name}' of function '${name}' requires description (requireDescriptions enabled)`);
+                        throw new RuntimeError('RILL-R070', `Parameter '${param.name}' of function '${name}' requires description (requireDescriptions enabled)`);
                     }
                 }
             }
@@ -194,15 +134,74 @@ export function createRuntimeContext(options = {}) {
     const resolverConfigs = new Map(options.configurations?.resolvers
         ? Object.entries(options.configurations.resolvers)
         : []);
-    // Build typeMethodDicts fresh per context so duplicate detection (EC-6)
-    // uses isolated state and does not leak across context instances.
-    const typeMethodDicts = buildTypeMethodDicts(Object.entries(BUILTIN_METHODS));
+    // EC-1: Validate no duplicate type names in registrations.
+    const seenTypeNames = new Set();
+    for (const reg of BUILT_IN_TYPES) {
+        if (seenTypeNames.has(reg.name)) {
+            throw new RuntimeError('RILL-R071', `Duplicate type registration '${reg.name}'`);
+        }
+        seenTypeNames.add(reg.name);
+    }
+    // EC-2: Validate every registration has protocol.format.
+    for (const reg of BUILT_IN_TYPES) {
+        if (!reg.protocol.format) {
+            throw new RuntimeError('RILL-R072', `Type '${reg.name}' missing required format protocol`);
+        }
+    }
+    // Derive typeNames from registrations (replaces VALID_TYPE_NAMES in context).
+    const typeNames = Object.freeze(BUILT_IN_TYPES.map((r) => r.name));
+    // Derive leafTypes from registrations where isLeaf === true, plus 'any'
+    // which has no registration but rejects type arguments (AC-4).
+    const leafTypes = Object.freeze(new Set([
+        ...BUILT_IN_TYPES.filter((r) => r.isLeaf).map((r) => r.name),
+        'any',
+    ]));
+    // Derive method dicts from registration.methods (absorbs buildTypeMethodDicts
+    // logic). Validates EC-6: duplicate method on same type.
+    const methodRegistry = new Map();
+    const typeMethodDicts = new Map();
+    for (const reg of BUILT_IN_TYPES) {
+        const methods = reg.methods;
+        if (!methods || Object.keys(methods).length === 0)
+            continue;
+        const seen = methodRegistry.get(reg.name) ?? new Set();
+        methodRegistry.set(reg.name, seen);
+        const existing = typeMethodDicts.get(reg.name) ?? {};
+        const dict = { ...existing };
+        for (const [name, fn] of Object.entries(methods)) {
+            if (seen.has(name)) {
+                throw new RuntimeError('RILL-R073', `Duplicate method '${name}' on type '${reg.name}'`);
+            }
+            seen.add(name);
+            const appCallable = {
+                __type: 'callable',
+                kind: 'application',
+                params: fn.params,
+                returnType: fn.returnType,
+                annotations: fn.annotations ?? {},
+                isProperty: false,
+                fn: fn.fn,
+            };
+            dict[name] = appCallable;
+        }
+        typeMethodDicts.set(reg.name, Object.freeze(dict));
+    }
+    // Derive bypass set from registrations: method names that handle their own
+    // receiver type checking. Generic RILL-R003 must not fire before the method body.
+    const unvalidatedMethodReceivers = deriveUnvalidatedMethodReceivers(BUILT_IN_TYPES);
+    // BC-5: Freeze all derived collections after creation.
+    Object.freeze(typeNames);
+    Object.freeze(typeMethodDicts);
+    // Suppress unused-variable warning for typeNames (consumed in later phases).
+    void typeNames;
     return {
         parent: undefined,
         variables,
         variableTypes,
         functions,
         typeMethodDicts,
+        leafTypes,
+        unvalidatedMethodReceivers,
         callbacks: { ...defaultCallbacks, ...options.callbacks },
         observability: options.observability ?? {},
         pipeValue: null,
@@ -232,6 +231,8 @@ export function createChildContext(parent, overrides) {
         variableTypes: new Map(),
         functions: parent.functions,
         typeMethodDicts: parent.typeMethodDicts,
+        leafTypes: parent.leafTypes,
+        unvalidatedMethodReceivers: parent.unvalidatedMethodReceivers,
         callbacks: parent.callbacks,
         observability: parent.observability,
         pipeValue: parent.pipeValue,

package/dist/runtime/core/eval/base.d.ts

@@ -7,8 +7,8 @@
  * @internal
  */
 import type { ASTNode, CaptureNode, SourceLocation } from '../../../types.js';
-import type { RuntimeContext } from '../types.js';
-import type { RillValue } from '../values.js';
+import type { RuntimeContext } from '../types/runtime.js';
+import type { RillValue } from '../types/structures.js';
 /**
  * Base class for the evaluator.
  * Contains shared utilities used by all mixins.

package/dist/runtime/core/eval/base.js

@@ -74,6 +74,8 @@ export class EvaluatorBase {
      * Phase 1-3 use the functional evaluator which has its own handleCapture.
      */
     handleCapture(_capture, _value) {
+        // AC-13: Intentional raw throw - internal mixin guard, not user-reachable.
+        // This stub only runs if mixin composition is incomplete (programming error).
         throw new Error('handleCapture requires full Evaluator composition with VariablesMixin');
     }
     /**

package/dist/runtime/core/eval/evaluator.d.ts

@@ -100,7 +100,7 @@
  *
  * @internal
  */
-import type { RuntimeContext } from '../types.js';
+import type { RuntimeContext } from '../types/runtime.js';
 /**
  * Complete Evaluator class composed from all mixins.
  *

package/dist/runtime/core/eval/index.d.ts

@@ -8,8 +8,8 @@
  */
 import type { AnnotatedStatementNode, ASTNode, CaptureNode, ExpressionNode, RillTypeName, SourceLocation, StatementNode } from '../../../types.js';
 import type { RillCallable } from '../callable.js';
-import type { RuntimeContext } from '../types.js';
-import type { RillValue, RillType } from '../values.js';
+import type { RuntimeContext } from '../types/runtime.js';
+import type { RillValue, TypeStructure } from '../types/structures.js';
 /**
  * Capture information returned by handleCapture.
  */
@@ -39,7 +39,7 @@ export declare function handleCapture(capture: CaptureNode | null, value: RillVa
  * Assert that a value is of the expected type.
  * Returns the value unchanged if assertion passes, throws on mismatch.
  */
-export declare function assertType(value: RillValue, expected: RillTypeName | RillType, location?: SourceLocation): RillValue;
+export declare function assertType(value: RillValue, expected: RillTypeName | TypeStructure, location?: SourceLocation): RillValue;
 /**
  * Evaluate an expression and return its value.
  * Main entry point for expression evaluation.

package/dist/runtime/core/eval/index.js

@@ -70,6 +70,17 @@ export function assertType(value, expected, location) {
         resolverConfigs: new Map(),
         resolvingSchemes: new Set(),
         typeMethodDicts: new Map(),
+        leafTypes: new Set([
+            'string',
+            'number',
+            'bool',
+            'vector',
+            'type',
+            'any',
+            'closure',
+            'field_descriptor',
+        ]),
+        unvalidatedMethodReceivers: new Set(),
     };
     const evaluator = getEvaluator(minimalContext);
     return evaluator.assertType(value, expected, location);