@rcrsr/rill 0.17.0 → 0.18.0

package/dist/ast-nodes.d.ts

@@ -129,6 +129,15 @@ export interface BreakNode extends BaseNode {
 export interface ReturnNode extends BaseNode {
     readonly type: 'Return';
 }
+/**
+ * Yield: emit value from a stream closure.
+ * Used as chain terminator: $x -> yield
+ * Or bare: yield (implicit $ -> yield)
+ * Only valid inside a closure with :stream(T):R return type annotation.
+ */
+export interface YieldNode extends BaseNode {
+    readonly type: 'Yield';
+}
 /**
  * Pass: pass through pipe value unchanged.
  * Used as chain terminator: $x -> pass
@@ -157,8 +166,8 @@ export interface ErrorNode extends BaseNode {
     readonly message: StringLiteralNode | null;
 }
 export type ExpressionNode = PipeChainNode;
-/** Chain terminator: capture, break, or return */
-export type ChainTerminator = CaptureNode | BreakNode | ReturnNode;
+/** Chain terminator: capture, break, return, or yield */
+export type ChainTerminator = CaptureNode | BreakNode | ReturnNode | YieldNode;
 export interface PipeChainNode extends BaseNode {
     readonly type: 'PipeChain';
     readonly head: ArithHead;
@@ -244,7 +253,7 @@ export interface DictEntryNode extends BaseNode {
  */
 export interface TypeConstructorNode extends BaseNode {
     readonly type: 'TypeConstructor';
-    readonly constructorName: 'list' | 'dict' | 'tuple' | 'ordered';
+    readonly constructorName: 'list' | 'dict' | 'tuple' | 'ordered' | 'stream';
     readonly args: FieldArg[];
 }
 /**
@@ -797,8 +806,9 @@ export interface UseExprNode extends BaseNode {
     readonly closureAnnotation: ReadonlyArray<{
         readonly name: string;
         readonly typeRef: TypeRef;
+        readonly defaultValue?: LiteralNode;
     }> | null;
 }
 export type SimplePrimaryNode = LiteralNode | VariableNode | HostCallNode | MethodCallNode | BlockNode | BinaryExprNode | UnaryExprNode | GroupedExprNode | PostfixExprNode | TypeAssertionNode | TypeCheckNode;
-export type ASTNode = ScriptNode | FrontmatterNode | ClosureNode | ClosureParamNode | StatementNode | CaptureNode | BreakNode | ReturnNode | PassNode | AssertNode | PipeChainNode | PostfixExprNode | MethodCallNode | InvokeNode | AnnotationAccessNode | HostCallNode | HostRefNode | ClosureCallNode | PipeInvokeNode | VariableNode | ConditionalNode | WhileLoopNode | DoWhileLoopNode | BlockNode | StringLiteralNode | InterpolationNode | NumberLiteralNode | BoolLiteralNode | ListSpreadNode | DictNode | DictEntryNode | BinaryExprNode | UnaryExprNode | GroupedExprNode | DestructureNode | DestructPatternNode | SliceNode | TypeAssertionNode | TypeCheckNode | TypeConstructorNode | ClosureSigLiteralNode | AnnotatedStatementNode | AnnotatedExprNode | NamedArgNode | SpreadArgNode | EachExprNode | MapExprNode | FoldExprNode | FilterExprNode | RecoveryErrorNode | ErrorNode | TypeNameExprNode | ListLiteralNode | DictLiteralNode | TupleLiteralNode | OrderedLiteralNode | DestructNode | ConvertNode | UseExprNode;
+export type ASTNode = ScriptNode | FrontmatterNode | ClosureNode | ClosureParamNode | StatementNode | CaptureNode | BreakNode | ReturnNode | YieldNode | PassNode | AssertNode | PipeChainNode | PostfixExprNode | MethodCallNode | InvokeNode | AnnotationAccessNode | HostCallNode | HostRefNode | ClosureCallNode | PipeInvokeNode | VariableNode | ConditionalNode | WhileLoopNode | DoWhileLoopNode | BlockNode | StringLiteralNode | InterpolationNode | NumberLiteralNode | BoolLiteralNode | ListSpreadNode | DictNode | DictEntryNode | BinaryExprNode | UnaryExprNode | GroupedExprNode | DestructureNode | DestructPatternNode | SliceNode | TypeAssertionNode | TypeCheckNode | TypeConstructorNode | ClosureSigLiteralNode | AnnotatedStatementNode | AnnotatedExprNode | NamedArgNode | SpreadArgNode | EachExprNode | MapExprNode | FoldExprNode | FilterExprNode | RecoveryErrorNode | ErrorNode | TypeNameExprNode | ListLiteralNode | DictLiteralNode | TupleLiteralNode | OrderedLiteralNode | DestructNode | ConvertNode | UseExprNode;
 export {};

package/dist/ast-unions.d.ts

@@ -2,4 +2,4 @@
  * AST Type Unions
  * String union of all AST node type literals.
  */
-export type NodeType = 'Script' | 'Frontmatter' | 'Closure' | 'ClosureParam' | 'Statement' | 'PipeChain' | 'PostfixExpr' | 'MethodCall' | 'Invoke' | 'AnnotationAccess' | 'HostCall' | 'HostRef' | 'ClosureCall' | 'PipeInvoke' | 'Variable' | 'Capture' | 'Conditional' | 'WhileLoop' | 'DoWhileLoop' | 'Block' | 'StringLiteral' | 'Interpolation' | 'NumberLiteral' | 'BoolLiteral' | 'ListSpread' | 'Dict' | 'DictEntry' | 'Break' | 'Return' | 'Pass' | 'Assert' | 'BinaryExpr' | 'UnaryExpr' | 'GroupedExpr' | 'Destructure' | 'DestructPattern' | 'Slice' | 'TypeAssertion' | 'TypeCheck' | 'AnnotatedStatement' | 'AnnotatedExpr' | 'NamedArg' | 'SpreadArg' | 'EachExpr' | 'MapExpr' | 'FoldExpr' | 'FilterExpr' | 'RecoveryError' | 'Error' | 'TypeNameExpr' | 'TypeConstructor' | 'ClosureSigLiteral' | 'ListLiteral' | 'DictLiteral' | 'TupleLiteral' | 'OrderedLiteral' | 'Destruct' | 'Convert' | 'UseExpr';
+export type NodeType = 'Script' | 'Frontmatter' | 'Closure' | 'ClosureParam' | 'Statement' | 'PipeChain' | 'PostfixExpr' | 'MethodCall' | 'Invoke' | 'AnnotationAccess' | 'HostCall' | 'HostRef' | 'ClosureCall' | 'PipeInvoke' | 'Variable' | 'Capture' | 'Conditional' | 'WhileLoop' | 'DoWhileLoop' | 'Block' | 'StringLiteral' | 'Interpolation' | 'NumberLiteral' | 'BoolLiteral' | 'ListSpread' | 'Dict' | 'DictEntry' | 'Break' | 'Return' | 'Yield' | 'Pass' | 'Assert' | 'BinaryExpr' | 'UnaryExpr' | 'GroupedExpr' | 'Destructure' | 'DestructPattern' | 'Slice' | 'TypeAssertion' | 'TypeCheck' | 'AnnotatedStatement' | 'AnnotatedExpr' | 'NamedArg' | 'SpreadArg' | 'EachExpr' | 'MapExpr' | 'FoldExpr' | 'FilterExpr' | 'RecoveryError' | 'Error' | 'TypeNameExpr' | 'TypeConstructor' | 'ClosureSigLiteral' | 'ListLiteral' | 'DictLiteral' | 'TupleLiteral' | 'OrderedLiteral' | 'Destruct' | 'Convert' | 'UseExpr';

package/dist/constants.d.ts

@@ -10,4 +10,4 @@
  * - Parser: array iteration for token validation
  * - Runtime: Set-based O(1) membership lookup
  */
-export declare const VALID_TYPE_NAMES: readonly ["string", "number", "bool", "closure", "list", "dict", "tuple", "ordered", "vector", "any", "type", "iterator"];
+export declare const VALID_TYPE_NAMES: readonly ["string", "number", "bool", "closure", "list", "dict", "tuple", "ordered", "vector", "any", "type", "iterator", "stream"];

package/dist/constants.js

@@ -26,4 +26,5 @@ export const VALID_TYPE_NAMES = [
     'any',
     'type',
     'iterator',
+    'stream',
 ];

package/dist/error-registry.js

@@ -228,6 +228,24 @@ const ERROR_DEFINITIONS = [
             },
         ],
     },
+    {
+        errorId: 'RILL-P006',
+        category: 'parse',
+        description: 'Invalid syntax in context',
+        messageTemplate: '{message}',
+        cause: 'A syntactic construct was used in a context where it is not allowed.',
+        resolution: 'Check that the construct is used in the correct context.',
+        examples: [
+            {
+                description: 'Spread in unsupported position',
+                code: '$x.method(...$args)  # spread not supported in method calls',
+            },
+            {
+                description: 'yield outside stream closure',
+                code: '|x| yield  # yield requires :stream() return type',
+            },
+        ],
+    },
     {
         errorId: 'RILL-P007',
         category: 'parse',
@@ -1330,6 +1348,216 @@ const ERROR_DEFINITIONS = [
             },
         ],
     },
+    // Type conversion: string to number (RILL-R064)
+    {
+        errorId: 'RILL-R064',
+        category: 'runtime',
+        description: 'Cannot convert string to number',
+        messageTemplate: 'Cannot convert string "{value}" to number',
+        cause: 'The string value is not a valid numeric representation or is empty/whitespace.',
+        resolution: 'Ensure the string contains a valid number before converting. Use as(number) only on numeric strings.',
+        examples: [
+            {
+                description: 'Non-numeric string conversion',
+                code: '"hello" -> as(number)  # Error: not a valid number',
+            },
+        ],
+    },
+    // Type conversion: string to bool (RILL-R065)
+    {
+        errorId: 'RILL-R065',
+        category: 'runtime',
+        description: 'Cannot convert string to bool',
+        messageTemplate: 'Cannot convert string "{value}" to bool',
+        cause: 'Only the strings "true" and "false" can convert to bool.',
+        resolution: 'Use the exact strings "true" or "false" for bool conversion.',
+        examples: [
+            {
+                description: 'Invalid bool string',
+                code: '"yes" -> as(bool)  # Error: only "true"/"false" allowed',
+            },
+        ],
+    },
+    // Type conversion: number to bool (RILL-R066)
+    {
+        errorId: 'RILL-R066',
+        category: 'runtime',
+        description: 'Cannot convert number to bool',
+        messageTemplate: 'Cannot convert number {value} to bool',
+        cause: 'Only the numbers 0 and 1 can convert to bool. Other numeric values have no bool equivalent.',
+        resolution: 'Use 0 (false) or 1 (true) for number-to-bool conversion.',
+        examples: [
+            {
+                description: 'Non-binary number conversion',
+                code: '42 -> as(bool)  # Error: only 0 and 1 allowed',
+            },
+        ],
+    },
+    // JSON serialization: value not serializable (RILL-R067)
+    {
+        errorId: 'RILL-R067',
+        category: 'runtime',
+        description: 'Value is not JSON-serializable',
+        messageTemplate: '{typeName} are not JSON-serializable',
+        cause: 'The value type cannot be represented in JSON. Only strings, numbers, bools, lists, and dicts serialize.',
+        resolution: 'Convert the value to a serializable type before JSON operations. Extract data from closures or iterators first.',
+        examples: [
+            {
+                description: 'Closure in JSON context',
+                code: '|x| $x + 1 -> as(string)  # Error: closures not serializable',
+            },
+        ],
+    },
+    // Method registration: frozen type registration (RILL-R068)
+    {
+        errorId: 'RILL-R068',
+        category: 'runtime',
+        description: 'Type registration is frozen',
+        messageTemplate: "Cannot populate methods on type '{typeName}': registration is frozen",
+        cause: 'The type registration object was deep-frozen, preventing method assignment.',
+        resolution: 'Ensure type registrations are not deep-frozen before calling populateBuiltinMethods.',
+        examples: [
+            {
+                description: 'Frozen registration object',
+                code: '# Object.freeze(registration) prevents method population',
+            },
+        ],
+    },
+    // Context validation: function missing description (RILL-R069)
+    {
+        errorId: 'RILL-R069',
+        category: 'runtime',
+        description: 'Function missing required description',
+        messageTemplate: "Function '{name}' requires description (requireDescriptions enabled)",
+        cause: 'The requireDescriptions option is enabled but the function has no description.',
+        resolution: 'Add a description field to the function definition, or disable requireDescriptions.',
+        examples: [
+            {
+                description: 'Missing function description',
+                code: '# registerFunction("greet", { fn: ... }) with requireDescriptions: true',
+            },
+        ],
+    },
+    // Context validation: parameter missing description (RILL-R070)
+    {
+        errorId: 'RILL-R070',
+        category: 'runtime',
+        description: 'Parameter missing required description',
+        messageTemplate: "Parameter '{paramName}' of function '{functionName}' requires description (requireDescriptions enabled)",
+        cause: 'The requireDescriptions option is enabled but a parameter has no description annotation.',
+        resolution: 'Add a description annotation to each parameter, or disable requireDescriptions.',
+        examples: [
+            {
+                description: 'Missing parameter description',
+                code: '# param { name: "x", annotations: {} } with requireDescriptions: true',
+            },
+        ],
+    },
+    // Context validation: duplicate type registration (RILL-R071)
+    {
+        errorId: 'RILL-R071',
+        category: 'runtime',
+        description: 'Duplicate type registration',
+        messageTemplate: "Duplicate type registration '{typeName}'",
+        cause: 'Two type registrations share the same name. Each type name must be unique.',
+        resolution: 'Remove or rename the duplicate type registration.',
+        examples: [
+            {
+                description: 'Duplicate type name',
+                code: '# Two registrations both named "string"',
+            },
+        ],
+    },
+    // Context validation: missing format protocol (RILL-R072)
+    {
+        errorId: 'RILL-R072',
+        category: 'runtime',
+        description: 'Type missing format protocol',
+        messageTemplate: "Type '{typeName}' missing required format protocol",
+        cause: 'Every type registration must include a format function in its protocol.',
+        resolution: 'Add a format function to the type registration protocol.',
+        examples: [
+            {
+                description: 'Missing format in protocol',
+                code: '# TypeRegistration { name: "custom", protocol: {} } missing format',
+            },
+        ],
+    },
+    // Context validation: duplicate method on type (RILL-R073)
+    {
+        errorId: 'RILL-R073',
+        category: 'runtime',
+        description: 'Duplicate method on type',
+        messageTemplate: "Duplicate method '{methodName}' on type '{typeName}'",
+        cause: 'A method with the same name is registered twice on the same type.',
+        resolution: 'Remove the duplicate method registration or rename one of them.',
+        examples: [
+            {
+                description: 'Method registered twice',
+                code: '# Type "string" has two methods both named "split"',
+            },
+        ],
+    },
+    // Value validation: empty vector (RILL-R074)
+    {
+        errorId: 'RILL-R074',
+        category: 'runtime',
+        description: 'Vector requires at least one dimension',
+        messageTemplate: 'Vector data must have at least one dimension',
+        cause: 'An empty Float32Array was passed to createVector. Vectors must have at least one element.',
+        resolution: 'Provide a non-empty Float32Array when creating vectors.',
+        examples: [
+            {
+                description: 'Zero-dimension vector',
+                code: '# createVector(new Float32Array([]), "model") fails',
+            },
+        ],
+    },
+    // Extension validation: missing event field (RILL-R075)
+    {
+        errorId: 'RILL-R075',
+        category: 'runtime',
+        description: 'Event missing event field',
+        messageTemplate: 'Event must include non-empty event field',
+        cause: 'The event object passed to emitExtensionEvent has no event field or the field is empty.',
+        resolution: 'Include a non-empty string event field in the event object.',
+        examples: [
+            {
+                description: 'Empty event field',
+                code: '# emitExtensionEvent(ctx, { event: "" }) fails',
+            },
+        ],
+    },
+    // Module resolution: unknown module (RILL-R076)
+    {
+        errorId: 'RILL-R076',
+        category: 'runtime',
+        description: 'Unknown module resource',
+        messageTemplate: "Unknown module '{resource}'",
+        cause: 'The module resolver received a resource identifier it does not recognize.',
+        resolution: 'Use a valid module resource. The ext module resolver only handles the "ext" resource.',
+        examples: [
+            {
+                description: 'Invalid module resource',
+                code: 'use<module:unknown>  # Error: unknown module',
+            },
+        ],
+    },
+    // Callable validation: invalid default value (RILL-R077)
+    {
+        errorId: 'RILL-R077',
+        category: 'runtime',
+        description: 'Invalid parameter default value',
+        messageTemplate: "Invalid defaultValue for parameter '{paramName}': expected {expectedType}, got {actualType}",
+        cause: 'The default value type does not match the declared parameter type.',
+        resolution: 'Ensure the defaultValue matches the parameter type in the function definition.',
+        examples: [
+            {
+                description: 'Type mismatch in default',
+                code: '# param { name: "x", type: "number", defaultValue: "hello" }',
+            },
+        ],
+    },
     // Check Errors (RILL-C0xx)
     {
         errorId: 'RILL-C001',

package/dist/ext/crypto/index.js

@@ -7,7 +7,7 @@
 import crypto from 'node:crypto';
 import { RuntimeError } from '../../error-classes.js';
 import { toCallable } from '../../runtime/core/callable.js';
-import { rillTypeToTypeValue, } from '../../runtime/core/values.js';
+import { structureToTypeValue } from '../../runtime/core/values.js';
 // ============================================================
 // TYPES
 // ============================================================
@@ -119,7 +119,7 @@ export function createCryptoExtension(config = {}) {
                 ],
                 fn: hash,
                 annotations: { description: 'Hash content, returns hex output' },
-                returnType: rillTypeToTypeValue({ kind: 'string' }),
+                returnType: structureToTypeValue({ kind: 'string' }),
             }),
             hmac: toCallable({
                 params: [
@@ -140,13 +140,13 @@ export function createCryptoExtension(config = {}) {
                 annotations: {
                     description: 'Generate HMAC signature, returns hex output',
                 },
-                returnType: rillTypeToTypeValue({ kind: 'string' }),
+                returnType: structureToTypeValue({ kind: 'string' }),
             }),
             uuid: toCallable({
                 params: [],
                 fn: uuid,
                 annotations: { description: 'Generate random UUID v4' },
-                returnType: rillTypeToTypeValue({ kind: 'string' }),
+                returnType: structureToTypeValue({ kind: 'string' }),
             }),
             random: toCallable({
                 params: [
@@ -159,7 +159,7 @@ export function createCryptoExtension(config = {}) {
                 ],
                 fn: random,
                 annotations: { description: 'Generate random bytes as hex string' },
-                returnType: rillTypeToTypeValue({ kind: 'string' }),
+                returnType: structureToTypeValue({ kind: 'string' }),
             }),
         },
     };

package/dist/ext/exec/index.js

@@ -5,7 +5,7 @@
  * Each declared command becomes a function with argument validation and process isolation.
  */
 import { toCallable } from '../../runtime/core/callable.js';
-import { rillTypeToTypeValue, } from '../../runtime/core/values.js';
+import { structureToTypeValue } from '../../runtime/core/values.js';
 import { runCommand, } from './runner.js';
 // ============================================================
 // TYPES
@@ -134,7 +134,7 @@ export function createExecExtension(config) {
             annotations: {
                 description: commandConfig.description ?? `Execute ${commandName} command`,
             },
-            returnType: rillTypeToTypeValue({ kind: 'dict' }),
+            returnType: structureToTypeValue({ kind: 'dict' }),
         };
     }
     // ============================================================
@@ -154,7 +154,7 @@ export function createExecExtension(config) {
         params: [],
         fn: commands,
         annotations: { description: 'List all configured commands' },
-        returnType: rillTypeToTypeValue({ kind: 'list' }),
+        returnType: structureToTypeValue({ kind: 'list' }),
     };
     // ============================================================
     // DISPOSE FUNCTION

package/dist/ext/fetch/index.js

@@ -7,7 +7,7 @@
  */
 import { RuntimeError } from '../../error-classes.js';
 import { toCallable } from '../../runtime/core/callable.js';
-import { rillTypeToTypeValue, } from '../../runtime/core/values.js';
+import { structureToTypeValue } from '../../runtime/core/values.js';
 import { buildRequest, executeRequest, createSemaphore, } from './request.js';
 // ============================================================
 // TYPE DEFINITIONS
@@ -176,8 +176,8 @@ export function createFetchExtension(config) {
             };
         });
         const returnTypeValue = (endpointConfig.responseShape ?? defaultResponseShape) === 'full'
-            ? rillTypeToTypeValue({ kind: 'dict' })
-            : rillTypeToTypeValue({ kind: 'any' });
+            ? structureToTypeValue({ kind: 'dict' })
+            : structureToTypeValue({ kind: 'any' });
         const hostFunctionDef = {
             params: rillParams,
             fn: endpointFn,
@@ -211,7 +211,7 @@ export function createFetchExtension(config) {
         params: [],
         fn: endpoints,
         annotations: { description: 'List configured endpoints' },
-        returnType: rillTypeToTypeValue({ kind: 'list' }),
+        returnType: structureToTypeValue({ kind: 'list' }),
     };
     // ============================================================
     // DISPOSAL

package/dist/ext/fetch/request.js

@@ -253,10 +253,10 @@ export async function executeRequest(url, options, config, namespace, responseSh
                 const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
                 try {
                     // Execute fetch request
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     const response = await fetch(url, {
                         ...options,
                         signal: controller.signal,
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     });
                     clearTimeout(timeoutId);
                     // Handle HTTP errors