@rcrsr/rill 0.16.0 → 0.18.0

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

@@ -0,0 +1,201 @@
+/**
+ * Value Constructors
+ *
+ * Factory functions for creating Rill compound values (tuples, ordered,
+ * vectors) and collection utilities (emptyForType, copyValue).
+ *
+ * Import constraints:
+ * - Imports from ./structures.js and ./guards.js
+ * - No imports from values.ts or callable.ts
+ */
+import { isCallable, isIterator, isOrdered, isStream, isTuple, isTypeValue, isVector, } from './guards.js';
+import { callable } from '../callable.js';
+import { RuntimeError } from '../../../types.js';
+/**
+ * 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 function createOrdered(entries) {
+    return Object.freeze({ __rill_ordered: true, entries: [...entries] });
+}
+/** Create tuple from entries array (positional, preserves order) */
+export function createTuple(entries) {
+    return Object.freeze({ __rill_tuple: true, entries: [...entries] });
+}
+/**
+ * Create vector from Float32Array with model name.
+ * @throws {RuntimeError} RILL-R074 if data.length is 0 (zero-dimension vectors not allowed)
+ */
+export function createVector(data, model) {
+    if (data.length === 0) {
+        throw new RuntimeError('RILL-R074', 'Vector data must have at least one dimension');
+    }
+    return { __rill_vector: true, data, model };
+}
+/**
+ * Create an empty collection value matching the given TypeStructure.
+ * Assumes the type is dict, ordered, or tuple.
+ */
+export function emptyForType(type) {
+    if (type.kind === 'dict')
+        return {};
+    if (type.kind === 'ordered')
+        return createOrdered([]);
+    if (type.kind === 'tuple')
+        return createTuple([]);
+    return {};
+}
+/**
+ * Create a RillStream from an AsyncIterable of chunks and a resolve function.
+ *
+ * The stream is a linked-list of steps. Each `.next` call advances to the
+ * next chunk. Once exhausted, `done` becomes true and re-iteration throws
+ * RILL-R002. The `resolve` function is called after chunk exhaustion (or on
+ * direct invocation) and caches its result for idempotent access.
+ *
+ * @throws {RuntimeError} RILL-R003 if chunks is not an AsyncIterable
+ * @throws {RuntimeError} RILL-R003 if resolve is not a function
+ */
+export function createRillStream(options) {
+    const { chunks, resolve, dispose, chunkType, retType } = options;
+    // Validate chunks is AsyncIterable
+    if (chunks === null ||
+        chunks === undefined ||
+        typeof chunks[Symbol.asyncIterator] !==
+            'function') {
+        throw new RuntimeError('RILL-R003', 'createRillStream requires AsyncIterable chunks');
+    }
+    // Validate resolve is a function
+    if (typeof resolve !== 'function') {
+        throw new RuntimeError('RILL-R003', 'createRillStream requires resolve function');
+    }
+    const iterator = chunks[Symbol.asyncIterator]();
+    let exhausted = false;
+    let disposed = false;
+    let cachedResolution;
+    /** Idempotent resolve wrapper that caches the resolution value. */
+    async function resolveOnce() {
+        if (cachedResolution !== undefined)
+            return cachedResolution.value;
+        const value = await resolve();
+        cachedResolution = { value };
+        return value;
+    }
+    /** Build a stream step from an iterator result. */
+    function makeStep(iterResult) {
+        if (iterResult.done) {
+            exhausted = true;
+            if (!disposed && dispose) {
+                disposed = true;
+                dispose();
+            }
+            const doneStep = {
+                __rill_stream: true,
+                done: true,
+                next: callable(() => {
+                    throw new RuntimeError('RILL-R002', 'Stream already consumed; cannot re-iterate');
+                }),
+            };
+            return doneStep;
+        }
+        let stale = false;
+        const step = {
+            __rill_stream: true,
+            done: false,
+            value: iterResult.value,
+            next: callable(async () => {
+                if (stale) {
+                    throw new RuntimeError('RILL-R002', 'Stream already consumed; cannot re-iterate');
+                }
+                if (exhausted) {
+                    throw new RuntimeError('RILL-R002', 'Stream already consumed; cannot re-iterate');
+                }
+                stale = true;
+                const next = await iterator.next();
+                return makeStep(next);
+            }),
+        };
+        return step;
+    }
+    // Build initial step: eagerly fetch the first chunk
+    // The stream object itself is a "pending" step that advances on first .next call
+    let initialized = false;
+    const stream = {
+        __rill_stream: true,
+        done: false,
+        next: callable(async () => {
+            if (initialized) {
+                throw new RuntimeError('RILL-R002', 'Stream already consumed; cannot re-iterate');
+            }
+            initialized = true;
+            const first = await iterator.next();
+            return makeStep(first);
+        }),
+    };
+    // Attach resolve as a hidden property for runtime access
+    Object.defineProperty(stream, '__rill_stream_resolve', {
+        value: resolveOnce,
+        enumerable: false,
+    });
+    if (dispose) {
+        Object.defineProperty(stream, '__rill_stream_dispose', {
+            value: () => {
+                if (!disposed) {
+                    disposed = true;
+                    dispose();
+                }
+            },
+            enumerable: false,
+        });
+    }
+    if (chunkType) {
+        Object.defineProperty(stream, '__rill_stream_chunk_type', {
+            value: chunkType,
+            enumerable: false,
+        });
+    }
+    if (retType) {
+        Object.defineProperty(stream, '__rill_stream_ret_type', {
+            value: retType,
+            enumerable: false,
+        });
+    }
+    return stream;
+}
+/**
+ * Copy a RillValue.
+ * Primitives and immutable compound values return the same reference.
+ * Mutable values (list, dict) copy recursively.
+ * Iterators return the same reference (not meaningfully copyable).
+ */
+export function copyValue(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    // Immutable compound types
+    if (isTuple(value) ||
+        isOrdered(value) ||
+        isVector(value) ||
+        isTypeValue(value) ||
+        isCallable(value))
+        return value;
+    // field_descriptor: immutable (no guard exported from guards.ts)
+    if ('__rill_field_descriptor' in value &&
+        value['__rill_field_descriptor'] === true)
+        return value;
+    // Mutable list (Array but not tuple/ordered — those were checked above)
+    if (Array.isArray(value))
+        return value.map(copyValue);
+    // Iterator: mutable but opaque — return same reference
+    if (isIterator(value))
+        return value;
+    // Stream: immutable — return same reference
+    if (isStream(value))
+        return value;
+    // Mutable dict
+    const dict = value;
+    const copy = {};
+    for (const [k, v] of Object.entries(dict))
+        copy[k] = copyValue(v);
+    return copy;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Type Guards
+ *
+ * Centralized type guard functions for all Rill value types.
+ * Extracted from values.ts and callable.ts to break the circular
+ * dependency between those modules.
+ *
+ * Import constraints:
+ * - Imports ONLY from ./markers.js and ./structures.js
+ * - No imports from values.ts or callable.ts
+ */
+import type { CallableMarker } from './markers.js';
+import type { RillIterator, RillOrdered, RillStream, RillTuple, RillTypeValue, RillValue, RillVector } from './structures.js';
+/** 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;
+/** Type guard for any callable */
+export declare function isCallable(value: RillValue): value is CallableMarker;
+/** Type guard for dict (plain object, not array, not callable, not tuple) */
+export declare function isDict(value: RillValue): value is Record<string, RillValue>;
+/**
+ * Type guard for RillStream (async lazy sequence with resolution).
+ * A stream has the __rill_stream discriminator set to true.
+ * Must precede isIterator in dispatch order because streams
+ * satisfy the iterator structural shape.
+ */
+export declare function isStream(value: RillValue): value is RillStream;
+/** Public API alias for isStream */
+export declare const isRillStream: (value: RillValue) => value is RillStream;
+/**
+ * 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 isIterator(value: RillValue): value is RillIterator;

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

@@ -0,0 +1,88 @@
+/**
+ * Type Guards
+ *
+ * Centralized type guard functions for all Rill value types.
+ * Extracted from values.ts and callable.ts to break the circular
+ * dependency between those modules.
+ *
+ * Import constraints:
+ * - Imports ONLY from ./markers.js and ./structures.js
+ * - No imports from values.ts or callable.ts
+ */
+/** Type guard for RillTuple (spread args) */
+export function isTuple(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_tuple' in value &&
+        value.__rill_tuple === true);
+}
+/** Type guard for RillVector */
+export function isVector(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_vector' in value &&
+        value.__rill_vector === true);
+}
+/** Type guard for RillOrdered (named spread args) */
+export function isOrdered(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_ordered' in value &&
+        value.__rill_ordered === true);
+}
+/** Type guard for RillTypeValue */
+export function isTypeValue(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_type' in value &&
+        value.__rill_type === true);
+}
+/** Type guard for any callable */
+export function isCallable(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__type' in value &&
+        value.__type === 'callable');
+}
+/** 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));
+}
+/**
+ * Type guard for RillStream (async lazy sequence with resolution).
+ * A stream has the __rill_stream discriminator set to true.
+ * Must precede isIterator in dispatch order because streams
+ * satisfy the iterator structural shape.
+ */
+export function isStream(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_stream' in value &&
+        value.__rill_stream === true);
+}
+/** Public API alias for isStream */
+export const isRillStream = isStream;
+/**
+ * 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 function isIterator(value) {
+    if (!isDict(value))
+        return false;
+    const dict = value;
+    if (!('done' in dict && typeof dict['done'] === 'boolean'))
+        return false;
+    if (!('next' in dict && isCallable(dict['next'])))
+        return false;
+    // 'value' field only required when not done
+    if (!dict['done'] && !('value' in dict))
+        return false;
+    return true;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Types Module Barrel
+ *
+ * Re-exports all public symbols from the types/ sub-modules.
+ * Internal runtime code may import sub-modules directly;
+ * this barrel provides a single import path for runtime/index.ts
+ * and other consumers.
+ */
+export type { RillFieldDef, RillIterator, RillOrdered, RillStream, RillTuple, RillTypeValue, RillValue, RillVector, TypeStructure, } from './structures.js';
+export type { CallableMarker, FieldDescriptorMarker } from './markers.js';
+export { isCallable, isDict, isIterator, isOrdered, isRillStream, isStream, isTuple, isTypeValue, isVector, } from './guards.js';
+export { copyValue, createOrdered, createRillStream, createTuple, createVector, emptyForType, } from './constructors.js';
+export type { DictStructure, FieldComparisonCallbacks, OrderedStructure, TupleStructure, } from './operations.js';
+export { commonType, compareStructuredFields, formatRillLiteral, formatStructure, inferElementType, inferStructure, paramToFieldDef, structureEquals, structureMatches, } from './operations.js';
+export type { TypeDefinition, TypeProtocol } from './registrations.js';
+export { BUILT_IN_TYPES, deepEquals, deserializeValue, formatValue, inferType, populateBuiltinMethods, serializeValue, } from './registrations.js';
+export type { CaptureEvent, ErrorEvent, ExecutionResult, ExecutionStepper, ExtensionEvent, FunctionReturnEvent, HostCallEvent, NativeArray, NativePlainObject, NativeValue, ObservabilityCallbacks, ResolverResult, RuntimeCallbacks, RuntimeContext, RuntimeOptions, SchemeResolver, StepEndEvent, StepResult, StepStartEvent, } from './runtime.js';
+export { bindDictCallables } from './runtime.js';

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

@@ -0,0 +1,19 @@
+/**
+ * Types Module Barrel
+ *
+ * Re-exports all public symbols from the types/ sub-modules.
+ * Internal runtime code may import sub-modules directly;
+ * this barrel provides a single import path for runtime/index.ts
+ * and other consumers.
+ */
+// ============================================================
+// GUARDS (type guard functions for all Rill value types)
+// ============================================================
+export { isCallable, isDict, isIterator, isOrdered, isRillStream, isStream, isTuple, isTypeValue, isVector, } from './guards.js';
+// ============================================================
+// CONSTRUCTORS (factory functions for compound values)
+// ============================================================
+export { copyValue, createOrdered, createRillStream, createTuple, createVector, emptyForType, } from './constructors.js';
+export { commonType, compareStructuredFields, formatRillLiteral, formatStructure, inferElementType, inferStructure, paramToFieldDef, structureEquals, structureMatches, } from './operations.js';
+export { BUILT_IN_TYPES, deepEquals, deserializeValue, formatValue, inferType, populateBuiltinMethods, serializeValue, } from './registrations.js';
+export { bindDictCallables } from './runtime.js';

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

@@ -0,0 +1,12 @@
+/**
+ * Shared marker interfaces for forward declarations.
+ *
+ * These interfaces break circular dependencies between values.ts,
+ * type-structures.ts, and callable.ts. Actual types are defined in callable.ts.
+ */
+export interface CallableMarker {
+    readonly __type: 'callable';
+}
+export interface FieldDescriptorMarker {
+    readonly __rill_field_descriptor: true;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Shared marker interfaces for forward declarations.
+ *
+ * These interfaces break circular dependencies between values.ts,
+ * type-structures.ts, and callable.ts. Actual types are defined in callable.ts.
+ */
+export {};

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

@@ -0,0 +1,98 @@
+/**
+ * Type Structure Operations
+ *
+ * Structural comparison, matching, inference, and formatting functions
+ * extracted from values.ts. Provides `compareStructuredFields()` to
+ * deduplicate dict/tuple/ordered dispatch across structureEquals,
+ * structureMatches, and formatStructure.
+ *
+ * Import constraints:
+ * - Imports from ./structures.js, ./guards.js, ./registrations.js
+ * - Circular with registrations.ts (runtime-safe: no init-time cross-calls)
+ */
+import type { RillFieldDef, RillValue, TypeStructure } from './structures.js';
+export type DictStructure = {
+    kind: 'dict';
+    fields?: Record<string, RillFieldDef>;
+    valueType?: TypeStructure;
+};
+export type TupleStructure = {
+    kind: 'tuple';
+    elements?: RillFieldDef[];
+    valueType?: TypeStructure;
+};
+export type OrderedStructure = {
+    kind: 'ordered';
+    fields?: RillFieldDef[];
+    valueType?: TypeStructure;
+};
+/**
+ * Callbacks for kind-specific field dispatch in dict/tuple/ordered types.
+ * `compareStructuredFields` handles the common valueType check and
+ * kind-based field extraction, then delegates to these callbacks.
+ */
+export interface FieldComparisonCallbacks<T> {
+    /** Both structures carry a uniform valueType */
+    onValueType(aValueType: TypeStructure, bValueType: TypeStructure): T;
+    /** One structure has valueType, the other does not */
+    onValueTypeMismatch(): T;
+    /** Neither structure has fields/elements */
+    onBothEmpty(): T;
+    /** One structure has fields/elements, the other does not */
+    onFieldPresenceMismatch(): T;
+    /** Dict with keyed fields on both sides */
+    onDictFields(aFields: Record<string, RillFieldDef>, bFields: Record<string, RillFieldDef>): T;
+    /** Tuple with positional elements on both sides */
+    onTupleElements(aElements: RillFieldDef[], bElements: RillFieldDef[]): T;
+    /** Ordered with named positional fields on both sides */
+    onOrderedFields(aFields: RillFieldDef[], bFields: RillFieldDef[]): T;
+}
+/**
+ * Shared dispatch for dict/tuple/ordered field comparison.
+ * Handles valueType check and field iteration across
+ * structureEquals, structureMatches, and formatStructure.
+ *
+ * Constraints:
+ * - Dict: keyed fields, sorted key comparison
+ * - Tuple: positional elements
+ * - Ordered: named positional fields
+ * - Recurses via caller-provided callbacks
+ *
+ * Callers validate that a.kind === b.kind before calling.
+ * Invalid kind values fall through to the final return.
+ */
+export declare function compareStructuredFields<T>(a: TypeStructure, b: TypeStructure, callbacks: FieldComparisonCallbacks<T>, fallback: T): T;
+/** Format a RillValue as a rill literal for use in type signatures. */
+export declare function formatRillLiteral(value: RillValue): string;
+/** Compare two structural types for equality. */
+export declare function structureEquals(a: TypeStructure, b: TypeStructure): boolean;
+/**
+ * Check if a value matches a structural type descriptor.
+ * Used for runtime type checking (`:?` operator).
+ */
+export declare function structureMatches(value: RillValue, type: TypeStructure): boolean;
+/** Format a structural type descriptor as a human-readable string. */
+export declare function formatStructure(type: TypeStructure): string;
+/** Build a closure param field definition from name, type, and optional default. */
+export declare function paramToFieldDef(name: string, type: TypeStructure, defaultValue: RillValue | undefined): RillFieldDef;
+/**
+ * Infer the element type for a homogeneous list.
+ * Empty arrays return { kind: 'any' }.
+ * Mixed types throw RILL-R002.
+ */
+export declare function inferElementType(elements: RillValue[]): TypeStructure;
+/** Infer the structural type descriptor for any Rill value. */
+export declare function inferStructure(value: 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;