@rcrsr/rill 0.16.0 → 0.18.0

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

@@ -43,38 +43,161 @@
  */
 import { RillError, RuntimeError } from '../../../../types.js';
 import { isCallable, isScriptCallable, isApplicationCallable, isDict, marshalArgs, } from '../../callable.js';
-import { getVariable, pushCallFrame, popCallFrame, UNVALIDATED_METHOD_PARAMS, UNVALIDATED_METHOD_RECEIVERS, } from '../../context.js';
-import { inferType, isTypeValue, isTuple, isOrdered, paramToFieldDef, inferStructuralType, structuralTypeMatches, formatStructuralType, anyTypeValue, rillTypeToTypeValue, } from '../../values.js';
+import { getVariable, pushCallFrame, popCallFrame, UNVALIDATED_METHOD_PARAMS, } from '../../context.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.
@@ -215,17 +344,58 @@ function createClosuresMixin(Base) {
         validateParamType(param, value, callLocation) {
             if (param.type === undefined)
                 return;
-            if (!structuralTypeMatches(value, param.type)) {
-                const expectedType = formatStructuralType(param.type);
+            if (!structureMatches(value, param.type)) {
+                const expectedType = formatStructure(param.type);
                 const actualType = inferType(value);
                 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) });
             }
@@ -541,13 +861,13 @@ function createClosuresMixin(Base) {
                 throw new RuntimeError('RILL-R003', `Method .${node.name} not available on callable (invoke with -> $() first)`, this.getNodeLocation(node), { methodName: node.name, receiverType: 'callable' });
             }
             // IR-3: .name on type values returns the typeName string (method path)
-            // IR-4: .signature on type values returns formatStructuralType(structure)
+            // IR-4: .signature on type values returns formatStructure(structure)
             if (isTypeValue(receiver)) {
                 if (node.name === 'name') {
                     return receiver.typeName;
                 }
                 if (node.name === 'signature') {
-                    return formatStructuralType(receiver.structure);
+                    return formatStructure(receiver.structure);
                 }
             }
             const args = await this.evaluateArgs(node.args);
@@ -617,10 +937,10 @@ function createClosuresMixin(Base) {
                 throw new RuntimeError('RILL-R009', `Property '${node.name}' not found on type value (available: name, signature)`, this.getNodeLocation(node), { property: node.name, type: 'type value' });
             }
             // RILL-R003: method exists on other types but not this receiver's type.
-            // Methods in UNVALIDATED_METHOD_RECEIVERS handle their own receiver validation
+            // Methods in unvalidatedMethodReceivers handle their own receiver validation
             // with specific error messages; skip generic RILL-R003 for them and let the
             // method body run its own check (they exist in at least one type dict).
-            if (!UNVALIDATED_METHOD_RECEIVERS.has(node.name)) {
+            if (!this.ctx.unvalidatedMethodReceivers.has(node.name)) {
                 const supportedTypes = [];
                 for (const [dictType, dict] of this.ctx.typeMethodDicts) {
                     if (dict[node.name] !== undefined) {
@@ -632,14 +952,14 @@ function createClosuresMixin(Base) {
                 }
             }
             else {
-                // UNVALIDATED_METHOD_RECEIVERS: dispatch to the method in ANY type dict so the
+                // unvalidatedMethodReceivers: dispatch to the method in ANY type dict so the
                 // method body can run its own custom receiver validation and error message.
                 for (const [, dict] of this.ctx.typeMethodDicts) {
                     const fallbackMethod = dict[node.name];
                     if (fallbackMethod !== undefined &&
                         isApplicationCallable(fallbackMethod)) {
                         try {
-                            // UNVALIDATED_METHOD_RECEIVERS handle their own receiver validation.
+                            // Unvalidated methods handle their own receiver validation.
                             // Build named record with receiver so buildMethodEntry extracts it correctly;
                             // the method body performs its own receiver type check with a custom error.
                             const fbMethodArgs = { receiver };
@@ -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) });
             }
@@ -706,7 +1030,7 @@ function createClosuresMixin(Base) {
                 const typeValue = Object.freeze({
                     __rill_type: true,
                     typeName: inferType(value),
-                    structure: inferStructuralType(value),
+                    structure: inferStructure(value),
                 });
                 return typeValue;
             }
@@ -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) });
@@ -728,10 +1068,10 @@ function createClosuresMixin(Base) {
             if (key === 'input') {
                 // Untyped host callables have params set to undefined at runtime (see callable() factory)
                 if (value.params === undefined) {
-                    return rillTypeToTypeValue({ type: 'ordered', fields: [] });
+                    return structureToTypeValue({ kind: 'ordered', fields: [] });
                 }
-                const fields = value.params.map((param) => paramToFieldDef(param.name, param.type ?? { type: 'any' }, param.defaultValue));
-                return rillTypeToTypeValue({ type: 'ordered', fields });
+                const fields = value.params.map((param) => paramToFieldDef(param.name, param.type ?? { kind: 'any' }, param.defaultValue));
+                return structureToTypeValue({ kind: 'ordered', fields });
             }
             // IR-3: ^output reads callable.returnType directly for all kinds
             if (key === 'output') {
@@ -894,7 +1234,7 @@ function createClosuresMixin(Base) {
                 const paramEntry = {};
                 // Add type field if param has type annotation
                 if (param.type !== undefined) {
-                    paramEntry['type'] = formatStructuralType(param.type);
+                    paramEntry['type'] = formatStructure(param.type);
                 }
                 // Add __annotations field if param has parameter-level annotations
                 if (Object.keys(param.annotations).length > 0) {