@rcrsr/rill 0.15.0 → 0.17.0

package/dist/runtime/core/type-structures.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Type Structure Definitions
+ *
+ * Defines the TypeStructure union (discriminated by `.kind`) and
+ * associated value interfaces. These types form the foundation for
+ * the type registration and dispatch system.
+ *
+ * The TypeStructure union mirrors the existing RillType union but uses
+ * `.kind` as its discriminator instead of `.type`, enabling future
+ * coexistence during migration.
+ */
+import type { RillTypeName } from '../../types.js';
+import type { CallableMarker, FieldDescriptorMarker } from './markers.js';
+/**
+ * Field definition - describes a single field in a structural type.
+ * Used by dict, tuple, ordered, and closure type descriptors.
+ * Default detection: `field.defaultValue !== undefined`.
+ *
+ * Uses TypeStructure (not RillType) for the field's type descriptor.
+ */
+export interface RillFieldDef {
+    name?: string | undefined;
+    type: TypeStructure;
+    defaultValue?: RillValue | undefined;
+}
+/**
+ * Structural type descriptor - describes the shape of a value in the type system.
+ * Discriminated by `.kind` (not `.type`).
+ *
+ * Includes all 12 built-in variants plus a catch-all for types without
+ * parameterized structure (e.g. iterator).
+ */
+export type TypeStructure = {
+    kind: 'number';
+} | {
+    kind: 'string';
+} | {
+    kind: 'bool';
+} | {
+    kind: 'vector';
+} | {
+    kind: 'type';
+} | {
+    kind: 'any';
+} | {
+    kind: 'dict';
+    fields?: Record<string, RillFieldDef> | undefined;
+    valueType?: TypeStructure | undefined;
+} | {
+    kind: 'list';
+    element?: TypeStructure | undefined;
+} | {
+    kind: 'closure';
+    params?: RillFieldDef[] | undefined;
+    ret?: TypeStructure | undefined;
+} | {
+    kind: 'tuple';
+    elements?: RillFieldDef[] | undefined;
+    valueType?: TypeStructure | undefined;
+} | {
+    kind: 'ordered';
+    fields?: RillFieldDef[] | undefined;
+    valueType?: TypeStructure | undefined;
+} | {
+    kind: 'union';
+    members: TypeStructure[];
+} | {
+    kind: 'iterator';
+} | {
+    kind: string;
+    data?: unknown;
+};
+/**
+ * Tuple type - represents positional unpacked arguments for closure invocation.
+ * Created by the * (spread) operator from lists.
+ * Entries are positional only.
+ *
+ * Note: In Rill, "tuple" refers to fixed-size argument packing (like function signatures),
+ * while "list" refers to dynamic ordered collections ([1, 2, 3]).
+ */
+export interface RillTuple {
+    readonly __rill_tuple: true;
+    readonly entries: RillValue[];
+}
+/**
+ * Ordered type - represents named key-value pairs with preserved insertion order.
+ * Created by the * (spread) operator from dicts.
+ * Entries may carry an optional third element (default value) when representing
+ * closure parameter reflection via `.^input`.
+ */
+export interface RillOrdered {
+    readonly __rill_ordered: true;
+    readonly entries: [string, RillValue, RillValue?][];
+}
+/**
+ * Vector type - represents dense numeric embeddings.
+ * Immutable Float32Array with associated model name.
+ */
+export interface RillVector {
+    readonly __rill_vector: true;
+    readonly data: Float32Array;
+    readonly model: string;
+}
+/**
+ * Type value - represents a first-class type name at runtime.
+ * Created when a type name expression (e.g. `string`, `number`) is evaluated.
+ */
+export interface RillTypeValue {
+    readonly __rill_type: true;
+    readonly typeName: RillTypeName;
+    readonly structure: TypeStructure;
+}
+/**
+ * Iterator type - represents a lazy sequence.
+ * An iterator is a dict with:
+ * - done: boolean - whether iteration is complete
+ * - next: callable - function to get next iterator
+ * - value?: any - current value (absent when done)
+ */
+export interface RillIterator extends Record<string, RillValue> {
+    readonly done: boolean;
+    readonly next: CallableMarker;
+    readonly value?: RillValue;
+}
+/** Any value that can flow through Rill */
+export type RillValue = string | number | boolean | null | RillValue[] | {
+    [key: string]: RillValue;
+} | CallableMarker | RillTuple | RillOrdered | RillVector | FieldDescriptorMarker | RillTypeValue;

package/dist/runtime/core/type-structures.js

@@ -0,0 +1,12 @@
+/**
+ * Type Structure Definitions
+ *
+ * Defines the TypeStructure union (discriminated by `.kind`) and
+ * associated value interfaces. These types form the foundation for
+ * the type registration and dispatch system.
+ *
+ * The TypeStructure union mirrors the existing RillType union but uses
+ * `.kind` as its discriminator instead of `.type`, enabling future
+ * coexistence during migration.
+ */
+export {};

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

@@ -6,7 +6,7 @@
  */
 import type { RillTypeName } from '../../types.js';
 import type { CallableFn, RillFunction } from './callable.js';
-import type { RillType, RillValue } from './values.js';
+import type { TypeStructure, RillValue } from './values.js';
 export type { NativeArray, NativePlainObject, NativeValue } from './values.js';
 /** I/O callbacks for runtime operations */
 export interface RuntimeCallbacks {
@@ -119,7 +119,7 @@ export interface RuntimeContext {
     /** Named variables ($varname) - local to this scope */
     readonly variables: Map<string, RillValue>;
     /** Variable types - locked after first assignment (local to this scope) */
-    readonly variableTypes: Map<string, RillTypeName | RillType>;
+    readonly variableTypes: Map<string, RillTypeName | TypeStructure>;
     /** Built-in and user-defined functions (CallableFn for untyped, ApplicationCallable for typed) */
     readonly functions: Map<string, CallableFn | import('./callable.js').ApplicationCallable>;
     /** I/O callbacks */
@@ -158,9 +158,21 @@ export interface RuntimeContext {
     /**
      * Per-type method dictionaries: maps type name to a frozen dict of ApplicationCallable values.
      * Keys: "string", "list", "dict", "number", "bool", "vector".
-     * Populated at context creation from BUILTIN_METHODS; propagated to child contexts.
+     * Populated at context creation from type registrations; propagated to child contexts.
      */
     readonly typeMethodDicts: ReadonlyMap<string, Readonly<Record<string, RillValue>>>;
+    /**
+     * Type names that reject type arguments in type constructors.
+     * Derived from BUILT_IN_TYPES registrations where isLeaf === true, plus 'any'.
+     * Used by type assertion/check evaluation to reject e.g. string(number).
+     */
+    readonly leafTypes: ReadonlySet<string>;
+    /**
+     * Method names that handle their own receiver type checking with specific
+     * error messages. Generic RILL-R003 must not fire before the method body runs.
+     * Derived from registration method dicts at context creation.
+     */
+    readonly unvalidatedMethodReceivers: ReadonlySet<string>;
     /** Scheme-to-resolver map, populated from RuntimeOptions.resolvers (empty Map when absent) */
     readonly resolvers: ReadonlyMap<string, SchemeResolver>;
     /** Per-scheme config data, populated from RuntimeOptions.configurations.resolvers (empty Map when absent) */
@@ -255,4 +267,3 @@ export interface ExecutionStepper {
  * This sets boundDict on each callable so they can access their container.
  */
 export declare function bindDictCallables(value: RillValue): RillValue;
-//# sourceMappingURL=types.d.ts.map

package/dist/runtime/core/types.js

@@ -47,4 +47,3 @@ export function bindDictCallables(value) {
     }
     return result;
 }
-//# sourceMappingURL=types.js.map

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

@@ -3,112 +3,30 @@
  *
  * Core value types that flow through Rill programs.
  * Public API for host applications.
- */
-import type { RillTypeName } from '../../types.js';
-interface CallableMarker {
-    readonly __type: 'callable';
-}
-interface FieldDescriptorMarker {
-    readonly __rill_field_descriptor: true;
-}
-/**
- * Tuple type - represents positional unpacked arguments for closure invocation.
- * Created by the * (spread) operator from lists.
- * Entries are positional only.
  *
- * Note: In Rill, "tuple" refers to fixed-size argument packing (like function signatures),
- * while "list" refers to dynamic ordered collections ([1, 2, 3]).
- */
-export interface RillTuple {
-    readonly __rill_tuple: true;
-    readonly entries: RillValue[];
-}
-/**
- * Ordered type - represents named key-value pairs with preserved insertion order.
- * Created by the * (spread) operator from dicts.
- */
-export interface RillOrdered {
-    readonly __rill_ordered: true;
-    readonly entries: [string, RillValue][];
-}
-/**
- * Vector type - represents dense numeric embeddings.
- * Immutable Float32Array with associated model name.
+ * Dispatch functions (inferType, formatValue, deepEquals, serializeValue,
+ * copyValue) re-export from type-registrations.ts protocol implementations.
  */
-export interface RillVector {
-    readonly __rill_vector: true;
-    readonly data: Float32Array;
-    readonly model: string;
-}
-/**
- * Structural type descriptor - describes the shape of a value in the type system.
- * Used by RillTypeValue to carry type structure information at runtime.
- */
-export type RillType = {
-    type: 'number';
-} | {
-    type: 'string';
-} | {
-    type: 'bool';
-} | {
-    type: 'vector';
-} | {
-    type: 'type';
-} | {
-    type: 'any';
-} | {
-    type: 'dict';
-    fields?: Record<string, RillFieldType>;
-} | {
-    type: 'list';
-    element?: RillType;
-} | {
-    type: 'closure';
-    params?: [string, RillType, RillValue?][];
-    ret?: RillType;
-} | {
-    type: 'tuple';
-    elements?: [RillType, RillValue?][];
-} | {
-    type: 'ordered';
-    fields?: [string, RillType, RillValue?][];
-} | {
-    type: 'union';
-    members: RillType[];
+import type { RillTypeName } from '../../types.js';
+import type { RillFieldDef, RillIterator, RillOrdered, RillTuple, RillTypeValue, RillValue, RillVector, TypeStructure } from './type-structures.js';
+export type { RillFieldDef, RillIterator, RillOrdered, RillTuple, RillTypeValue, RillValue, RillVector, TypeStructure, };
+export type DictStructure = {
+    kind: 'dict';
+    fields?: Record<string, RillFieldDef>;
+    valueType?: TypeStructure;
 };
-/**
- * Dict field type - either a plain RillType or a RillType paired with a default value.
- * Used in dict structural types to carry optional default values per field.
- */
-export type RillFieldType = RillType | {
-    type: RillType;
-    defaultValue: RillValue;
+export type TupleStructure = {
+    kind: 'tuple';
+    elements?: RillFieldDef[];
+    valueType?: TypeStructure;
 };
-/**
- * Type guard to distinguish the `{ type, defaultValue }` form of RillFieldType
- * from a plain RillType.
- */
-export declare function isFieldTypeWithDefault(fieldType: RillFieldType): fieldType is {
-    type: RillType;
-    defaultValue: RillValue;
+export type OrderedStructure = {
+    kind: 'ordered';
+    fields?: RillFieldDef[];
+    valueType?: TypeStructure;
 };
-/**
- * @deprecated Use RillType instead. Will be removed in the next major version.
- */
-export type RillStructuralType = RillType;
-/**
- * Type value - represents a first-class type name at runtime.
- * Created when a type name expression (e.g. `string`, `number`) is evaluated.
- */
-export interface RillTypeValue {
-    readonly __rill_type: true;
-    readonly typeName: RillTypeName;
-    readonly structure: RillType;
-}
-/** Any value that can flow through Rill */
-export type RillValue = string | number | boolean | null | RillValue[] | {
-    [key: string]: RillValue;
-} | CallableMarker | RillTuple | RillOrdered | RillVector | FieldDescriptorMarker | RillTypeValue;
+/** @deprecated Use TypeStructure instead. */
+export type RillType = TypeStructure;
 /** Type guard for RillTuple (spread args) */
 export declare function isTuple(value: RillValue): value is RillTuple;
 /** Type guard for RillVector */
@@ -117,8 +35,12 @@ export declare function isVector(value: RillValue): value is RillVector;
 export declare function isOrdered(value: RillValue): value is RillOrdered;
 /** Type guard for RillTypeValue */
 export declare function isTypeValue(value: RillValue): value is RillTypeValue;
-/** Create ordered from entries array (named, preserves insertion order) */
-export declare function createOrdered(entries: [string, RillValue][]): RillOrdered;
+/**
+ * Create ordered from entries array (named, preserves insertion order).
+ * Entries may be 2-element [name, value] or 3-element [name, value, default]
+ * tuples; the third element carries a default value for `.^input` reflection.
+ */
+export declare function createOrdered(entries: [string, RillValue, RillValue?][]): RillOrdered;
 /** Create tuple from entries array (positional, preserves order) */
 export declare function createTuple(entries: RillValue[]): RillTuple;
 /**
@@ -126,27 +48,48 @@ export declare function createTuple(entries: RillValue[]): RillTuple;
  * @throws {Error} if data.length is 0 (zero-dimension vectors not allowed)
  */
 export declare function createVector(data: Float32Array, model: string): RillVector;
-/** Infer the Rill type from a runtime value */
-export declare function inferType(value: RillValue): RillTypeName;
+/** Infer the Rill type from a runtime value. Delegates to type-registrations. */
+export declare const inferType: (value: RillValue) => string;
 /**
  * Infer the element type for a homogeneous list.
- * Empty arrays return { type: 'any' }.
+ * Empty arrays return { kind: 'any' }.
  * Mixed types throw RILL-R002.
  */
-export declare function inferElementType(elements: RillValue[]): RillType;
+export declare function inferElementType(elements: RillValue[]): TypeStructure;
+/**
+ * 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 declare function commonType(a: TypeStructure, b: TypeStructure): TypeStructure | null;
 /** Compare two structural types for equality. */
-export declare function structuralTypeEquals(a: RillType, b: RillType): boolean;
+export declare function structureEquals(a: TypeStructure, b: TypeStructure): boolean;
+/** @deprecated Use structureEquals instead. */
+export declare const structuralTypeEquals: typeof structureEquals;
 /** Infer the structural type descriptor for any Rill value. */
-export declare function inferStructuralType(value: RillValue): RillType;
+export declare function inferStructure(value: RillValue): TypeStructure;
+/** @deprecated Use inferStructure instead. */
+export declare const inferStructuralType: typeof inferStructure;
 /**
  * Check if a value matches a structural type descriptor.
  * Used for runtime type checking (`:?` operator).
  */
-export declare function structuralTypeMatches(value: RillValue, type: RillType): boolean;
-/** Build a closure param tuple, omitting the optional third element when no default. */
-export declare function paramToTypeTuple(name: string, type: RillType, defaultValue: RillValue | undefined): [string, RillType, RillValue?];
+export declare function structureMatches(value: RillValue, type: TypeStructure): boolean;
+/** @deprecated Use structureMatches instead. */
+export declare const structuralTypeMatches: typeof structureMatches;
+/** Build a closure param field definition from name, type, and optional default. */
+export declare function paramToFieldDef(name: string, type: TypeStructure, defaultValue: RillValue | undefined): RillFieldDef;
 /** Format a structural type descriptor as a human-readable string. */
-export declare function formatStructuralType(type: RillType): string;
+export declare function formatStructure(type: TypeStructure): string;
+/** @deprecated Use formatStructure instead. */
+export declare const formatStructuralType: typeof formatStructure;
 /**
  * Check if a value is of the expected type.
  * Returns true if the value matches the expected type, false otherwise.
@@ -156,8 +99,8 @@ export declare function checkType(value: RillValue, expected: RillTypeName): boo
 export declare function isTruthy(value: RillValue): boolean;
 /** Check if a value is empty (inverse of truthy) */
 export declare function isEmpty(value: RillValue): boolean;
-/** Format a value for display */
-export declare function formatValue(value: RillValue): string;
+/** Format a value for display. Delegates to type-registrations. */
+export declare const formatValue: (value: RillValue) => string;
 /**
  * Recursive native (host-side) value type.
  * Represents values that can cross the host/script boundary.
@@ -171,31 +114,25 @@ export type NativePlainObject = {
 };
 /** Structured result from toNative conversion */
 export interface NativeResult {
-    /** Rill type name — matches RillTypeName, or 'iterator' for lazy sequences */
+    /** Rill type name -- matches RillTypeName, or 'iterator' for lazy sequences */
     rillTypeName: string;
     /** Human-readable type signature, e.g. "string", "list(number)", "|x: number| :string" */
     rillTypeSignature: string;
     /** Native JS representation. Non-native types produce descriptor objects. */
     value: NativeValue;
 }
-/**
- * Convert a RillValue to a JSON-serializable value.
- * @throws {Error} plain Error (not RuntimeError) for non-serializable types
- */
-export declare function valueToJSON(value: RillValue): unknown;
+/** Serialize a Rill value for JSON transport. Delegates to type-registrations. */
+export declare const serializeValue: (value: RillValue) => unknown;
+/** @deprecated Use serializeValue instead. */
+export declare const valueToJSON: (value: RillValue) => unknown;
 /**
  * Convert a RillValue to a NativeResult for host consumption.
  * Non-representable types (closures, vectors, type values, iterators) produce descriptor objects.
  * Tuples convert to native arrays. Ordered values convert to plain objects.
  */
 export declare function toNative(value: RillValue): NativeResult;
-/**
- * Deep structural equality for all Rill values.
- * - Primitives: value equality
- * - Tuples: length + recursive element equality
- * - Dicts: same keys + recursive value equality (order-independent)
- */
-export declare function deepEquals(a: RillValue, b: RillValue): boolean;
+/** Deep structural equality for all Rill values. Delegates to type-registrations. */
+export declare const deepEquals: (a: RillValue, b: RillValue) => boolean;
 /** Reserved dict method names that cannot be overridden */
 export declare const RESERVED_DICT_METHODS: readonly ["keys", "values", "entries"];
 /**
@@ -204,25 +141,26 @@ export declare const RESERVED_DICT_METHODS: readonly ["keys", "values", "entries
  */
 export declare const anyTypeValue: RillTypeValue;
 /**
- * Convert a RillType structural descriptor to a RillTypeValue.
- * Uses the RillType's `type` field as the `typeName`.
+ * Convert a TypeStructure descriptor to a RillTypeValue.
+ * Uses the TypeStructure's `kind` field as the `typeName`.
  * Falls back to 'any' for compound types that lack a direct RillTypeName mapping.
  */
-export declare function rillTypeToTypeValue(type: RillType): RillTypeValue;
-/** Check if a key name is reserved */
-export declare function isReservedMethod(name: string): boolean;
+export declare function structureToTypeValue(type: TypeStructure): RillTypeValue;
+/** @deprecated Use structureToTypeValue instead. */
+export declare const rillTypeToTypeValue: typeof structureToTypeValue;
 /**
- * Iterator type - represents a lazy sequence.
- * An iterator is a dict with:
- * - done: boolean - whether iteration is complete
- * - next: callable - function to get next iterator
- * - value: any (only required when not done) - current element
+ * Check if a type is a collection (dict, ordered, tuple) with defined
+ * fields or elements. Used to decide if an empty collection can be
+ * synthesized and hydrated.
  */
-export interface RillIterator extends Record<string, RillValue> {
-    readonly done: boolean;
-    readonly next: CallableMarker;
-    readonly value?: RillValue;
-}
+export declare function hasCollectionFields(type: TypeStructure): boolean;
+/**
+ * Create an empty collection value matching the given TypeStructure.
+ * Assumes the type is dict, ordered, or tuple.
+ */
+export declare function emptyForType(type: TypeStructure): RillValue;
+/** Check if a key name is reserved */
+export declare function isReservedMethod(name: string): boolean;
 /**
  * Type guard for Rill iterator (lazy sequence).
  * An iterator is a dict with:
@@ -230,6 +168,10 @@ export interface RillIterator extends Record<string, RillValue> {
  * - next: callable - function to get next iterator
  * - value: any (only required when not done) - current element
  */
-export declare function isRillIterator(value: RillValue): value is RillIterator;
-export {};
-//# sourceMappingURL=values.d.ts.map
+export declare function isIterator(value: RillValue): value is RillIterator;
+/** @deprecated Use isIterator instead. */
+export declare const isRillIterator: typeof isIterator;
+/** Copy a RillValue. Delegates to type-registrations. */
+export declare const copyValue: (value: RillValue) => RillValue;
+/** @deprecated Use copyValue instead. */
+export declare const deepCopyRillValue: (value: RillValue) => RillValue;