@rcrsr/rill 0.17.0 → 0.18.0

package/dist/runtime/core/eval/mixins/conversion.js

@@ -27,9 +27,12 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { inferType, isTuple, isOrdered, isTypeValue, createOrdered, createTuple, deepCopyRillValue, hasCollectionFields, emptyForType, } from '../../values.js';
+import { inferType } from '../../types/registrations.js';
+import { isTuple, isOrdered, isTypeValue } from '../../types/guards.js';
+import { createOrdered, createTuple, copyValue, emptyForType, } from '../../types/constructors.js';
+import { hasCollectionFields } from '../../values.js';
 import { isDict } from '../../callable.js';
-import { BUILT_IN_TYPES } from '../../type-registrations.js';
+import { BUILT_IN_TYPES } from '../../types/registrations.js';
 import { getVariable } from '../../context.js';
 /**
  * ConversionMixin implementation.
@@ -123,6 +126,10 @@ function createConversionMixin(Base) {
             if (sourceType === targetType) {
                 return input;
             }
+            // IR-11: :>stream is not supported — stream type cannot be a conversion target
+            if (targetType === 'stream') {
+                throw new RuntimeError('RILL-R003', 'Type conversion not supported for stream type', this.getNodeLocation(node));
+            }
             // dict -> :>ordered without structural sig is always RILL-R037 (EC-11)
             if (sourceType === 'dict' && targetType === 'ordered') {
                 throw new RuntimeError('RILL-R037', 'dict to ordered conversion requires structural type signature', this.getNodeLocation(node));
@@ -137,10 +144,8 @@ function createConversionMixin(Base) {
                 return converter(input);
             }
             catch (err) {
-                // Protocol converters throw plain Errors; wrap as RuntimeError
-                // with the appropriate error code.
-                if (err instanceof RuntimeError)
-                    throw err;
+                // Protocol converters throw RuntimeError (RILL-R064/R065/R066);
+                // wrap with evaluator-level error codes for user-facing messages.
                 // String-to-number parse failures use RILL-R038 (EC-12)
                 // Preserve the protocol's detailed message (includes unparseable value).
                 if (sourceType === 'string' && targetType === 'number') {
@@ -190,7 +195,7 @@ function createConversionMixin(Base) {
                 else if (field.defaultValue !== undefined) {
                     entries.push([
                         fieldName,
-                        this.hydrateNested(deepCopyRillValue(field.defaultValue), field.type, node),
+                        this.hydrateNested(copyValue(field.defaultValue), field.type, node),
                     ]);
                 }
                 else if (hasCollectionFields(field.type)) {
@@ -252,7 +257,7 @@ function createConversionMixin(Base) {
                     // Field missing from input: use default if available, else error
                     if (resolvedField !== undefined &&
                         resolvedField.defaultValue !== undefined) {
-                        result[fieldName] = this.hydrateNested(deepCopyRillValue(resolvedField.defaultValue), resolvedField.type, node);
+                        result[fieldName] = this.hydrateNested(copyValue(resolvedField.defaultValue), resolvedField.type, node);
                     }
                     else if (resolvedField !== undefined &&
                         hasCollectionFields(resolvedField.type)) {
@@ -298,7 +303,7 @@ function createConversionMixin(Base) {
                 }
                 else if (element.defaultValue !== undefined) {
                     // Missing trailing element with default: deep copy and hydrate
-                    result.push(this.hydrateNested(deepCopyRillValue(element.defaultValue), element.type, node));
+                    result.push(this.hydrateNested(copyValue(element.defaultValue), element.type, node));
                 }
                 else if (hasCollectionFields(element.type)) {
                     // Missing element with collection type: seed empty and hydrate
@@ -330,7 +335,7 @@ function createConversionMixin(Base) {
                     }
                     else {
                         if (resolvedField.defaultValue !== undefined) {
-                            result[fieldName] = this.hydrateNested(deepCopyRillValue(resolvedField.defaultValue), resolvedField.type, node);
+                            result[fieldName] = this.hydrateNested(copyValue(resolvedField.defaultValue), resolvedField.type, node);
                         }
                         else if (hasCollectionFields(resolvedField.type)) {
                             result[fieldName] = this.hydrateNested(emptyForType(resolvedField.type), resolvedField.type, node);
@@ -364,7 +369,7 @@ function createConversionMixin(Base) {
                     else if (field.defaultValue !== undefined) {
                         resultEntries.push([
                             name,
-                            this.hydrateNested(deepCopyRillValue(field.defaultValue), field.type, node),
+                            this.hydrateNested(copyValue(field.defaultValue), field.type, node),
                         ]);
                     }
                     else if (hasCollectionFields(field.type)) {
@@ -395,7 +400,7 @@ function createConversionMixin(Base) {
                         resultEntries.push(elementValue);
                     }
                     else if (element.defaultValue !== undefined) {
-                        resultEntries.push(this.hydrateNested(deepCopyRillValue(element.defaultValue), element.type, node));
+                        resultEntries.push(this.hydrateNested(copyValue(element.defaultValue), element.type, node));
                     }
                     else if (hasCollectionFields(element.type)) {
                         resultEntries.push(this.hydrateNested(emptyForType(element.type), element.type, node));

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

@@ -21,7 +21,7 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { isTuple } from '../../values.js';
+import { isTuple } from '../../types/guards.js';
 import { isCallable, isDict, isScriptCallable } from '../../callable.js';
 import { BreakSignal, ReturnSignal } from '../../signals.js';
 /**
@@ -102,7 +102,7 @@ function createCoreMixin(Base) {
                 value = await this.evaluatePipeTarget(target, value);
                 this.ctx.pipeValue = value; // OK: flows within chain
             }
-            // Handle chain terminator (capture, break, return)
+            // Handle chain terminator (capture, break, return, yield)
             if (chain.terminator) {
                 if (chain.terminator.type === 'Break') {
                     // Restore parent's $ before throwing (cleanup)
@@ -114,6 +114,19 @@ function createCoreMixin(Base) {
                     this.ctx.pipeValue = savedPipeValue;
                     throw new ReturnSignal(value);
                 }
+                if (chain.terminator.type === 'Yield') {
+                    // Restore parent's $ before throwing (cleanup)
+                    this.ctx.pipeValue = savedPipeValue;
+                    // Delegate to evaluateYield for chunk type validation + YieldSignal.
+                    // When inside a stream closure body, evaluateYield pushes to the
+                    // channel and blocks until the consumer pulls (returns Promise<void>).
+                    // When outside, it throws YieldSignal synchronously.
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    await this.evaluateYield(value, chain.terminator.span.start);
+                    // After yield resumes (stream channel case), restore pipe value
+                    // and return the yielded value as the chain result
+                    return value;
+                }
                 // Capture
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 await this.handleCapture(chain.terminator, value);

package/dist/runtime/core/eval/mixins/expressions.js

@@ -18,8 +18,9 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { inferType, isTruthy } from '../../values.js';
-import { BUILT_IN_TYPES } from '../../type-registrations.js';
+import { inferType } from '../../types/registrations.js';
+import { isTruthy } from '../../values.js';
+import { BUILT_IN_TYPES } from '../../types/registrations.js';
 import { createChildContext } from '../../context.js';
 import { isCallable } from '../../callable.js';
 /**

package/dist/runtime/core/eval/mixins/extraction.js

@@ -7,7 +7,8 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { createOrdered, createTuple, inferElementType } from '../../values.js';
+import { createOrdered, createTuple } from '../../types/constructors.js';
+import { inferElementType } from '../../types/operations.js';
 import { isDict } from '../../callable.js';
 import { getVariable } from '../../context.js';
 /**
@@ -77,7 +78,6 @@ function createExtractionMixin(Base) {
                     }
                     // Note: setVariable and resolveTypeRef will be available from VariablesMixin
                     // and TypesMixin which are applied before ExtractionMixin in the composition order
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     const dictResolved = elem.typeRef !== null
                         ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
                             await this.resolveTypeRef(elem.typeRef, (name) => getVariable(this.ctx, name))
@@ -112,7 +112,6 @@ function createExtractionMixin(Base) {
                     }
                     // Note: setVariable and resolveTypeRef will be available from VariablesMixin
                     // and TypesMixin which are applied before ExtractionMixin in the composition order
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     const listResolved = elem.typeRef !== null
                         ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
                             await this.resolveTypeRef(elem.typeRef, (name) => getVariable(this.ctx, name))

package/dist/runtime/core/eval/mixins/list-dispatch.js

@@ -14,7 +14,7 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { inferElementType } from '../../values.js';
+import { inferElementType } from '../../types/operations.js';
 /**
  * ListDispatchMixin implementation.
  *

package/dist/runtime/core/eval/mixins/literals.js

@@ -25,7 +25,10 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { anyTypeValue, deepEquals, formatValue, inferElementType, isReservedMethod, isTypeValue, isVector, } from '../../values.js';
+import { deepEquals, formatValue } from '../../types/registrations.js';
+import { isTypeValue, isVector } from '../../types/guards.js';
+import { inferElementType } from '../../types/operations.js';
+import { anyTypeValue, isReservedMethod } from '../../values.js';
 import { isCallable, } from '../../callable.js';
 import { getVariable } from '../../context.js';
 /**
@@ -667,12 +670,20 @@ function createLiteralsMixin(Base) {
             }
             const isProperty = rillParams.length === 0;
             // Evaluate returnTypeTarget at closure creation time (IR-4).
+            // TypeConstructorNode → resolve via evaluateTypeConstructor() (e.g., stream(T):R).
             // TypeRef → resolve via resolveTypeRef() — returns RillTypeValue.
             // Absent → returnType defaults to anyTypeValue (omission implies :any, AC-17, AC-18, AC-19).
             let returnType = anyTypeValue;
             if (node.returnTypeTarget !== undefined) {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                returnType = await this.resolveTypeRef(node.returnTypeTarget, (name) => getVariable(this.ctx, name));
+                if ('type' in node.returnTypeTarget &&
+                    node.returnTypeTarget.type === 'TypeConstructor') {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    returnType = await this.evaluateTypeConstructor(node.returnTypeTarget);
+                }
+                else {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    returnType = await this.resolveTypeRef(node.returnTypeTarget, (name) => getVariable(this.ctx, name));
+                }
             }
             return {
                 __type: 'callable',

package/dist/runtime/core/eval/mixins/types.js

@@ -23,7 +23,10 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { inferType, checkType, isTypeValue, structureMatches, inferStructure, formatStructure, } from '../../values.js';
+import { inferType } from '../../types/registrations.js';
+import { isTypeValue } from '../../types/guards.js';
+import { structureMatches, inferStructure, formatStructure, } from '../../types/operations.js';
+import { checkType, structureToTypeValue } from '../../values.js';
 import { getVariable } from '../../context.js';
 /**
  * TypesMixin implementation.
@@ -251,6 +254,19 @@ function createTypesMixin(Base) {
                 if (this.ctx.leafTypes.has(typeName)) {
                     throw new RuntimeError('RILL-R004', `${typeName} does not accept type arguments`);
                 }
+                // Stream type: extract chunk/ret from args if present
+                if (typeName === 'stream') {
+                    const streamStructure = { kind: 'stream' };
+                    if (args.length > 0 && args[0] !== undefined) {
+                        const chunkResolved = await this.resolveTypeRef(args[0].value, getVariableFn);
+                        streamStructure.chunk = chunkResolved.structure;
+                    }
+                    if (args.length > 1 && args[1] !== undefined) {
+                        const retResolved = await this.resolveTypeRef(args[1].value, getVariableFn);
+                        streamStructure.ret = retResolved.structure;
+                    }
+                    return structureToTypeValue(streamStructure);
+                }
                 // Delegate to buildCollectionType with recursive resolveTypeRef
                 return this.buildCollectionType(typeName, args, async (arg) => {
                     const resolved = await this.resolveTypeRef(arg.value, getVariableFn);
@@ -397,6 +413,19 @@ function createTypesMixin(Base) {
         async evaluateTypeConstructor(node) {
             const name = node.constructorName;
             const location = node.span.start;
+            // Stream type constructor: extract chunk type (arg 0) and ret type (arg 1)
+            if (name === 'stream') {
+                const streamStructure = { kind: 'stream' };
+                if (node.args.length > 0 && node.args[0] !== undefined) {
+                    const chunkResolved = await this.resolveTypeRef(node.args[0].value, (varName) => getVariable(this.ctx, varName));
+                    streamStructure.chunk = chunkResolved.structure;
+                }
+                if (node.args.length > 1 && node.args[1] !== undefined) {
+                    const retResolved = await this.resolveTypeRef(node.args[1].value, (varName) => getVariable(this.ctx, varName));
+                    streamStructure.ret = retResolved.structure;
+                }
+                return structureToTypeValue(streamStructure);
+            }
             return this.buildCollectionType(name, node.args, async (arg) => {
                 const resolved = await this.resolveTypeRef(arg.value, (varName) => getVariable(this.ctx, varName));
                 return resolved.structure.kind === 'any' &&

package/dist/runtime/core/eval/mixins/variables.js

@@ -31,7 +31,9 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { formatStructure, inferType, isTypeValue, structureMatches, } from '../../values.js';
+import { inferType } from '../../types/registrations.js';
+import { isTypeValue } from '../../types/guards.js';
+import { formatStructure, structureMatches } from '../../types/operations.js';
 import { getVariable, hasVariable } from '../../context.js';
 import { isDict, isCallable } from '../../callable.js';
 /**

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

@@ -5,7 +5,7 @@
  * Provides both full execution and step-by-step execution.
  */
 import type { ScriptNode } from '../../types.js';
-import type { ExecutionResult, ExecutionStepper, RuntimeContext } from './types.js';
+import type { ExecutionResult, ExecutionStepper, RuntimeContext } from './types/runtime.js';
 /**
  * Execute a parsed Rill script.
  *

package/dist/runtime/core/field-descriptor.d.ts

@@ -8,7 +8,7 @@
  * @internal
  */
 import type { SourceLocation } from '../../types.js';
-import type { RillFieldDef, TypeStructure } from './values.js';
+import type { RillFieldDef, TypeStructure } from './types/structures.js';
 /**
  * Field descriptor — carries field name and structural type when accessing a
  * dict-kind RillType field.

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

@@ -4,8 +4,8 @@
  * Functions for inspecting runtime context at runtime.
  * These enable host applications to discover available functions and their signatures.
  */
-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';
 /**
  * Metadata describing a function's signature and documentation.
  * Returned by introspection APIs like getFunctions().

package/dist/runtime/core/introspection.js

@@ -4,7 +4,8 @@
  * Functions for inspecting runtime context at runtime.
  * These enable host applications to discover available functions and their signatures.
  */
-import { formatStructure, formatValue } from './values.js';
+import { formatStructure } from './types/operations.js';
+import { formatValue } from './types/registrations.js';
 import { isApplicationCallable, isRuntimeCallable, isScriptCallable, } from './callable.js';
 import { LANGUAGE_REFERENCE } from '../../generated/introspection-data.js';
 import { BUILTIN_FUNCTIONS } from '../ext/builtins.js';

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

@@ -4,7 +4,7 @@
  * moduleResolver — reads Rill source files from the filesystem.
  * extResolver    — returns extension values from a host-provided config map.
  */
-import type { SchemeResolver } from './types.js';
+import type { SchemeResolver } from './types/runtime.js';
 /**
  * Resolves a module ID to Rill source text by reading a file.
  *

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

@@ -5,7 +5,7 @@
  * These are part of the public API for host applications that
  * need to catch and handle control flow.
  */
-import type { RillValue } from './values.js';
+import type { RillValue } from './types/structures.js';
 /** Signal thrown by `break` to exit loops */
 export declare class BreakSignal extends Error {
     readonly value: RillValue;
@@ -16,3 +16,8 @@ export declare class ReturnSignal extends Error {
     readonly value: RillValue;
     constructor(value: RillValue);
 }
+/** Signal thrown when a stream yields a chunk value */
+export declare class YieldSignal extends Error {
+    readonly value: RillValue;
+    constructor(value: RillValue);
+}

package/dist/runtime/core/signals.js

@@ -23,3 +23,12 @@ export class ReturnSignal extends Error {
         this.name = 'ReturnSignal';
     }
 }
+/** Signal thrown when a stream yields a chunk value */
+export class YieldSignal extends Error {
+    value;
+    constructor(value) {
+        super('yield');
+        this.value = value;
+        this.name = 'YieldSignal';
+    }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * 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 type { RillOrdered, RillStream, RillTuple, RillValue, RillVector, TypeStructure } from './structures.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 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 {RuntimeError} RILL-R074 if data.length is 0 (zero-dimension vectors not allowed)
+ */
+export declare function createVector(data: Float32Array, model: string): RillVector;
+/**
+ * Create an empty collection value matching the given TypeStructure.
+ * Assumes the type is dict, ordered, or tuple.
+ */
+export declare function emptyForType(type: TypeStructure): RillValue;
+/**
+ * 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 declare function createRillStream(options: {
+    chunks: AsyncIterable<RillValue>;
+    resolve: () => Promise<RillValue>;
+    dispose?: (() => void) | undefined;
+    chunkType?: TypeStructure | undefined;
+    retType?: TypeStructure | undefined;
+}): RillStream;
+/**
+ * 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 declare function copyValue(value: RillValue): RillValue;

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;
+}