@rcrsr/rill 0.5.0 → 0.6.0

package/dist/types.js

@@ -3,55 +3,18 @@
  * Based on docs/grammar.ebnf
  */
 import { VERSION } from './generated/version-data.js';
-// ============================================================
-// ERROR HIERARCHY
-// ============================================================
-/** Error codes for programmatic handling */
-export const RILL_ERROR_CODES = {
-    // Parse errors
-    PARSE_UNEXPECTED_TOKEN: 'PARSE_UNEXPECTED_TOKEN',
-    PARSE_INVALID_SYNTAX: 'PARSE_INVALID_SYNTAX',
-    PARSE_INVALID_TYPE: 'PARSE_INVALID_TYPE',
-    // Runtime errors
-    RUNTIME_UNDEFINED_VARIABLE: 'RUNTIME_UNDEFINED_VARIABLE',
-    RUNTIME_UNDEFINED_FUNCTION: 'RUNTIME_UNDEFINED_FUNCTION',
-    RUNTIME_UNDEFINED_METHOD: 'RUNTIME_UNDEFINED_METHOD',
-    RUNTIME_UNDEFINED_ANNOTATION: 'RUNTIME_UNDEFINED_ANNOTATION',
-    RUNTIME_TYPE_ERROR: 'RUNTIME_TYPE_ERROR',
-    RUNTIME_TIMEOUT: 'RUNTIME_TIMEOUT',
-    RUNTIME_INVALID_PATTERN: 'RUNTIME_INVALID_PATTERN',
-    RUNTIME_AUTO_EXCEPTION: 'RUNTIME_AUTO_EXCEPTION',
-    RUNTIME_ABORTED: 'RUNTIME_ABORTED',
-    RUNTIME_PROPERTY_NOT_FOUND: 'RUNTIME_PROPERTY_NOT_FOUND',
-    RUNTIME_LIMIT_EXCEEDED: 'RUNTIME_LIMIT_EXCEEDED',
-    RUNTIME_ASSERTION_FAILED: 'RUNTIME_ASSERTION_FAILED',
-    RUNTIME_ERROR_RAISED: 'RUNTIME_ERROR_RAISED',
-    // Check errors
-    CHECK_FILE_NOT_FOUND: 'CHECK_FILE_NOT_FOUND',
-    CHECK_FILE_UNREADABLE: 'CHECK_FILE_UNREADABLE',
-    CHECK_INVALID_CONFIG: 'CHECK_INVALID_CONFIG',
-    CHECK_FIX_COLLISION: 'CHECK_FIX_COLLISION',
-};
 class ErrorRegistryImpl {
     byId;
-    byLegacyCode;
     constructor(definitions) {
         const idMap = new Map();
-        const codeMap = new Map();
         for (const def of definitions) {
             idMap.set(def.errorId, def);
-            const existing = codeMap.get(def.legacyCode) ?? [];
-            codeMap.set(def.legacyCode, [...existing, def]);
         }
         this.byId = idMap;
-        this.byLegacyCode = codeMap;
     }
     get(errorId) {
         return this.byId.get(errorId);
     }
-    getByLegacyCode(code) {
-        return this.byLegacyCode.get(code) ?? [];
-    }
     has(errorId) {
         return this.byId.has(errorId);
     }
@@ -67,216 +30,576 @@ const ERROR_DEFINITIONS = [
     // Lexer Errors (RILL-L0xx)
     {
         errorId: 'RILL-L001',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
         category: 'lexer',
         description: 'Unterminated string literal',
         messageTemplate: 'Unterminated string literal at {location}',
+        cause: 'String opened with quote but never closed before end of line or file.',
+        resolution: 'Add closing quote to complete the string, or use multiline strings with triple quotes (""") for multi-line content.',
+        examples: [
+            {
+                description: 'Missing closing quote on single line',
+                code: '"hello',
+            },
+            {
+                description: 'Newline inside single-quoted string',
+                code: '"hello\nworld"',
+            },
+        ],
     },
     {
         errorId: 'RILL-L002',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
         category: 'lexer',
         description: 'Invalid character',
         messageTemplate: 'Invalid character {char} at {location}',
+        cause: 'Character not recognized by the lexer (not part of Rill syntax).',
+        resolution: 'Remove or replace the invalid character. Common causes: unicode characters in identifiers, unsupported operators, or copy-paste artifacts.',
+        examples: [
+            {
+                description: 'Unicode character in code',
+                code: '$x → "value"  # → is not valid, use ->',
+            },
+            {
+                description: 'Backtick instead of quote',
+                code: '`hello`  # Use "hello" instead',
+            },
+        ],
     },
     {
         errorId: 'RILL-L003',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
         category: 'lexer',
         description: 'Invalid number format',
         messageTemplate: 'Invalid number format: {value}',
+        cause: 'Number contains invalid characters, multiple decimal points, or unsupported notation.',
+        resolution: 'Use valid number format: integers (123), decimals (1.5), or scientific notation (1e5). No underscores, trailing dots, or multiple decimals allowed.',
+        examples: [
+            {
+                description: 'Multiple decimal points',
+                code: '1.2.3',
+            },
+            {
+                description: 'Trailing decimal point',
+                code: '123.',
+            },
+            {
+                description: 'Leading zeros (octal notation not supported)',
+                code: '0123',
+            },
+        ],
     },
     {
         errorId: 'RILL-L004',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
         category: 'lexer',
         description: 'Unterminated multiline string',
         messageTemplate: 'Unterminated multiline string starting at {location}',
+        cause: 'Multiline string opened with triple quotes (""") but never closed.',
+        resolution: 'Add closing triple quotes (""") to complete the multiline string.',
+        examples: [
+            {
+                description: 'Missing closing triple quotes',
+                code: '"""hello\nworld',
+            },
+            {
+                description: 'Only two closing quotes instead of three',
+                code: '"""content""',
+            },
+        ],
     },
     {
         errorId: 'RILL-L005',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
         category: 'lexer',
         description: 'Invalid escape sequence',
         messageTemplate: 'Invalid escape sequence {sequence} at {location}',
+        cause: 'Backslash followed by unsupported character in string literal.',
+        resolution: 'Use valid escape sequences: \\n (newline), \\t (tab), \\\\ (backslash), \\" (quote), \\{ (brace). For literal backslash, use \\\\.',
+        examples: [
+            {
+                description: 'Invalid escape character',
+                code: '"hello\\xworld"  # \\x not supported',
+            },
+            {
+                description: 'Incomplete escape at end',
+                code: '"path\\',
+            },
+        ],
     },
     // Parse Errors (RILL-P0xx)
     {
         errorId: 'RILL-P001',
-        legacyCode: RILL_ERROR_CODES.PARSE_UNEXPECTED_TOKEN,
         category: 'parse',
         description: 'Unexpected token',
         messageTemplate: 'Unexpected token {token}, expected {expected}',
+        cause: 'Token appears in invalid position according to grammar rules.',
+        resolution: 'Check syntax at the indicated position. Common causes: missing operators, mismatched delimiters, or keywords in wrong context.',
+        examples: [
+            {
+                description: 'Missing pipe operator between expressions',
+                code: '"hello" "world"  # Missing -> between',
+            },
+            {
+                description: 'Statement starting with operator',
+                code: '-> "value"  # Missing left side',
+            },
+            {
+                description: 'Unexpected closing brace',
+                code: '{ "value" }}  # Extra closing brace',
+            },
+        ],
     },
     {
         errorId: 'RILL-P002',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
         category: 'parse',
         description: 'Unexpected end of input',
         messageTemplate: 'Unexpected end of input, expected {expected}',
+        cause: 'File or block ended while parser expected more tokens (incomplete expression or statement).',
+        resolution: 'Complete the incomplete construct. Common causes: unclosed blocks, incomplete pipe chains, or missing expression after operator.',
+        examples: [
+            {
+                description: 'Unclosed block',
+                code: '{ "value"',
+            },
+            {
+                description: 'Pipe with no target',
+                code: '"hello" ->',
+            },
+            {
+                description: 'Incomplete conditional',
+                code: '?($x > 0) "yes"  # Missing else branch',
+            },
+        ],
     },
     {
         errorId: 'RILL-P003',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_TYPE,
         category: 'parse',
         description: 'Invalid type annotation',
         messageTemplate: 'Invalid type annotation: {type}',
+        cause: 'Type name not recognized. Rill supports: string, number, bool, closure, list, dict, tuple.',
+        resolution: 'Use valid type name from supported set. Check spelling and casing (types are lowercase).',
+        examples: [
+            {
+                description: 'Uppercase type name',
+                code: '$x => String  # Use "string" not "String"',
+            },
+            {
+                description: 'Invalid type name',
+                code: '$x => int  # Use "number" for all numeric types',
+            },
+            {
+                description: 'Generic type syntax not supported',
+                code: '$x => list<string>  # Use "list" only',
+            },
+        ],
     },
     {
         errorId: 'RILL-P004',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
         category: 'parse',
         description: 'Invalid expression',
         messageTemplate: 'Invalid expression: {details}',
+        cause: 'Expression structure violates grammar rules or contains unsupported constructs.',
+        resolution: 'Check expression syntax. Common causes: invalid operator combinations, malformed literals, or unsupported language features.',
+        examples: [
+            {
+                description: 'Double operators',
+                code: '$x + + $y',
+            },
+            {
+                description: 'Assignment operator (not supported)',
+                code: '$x = 5  # Use "5 => $x" instead',
+            },
+        ],
     },
     {
         errorId: 'RILL-P005',
-        legacyCode: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
         category: 'parse',
         description: 'Missing delimiter',
         messageTemplate: 'Missing {delimiter}, found {found}',
+        cause: 'Expected closing delimiter (parenthesis, bracket, brace) not found.',
+        resolution: 'Add the missing delimiter. Check for proper nesting and matching pairs.',
+        examples: [
+            {
+                description: 'Missing closing parenthesis',
+                code: 'func($a, $b',
+            },
+            {
+                description: 'Missing closing bracket in tuple',
+                code: '[1, 2, 3',
+            },
+            {
+                description: 'Mismatched delimiters',
+                code: '{ "value"]  # Opened with { but closed with ]',
+            },
+        ],
+    },
+    {
+        errorId: 'RILL-P006',
+        category: 'parse',
+        description: 'Deprecated capture arrow syntax',
+        messageTemplate: 'The capture arrow syntax changed from :> to =>',
+        cause: 'Code uses old capture arrow syntax (:>) instead of current syntax (=>).',
+        resolution: 'Replace :> with => for all variable captures. This change was made in version 0.4.0.',
+        examples: [
+            {
+                description: 'Old capture syntax',
+                code: '"value" :> $x  # Change to "value" => $x',
+            },
+            {
+                description: 'Old typed capture',
+                code: '5 :> $x:number  # Change to 5 => $x:number',
+            },
+        ],
     },
     // Runtime Errors (RILL-R0xx)
     {
         errorId: 'RILL-R001',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_TYPE_ERROR,
         category: 'runtime',
         description: 'Parameter type mismatch',
         messageTemplate: 'Function {function} expects parameter {param} (position {position}) to be {expected}, got {actual}',
+        cause: 'Argument passed to function does not match declared parameter type.',
+        resolution: 'Pass value of correct type, or convert the value before passing. Check function signature for expected types.',
+        examples: [
+            {
+                description: 'String passed to number parameter',
+                code: '|x: number| $x * 2\n"5" -> $()',
+            },
+            {
+                description: 'Number passed to string method',
+                code: '123 -> .split(",")  # split expects string',
+            },
+        ],
     },
     {
         errorId: 'RILL-R002',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_TYPE_ERROR,
         category: 'runtime',
         description: 'Operator type mismatch',
         messageTemplate: 'Operator {operator} cannot be applied to {leftType} and {rightType}',
+        cause: 'Binary operator applied to incompatible types. Rill does not perform implicit type coercion.',
+        resolution: 'Ensure both operands are compatible types. Convert values explicitly if needed using type-specific methods.',
+        examples: [
+            {
+                description: 'Adding string and number',
+                code: '"5" + 1  # Error: no implicit coercion',
+            },
+            {
+                description: 'Comparing different types',
+                code: '"10" == 10  # Always false, no coercion',
+            },
+            {
+                description: 'Arithmetic on non-numbers',
+                code: '"hello" * 2',
+            },
+        ],
     },
     {
         errorId: 'RILL-R003',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_TYPE_ERROR,
         category: 'runtime',
         description: 'Method receiver type mismatch',
         messageTemplate: 'Method {method} cannot be called on {type}',
+        cause: 'Method called on value of wrong type. String methods require strings, list methods require lists, etc.',
+        resolution: 'Call method on correct type, or convert value before calling. Check method documentation for receiver type.',
+        examples: [
+            {
+                description: 'String method on number',
+                code: '123 -> .upper()  # upper() is string method',
+            },
+            {
+                description: 'List method on string',
+                code: '"hello" -> .first()  # first() is list method',
+            },
+        ],
     },
     {
         errorId: 'RILL-R004',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_TYPE_ERROR,
         category: 'runtime',
         description: 'Type conversion failure',
         messageTemplate: 'Cannot convert {value} to {targetType}',
+        cause: 'Value cannot be converted to target type (invalid format or incompatible types).',
+        resolution: 'Ensure value has valid format for target type. For string-to-number: check numeric format. For parse operations: validate input structure.',
+        examples: [
+            {
+                description: 'Invalid number string',
+                code: '"abc" -> to_number()  # Not a valid number',
+            },
+            {
+                description: 'Invalid JSON',
+                code: '"{bad json}" -> parse_json()',
+            },
+        ],
     },
     {
         errorId: 'RILL-R005',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_UNDEFINED_VARIABLE,
         category: 'runtime',
         description: 'Undefined variable',
         messageTemplate: 'Variable {name} is not defined',
+        cause: 'Variable referenced before assignment, or variable name misspelled.',
+        resolution: 'Assign value to variable before use (value => $var), or check spelling. Variables must be captured before reference.',
+        examples: [
+            {
+                description: 'Variable used before assignment',
+                code: '$count + 1  # $count never assigned',
+            },
+            {
+                description: 'Typo in variable name',
+                code: '"hi" => $mesage\n$message  # Typo: mesage vs message',
+            },
+            {
+                description: 'Variable out of scope',
+                code: '{ "local" => $x }\n$x  # $x only exists inside block',
+            },
+        ],
     },
     {
         errorId: 'RILL-R006',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_UNDEFINED_FUNCTION,
         category: 'runtime',
         description: 'Undefined function',
         messageTemplate: 'Function {name} is not defined',
+        cause: 'Function name not found in runtime context (not a built-in or host-provided function).',
+        resolution: 'Check function name spelling, ensure function is provided by host application, or verify module imports.',
+        examples: [
+            {
+                description: 'Misspelled function name',
+                code: 'leng("hello")  # Should be length()',
+            },
+            {
+                description: 'Missing host function',
+                code: 'app::fetch($url)  # Host must provide app::fetch',
+            },
+        ],
     },
     {
         errorId: 'RILL-R007',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_UNDEFINED_METHOD,
         category: 'runtime',
         description: 'Undefined method',
         messageTemplate: 'Method {method} is not defined on {type}',
+        cause: 'Method name not supported for the given type, or method name misspelled.',
+        resolution: 'Check method documentation for the type. Verify method name spelling and that it exists for this type.',
+        examples: [
+            {
+                description: 'Method not available on type',
+                code: '123 -> .trim()  # trim() only on strings',
+            },
+            {
+                description: 'Misspelled method name',
+                code: '"hello" -> .upcase()  # Should be .upper()',
+            },
+        ],
     },
     {
         errorId: 'RILL-R008',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_UNDEFINED_ANNOTATION,
         category: 'runtime',
         description: 'Undefined annotation',
         messageTemplate: 'Annotation {key} is not defined',
+        cause: 'Annotation key accessed but not set on statement or parameter.',
+        resolution: 'Set annotation before accessing (^(key: value)), or check annotation key spelling.',
+        examples: [
+            {
+                description: 'Accessing undefined annotation',
+                code: '$stmt.^timeout  # No ^(timeout: ...) set',
+            },
+        ],
     },
     {
         errorId: 'RILL-R009',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_PROPERTY_NOT_FOUND,
         category: 'runtime',
         description: 'Property not found',
         messageTemplate: 'Property {property} not found on {type}',
+        cause: 'Dict key or tuple index does not exist in the value.',
+        resolution: 'Check property name spelling, verify the property exists, or use null-coalescing (??) to provide default. For safe access, use .? operator.',
+        examples: [
+            {
+                description: 'Missing dict key',
+                code: '[name: "x"] -> .age  # age key not in dict',
+            },
+            {
+                description: 'Index out of bounds',
+                code: '[1, 2, 3] -> [5]  # Only 3 elements (0-2)',
+            },
+            {
+                description: 'Safe alternative',
+                code: '[name: "x"] -> .age ?? 0  # Returns 0 if missing',
+            },
+        ],
     },
     {
         errorId: 'RILL-R010',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_LIMIT_EXCEEDED,
         category: 'runtime',
         description: 'Iteration limit exceeded',
         messageTemplate: 'Iteration limit of {limit} exceeded',
+        cause: 'Loop or collection operation exceeded configured iteration limit (prevents infinite loops).',
+        resolution: 'Reduce data size, adjust iteration limit via RuntimeOptions, or check for infinite loop conditions.',
+        examples: [
+            {
+                description: 'Infinite loop without termination',
+                code: '(true) @ { "looping" }  # Never terminates',
+            },
+            {
+                description: 'Large collection with default limit',
+                code: 'range(0, 1000000) -> each |x| $x  # May exceed default limit',
+            },
+        ],
     },
     {
         errorId: 'RILL-R011',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_INVALID_PATTERN,
         category: 'runtime',
         description: 'Invalid regex pattern',
         messageTemplate: 'Invalid regex pattern: {pattern}',
+        cause: 'Regular expression pattern has invalid syntax or unsupported features.',
+        resolution: 'Fix regex syntax errors. Check for unescaped special characters, unclosed groups, or invalid quantifiers.',
+        examples: [
+            {
+                description: 'Unclosed group',
+                code: '"test" -> .match("(abc")  # Missing closing )',
+            },
+            {
+                description: 'Invalid quantifier',
+                code: '"test" -> .match("a{,5}")  # Empty min in range',
+            },
+        ],
     },
     {
         errorId: 'RILL-R012',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_TIMEOUT,
         category: 'runtime',
         description: 'Operation timeout',
         messageTemplate: 'Operation timed out after {timeout}ms',
+        cause: 'Function execution exceeded configured timeout duration.',
+        resolution: 'Increase timeout via RuntimeOptions, optimize slow operations, or add ^(timeout: ms) annotation to specific calls.',
+        examples: [
+            {
+                description: 'Slow host function',
+                code: 'app::slow_api()  # Times out if exceeds limit',
+            },
+            {
+                description: 'Setting higher timeout',
+                code: '^(timeout: 30000) app::slow_api()  # 30 seconds',
+            },
+        ],
     },
     {
         errorId: 'RILL-R013',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_ABORTED,
         category: 'runtime',
         description: 'Execution aborted',
         messageTemplate: 'Execution aborted by signal',
+        cause: 'Host application cancelled execution via AbortSignal.',
+        resolution: 'This is intentional cancellation, not an error. If unexpected, check host abort signal logic.',
+        examples: [
+            {
+                description: 'User cancellation in UI',
+                code: '# Long-running script cancelled by user',
+            },
+        ],
     },
     {
         errorId: 'RILL-R014',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_AUTO_EXCEPTION,
         category: 'runtime',
         description: 'Auto-exception triggered',
         messageTemplate: 'Auto-exception triggered: pattern {pattern} matched',
+        cause: 'Value matched auto-exception pattern (configured to halt on specific error patterns in output).',
+        resolution: 'Handle error condition that produced the matched pattern, or adjust auto-exception configuration.',
+        examples: [
+            {
+                description: 'API error response',
+                code: '# API returned "ERROR:" prefix, auto-exception configured to catch this',
+            },
+        ],
     },
     {
         errorId: 'RILL-R015',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_ASSERTION_FAILED,
         category: 'runtime',
         description: 'Assertion failed',
         messageTemplate: 'Assertion failed: {condition}',
+        cause: 'Assertion statement evaluated to false.',
+        resolution: 'Fix the condition causing assertion failure, or remove/adjust assertion if condition is incorrect.',
+        examples: [
+            {
+                description: 'Basic assertion',
+                code: 'assert $count > 0  # Fails if $count <= 0',
+            },
+            {
+                description: 'Assertion with message',
+                code: 'assert $age >= 18 "Must be adult"',
+            },
+        ],
     },
     {
         errorId: 'RILL-R016',
-        legacyCode: RILL_ERROR_CODES.RUNTIME_ERROR_RAISED,
         category: 'runtime',
         description: 'Error statement executed',
         messageTemplate: 'Error raised: {message}',
+        cause: 'Error statement executed explicitly in code.',
+        resolution: 'This is intentional error raising. Fix the condition that triggers the error statement, or handle the error case differently.',
+        examples: [
+            {
+                description: 'Explicit error',
+                code: 'error "Invalid configuration"',
+            },
+            {
+                description: 'Conditional error',
+                code: '($status == "failed") ? { error "Process failed" } ! "ok"',
+            },
+        ],
     },
     // Check Errors (RILL-C0xx)
     {
         errorId: 'RILL-C001',
-        legacyCode: RILL_ERROR_CODES.CHECK_FILE_NOT_FOUND,
         category: 'check',
         description: 'File not found',
         messageTemplate: 'File not found: {path}',
+        cause: 'Specified file path does not exist in filesystem.',
+        resolution: 'Verify file path is correct, check file exists, or create the file if it should exist.',
+        examples: [
+            {
+                description: 'Nonexistent file',
+                code: 'rill-check missing.rill',
+            },
+            {
+                description: 'Wrong file extension',
+                code: 'rill-check script.txt  # Should be script.rill',
+            },
+        ],
     },
     {
         errorId: 'RILL-C002',
-        legacyCode: RILL_ERROR_CODES.CHECK_FILE_UNREADABLE,
         category: 'check',
         description: 'File unreadable',
         messageTemplate: 'File unreadable: {path}',
+        cause: 'File exists but cannot be read (permission denied or IO error).',
+        resolution: 'Check file permissions, ensure read access, or verify file is not locked by another process.',
+        examples: [
+            {
+                description: 'Permission denied',
+                code: 'rill-check protected.rill  # File exists but no read permission',
+            },
+        ],
     },
     {
         errorId: 'RILL-C003',
-        legacyCode: RILL_ERROR_CODES.CHECK_INVALID_CONFIG,
         category: 'check',
         description: 'Invalid configuration',
         messageTemplate: 'Invalid configuration: {details}',
+        cause: 'Configuration file or options contain invalid values or structure.',
+        resolution: 'Fix configuration syntax, ensure all required fields are present, and values are of correct type.',
+        examples: [
+            {
+                description: 'Invalid JSON in config',
+                code: '# .rillrc.json contains malformed JSON',
+            },
+            {
+                description: 'Unknown config option',
+                code: '# Config contains unsupported option key',
+            },
+        ],
     },
     {
         errorId: 'RILL-C004',
-        legacyCode: RILL_ERROR_CODES.CHECK_FIX_COLLISION,
         category: 'check',
         description: 'Fix collision detected',
         messageTemplate: 'Fix collision detected for {location}',
+        cause: 'Multiple auto-fix rules attempt to modify the same source location.',
+        resolution: 'Apply fixes one at a time, or disable conflicting lint rules. Some fixes may need manual resolution.',
+        examples: [
+            {
+                description: 'Overlapping fix ranges',
+                code: '# Two rules try to fix same code section',
+            },
+        ],
     },
 ];
 /**
@@ -356,7 +679,7 @@ export function renderMessage(template, context) {
 /**
  * Generates documentation URL for an error ID.
  *
- * Format: https://github.com/rcrsr/rill/blob/v{version}/docs/88_errors.md#{errorId}
+ * Format: https://github.com/rcrsr/rill/blob/v{version}/docs/ref-errors.md#{errorId}
  * Error ID is lowercased in anchor.
  *
  * @param errorId - Error identifier (format: RILL-{category}{3-digit}, e.g., RILL-R001)
@@ -365,7 +688,7 @@ export function renderMessage(template, context) {
  *
  * @example
  * getHelpUrl("RILL-R001", "0.4.1")
- * // Returns: "https://github.com/rcrsr/rill/blob/v0.4.1/docs/88_errors.md#rill-r001"
+ * // Returns: "https://github.com/rcrsr/rill/blob/v0.4.1/docs/ref-errors.md#rill-r001"
  *
  * @example
  * getHelpUrl("invalid", "0.4.1")
@@ -385,7 +708,7 @@ export function getHelpUrl(errorId, version) {
     }
     // Build URL with lowercased errorId in anchor
     const anchor = errorId.toLowerCase();
-    return `https://github.com/rcrsr/rill/blob/v${version}/docs/88_errors.md#${anchor}`;
+    return `https://github.com/rcrsr/rill/blob/v${version}/docs/ref-errors.md#${anchor}`;
 }
 // ============================================================
 // ERROR FACTORY
@@ -426,9 +749,8 @@ export function createError(errorId, context, location) {
     // This is acceptable per spec - the error is still created, just without complete location info
     // Compute helpUrl from errorId using VERSION constant
     const helpUrl = getHelpUrl(errorId, VERSION);
-    // Create RillError with errorId, helpUrl, legacy code, and rendered message
+    // Create RillError with errorId, helpUrl, and rendered message
     return new RillError({
-        code: definition.legacyCode,
         errorId,
         helpUrl: helpUrl || undefined, // Convert empty string to undefined
         message,
@@ -441,18 +763,24 @@ export function createError(errorId, context, location) {
  * Provides structured data for host applications to format as needed.
  */
 export class RillError extends Error {
-    code;
     errorId;
     helpUrl;
     location;
     context;
     constructor(data) {
+        // EC-3: Missing errorId
+        if (!data.errorId) {
+            throw new TypeError('errorId is required');
+        }
+        // EC-4: Unknown errorId
+        if (!ERROR_REGISTRY.has(data.errorId)) {
+            throw new TypeError(`Unknown error ID: ${data.errorId}`);
+        }
         const locationStr = data.location
             ? ` at ${data.location.line}:${data.location.column}`
             : '';
         super(`${data.message}${locationStr}`);
         this.name = 'RillError';
-        this.code = data.code;
         this.errorId = data.errorId;
         this.helpUrl = data.helpUrl;
         this.location = data.location;
@@ -461,7 +789,6 @@ export class RillError extends Error {
     /** Get structured error data for custom formatting */
     toData() {
         return {
-            code: this.code,
             errorId: this.errorId,
             helpUrl: this.helpUrl,
             message: this.message.replace(/ at \d+:\d+$/, ''), // Strip location suffix
@@ -478,59 +805,52 @@ export class RillError extends Error {
 }
 /** Parse-time errors */
 export class ParseError extends RillError {
-    constructor(message, location, context, errorId) {
-        // When errorId provided, look up definition and derive legacyCode
-        if (errorId) {
-            const definition = ERROR_REGISTRY.get(errorId);
-            if (!definition) {
-                throw new TypeError(`Unknown error ID: ${errorId}`);
-            }
-            super({
-                code: definition.legacyCode,
-                errorId,
-                message,
-                location,
-                context,
-            });
+    constructor(errorId, message, location, context) {
+        // EC-7: Unknown errorId
+        const definition = ERROR_REGISTRY.get(errorId);
+        if (!definition) {
+            throw new TypeError(`Unknown error ID: ${errorId}`);
         }
-        else {
-            // Backward compatible: use default PARSE_INVALID_SYNTAX code
-            super({
-                code: RILL_ERROR_CODES.PARSE_INVALID_SYNTAX,
-                message,
-                location,
-                context,
-            });
+        // EC-8: Wrong category
+        if (definition.category !== 'parse') {
+            throw new TypeError(`Expected parse error ID, got: ${errorId}`);
         }
+        const helpUrl = getHelpUrl(errorId, VERSION);
+        super({
+            errorId,
+            helpUrl: helpUrl || undefined,
+            message,
+            location,
+            context,
+        });
         this.name = 'ParseError';
     }
 }
 /** Runtime execution errors */
 export class RuntimeError extends RillError {
-    constructor(code, message, location, context, errorId) {
-        // When errorId provided, look up definition and derive legacyCode
-        if (errorId) {
-            const definition = ERROR_REGISTRY.get(errorId);
-            if (!definition) {
-                throw new TypeError(`Unknown error ID: ${errorId}`);
-            }
-            super({
-                code: definition.legacyCode,
-                errorId,
-                message,
-                location,
-                context,
-            });
+    constructor(errorId, message, location, context) {
+        // Validate errorId exists in registry
+        const definition = ERROR_REGISTRY.get(errorId);
+        if (!definition) {
+            throw new TypeError(`Unknown error ID: ${errorId}`);
         }
-        else {
-            // Backward compatible: use provided code directly
-            super({ code, message, location, context });
+        // Validate errorId is a runtime error
+        if (definition.category !== 'runtime') {
+            throw new TypeError(`Expected runtime error ID, got: ${errorId}`);
         }
+        const helpUrl = getHelpUrl(errorId, VERSION);
+        super({
+            errorId,
+            helpUrl: helpUrl || undefined,
+            message,
+            location,
+            context,
+        });
         this.name = 'RuntimeError';
     }
     /** Create from an AST node */
-    static fromNode(code, message, node, context, errorId) {
-        return new RuntimeError(code, message, node?.span.start, context, errorId);
+    static fromNode(errorId, message, node, context) {
+        return new RuntimeError(errorId, message, node?.span.start, context);
     }
 }
 /** Timeout errors */
@@ -538,7 +858,7 @@ export class TimeoutError extends RuntimeError {
     functionName;
     timeoutMs;
     constructor(functionName, timeoutMs, location) {
-        super(RILL_ERROR_CODES.RUNTIME_TIMEOUT, `Function '${functionName}' timed out after ${timeoutMs}ms`, location, { functionName, timeoutMs });
+        super('RILL-R012', `Function '${functionName}' timed out after ${timeoutMs}ms`, location, { functionName, timeoutMs });
         this.name = 'TimeoutError';
         this.functionName = functionName;
         this.timeoutMs = timeoutMs;
@@ -549,7 +869,7 @@ export class AutoExceptionError extends RuntimeError {
     pattern;
     matchedValue;
     constructor(pattern, matchedValue, location) {
-        super(RILL_ERROR_CODES.RUNTIME_AUTO_EXCEPTION, `Auto-exception triggered: pattern '${pattern}' matched`, location, { pattern, matchedValue });
+        super('RILL-R014', `Auto-exception triggered: pattern '${pattern}' matched`, location, { pattern, matchedValue });
         this.name = 'AutoExceptionError';
         this.pattern = pattern;
         this.matchedValue = matchedValue;
@@ -558,7 +878,7 @@ export class AutoExceptionError extends RuntimeError {
 /** Abort errors (when execution is cancelled via AbortSignal) */
 export class AbortError extends RuntimeError {
     constructor(location) {
-        super(RILL_ERROR_CODES.RUNTIME_ABORTED, 'Execution aborted', location, {});
+        super('RILL-R013', 'Execution aborted', location, {});
         this.name = 'AbortError';
     }
 }
@@ -578,7 +898,7 @@ export const TOKEN_TYPES = {
     PIPE_VAR: 'PIPE_VAR', // $ (lone dollar sign)
     // Operators
     ARROW: 'ARROW', // ->
-    CAPTURE_ARROW: 'CAPTURE_ARROW', // :>
+    CAPTURE_ARROW: 'CAPTURE_ARROW', // =>
     DOT: 'DOT', // .
     QUESTION: 'QUESTION', // ?
     AT: 'AT', // @