@rcrsr/rill 0.15.0 → 0.17.0

package/dist/parser/parser-use.js

@@ -56,7 +56,13 @@ Parser.prototype.parseUseExpr = function () {
     let typeRef = null;
     let closureAnnotation = null;
     if (check(this.state, TOKEN_TYPES.COLON)) {
-        if (peek(this.state, 1).type === TOKEN_TYPES.PIPE_BAR) {
+        if (peek(this.state, 1).type === TOKEN_TYPES.OR) {
+            // Zero-param closure annotation: :||
+            advance(this.state); // consume :
+            advance(this.state); // consume || (OR token)
+            closureAnnotation = [];
+        }
+        else if (peek(this.state, 1).type === TOKEN_TYPES.PIPE_BAR) {
             // Closure annotation: :|param: type, ...|
             advance(this.state); // consume :
             advance(this.state); // consume opening |
@@ -93,4 +99,3 @@ Parser.prototype.parseUseExpr = function () {
         span: makeSpan(start, current(this.state).span.end),
     };
 };
-//# sourceMappingURL=parser-use.js.map

package/dist/parser/parser-variables.d.ts

@@ -17,4 +17,3 @@ declare module './parser.js' {
         parseDefaultValue(): BodyNode;
     }
 }
-//# sourceMappingURL=parser-variables.d.ts.map

package/dist/parser/parser-variables.js

@@ -175,4 +175,3 @@ Parser.prototype.parseDefaultValue = function () {
     }
     return this.parsePipeChain();
 };
-//# sourceMappingURL=parser-variables.js.map

package/dist/parser/parser.d.ts

@@ -46,4 +46,3 @@ export declare class Parser {
      */
     get errors(): ParseError[];
 }
-//# sourceMappingURL=parser.d.ts.map

package/dist/parser/parser.js

@@ -51,4 +51,3 @@ export class Parser {
         return this.state.errors;
     }
 }
-//# sourceMappingURL=parser.js.map

package/dist/parser/state.d.ts

@@ -43,4 +43,3 @@ export declare function skipNewlines(state: ParserState): void;
 export declare function skipNewlinesIfFollowedBy(state: ParserState, tokenType: string): boolean;
 /** @internal */
 export declare function makeSpan(start: SourceLocation, end: SourceLocation): SourceSpan;
-//# sourceMappingURL=state.d.ts.map

package/dist/parser/state.js

@@ -150,4 +150,3 @@ function generateHint(expectedType, actualToken) {
 export function makeSpan(start, end) {
     return { start, end };
 }
-//# sourceMappingURL=state.js.map

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

@@ -17,10 +17,10 @@
  *
  * [ASSUMPTION] validateDefaultValueType _functionName Parameter
  * - Parameter accepted but unused (prefixed with _ to satisfy eslint)
- * - Kept for API consistency with validateCallableArgs signature
+ * - Kept for API consistency with marshalArgs signature
  */
 import type { BodyNode, SourceLocation } from '../../types.js';
-import type { RillType, RillTypeValue, RillValue } from './values.js';
+import type { TypeStructure, RillTypeValue, RillValue } from './values.js';
 interface RuntimeContextLike {
     readonly parent?: RuntimeContextLike | undefined;
     readonly variables: Map<string, RillValue>;
@@ -31,7 +31,7 @@ interface RuntimeContextLike {
  * Callable function signature.
  * Used for both host-provided functions and runtime callables.
  */
-export type CallableFn = (args: RillValue[], ctx: RuntimeContextLike, location?: SourceLocation) => RillValue | Promise<RillValue>;
+export type CallableFn = (args: Record<string, RillValue>, ctx: RuntimeContextLike, location?: SourceLocation) => RillValue | Promise<RillValue>;
 /**
  * Unified parameter definition for all callable types (script closures and host functions).
  *
@@ -42,7 +42,7 @@ export type CallableFn = (args: RillValue[], ctx: RuntimeContextLike, location?:
  */
 export interface RillParam {
     readonly name: string;
-    readonly type: RillType | undefined;
+    readonly type: TypeStructure | undefined;
     readonly defaultValue: RillValue | undefined;
     readonly annotations: Record<string, RillValue>;
 }
@@ -57,6 +57,8 @@ export interface RillFunction {
     readonly fn: CallableFn;
     readonly annotations?: Record<string, RillValue>;
     readonly returnType: RillTypeValue;
+    /** When true, RILL-R003 generic receiver validation is skipped for this method. */
+    readonly skipReceiverValidation?: boolean;
 }
 /** Common fields for all callable types */
 interface CallableBase {
@@ -112,6 +114,16 @@ export declare function isApplicationCallable(value: RillValue): value is Applic
  * @param isProperty If true, auto-invokes when accessed from dict (property-style)
  */
 export declare function callable(fn: CallableFn, isProperty?: boolean): ApplicationCallable;
+/**
+ * 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 declare function toCallable(def: RillFunction, isProperty?: boolean): ApplicationCallable;
 /** Type guard for dict (plain object, not array, not callable, not tuple) */
 export declare function isDict(value: RillValue): value is Record<string, RillValue>;
 /** Format a callable for display */
@@ -129,19 +141,19 @@ export declare function formatCallable(callable: RillCallable): string;
  */
 export declare function callableEquals(a: ScriptCallable, b: ScriptCallable, valueEquals?: (a: RillValue, b: RillValue) => boolean): boolean;
 /**
- * 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 declare function paramsToStructuralType(params: readonly RillParam[]): RillType;
+export declare function paramsToStructuralType(params: readonly RillParam[]): TypeStructure;
 /**
  * Validate defaultValue type matches declared parameter type.
  *
@@ -154,19 +166,46 @@ export declare function paramsToStructuralType(params: readonly RillParam[]): Ri
  */
 export declare function validateDefaultValueType(param: RillParam, _functionName: string): void;
 /**
- * Validate arguments against RillParam[] using structural type matching.
+ * Options for marshalArgs error reporting.
+ */
+export interface MarshalOptions {
+    /** Function name included in error messages */
+    readonly functionName: string;
+    /** Source location for error reporting */
+    readonly location: SourceLocation | undefined;
+}
+/**
+ * Hydrate missing dict/ordered field-level defaults into a value.
+ *
+ * When a param has type `dict(a: string = "x", b: number)` and the caller
+ * passes `[b: 2]`, this fills in `a` with its default `"x"`. Fields without
+ * defaults are left absent so Stage 3 catches them with RILL-R001.
+ *
+ * Pure function: no class context, no evaluator, no side effects.
+ */
+export declare function hydrateFieldDefaults(value: RillValue, type: TypeStructure): RillValue;
+/**
+ * Unified marshaling entry point for all 3 invocation paths.
+ *
+ * Builds a named argument map from positional args, hydrates defaults,
+ * type-checks each field, and returns a Record<string, RillValue>.
+ *
+ * Stages:
+ * 1. Excess args check (RILL-R045)
+ * 2. Default hydration + missing required check (RILL-R044)
+ * 2.5. Dict/ordered field-level default hydration
+ * 3. Type check per field (RILL-R001)
  *
- * Single validation path for all callable kinds (host, built-in, script).
- * Uses structuralTypeMatches for type checking when param.type is defined.
- * Skips type check when param.type is undefined (any-typed).
- * Applies defaultValue in-place on the args array before validation.
+ * Preconditions (enforced by caller):
+ * - args contains already-evaluated RillValue[]
+ * - pipe value already inserted as first element by caller
+ * - boundDict already prepended as first element by caller
+ * - params is defined (caller skips marshalArgs for untyped callables)
  *
- * @param args - Arguments array (mutated in-place when defaults applied)
+ * @param args - Positional arguments (already evaluated)
  * @param params - Parameter definitions
- * @param functionName - Function name for error messages
- * @param location - Source location for error reporting
- * @throws RuntimeError with RILL-R001 on validation failure
+ * @param options - Error context: functionName and location
+ * @returns Named argument map keyed by param name
  */
-export declare function validateCallableArgs(args: RillValue[], params: readonly RillParam[], functionName: string, location?: SourceLocation): void;
+export declare function marshalArgs(args: RillValue[], params: readonly RillParam[], options?: MarshalOptions): Record<string, RillValue>;
 export {};
-//# sourceMappingURL=callable.d.ts.map

package/dist/runtime/core/callable.js

@@ -17,11 +17,11 @@
  *
  * [ASSUMPTION] validateDefaultValueType _functionName Parameter
  * - Parameter accepted but unused (prefixed with _ to satisfy eslint)
- * - Kept for API consistency with validateCallableArgs signature
+ * - Kept for API consistency with marshalArgs signature
  */
 import { RuntimeError } from '../../types.js';
 import { astEquals } from './equals.js';
-import { formatValue, formatStructuralType, inferType, isTuple, paramToTypeTuple, structuralTypeEquals, structuralTypeMatches, anyTypeValue, } from './values.js';
+import { formatValue, formatStructure, inferType, isOrdered, createOrdered, copyValue, isTuple, paramToFieldDef, structureEquals, structureMatches, anyTypeValue, hasCollectionFields, emptyForType, } from './values.js';
 /** Type guard for any callable */
 export function isCallable(value) {
     return (typeof value === 'object' &&
@@ -61,6 +61,35 @@ export function callable(fn, isProperty = false) {
         isProperty,
     };
 }
+/**
+ * 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 ?? {},
+    };
+}
 /** Type guard for dict (plain object, not array, not callable, not tuple) */
 export function isDict(value) {
     return (typeof value === 'object' &&
@@ -116,14 +145,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 +175,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) => paramToTypeTuple(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,61 +211,180 @@ 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);
+        const expectedType = formatStructure(param.type);
         throw new Error(`Invalid defaultValue for parameter '${param.name}': expected ${expectedType}, got ${actualType}`);
     }
 }
 /**
- * Validate arguments against RillParam[] using structural type matching.
+ * Hydrate missing dict/ordered field-level defaults into a value.
+ *
+ * When a param has type `dict(a: string = "x", b: number)` and the caller
+ * passes `[b: 2]`, this fills in `a` with its default `"x"`. Fields without
+ * defaults are left absent so Stage 3 catches them with RILL-R001.
+ *
+ * Pure function: no class context, no evaluator, no side effects.
+ */
+export function hydrateFieldDefaults(value, type) {
+    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(t.fields)) {
+            if (fieldName in dictValue) {
+                result[fieldName] = hydrateFieldDefaults(dictValue[fieldName], fieldDef.type);
+            }
+            else if (fieldDef.defaultValue !== undefined) {
+                result[fieldName] = hydrateFieldDefaults(copyValue(fieldDef.defaultValue), fieldDef.type);
+            }
+            else if (hasCollectionFields(fieldDef.type)) {
+                result[fieldName] = hydrateFieldDefaults(emptyForType(fieldDef.type), fieldDef.type);
+            }
+            // Missing without default and not collection: leave absent for Stage 3
+        }
+        return result;
+    }
+    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(t.fields.map((f) => f.name ?? ''));
+        const resultEntries = [];
+        for (const field of t.fields) {
+            const name = field.name ?? '';
+            if (lookup.has(name)) {
+                resultEntries.push([
+                    name,
+                    hydrateFieldDefaults(lookup.get(name), field.type),
+                ]);
+            }
+            else if (field.defaultValue !== undefined) {
+                resultEntries.push([
+                    name,
+                    hydrateFieldDefaults(copyValue(field.defaultValue), field.type),
+                ]);
+            }
+            else if (hasCollectionFields(field.type)) {
+                resultEntries.push([
+                    name,
+                    hydrateFieldDefaults(emptyForType(field.type), field.type),
+                ]);
+            }
+            // Missing without default and not collection: leave absent for Stage 3
+        }
+        // Append extra entries not declared in type.fields (structural match allows extras)
+        for (const [k, v] of value.entries) {
+            if (!fieldNames.has(k)) {
+                resultEntries.push([k, v]);
+            }
+        }
+        return createOrdered(resultEntries);
+    }
+    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
+        if (entries.length >= elements.length) {
+            const resultEntries = elements.map((el, i) => hydrateFieldDefaults(entries[i], el.type));
+            // Preserve any extra trailing entries beyond the type definition
+            for (let i = elements.length; i < entries.length; i++) {
+                resultEntries.push(entries[i]);
+            }
+            return { __rill_tuple: true, entries: resultEntries };
+        }
+        // Value shorter: fill missing trailing positions with defaults
+        const resultEntries = [];
+        for (let i = 0; i < elements.length; i++) {
+            const el = elements[i];
+            if (i < entries.length) {
+                resultEntries.push(hydrateFieldDefaults(entries[i], el.type));
+            }
+            else if (el.defaultValue !== undefined) {
+                resultEntries.push(hydrateFieldDefaults(copyValue(el.defaultValue), el.type));
+            }
+            else if (hasCollectionFields(el.type)) {
+                resultEntries.push(hydrateFieldDefaults(emptyForType(el.type), el.type));
+            }
+            // Missing without default and not collection: leave absent (shorter tuple) for Stage 3
+        }
+        return { __rill_tuple: true, entries: resultEntries };
+    }
+    return value;
+}
+/**
+ * Unified marshaling entry point for all 3 invocation paths.
  *
- * Single validation path for all callable kinds (host, built-in, script).
- * Uses structuralTypeMatches for type checking when param.type is defined.
- * Skips type check when param.type is undefined (any-typed).
- * Applies defaultValue in-place on the args array before validation.
+ * Builds a named argument map from positional args, hydrates defaults,
+ * type-checks each field, and returns a Record<string, RillValue>.
  *
- * @param args - Arguments array (mutated in-place when defaults applied)
+ * Stages:
+ * 1. Excess args check (RILL-R045)
+ * 2. Default hydration + missing required check (RILL-R044)
+ * 2.5. Dict/ordered field-level default hydration
+ * 3. Type check per field (RILL-R001)
+ *
+ * Preconditions (enforced by caller):
+ * - args contains already-evaluated RillValue[]
+ * - pipe value already inserted as first element by caller
+ * - boundDict already prepended as first element by caller
+ * - params is defined (caller skips marshalArgs for untyped callables)
+ *
+ * @param args - Positional arguments (already evaluated)
  * @param params - Parameter definitions
- * @param functionName - Function name for error messages
- * @param location - Source location for error reporting
- * @throws RuntimeError with RILL-R001 on validation failure
+ * @param options - Error context: functionName and location
+ * @returns Named argument map keyed by param name
  */
-export function validateCallableArgs(args, params, functionName, location) {
-    // Check for excess arguments
+export function marshalArgs(args, params, options) {
+    const functionName = options?.functionName ?? '<anonymous>';
+    const location = options?.location;
+    // Stage 1: Excess args check
     if (args.length > params.length) {
-        throw new RuntimeError('RILL-R001', `Function '${functionName}' expects ${params.length} arguments, got ${args.length}`, location, {
+        throw new RuntimeError('RILL-R045', `Function expects ${params.length} arguments, got ${args.length}`, location, {
             functionName,
             expectedCount: params.length,
             actualCount: args.length,
         });
     }
-    // Validate each parameter
+    const result = {};
+    // Stage 2 + 3: Hydrate defaults, check required, type-check
     for (let i = 0; i < params.length; i++) {
         const param = params[i];
         if (param === undefined)
             continue;
-        let arg = args[i];
-        // Apply defaultValue in-place for missing arguments
-        if (arg === undefined) {
+        let value = args[i];
+        // Hydrate default when no positional arg was supplied
+        if (value === undefined) {
             if (param.defaultValue !== undefined) {
-                arg = param.defaultValue;
-                args[i] = arg;
+                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 {
-                // Missing required argument
-                throw new RuntimeError('RILL-R001', `Missing required argument '${param.name}' for function '${functionName}'`, location, {
+                // Stage 2: Missing required parameter
+                throw new RuntimeError('RILL-R044', `Missing argument for parameter '${param.name}'`, location, {
                     functionName,
                     paramName: param.name,
                 });
             }
         }
-        // Type check via structuralTypeMatches when param.type is defined
+        // Stage 2.5: Hydrate dict/ordered field-level defaults
+        if (param.type !== undefined) {
+            value = hydrateFieldDefaults(value, param.type);
+        }
+        // Stage 3: Type check when param.type is defined
         if (param.type !== undefined) {
-            if (!structuralTypeMatches(arg, param.type)) {
-                const expectedType = formatStructuralType(param.type);
-                const actualType = inferType(arg);
-                throw new RuntimeError('RILL-R001', `Type mismatch in ${functionName}: parameter '${param.name}' expects ${expectedType}, got ${actualType}`, location, {
+            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,
                     paramName: param.name,
                     expectedType,
@@ -244,6 +392,7 @@ export function validateCallableArgs(args, params, functionName, location) {
                 });
             }
         }
+        result[param.name] = value;
     }
+    return result;
 }
-//# sourceMappingURL=callable.js.map

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

@@ -6,18 +6,7 @@
  */
 import type { RuntimeContext, RuntimeOptions } from './types.js';
 import { type RillValue } from './values.js';
-import { type RillFunction } from './callable.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.
@@ -62,4 +51,3 @@ export declare function pushCallFrame(ctx: RuntimeContext, frame: import('../../
  * Pop frame from call stack after function/closure returns.
  */
 export declare function popCallFrame(ctx: RuntimeContext): void;
-//# sourceMappingURL=context.d.ts.map