@rcrsr/rill 0.17.0 → 0.18.0

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

@@ -44,37 +44,160 @@
 import { RillError, RuntimeError } from '../../../../types.js';
 import { isCallable, isScriptCallable, isApplicationCallable, isDict, marshalArgs, } from '../../callable.js';
 import { getVariable, pushCallFrame, popCallFrame, UNVALIDATED_METHOD_PARAMS, } from '../../context.js';
-import { inferType, isTypeValue, isTuple, isOrdered, paramToFieldDef, inferStructure, structureMatches, formatStructure, anyTypeValue, structureToTypeValue, } from '../../values.js';
+import { inferType } from '../../types/registrations.js';
+import { isTypeValue, isTuple, isOrdered, isStream, } from '../../types/guards.js';
+import { paramToFieldDef, inferStructure, structureMatches, formatStructure, } from '../../types/operations.js';
+import { createRillStream } from '../../types/constructors.js';
+import { anyTypeValue, structureToTypeValue } from '../../values.js';
+import { YieldSignal, ReturnSignal } from '../../signals.js';
 /**
- * ClosuresMixin implementation.
+ * Create a rendezvous channel for stream chunk handoff.
  *
- * Evaluates callable operations: host functions, closures, methods, invocations.
- * Handles parameter binding, type checking, and callable contexts.
+ * Producer (body) calls push() which blocks until consumer calls pull().
+ * Consumer (async generator) calls pull() which blocks until producer pushes.
+ * close() and error() signal body termination.
  *
- * Depends on:
- * - EvaluatorBase: ctx, checkAborted(), getNodeLocation(), withTimeout()
- * - evaluateExpression() (from future CoreMixin composition)
- * - evaluateBodyExpression() (from ControlFlowMixin)
- *
- * Methods added:
- * - invokeCallable(callable, args, location) -> Promise<RillValue>
- * - evaluateHostCall(node) -> Promise<RillValue>
- * - evaluateClosureCall(node) -> Promise<RillValue>
- * - evaluateClosureCallWithPipe(node, pipeInput) -> Promise<RillValue>
- * - evaluatePipePropertyAccess(node, pipeInput) -> Promise<RillValue>
- * - evaluateVariableInvoke(node, pipeInput) -> Promise<RillValue>
- * - evaluatePipeInvoke(node, input) -> Promise<RillValue>
- * - evaluateMethod(node, receiver) -> Promise<RillValue>
- * - evaluateInvoke(node, receiver) -> Promise<RillValue>
- * - evaluateArgs(argExprs) -> Promise<RillValue[]> (helper)
- * - invokeFnCallable(callable, args, location) -> Promise<RillValue> (helper)
- * - invokeScriptCallable(callable, args, location) -> Promise<RillValue> (helper)
- * - createCallableContext(callable) -> RuntimeContext (helper)
- * - validateParamType(param, value, location) -> void (helper)
- * - bindArgsToParams(argNodes, callable, callLocation) -> Promise<BoundArgs> (helper)
+ * @internal
  */
+function createStreamChannel() {
+    // Pending chunk waiting for consumer
+    let pendingChunk;
+    // Consumer waiting for a chunk
+    let pendingPull;
+    // Terminal state
+    let closed = false;
+    let closedResolution;
+    let closedError;
+    return {
+        async push(value) {
+            if (closed)
+                return;
+            // If consumer is already waiting, deliver immediately
+            if (pendingPull) {
+                const pull = pendingPull;
+                pendingPull = undefined;
+                pull.resolve({ value, done: false });
+                return;
+            }
+            // Otherwise, wait for consumer to pull
+            return new Promise((resolve) => {
+                pendingChunk = { value, resume: resolve };
+            });
+        },
+        async pull() {
+            // If there's a pending chunk from the producer, consume it
+            if (pendingChunk) {
+                const chunk = pendingChunk;
+                pendingChunk = undefined;
+                chunk.resume(); // unblock producer
+                return { value: chunk.value, done: false };
+            }
+            // If body already completed, return done
+            if (closed) {
+                if (closedError !== undefined)
+                    throw closedError;
+                return { done: true };
+            }
+            // Wait for producer to push
+            return new Promise((resolve, reject) => {
+                pendingPull = { resolve, reject };
+            });
+        },
+        close(_resolution) {
+            closed = true;
+            closedResolution = _resolution;
+            // Wake up waiting consumer
+            if (pendingPull) {
+                const pull = pendingPull;
+                pendingPull = undefined;
+                pull.resolve({ done: true });
+            }
+        },
+        error(err) {
+            closed = true;
+            closedError = err;
+            // Wake up waiting consumer with error
+            if (pendingPull) {
+                const pull = pendingPull;
+                pendingPull = undefined;
+                pull.reject(err);
+            }
+        },
+        /** Access cached resolution value after close(). */
+        get resolution() {
+            return closedResolution ?? null;
+        },
+    };
+}
 function createClosuresMixin(Base) {
     return class ClosuresEvaluator extends Base {
+        /**
+         * Active stream channel for the current stream closure body execution.
+         * Set during stream closure body execution; null otherwise.
+         * Used by evaluateYield to push chunks to the async generator.
+         */
+        activeStreamChannel = null;
+        /**
+         * Expected chunk type for the active stream closure.
+         * Set during stream closure body execution; null otherwise.
+         * Used by evaluateYield for chunk type validation (FR-STREAM-10).
+         */
+        activeStreamChunkType = null;
+        /**
+         * Stack of active stream lists for IR-14 scope exit cleanup.
+         * Each entry represents a scope boundary. Streams are tracked in
+         * creation order; disposed in reverse order on scope exit.
+         */
+        streamScopeStack = [];
+        /**
+         * Track a stream in the current scope for cleanup on scope exit (IR-14).
+         * Streams with dispose functions get cleaned up when their scope exits.
+         */
+        trackStream(stream) {
+            const current = this.streamScopeStack[this.streamScopeStack.length - 1];
+            if (current) {
+                current.push(stream);
+            }
+        }
+        /**
+         * Dispose a list of unconsumed streams in reverse creation order (IR-14).
+         * Propagates dispose errors as RILL-R002 — does not swallow.
+         */
+        async disposeStreams(streams) {
+            for (let i = streams.length - 1; i >= 0; i--) {
+                const stream = streams[i];
+                // Only dispose streams that are not fully consumed
+                if (stream.done)
+                    continue;
+                const disposeFn = stream['__rill_stream_dispose'];
+                if (typeof disposeFn === 'function') {
+                    try {
+                        disposeFn();
+                    }
+                    catch (err) {
+                        // Propagate dispose errors — do not swallow (IR-14)
+                        if (err instanceof RuntimeError)
+                            throw err;
+                        throw new RuntimeError('RILL-R002', err instanceof Error ? err.message : String(err));
+                    }
+                }
+            }
+        }
+        /**
+         * Wrap evaluateBlock to add scope exit cleanup for streams (IR-14).
+         * Pushes a scope boundary, runs the block, then disposes unconsumed streams.
+         */
+        async evaluateBlock(node) {
+            this.streamScopeStack.push([]);
+            try {
+                // Call the ControlFlowMixin's evaluateBlock via prototype chain
+                return await Object.getPrototypeOf(ClosuresEvaluator.prototype).evaluateBlock.call(this, node);
+            }
+            finally {
+                const streams = this.streamScopeStack.pop();
+                await this.disposeStreams(streams);
+            }
+        }
         /**
          * Evaluate argument expressions while preserving the current pipeValue.
          * Used by all callable invocations to prepare arguments.
@@ -112,12 +235,18 @@ function createClosuresMixin(Base) {
                 pushCallFrame(this.ctx, frame);
             }
             try {
+                let result;
                 if (callable.kind === 'script') {
-                    return await this.invokeScriptCallable(callable, args, callLocation);
+                    result = await this.invokeScriptCallable(callable, args, callLocation);
                 }
                 else {
-                    return await this.invokeFnCallable(callable, args, callLocation, functionName);
+                    result = await this.invokeFnCallable(callable, args, callLocation, functionName);
+                }
+                // IR-14: Track returned streams for scope exit cleanup
+                if (isStream(result)) {
+                    this.trackStream(result);
                 }
+                return result;
             }
             catch (error) {
                 // Snapshot call stack onto error before finally pops the frame.
@@ -221,11 +350,52 @@ function createClosuresMixin(Base) {
                 throw new RuntimeError('RILL-R001', `Parameter type mismatch: ${param.name} expects ${expectedType}, got ${actualType}`, callLocation, { paramName: param.name, expectedType, actualType });
             }
         }
+        /**
+         * Evaluate yield: validate chunk type and throw YieldSignal (IR-6).
+         *
+         * When inside a stream closure body (activeStreamChannel is set),
+         * pushes the value to the stream channel instead of throwing.
+         * When no stream channel is active, throws YieldSignal directly
+         * (for nested evaluation contexts that catch it).
+         *
+         * Validates pipe value against declared chunk type at emission (FR-STREAM-10).
+         * Throws RILL-R004 if chunk type does not match declared type.
+         */
+        evaluateYield(value, location) {
+            // Validate chunk type if constrained
+            if (this.activeStreamChunkType !== null) {
+                if (!structureMatches(value, this.activeStreamChunkType)) {
+                    const expected = formatStructure(this.activeStreamChunkType);
+                    const actual = inferType(value);
+                    throw new RuntimeError('RILL-R004', `Yielded value type mismatch: expected ${expected}, got ${actual}`, location, { expected, actual });
+                }
+            }
+            // Push to stream channel if inside a stream closure body
+            if (this.activeStreamChannel) {
+                return this.activeStreamChannel.push(value);
+            }
+            // Fallback: throw YieldSignal (caught by stream body wrapper)
+            throw new YieldSignal(value);
+        }
         /**
          * Invoke script callable with positional arguments.
          * Handles parameter binding, default values, and type checking.
+         *
+         * Stream closures (returnType.structure.kind === 'stream') are detected
+         * and dispatched to invokeStreamClosure for lazy body execution (IR-13).
          */
         async invokeScriptCallable(callable, args, callLocation) {
+            // IR-13: Stream closure detection — dispatch to stream-specific invocation
+            if (callable.returnType.structure.kind === 'stream') {
+                return this.invokeStreamClosure(callable, args, callLocation);
+            }
+            return this.invokeRegularScriptCallable(callable, args, callLocation);
+        }
+        /**
+         * Invoke a regular (non-stream) script callable.
+         * Extracted from invokeScriptCallable for clarity after stream dispatch.
+         */
+        async invokeRegularScriptCallable(callable, args, callLocation) {
             const callableCtx = this.createCallableContext(callable);
             // Marshal positional args to named record (IC-1).
             // Script callables always have params defined.
@@ -280,6 +450,152 @@ function createClosuresMixin(Base) {
                 this.ctx = savedCtx;
             }
         }
+        /**
+         * Invoke a stream closure: produces a RillStream instead of body result (IR-13).
+         *
+         * Sets up a rendezvous channel between the closure body and an async generator.
+         * The body executes lazily as chunks are consumed:
+         * - yield in body → pushes chunk to channel → consumer yields to iterator
+         * - return in body → sets resolution value
+         * - Body end without return → resolution is null
+         *
+         * Each call produces a new, independent stream instance (idempotency).
+         *
+         * Error contracts:
+         * - Chunk type mismatch at yield → RILL-R004 (validated by evaluateYield)
+         * - Resolution type mismatch → RILL-R004
+         */
+        async invokeStreamClosure(callable, args, callLocation) {
+            const callableCtx = this.createCallableContext(callable);
+            // Marshal positional args to named record (IC-1).
+            const record = marshalArgs(args, callable.params, {
+                functionName: '<anonymous>',
+                location: callLocation,
+            });
+            // Bind each named value into the callable context.
+            for (const [name, value] of Object.entries(record)) {
+                callableCtx.variables.set(name, value);
+            }
+            // IR-4: Block closure pipe sync
+            if (callable.params[0]?.name === '$') {
+                callableCtx.pipeValue = record['$'];
+            }
+            // Extract chunk and ret types from the stream structure
+            const streamStructure = callable.returnType.structure;
+            // Create channel and async generator for lazy body execution
+            const channel = createStreamChannel();
+            // Start body execution asynchronously.
+            // Arrow function captures `this` from invokeStreamClosure scope.
+            // The body runs concurrently with consumption, blocking at each yield
+            // until the consumer pulls the next chunk.
+            const bodyPromise = (async () => {
+                const savedCtx = this.ctx;
+                const savedChannel = this.activeStreamChannel;
+                const savedChunkType = this.activeStreamChunkType;
+                this.ctx = callableCtx;
+                this.activeStreamChannel = channel;
+                this.activeStreamChunkType = streamStructure.chunk ?? null;
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const result = await this.evaluateBodyExpression(callable.body);
+                    // Validate resolution type if declared
+                    if (streamStructure.ret !== undefined) {
+                        if (!structureMatches(result, streamStructure.ret)) {
+                            const expected = formatStructure(streamStructure.ret);
+                            const actual = inferType(result);
+                            throw new RuntimeError('RILL-R004', `Stream resolution type mismatch: expected ${expected}, got ${actual}`, callLocation, { expected, actual });
+                        }
+                    }
+                    channel.close(result);
+                }
+                catch (error) {
+                    if (error instanceof ReturnSignal) {
+                        // return in stream body sets resolution value
+                        const result = error.value;
+                        if (streamStructure.ret !== undefined) {
+                            if (!structureMatches(result, streamStructure.ret)) {
+                                const expected = formatStructure(streamStructure.ret);
+                                const actual = inferType(result);
+                                channel.error(new RuntimeError('RILL-R004', `Stream resolution type mismatch: expected ${expected}, got ${actual}`, callLocation, { expected, actual }));
+                                return;
+                            }
+                        }
+                        channel.close(result);
+                    }
+                    else {
+                        channel.error(error);
+                    }
+                }
+                finally {
+                    this.ctx = savedCtx;
+                    this.activeStreamChannel = savedChannel;
+                    this.activeStreamChunkType = savedChunkType;
+                }
+            })();
+            // Create async generator that pulls from the channel
+            async function* generateChunks() {
+                try {
+                    while (true) {
+                        const result = await channel.pull();
+                        if (result.done)
+                            return;
+                        yield result.value;
+                    }
+                }
+                finally {
+                    // Ensure body promise settles to prevent unhandled rejections
+                    await bodyPromise.catch(() => { });
+                }
+            }
+            // Build the RillStream (IR-13)
+            const stream = createRillStream({
+                chunks: generateChunks(),
+                resolve: async () => {
+                    // Wait for body to complete
+                    await bodyPromise.catch(() => { });
+                    return channel.resolution;
+                },
+                chunkType: streamStructure.chunk,
+                retType: streamStructure.ret,
+            });
+            return stream;
+        }
+        /**
+         * Invoke a stream as a function (IR-12).
+         * Drains remaining chunks internally, calls resolve, caches result.
+         * Subsequent calls return the cached value (idempotent).
+         *
+         * Drain is necessary for stream closures where the body blocks at
+         * yield until the consumer pulls. Without draining, resolve() would
+         * hang because the body never completes.
+         */
+        async invokeStream(stream) {
+            const resolveFn = stream['__rill_stream_resolve'];
+            if (typeof resolveFn !== 'function') {
+                throw new RuntimeError('RILL-R002', 'Stream has no resolve function');
+            }
+            // Drain remaining chunks by walking the stream's linked list (AC-4).
+            // This unblocks the body (which may be waiting at a yield/push).
+            let current = stream;
+            while (!current.done) {
+                const nextCallable = current['next'];
+                if (!nextCallable || !isCallable(nextCallable))
+                    break;
+                try {
+                    const next = await this.invokeCallable(nextCallable, []);
+                    if (typeof next !== 'object' ||
+                        next === null ||
+                        !isStream(next))
+                        break;
+                    current = next;
+                }
+                catch {
+                    // Drain errors are expected when stream is already consumed
+                    break;
+                }
+            }
+            return resolveFn();
+        }
         /**
          * Evaluate host function call: functionName(args)
          * Looks up function in context and invokes it.
@@ -437,6 +753,10 @@ function createClosuresMixin(Base) {
                     throw new RuntimeError('RILL-R002', `Cannot access property on non-dict value at '${fullPath}'`, this.getNodeLocation(node));
                 }
             }
+            // IR-12: Stream invocation — $s() returns the resolution value
+            if (isStream(value)) {
+                return this.invokeStream(value);
+            }
             if (!isCallable(value)) {
                 throw new RuntimeError('RILL-R002', `'${fullPath}' is not callable`, this.getNodeLocation(node), { path: fullPath, actualType: inferType(value) });
             }
@@ -677,6 +997,10 @@ function createClosuresMixin(Base) {
          * Calls the receiver value as a closure with the given arguments.
          */
         async evaluateInvoke(node, receiver) {
+            // IR-12: Stream invocation — $s() returns the resolution value
+            if (isStream(receiver)) {
+                return this.invokeStream(receiver);
+            }
             if (!isCallable(receiver)) {
                 throw new RuntimeError('RILL-R002', `Cannot invoke non-callable value (got ${inferType(receiver)})`, this.getNodeLocation(node), { actualType: inferType(receiver) });
             }
@@ -714,6 +1038,22 @@ function createClosuresMixin(Base) {
             if (isTypeValue(value)) {
                 throw new RuntimeError('RILL-R008', `Annotation access not supported on type values`, location, { annotationKey: key });
             }
+            // IR-11: Stream reflection — ^chunk and ^output on stream values
+            if (isStream(value)) {
+                if (key === 'chunk') {
+                    const chunkType = value['__rill_stream_chunk_type'];
+                    if (chunkType === undefined)
+                        return anyTypeValue;
+                    return structureToTypeValue(chunkType);
+                }
+                if (key === 'output') {
+                    const retType = value['__rill_stream_ret_type'];
+                    if (retType === undefined)
+                        return anyTypeValue;
+                    return structureToTypeValue(retType);
+                }
+                throw new RuntimeError('RILL-R003', `annotation not found: ^${key}`, location, { actualType: 'stream' });
+            }
             // Non-callable values do not support annotation reflection
             if (!isCallable(value)) {
                 throw new RuntimeError('RILL-R003', `annotation not found: ^${key}`, location, { actualType: inferType(value) });

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

@@ -21,7 +21,8 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { inferType, isRillIterator, isVector } from '../../values.js';
+import { inferType } from '../../types/registrations.js';
+import { isIterator, isStream, isVector } from '../../types/guards.js';
 import { createChildContext, getVariable } from '../../context.js';
 import { BreakSignal } from '../../signals.js';
 import { isCallable, isDict, marshalArgs } from '../../callable.js';
@@ -35,7 +36,7 @@ const DEFAULT_MAX_ITERATIONS = 10000;
  * CollectionsMixin implementation.
  *
  * Evaluates collection operators: each, map, fold, filter.
- * Handles iteration over lists, strings, dicts, and iterators.
+ * Handles iteration over lists, strings, dicts, iterators, and streams.
  *
  * Depends on:
  * - EvaluatorBase: ctx, checkAborted(), getNodeLocation()
@@ -55,17 +56,18 @@ const DEFAULT_MAX_ITERATIONS = 10000;
  * - getIterableElements(input) -> Promise<RillValue[]> (helper)
  * - evaluateIteratorBody(body, element, accumulator) -> Promise<RillValue> (helper)
  * - expandIterator(iterator, limit?) -> Promise<RillValue[]> (helper)
+ * - expandStream(stream, node, limit?) -> Promise<RillValue[]> (helper)
  */
 function createCollectionsMixin(Base) {
     return class CollectionsEvaluator extends Base {
         /**
-         * Get elements from an iterable value (list, string, dict, or iterator).
+         * Get elements from an iterable value (list, string, dict, iterator, or stream).
          * Throws RuntimeError if value is not iterable.
          */
         async getIterableElements(input, node) {
             // Vector guard [EC-32]
             if (isVector(input)) {
-                throw new RuntimeError('RILL-R003', 'Collection operators require list, string, dict, or iterator, got vector', node.span.start);
+                throw new RuntimeError('RILL-R003', 'Collection operators require list, string, dict, iterator, or stream, got vector', node.span.start);
             }
             if (Array.isArray(input)) {
                 return input;
@@ -73,8 +75,12 @@ function createCollectionsMixin(Base) {
             if (typeof input === 'string') {
                 return [...input];
             }
+            // Check for stream BEFORE iterator (streams satisfy iterator shape)
+            if (isStream(input)) {
+                return this.expandStream(input, node);
+            }
             // Check for iterator protocol BEFORE generic dict handling
-            if (isRillIterator(input)) {
+            if (isIterator(input)) {
                 return this.expandIterator(input, node);
             }
             if (isDict(input)) {
@@ -85,7 +91,7 @@ function createCollectionsMixin(Base) {
                     value: input[key],
                 }));
             }
-            throw new RuntimeError('RILL-R002', `Collection operators require list, string, dict, or iterator, got ${inferType(input)}`, node.span.start);
+            throw new RuntimeError('RILL-R002', `Collection operators require list, string, dict, iterator, or stream, got ${inferType(input)}`, node.span.start);
         }
         /**
          * Expand an iterator to a list of values.
@@ -119,6 +125,75 @@ function createCollectionsMixin(Base) {
             }
             return elements;
         }
+        /**
+         * Expand a stream to a list of chunk values.
+         * Consumes async chunks by repeatedly calling the stream's next callable.
+         * Respects iteration limits to prevent unbounded expansion.
+         *
+         * On BreakSignal, calls the stream's dispose callable (if present)
+         * before re-throwing (NFR-STREAM-2).
+         */
+        async expandStream(stream, node, limit = DEFAULT_MAX_ITERATIONS) {
+            const elements = [];
+            let current = stream;
+            let count = 0;
+            let expectedType;
+            try {
+                while (!current.done && count < limit) {
+                    this.checkAborted();
+                    const val = current['value'];
+                    if (val !== undefined) {
+                        const actualType = inferType(val);
+                        if (expectedType === undefined) {
+                            expectedType = actualType;
+                        }
+                        else if (actualType !== expectedType) {
+                            throw new RuntimeError('RILL-R004', `Stream chunk type mismatch: expected ${expectedType}, got ${actualType}`, node.span.start);
+                        }
+                        elements.push(val);
+                    }
+                    count++;
+                    // Invoke next() to advance the stream
+                    const nextClosure = current['next'];
+                    if (nextClosure === undefined || !isCallable(nextClosure)) {
+                        throw new RuntimeError('RILL-R002', 'Stream .next must be a closure', node.span.start);
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const nextStep = await this.invokeCallable(nextClosure, [], this.ctx, node.span.start);
+                    if (typeof nextStep !== 'object' || nextStep === null) {
+                        throw new RuntimeError('RILL-R002', 'Stream .next must return a stream step', node.span.start);
+                    }
+                    current = nextStep;
+                }
+            }
+            catch (e) {
+                if (e instanceof BreakSignal) {
+                    // Dispose stream resources before re-throwing (IR-14)
+                    // Access __rill_stream_dispose on the original stream object
+                    // (step objects don't carry dispose; it lives on the root stream)
+                    const disposeFn = stream['__rill_stream_dispose'];
+                    if (typeof disposeFn === 'function') {
+                        try {
+                            disposeFn();
+                        }
+                        catch (disposeErr) {
+                            // Propagate dispose errors as RILL-R002 (EC-15)
+                            if (disposeErr instanceof RuntimeError)
+                                throw disposeErr;
+                            throw new RuntimeError('RILL-R002', disposeErr instanceof Error
+                                ? disposeErr.message
+                                : String(disposeErr), node.span.start);
+                        }
+                    }
+                    throw e;
+                }
+                throw e;
+            }
+            if (count >= limit) {
+                throw new RuntimeError('RILL-R010', `Stream expansion exceeded ${limit} iterations`, node.span.start, { limit, iterations: count });
+            }
+            return elements;
+        }
         /**
          * Evaluate collection body for a single element.
          * Handles all body forms: closure, block, grouped, variable, postfix, spread.

package/dist/runtime/core/eval/mixins/control-flow.js

@@ -24,7 +24,7 @@
  * @internal
  */
 import { RuntimeError } from '../../../../types.js';
-import { inferType } from '../../values.js';
+import { inferType } from '../../types/registrations.js';
 import { createChildContext } from '../../context.js';
 import { BreakSignal, ReturnSignal } from '../../signals.js';
 /**