@rcrsr/rill 0.16.0 → 0.18.0

package/dist/runtime/core/{types.d.ts → types/runtime.d.ts}

@@ -4,10 +4,10 @@
  * Public types for runtime configuration and execution results.
  * These types are the primary interface for host applications.
  */
-import type { RillTypeName } from '../../types.js';
-import type { CallableFn, RillFunction } from './callable.js';
-import type { RillType, RillValue } from './values.js';
-export type { NativeArray, NativePlainObject, NativeValue } from './values.js';
+import type { RillTypeName } from '../../../types.js';
+import type { CallableFn, RillFunction } from '../callable.js';
+import type { TypeStructure, RillValue } from './structures.js';
+export type { NativeArray, NativePlainObject, NativeValue } from '../values.js';
 /** I/O callbacks for runtime operations */
 export interface RuntimeCallbacks {
     /** Called when .log is invoked */
@@ -119,9 +119,9 @@ 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>;
+    readonly functions: Map<string, CallableFn | import('../callable.js').ApplicationCallable>;
     /** I/O callbacks */
     readonly callbacks: RuntimeCallbacks;
     /** Observability callbacks */
@@ -152,15 +152,27 @@ export interface RuntimeContext {
      * Call stack for error context.
      * Managed by evaluator; pushed on function entry, popped on exit.
      */
-    readonly callStack: import('../../types.js').CallFrame[];
+    readonly callStack: import('../../../types.js').CallFrame[];
     /** Arbitrary string metadata passed from the host (e.g. request IDs, user IDs) */
     readonly metadata?: Record<string, string> | undefined;
     /**
      * 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) */
@@ -172,7 +184,7 @@ export interface RuntimeContext {
      * Must be provided when `kind: 'source'` resolver results are expected.
      * Omit if only `kind: 'value'` resolvers are used.
      */
-    readonly parseSource?: ((text: string) => import('../../types.js').ScriptNode) | undefined;
+    readonly parseSource?: ((text: string) => import('../../../types.js').ScriptNode) | undefined;
     /** Identifies the current source file for cross-module error reporting */
     readonly sourceId?: string | undefined;
     /** Source text of the current file for cross-module error snippets */
@@ -212,7 +224,7 @@ export interface RuntimeOptions {
      * Parser function for executing resolver source results.
      * Required when resolvers may return `kind: 'source'` results.
      */
-    parseSource?: (text: string) => import('../../types.js').ScriptNode;
+    parseSource?: (text: string) => import('../../../types.js').ScriptNode;
 }
 /** Result of script execution */
 export interface ExecutionResult {

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

@@ -0,0 +1,146 @@
+/**
+ * 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 13 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: 'stream';
+    chunk?: TypeStructure;
+    ret?: TypeStructure;
+} | {
+    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;
+}
+/**
+ * Stream type - represents an async lazy sequence with resolution.
+ * A stream is a dict with:
+ * - __rill_stream: true - discriminator for stream detection
+ * - done: boolean - whether all chunks have been consumed
+ * - next: callable - function to advance to the next stream step
+ * - value?: any - current chunk value (present when done is false)
+ */
+export interface RillStream extends Record<string, RillValue> {
+    readonly __rill_stream: true;
+    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 | RillStream;

package/dist/runtime/core/types/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/values.d.ts

@@ -3,166 +3,27 @@
  *
  * 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.
- * 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;
-}
-/**
- * Field definition - describes a single field in a structural type.
- * Used by dict, tuple, ordered, and closure type descriptors.
- * Default detection: `field.defaultValue !== undefined`.
- */
-export interface RillFieldDef {
-    name?: string;
-    type: RillType;
-    defaultValue?: RillValue;
-}
-/**
- * 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, RillFieldDef>;
-    valueType?: RillType;
-} | {
-    type: 'list';
-    element?: RillType;
-} | {
-    type: 'closure';
-    params?: RillFieldDef[];
-    ret?: RillType;
-} | {
-    type: 'tuple';
-    elements?: RillFieldDef[];
-    valueType?: RillType;
-} | {
-    type: 'ordered';
-    fields?: RillFieldDef[];
-    valueType?: RillType;
-} | {
-    type: 'union';
-    members: RillType[];
-};
-/**
- * @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;
-/** Type guard for RillTuple (spread args) */
-export declare function isTuple(value: RillValue): value is RillTuple;
-/** Type guard for RillVector */
-export declare function isVector(value: RillValue): value is RillVector;
-/** Type guard for RillOrdered (named spread args) */
-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).
- * 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;
-/**
- * Create vector from Float32Array with model name.
- * @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 element type for a homogeneous list.
- * Empty arrays return { type: 'any' }.
- * Mixed types throw RILL-R002.
- */
-export declare function inferElementType(elements: RillValue[]): RillType;
-/**
- * Return the most specific shared type for two RillType values.
- * Returns null when types are incompatible at the top level.
+ * Structural operations (structureEquals, structureMatches, formatStructure,
+ * inferStructure, commonType) live in types/operations.ts and are re-exported.
  *
- * Cascade priority:
- * 1. Any-narrowing: if either side is `any`, return the other
- * 2. Structural match: delegate to structuralTypeEquals; 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: RillType, b: RillType): RillType | null;
-/** Compare two structural types for equality. */
-export declare function structuralTypeEquals(a: RillType, b: RillType): boolean;
-/** Infer the structural type descriptor for any Rill value. */
-export declare function inferStructuralType(value: RillValue): RillType;
-/**
- * Check if a value matches a structural type descriptor.
- * Used for runtime type checking (`:?` operator).
+ * Dispatch functions (inferType, formatValue, deepEquals, serializeValue,
+ * copyValue) re-export from type-registrations.ts protocol implementations.
  */
-export declare function structuralTypeMatches(value: RillValue, type: RillType): boolean;
-/** Build a closure param field definition from name, type, and optional default. */
-export declare function paramToFieldDef(name: string, type: RillType, defaultValue: RillValue | undefined): RillFieldDef;
-/** Format a structural type descriptor as a human-readable string. */
-export declare function formatStructuralType(type: RillType): string;
+import type { RillTypeName } from '../../types.js';
+import type { RillCallable } from './callable.js';
+import { isDict, isIterator, isOrdered, isStream, isTuple, isTypeValue, isVector } from './types/guards.js';
+/** isCallable guard widened to narrow to full RillCallable (not just CallableMarker) */
+declare const isCallable: (value: RillValue) => value is RillCallable;
+import type { RillFieldDef, RillIterator, RillOrdered, RillTuple, RillTypeValue, RillValue, RillVector, TypeStructure } from './types/structures.js';
+export type { RillFieldDef, RillIterator, RillOrdered, RillTuple, RillTypeValue, RillValue, RillVector, TypeStructure, };
+export type { DictStructure, TupleStructure, OrderedStructure, } from './types/operations.js';
+export { isCallable, isDict, isIterator, isOrdered, isStream, isTuple, isTypeValue, isVector, };
+export { copyValue, createOrdered, createTuple, createVector, emptyForType, } from './types/constructors.js';
+export { commonType, compareStructuredFields, formatStructure, inferElementType, inferStructure, paramToFieldDef, structureEquals, structureMatches, } from './types/operations.js';
+export type { FieldComparisonCallbacks } from './types/operations.js';
+/** Infer the Rill type from a runtime value. Delegates to type-registrations. */
+export declare const inferType: (value: RillValue) => string;
 /**
  * Check if a value is of the expected type.
  * Returns true if the value matches the expected type, false otherwise.
@@ -172,8 +33,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.
@@ -187,31 +48,23 @@ 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;
 /**
  * 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"];
 /**
@@ -220,49 +73,16 @@ 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;
+export declare function structureToTypeValue(type: TypeStructure): RillTypeValue;
 /**
  * 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 declare function hasCollectionFields(type: RillType): boolean;
-/**
- * Create an empty collection value matching the given RillType.
- * Assumes the type is dict, ordered, or tuple.
- */
-export declare function emptyForType(type: RillType): RillValue;
+export declare function hasCollectionFields(type: TypeStructure): boolean;
 /** Check if a key name is reserved */
 export declare function isReservedMethod(name: string): boolean;
-/**
- * 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
- */
-export interface RillIterator extends Record<string, RillValue> {
-    readonly done: boolean;
-    readonly next: CallableMarker;
-    readonly value?: RillValue;
-}
-/**
- * Type guard for Rill iterator (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
- */
-export declare function isRillIterator(value: RillValue): value is RillIterator;
-/**
- * Deep copy a RillValue, producing a new independent value.
- * Handles primitives, arrays, plain dicts, and null.
- * Special markers (closures, tuples, ordered, vectors, type values) are returned
- * as-is since they are immutable by contract.
- */
-export declare function deepCopyRillValue(value: RillValue): RillValue;
-export {};