@rcrsr/rill 0.5.0 → 0.6.1

package/README.md

@@ -1,36 +1,14 @@
-<p align="center">
-  <img src="docs/assets/logo.png" alt="rill logo" width="280">
-</p>
+# @rcrsr/rill
 
-*The workflow language designed for LLMs*
+Embeddable runtime for the [rill](https://github.com/rcrsr/rill) workflow language. Zero dependencies. Browser and Node.js compatible.
 
-> [!WARNING]
-> **This language is experimental.** While usable, there may be significant bugs. Breaking changes will occur until v1.0.
+> **Experimental.** Breaking changes will occur until v1.0.
 
-## The Problem
+## Install
 
-Give an LLM a general-purpose language and you get unpredictable edge cases — state drift from mutable variables, runaway loops, silent misgeneration that passes a linter but fails at runtime. The more expressive the language, the more ways generated code can go wrong. LLMs don't benefit from expressiveness the way humans do. A human might prefer Python's flexibility. An LLM just needs unambiguous rules and guardrails that make wrong code unrepresentable.
-
-Rill treats codegen reliability as a first-class design constraint. It's a language *for LLMs* that humans can read, audit, and learn — but the primary developer is meant to be an agent.
-
-Rill solves for AI platforms what Lua solves for game engines and Liquid solves for e-commerce: safe, user-authored logic — except the "user" is increasingly an LLM.
-
-## Why Rill?
-
-- **Embeddable.** Zero dependencies. [Integration](docs/14_host-integration.md) takes a few lines of code, browser or backend.
-- **Sandboxed.** No filesystem, no network, no `eval()`. The host controls the entire function surface, not just what's blocked.
-- **Bounded execution.** `^(limit: N)` annotations prevent runaway loops from exhausting LLM usage budgets.
-- **LLM-optimized syntax.** Ships with [EBNF grammar](docs/15_grammar.ebnf) and [LLM reference](docs/99_llm-reference.txt). No ambiguity for codegen — one way to do each thing.
-- **Intentionally constrained.** No null, no truthiness, sealed scopes, locked types. Removes the degrees of freedom where LLMs misgenerate.
-- **Built-in LLM output parsing.** [Auto-detect](docs/10_parsing.md) and parse JSON, XML, YAML, checklists from model responses.
-
-## Who Is This For?
-
-**Agentic or Workflow Platform builders** who want safe, LLM-authored workflows inside their apps.
-
-Rill is not a general-purpose language and it's intentionally constrained. For general application development, you'll want TypeScript, Python, or Go.
-
-Rill powers [Claude Code Runner](https://github.com/rcrsr/claude-code-runner), a rich automation tool for Claude Code.
+```bash
+npm install @rcrsr/rill
+```
 
 ## Quick Start
 
@@ -48,175 +26,123 @@ const ctx = createRuntimeContext({
       params: [{ name: 'message', type: 'string' }],
       fn: async (args) => await callYourLLM(args[0]),
     },
-    error: {
-      params: [{ name: 'message', type: 'string' }],
-      fn: (args) => { throw new Error(String(args[0])); },
-    },
   },
 });
 
 const result = await execute(parse(script), ctx);
+console.log(result.value);
 ```
 
-## Language Overview
+## API
 
-### Pipes
+### Core Pipeline
 
-Data flows forward through pipes (`app::*` denotes an application-specific host function call).
-
-```rill
-app::prompt("analyze this code") -> .trim -> log
 ```
-
-### Pattern-Driven Conditionals
-
-Branch based on content patterns. Ideal for parsing LLM output.
-
-```rill
-app::prompt("analyze code")
-  -> .contains("ERROR") ? app::error() ! app::process()
+Source Text → parse() → AST → execute() → Result
 ```
 
-### Bounded Loops
-
-`^(limit: N)` annotations prevent runaway execution. The host stays in control.
-
-```rill
-# Retry until non-empty, bail after 5 attempts
-^(limit: 5) "" -> ($ == "") @ {
-  app::prompt("Generate a summary")
-}
-```
-
-```rill
-# Bounded iteration
-^(limit: 100) $items -> each { "Processing: {$}" -> log }
-```
+| Export | Purpose |
+|--------|---------|
+| `parse(source)` | Parse rill source into an AST |
+| `execute(ast, ctx)` | Execute an AST with a runtime context |
+| `createRuntimeContext(opts)` | Create a configured runtime context |
+| `callable(fn, isProperty?)` | Wrap a function as a rill-callable value |
+| `prefixFunctions(prefix, fns)` | Namespace host functions (e.g., `app::`) |
 
-### Closures
+### Runtime Options
 
-First-class functions with captured environment.
-
-```rill
-|x| ($x * 2) :> $double
-[1, 2, 3] -> map $double  # [2, 4, 6]
-5 -> $double              # 10
-```
+```typescript
+const ctx = createRuntimeContext({
+  // Host functions available to scripts
+  functions: {
+    prompt: {
+      params: [{ name: 'text', type: 'string' }],
+      fn: async (args, ctx, location) => { /* ... */ },
+    },
+  },
 
-### Parallel Execution
+  // Variables injected into script scope
+  variables: {
+    config: { greeting: 'hello' },
+  },
 
-Fan out work concurrently. Results preserve order.
+  // Callbacks
+  callbacks: {
+    onLog: (value) => console.log(value),
+  },
 
-```rill
-# Parallel map with closure
-["security", "performance", "style"] -> map |aspect| {
-  app::prompt("Review for {$aspect} issues")
-}
-```
+  // Observability hooks
+  observability: {
+    onStepStart: (e) => { /* ... */ },
+    onStepEnd: (e) => { /* ... */ },
+  },
 
-```rill
-# Parallel filter with method
-["critical bug", "minor note", "critical fix"] -> filter .contains("critical")
+  // Execution limits
+  timeout: 30000,
+  signal: abortController.signal,
+});
 ```
 
-### LLM Output Parsing
+### Stepper API
 
-Built-in functions for extracting structured data from LLM responses.
+Step through execution one statement at a time:
 
-```rill
-# Auto-detect format (JSON, XML, YAML, checklist)
-"[1, 2, 3]" -> parse_auto -> .data  # [1, 2, 3]
-```
+```typescript
+import { parse, createRuntimeContext, createStepper } from '@rcrsr/rill';
 
-```rill
-# Extract fenced code blocks
-"```json\n[1,2]\n```" -> parse_fence("json") -> parse_json
-```
+const stepper = createStepper(parse(script), createRuntimeContext());
 
-```rill
-# Extract XML tags
-"<answer>42</answer>" -> parse_xml("answer")  # "42"
+let step;
+while (!(step = await stepper.next()).done) {
+  console.log(step.value);
+}
 ```
 
-### String Interpolation
+### Additional Exports
 
-Embed expressions in strings. Triple-quotes for multi-line.
+| Export | Purpose |
+|--------|---------|
+| `parseWithRecovery(source)` | Parse with error recovery (for editors) |
+| `tokenize(source)` | Tokenize source into a token stream |
+| `TOKEN_HIGHLIGHT_MAP` | Syntax highlighting category map |
+| `getLanguageReference()` | LLM-optimized language reference text |
+| `getDocumentationCoverage()` | Coverage stats for doc examples |
+| `getFunctions()` | List of built-in function metadata |
+| `VERSION` / `VERSION_INFO` | Runtime version string and metadata |
 
-```rill
-"world" -> "Hello, {$}!" -> log  # Hello, world!
-```
+### Error Handling
 
-```rill
-"x + 1" :> $code
-"""
-Analyze: {$code}
-Return: PASS or FAIL
-"""
+```typescript
+import { parse, execute, createRuntimeContext, AbortError } from '@rcrsr/rill';
+
+try {
+  const result = await execute(parse(script), ctx);
+} catch (err) {
+  if (err instanceof AbortError) {
+    // Execution was cancelled via signal
+  }
+  // Runtime errors include source location and error code
+}
 ```
 
-## Designed for LLM Codegen
-
-These aren't arbitrary constraints — they're guardrails for reliable codegen.
-
-| Design choice | Codegen rationale |
-|---------------|-------------------|
-| **No null/undefined** | Eliminates the edge cases LLMs most frequently hallucinate |
-| **No truthiness** | Forces explicit boolean checks — no silent type coercion bugs |
-| **Value semantics** | Deep copy, deterministic equality. Safe for serialization, caching, replay |
-| **Immutable scoping** | Parent variables are read-only in child scopes. Prevents state drift across iterations |
-| **`$` prefix on variables** | Single-pass parsing, no symbol table. `name()` is a host function, `$name` is a variable — zero ambiguity |
-| **Type locking** | Variables lock type on first assignment. Catches type hallucinations at the assignment site |
-| **Linear error handling** | No try/catch, no unwinding. `assert` and `error` are terminal — easy for models to place correctly |
-| **Loops as expressions** | `fold`, `each`, `(cond) @ {}` return state instead of mutating it. Aligns with step-by-step LLM reasoning |
-
-## What Our Target Users Say
-
-We asked LLMs to review Rill. They had opinions.
-
-> "Disciplined to the point of stubbornness, but in a good way. It trades familiarity for predictability."
-> — ChatGPT
-
-> "You've basically banned the most common footguns in scripting languages."
-> — Gemini
+### Type Guards
 
-> "It's possibly the first language I've seen where humans are the secondary audience."
-> — Claude
-
-## Core Syntax
-
-| Syntax | Description |
-|--------|-------------|
-| `->` | Pipe data forward |
-| `:>` | Capture and continue |
-| `$` | Current pipe value |
-| `.field` | Property access on `$` |
-| `cond ? a ! b` | Conditional |
-| `cond @ { }` | While loop |
-| `@ { } ? cond` | Do-while loop |
-| `each`, `map`, `filter` | Collection operators |
-| `fold(init)` | Reduction |
-| `\|args\| { }` | Closure |
-
-## Use Cases
-
-- **User-defined workflows.** Let power users script automation without exposing arbitrary code execution.
-- **Multi-phase pipelines.** Chain LLM calls with review gates between each step.
-- **Parallel agent fan-out.** Launch specialist agents concurrently, collect structured results.
-- **Edit-review loops.** Iterate until approval or `^(limit: N)` max attempts.
-
-See [Examples](docs/12_examples.md) for complete workflow patterns.
+| Export | Purpose |
+|--------|---------|
+| `isDict(value)` | Check if value is a rill dict |
+| `isTuple(value)` | Check if value is a rill tuple |
+| `isCallable(value)` | Check if value is any callable |
+| `isScriptCallable(value)` | Check if value is a script-defined closure |
+| `isApplicationCallable(value)` | Check if value is a host-provided callable |
 
 ## Documentation
 
-See [docs/00_INDEX.md](docs/00_INDEX.md) for full navigation.
-
 | Document | Description |
 |----------|-------------|
-| [Guide](docs/01_guide.md) | Beginner introduction |
-| [Reference](docs/11_reference.md) | Language specification |
-| [Examples](docs/12_examples.md) | Workflow patterns |
-| [Host Integration](docs/14_host-integration.md) | Embedding API |
-| [Design Principles](docs/18_design-principles.md) | Why Rill works the way it does |
+| [Host Integration](https://github.com/rcrsr/rill/blob/main/docs/integration-host.md) | Embedding guide |
+| [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) | Complete TypeScript API |
+| [Language Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-language.md) | Language specification |
+| [Extensions](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) | Reusable host function packages |
 
 ## License
 

package/dist/generated/introspection-data.d.ts

@@ -1,2 +1,2 @@
-export declare const LANGUAGE_REFERENCE = "RILL LANGUAGE REFERENCE\n=======================\n\nRill is designed to be generated by LLMs and understood by humans. The focus is on auditable LLM output, not ergonomic human authoring. It combines the flexibility of imperative languages with the strictness of declaritive specifications.\n\nSTRENGTHS AND USE CASES\n-----------------------\nStrengths:\n  - Unambiguous syntax: $ prefix, explicit operators, no implicit coercion\n  - Single-pass parseable: LLMs generate correct code without symbol tables\n  - Readable by humans: pipe chains show data flow left-to-right\n  - Safe defaults: immutable values, type locking, no null/undefined\n\nUse cases:\n  - Workflow orchestration: chain LLM calls, API requests, transformations\n  - State machines: (cond) @ { } loops with $ as state dict handle multi-state logic\n  - Data pipelines: each/map/filter/fold process collections declaratively\n  - Prompt engineering: parse LLM output with parse_json, parse_xml, parse_fence\n\nState machine pattern ($ carries state through iterations):\n  [state: \"init\", data: $input]\n    -> ($.state != \"done\") @ {\n      $.state -> [\n        init: { [state: \"process\", data: transform($.data)] },\n        process: { [state: \"done\", data: finalize($.data)] }\n      ]\n    }\n\nNAMING CONVENTION: snake_case\n-----------------------------\nUse snake_case for all identifiers:\n  $user_name, $item_list, $is_valid    # variables\n  $double_value, $cleanup_text         # closures\n  [first_name: \"x\", last_name: \"y\"]    # dict keys\n\nWHY VARIABLES USE $ PREFIX\n--------------------------\nThe $ prefix enables single-pass parsing without a symbol table:\n\n  name()    -> host function call\n  $name()   -> closure invocation\n  $name     -> variable reference\n  name      -> dict key literal\n\nWithout $, \"process(data)\" is ambiguous: is process a host function or stored\nclosure? Is data a variable or key? This would require tracking all declarations.\n\nAdditional disambiguation:\n  - Capture: :> $x requires $ for lookahead (avoids conflict with slice /<1:>)\n  - Destructure: *<$a, $b> marks variables vs skip patterns\n  - Dynamic access: $data.$key distinguishes variable-key from literal field\n  - Visual clarity: $total is always a variable, no context needed\n\nThis follows rill's \"no magic\" principle: syntax communicates intent explicitly.\n\nSPACING RULES\n-------------\nOperators:    space both sides       5 + 3, $x -> .upper, \"a\" :> $b\nParentheses:  no inner space         ($x + 1), ($ > 3) ? \"yes\"\nBraces:       space inside           { $x + 1 }, each { $ * 2 }\nBrackets:     no inner space         $list[0], $dict.items[1]\nLiterals:     space after , and :    [1, 2, 3], [name: \"x\", age: 30]\nClosures:     space after params     |x| ($x * 2), |a, b| { $a + $b }\nMethods:      no space before . or ( $str.upper(), $list.join(\", \")\nPipes:        space both sides       \"x\" -> .upper -> .len\nContinuations: indent 2 spaces       $data\n                                       -> .filter { $.active }\n                                       -> map { $.name }\n\nIMPLICIT $ SHORTHAND (always prefer)\n------------------------------------\n$.method()  ->  .method            \"x\" -> .upper  (not $.upper())\nfunc($)     ->  func               \"x\" -> log     (not log($))\n$fn($)      ->  $fn                5 -> $double   (not $double($))\n\nNO THROWAWAY CAPTURES\n---------------------\nDon't capture just to continue - use line continuation instead:\n  # avoid                          # good\n  \"x\" :> $a                        \"x\"\n  $a -> .upper :> $b                 -> .upper\n  $b -> .len                         -> .len\n\nOnly capture when the variable is reused later in the code.\n\nCRITICAL DIFFERENCES FROM MAINSTREAM LANGUAGES\n----------------------------------------------\n\n1. NO ASSIGNMENT OPERATOR\n   Wrong: x = 5\n   Right: 5 :> $x\n\n   Pipe (->): passes value to next operation\n   Capture (:>): stores value AND continues chain\n   Example: \"hello\" :> $x -> .upper :> $y   # $x=\"hello\", $y=\"HELLO\"\n\n2. NO NULL/UNDEFINED\n   Empty values (\"\", [], [:]) exist. \"No value\" cannot be represented.\n   Use ?? for defaults: $dict.field ?? \"default\"\n   Use .empty to check: $str -> .empty ? \"was empty\"\n\n3. NO TRUTHINESS\n   Conditions MUST be boolean. No implicit coercion.\n   Wrong: \"\" ? \"yes\" ! \"no\"\n   Right: \"\" -> .empty ? \"yes\" ! \"no\"\n   Wrong: 0 ? \"yes\" ! \"no\"\n   Right: (0 == 0) ? \"yes\" ! \"no\"\n\n   Negation (!) also requires boolean:\n   Right: !true                          # false\n   Right: \"hello\" -> .empty -> (!$)      # true (negates boolean from .empty)\n   Wrong: !\"hello\"                       # ERROR: Negation requires boolean, got string\n   Wrong: !0                             # ERROR: Negation requires boolean, got number\n\n4. VARIABLES LOCK TO FIRST TYPE\n   \"hello\" :> $x\n   42 :> $x        # ERROR: cannot assign number to string variable\n\n5. NO VARIABLE SHADOWING (CRITICAL FOR LOOPS)\n   Child scopes can READ parent variables but cannot WRITE or redeclare them.\n   Variables created inside blocks/loops do NOT leak out.\n\n   WRONG - this pattern NEVER works:\n     0 :> $count\n     [1, 2, 3] -> each { $count + 1 :> $count }  # creates LOCAL $count\n     $count                                       # still 0!\n\n   RIGHT - use $ or $@ as state carrier (see LOOP STATE PATTERNS below)\n\n6. NO EXCEPTIONS\n   Errors halt execution. No try/catch. Use conditionals for error handling.\n   Built-in: assert (validate condition), error (halt with message).\n\n7. VALUE SEMANTICS (no references)\n   All copies are deep. All comparisons are by value. No object identity.\n   [1, 2, 3] == [1, 2, 3]   # true (content equality)\n   [1, 2] :> $a\n   $a :> $b                  # $b is an independent deep copy\n   Mainstream habit to avoid: expecting two variables to share the same object.\n\nSYNTAX QUICK REFERENCE\n----------------------\n\nVariables:     $name (always prefixed with $)\nStrings:       \"hello {$var}\"          # interpolation with {}\n               \"\"\"...\"\"\"               # multiline (also interpolates)\nNumbers:       42, 3.14, -7\nBooleans:      true, false\nLists:         [1, 2, 3]\n               [...$list, 4]               # spread: inline list elements\nDicts:         [name: \"alice\", age: 30]    # identifier keys\n               [1: \"one\", 2: \"two\"]        # number keys (incl. negative: [-1: \"neg\"])\n               [true: \"yes\", false: \"no\"]  # boolean keys\n               [[\"a\", \"b\"]: 1]             # multi-key: [a: 1, b: 1]\n               [$keyVar: value]            # variable key (must eval to string)\n               [($expr): value]            # computed key (must eval to string)\nTuples:        *[1, 2, 3]              # for argument unpacking\nClosures:      |x|($x + 1)             # like lambda/arrow functions\nType annot:    \"hi\" :> $x:string       # lock type on capture\nComments:      # single line only\n\nPIPES AND $ BINDING\n-------------------\n\n$ is the current piped value. Its meaning depends on context:\n\n| Context                    | $ contains              |\n|----------------------------|-------------------------|\n| -> { body }                | piped value             |\n| -> each { }                | current item            |\n| (cond) @ { }               | accumulated value       |\n| @ { } ? cond               | accumulated value       |\n| cond ? { } ! { }           | tested value            |\n| -> ? { } ! { }             | piped value             |\n| ||{ $.field } in dict      | the containing dict     |\n| |x|{ } stored closure      | N/A - use parameters    |\n\nImplied $: bare .method() means $ -> .method()\nExample: \"hello\" -> .upper   # same as \"hello\" -> $.upper()\n\nCONTROL FLOW\n------------\n\nConditional (if-else):\n  cond ? then_expr ! else_expr\n  cond ? then_expr                    # else returns \"\"\n\nPiped conditional ($ becomes condition):\n  value -> ? then_expr ! else_expr\n\nCondition loop (NO \"while\" keyword - use @ operator):\n  init_value -> ($ < 10) @ { $ + 1 }  # $ is accumulator\n\nDo-condition loop (body runs at least once):\n  init_value -> @ { $ + 1 } ? ($ < 10)\n\nBreak (exits loop, returns collected results before break):\n  [1,2,3,4,5] -> each { ($ == 3) ? break; $ }  # returns [1, 2]\n\nReturn (exits block or script with value):\n  { 5 :> $x; ($x > 3) ? (\"big\" -> return); \"small\" }  # returns \"big\"\n  \"done\" -> return                                     # exits script with \"done\"\n\nAssert (validate condition, halt if false, pass through if true):\n  5 -> assert ($ > 0)                   # returns 5\n  -1 -> assert ($ > 0)                  # ERROR: Assertion failed\n  \"\" -> assert !.empty \"Input required\" # ERROR: Input required\n  $val -> assert $:?list \"Expected list\" # type validation\n\nError (halt execution immediately with message):\n  error \"Something went wrong\"           # halt with message\n  \"Operation failed\" -> error            # piped form (must be string)\n  error \"Status: {$code}\"               # interpolation works\n\nPass (returns $ unchanged, explicit no-op):\n  cond ? pass ! \"fallback\"               # preserve $ when condition true\n  cond ? \"value\" ! pass                  # preserve $ when condition false\n  \"data\" -> { [status: pass] }           # include $ in dict: [status: \"data\"]\n  [1, -2, 3] -> map { ($ > 0) ? pass ! 0 }  # [1, 0, 3]\n  Note: pass requires pipe context. Using pass without $ throws error.\n\nLOOP STATE PATTERNS (CRITICAL)\n------------------------------\nRill loops CANNOT modify outer variables. All state must flow through $ or $@.\n\nWRONG - outer variable modification (NEVER works):\n  0 :> $sum\n  [1, 2, 3] -> each { $sum + $ :> $sum }  # $sum unchanged!\n\nWRONG - \"while\" keyword does not exist:\n  while ($i < 10) { $i + 1 :> $i }        # SYNTAX ERROR\n\nRIGHT - use fold for reduction:\n  [1, 2, 3] -> fold(0) { $@ + $ }         # 6 ($@ is accumulator)\n\nRIGHT - use each(init) when you need both results AND accumulator:\n  [1, 2, 3] -> each(0) { $@ + $ }         # [1, 3, 6] (running totals)\n\nRIGHT - use (cond) @ { } with $ as state dict for multiple values:\n  [iter: 0, max: 3, text: $input, done: false]\n    -> (!$.done && $.iter < $.max) @ {\n      $.iter + 1 :> $i\n      process($.text) :> $result\n      $result.finished ? [iter: $i, max: $.max, text: $.text, done: true]\n                       ! [iter: $i, max: $.max, text: $result.text, done: false]\n    }\n  # Access final state: $.text, $.iter\n\nPattern summary:\n  - Single value accumulation     -> fold(init) { $@ + $ }\n  - Per-item results + running    -> each(init) { ... $@ ... }\n  - Multiple state values / while -> (cond) @ { } with $ as state dict\n  - \"while\" and \"for\" keywords    -> DO NOT EXIST\n\nCOLLECTION OPERATORS\n--------------------\n\n| Operator           | Execution  | Returns              | Break? |\n|--------------------|------------|----------------------|--------|\n| -> each { }        | sequential | all body results     | yes    |\n| -> each(i) { $@+$} | sequential | all with accumulator | yes    |\n| -> map { }         | parallel   | all body results     | NO     |\n| -> filter { }      | parallel   | matching elements    | NO     |\n| -> fold(i) { $@+$} | sequential | final result only    | yes    |\n\n$@ is the accumulator in each(init) and fold(init).\n\nMethod shorthand in collection operators:\n  [\"a\", \"b\"] -> map .upper            # [\"A\", \"B\"]\n  [\"\", \"x\"] -> filter (!.empty)       # [\"x\"]\n  [\"a\", \"b\"] -> map .pad_start(3, \"0\") # [\"00a\", \"00b\"] (with args)\n  [\"  HI  \"] -> map .trim.lower       # [\"hi\"] (chained methods)\n\nBody forms (all operators accept these):\n  -> each { $ * 2 }                   # block ($ is current element)\n  -> each ($ + 10)                    # grouped expression\n  -> each |x| ($x * 2)               # inline closure\n  -> each $double                     # variable closure\n  -> each .upper                      # method shorthand\n\nDict iteration ($ contains key and value fields):\n  [a: 1, b: 2] -> each { \"{$.key}={$.value}\" }   # [\"a=1\", \"b=2\"]\n  [a: 1, b: 5] -> filter { $.value > 2 }          # entries where value > 2\n\nString iteration (iterates over characters):\n  \"abc\" -> each { \"{$}!\" }            # [\"a!\", \"b!\", \"c!\"]\n  \"hello\" -> filter { $ != \"l\" }      # [\"h\", \"e\", \"o\"]\n\nCLOSURES\n--------\n\nBLOCK-CLOSURES vs EXPLICIT CLOSURES:\n\nTwo ways to create closures:\n\n1. Block-closures: { body } in expression position\n   { $ + 1 } :> $inc                  # implicit $ parameter\n   $inc(5)                            # 6\n   5 -> $inc                          # 6 (pipe invocation)\n   [x: { $ * 2 }]                     # dict value is closure\n   type({ \"hi\" })                     # \"closure\"\n\n2. Explicit closures: |params| body\n   |x|($x + 1) :> $inc                # named parameter\n   |a, b|($a + $b) :> $add            # multiple params\n   |x = 0|($x + 1) :> $inc_or_one     # default value\n   |x: number|($x + 1) :> $typed      # type annotation\n\nCRITICAL: { } vs ( ) distinction\n\n| Syntax       | Semantics              | Example                    |\n|--------------|------------------------|----------------------------|\n| { body }     | Deferred (closure)     | { $ + 1 } :> $fn  # closure |\n| ( expr )     | Eager (immediate eval) | ( 5 + 1 ) :> $x  # 6        |\n\nWhen to use:\n  { body } :> $fn     # store closure for later use\n  ( expr ) :> $x      # store result value immediately\n\nPIPE TARGET: { } creates closure then immediately invokes it:\n  5 -> { $ + 1 }      # 6 (create closure, invoke with 5)\n  5 -> ($ + 1)        # 6 (evaluate expression with $=5)\n  Same observable result, different mechanism. Error messages differ.\n\nBlock-closure invocation:\n  { $ + 1 } :> $inc\n  $inc(5)                             # direct call: 6\n  5 -> $inc                           # pipe call: 6\n  [1,2,3] -> map $inc                 # in collection op\n\nLATE BINDING: closures capture scope, not values. Variables resolve at call time.\n\n$ vs named params:\n  Use $ in inline pipes and loops:     \"hello\" -> { .upper }\n  Use named params in stored closures: |x| ($x * 2) :> $double\n  $ is undefined when a stored closure is called later \u2014 always use params.\n\nZero-param dict closures (methods):\n  [count: 3, double: ||{ $.count * 2 }] :> $obj\n  $obj.double                         # 6 ($ is bound to dict)\n\nPROPERTY ACCESS\n---------------\n\n$data.field                           # dict field\n$data[0], $data[-1]                   # list index (negative from end)\n$data.$key                            # variable as key\n$data.($i + 1)                        # computed key\n$data.(a || b)                        # try keys left-to-right\n$data.field ?? \"default\"              # default if missing\n$data.?field                          # existence check (boolean)\n$data.?$keyVar                        # variable existence check\n$data.?($expr)                        # computed existence check\n$data.?field&string                   # existence AND type check\n$data.?$key&number                    # variable existence + type check\n$data.?($a -> \"{$}_b\")&list           # computed existence + type check\n\nDISPATCH OPERATORS\n------------------\n\nDICT DISPATCH (single key):\nPipe a value to a dict to match keys and return associated values:\n  $val -> [apple: \"fruit\", carrot: \"veg\"]        # returns \"fruit\" if $val is \"apple\"\n  $val -> [apple: \"fruit\"] ?? \"not found\"         # default if no match\n  $method -> [[\"GET\", \"HEAD\"]: \"safe\", [\"POST\", \"PUT\"]: \"unsafe\"]  # multi-key dispatch\n\nMulti-key dispatch uses the same syntax as multi-key dict literals:\n  [[\"GET\", \"HEAD\"]: \"safe\"]                      # dict with keys \"GET\" and \"HEAD\" both = \"safe\"\n  \"GET\" -> [[\"GET\", \"HEAD\"]: \"safe\"]             # \"safe\" (matches \"GET\" key)\n\nType-aware matching (keys matched by value AND type):\n  1 -> [1: \"number\", \"1\": \"string\"]              # \"number\" (number key matches)\n  \"1\" -> [1: \"number\", \"1\": \"string\"]            # \"string\" (string key matches)\n  true -> [true: \"bool\", \"true\": \"str\"]          # \"bool\" (boolean key matches)\n\nLIST DISPATCH (index):\nPipe a number to a list to get element at index:\n  0 -> [\"first\", \"second\"]                        # \"first\"\n  -1 -> [\"first\", \"second\"]                       # \"second\" (last)\n  5 -> [\"a\", \"b\"] ?? \"not found\"                  # default if out of bounds\n\nHIERARCHICAL DISPATCH (path navigation):\nPipe a list of keys/indexes to navigate nested structures:\n  [\"name\", \"first\"] -> [name: [first: \"Alice\"]]   # \"Alice\" (dict path)\n  [0, 1] -> [[1, 2, 3], [4, 5, 6]]                 # 2 (list path)\n  [\"users\", 0, \"name\"] -> [users: [[name: \"Alice\"]]] # \"Alice\" (mixed)\n  [] -> [a: 1]                                    # [a: 1] (empty path = unchanged)\n  [\"a\", \"missing\"] -> [a: [x: 1]] ?? \"default\"    # \"default\" (missing key)\n\nPath elements: strings for dict keys, numbers for list indexes (negative supported).\nTerminal closures receive $ bound to final path key:\n  [\"req\", \"draft\"] -> [req: [draft: { \"key={$}\" }]]  # \"key=draft\"\n\nTYPE OPERATIONS\n---------------\n\n:type   - assert type (error if wrong): 42:number passes; \"x\":number errors\n:?type  - check type (boolean): 42:?number is true; \"x\":?number is false\n\nTypes: string, number, boolean, list, dict, tuple, closure\n\nCOMPARISON METHODS\n------------------\n\nMethods for readable comparisons in conditionals:\n  .eq(val)   ==          $v -> .eq(\"A\") ? \"match\"\n  .ne(val)   !=          $v -> .ne(\"\") ? \"has value\"\n  .lt(val)   <           $v -> .lt(10) ? \"small\"\n  .gt(val)   >           5 -> .gt(3) ? \"big\"\n  .le(val)   <=          10 -> .le(10) ? \"ok\"\n  .ge(val)   >=          $age -> .ge(18) ? \"adult\"\n\nOPERATOR PRECEDENCE (highest to lowest)\n---------------------------------------\n\n1.  Member access:   .field, [index]\n2.  Type operators:  :type, :?type\n3.  Unary:           -, !\n4.  Multiplicative:  *, /, %\n5.  Additive:        +, -\n6.  Comparison:      ==, !=, <, >, <=, >=\n7.  Logical AND:     &&\n8.  Logical OR:      ||\n9.  Default:         ??\n10. Pipe:            ->\n11. Capture:         :>\n\nUse parentheses to override: (2 + 3) * 4\n\nEXTRACTION OPERATORS\n--------------------\n\nDestructure (*<>):\n  [1, 2, 3] -> *<$a, $b, $c>          # $a=1, $b=2, $c=3\n  [x: 1, y: 2] -> *<x: $a, y: $b>     # $a=1, $b=2\n  [1, 2, 3] -> *<$first, _, $third>   # _ skips element\n\nSlice (/<start:stop:step>):\n  [0,1,2,3,4] -> /<1:3>               # [1, 2]\n  [0,1,2,3,4] -> /<-2:>               # [3, 4]\n  [0,1,2,3,4] -> /<::-1>              # [4,3,2,1,0] (reverse)\n  \"hello\" -> /<1:4>                   # \"ell\"\n\nLIST SPREAD IN LITERALS\n-----------------------\n\nInline list elements into a new list using ... (spread operator):\n  [1, 2] :> $a\n  [...$a, 3]                          # [1, 2, 3]\n  [...$a, ...$b]                      # concatenate lists\n  [...[], 1]                          # [1] (empty spread contributes nothing)\n  [...($nums -> map {$ * 2})]         # spread expression result\n  [...$nested[0]]                     # spread from nested access\n\nError: spreading non-list throws RUNTIME_TYPE_ERROR\n  \"hello\" :> $s\n  [...$s]                             # ERROR: Spread requires list, got string\n\nMULTI-KEY DICT LITERALS\n-----------------------\n\nMap multiple keys to the same value using list syntax:\n  [[\"a\", \"b\"]: 1]                     # [a: 1, b: 1]\n  [[1, \"1\"]: \"x\"]                     # [1: \"x\", \"1\": \"x\"] (mixed types)\n  [a: 0, [\"b\", \"c\"]: 1]               # [a: 0, b: 1, c: 1] (mixed entries)\n  [a: 0, [\"a\", \"b\"]: 1]               # [a: 1, b: 1] (last-write-wins)\n\nError cases:\n  [[]: 1]                             # ERROR: empty key list\n  [[[1, 2], \"a\"]: 1]                  # ERROR: non-primitive key element\n\nTUPLES FOR ARGUMENT UNPACKING\n-----------------------------\n\n*[1, 2, 3] -> $fn()                   # positional: $fn(1, 2, 3)\n*[b: 2, a: 1] -> $fn()                # named: $fn(a=1, b=2)\n*[...$list, 3] -> $fn()               # spread in tuple: combines elements\n\nSPREAD OPERATOR (@)\n-------------------\n\nChains closures sequentially:\n  5 -> @[$inc, $double, $add10]       # (5+1)*2+10 = 22\n\nSTRING METHODS\n--------------\n\n.len            length\n.empty          is empty string\n.trim           remove whitespace\n.upper          uppercase\n.lower          lowercase\n.split(sep)     split into list\n.lines          split on newlines\n.join(sep)      join list with separator (on list)\n.contains(s)    substring check\n.starts_with(s) prefix check\n.ends_with(s)   suffix check\n.replace(p,r)   replace first match\n.replace_all(p,r) replace all matches\n.match(regex)   first match info (dict with matched, index, groups)\n.is_match(regex) boolean regex check\n.head           first character\n.tail           last character\n.at(i)          character at index\n.index_of(s)    position of first match (-1 if none)\n.repeat(n)      repeat string n times: \"ab\" -> .repeat(3)  # \"ababab\"\n.pad_start(n,f) pad start to length: \"42\" -> .pad_start(5, \"0\")  # \"00042\"\n.pad_end(n,f)   pad end to length: \"42\" -> .pad_end(5, \"0\")  # \"42000\"\n.str            convert any value to string: 42 -> .str  # \"42\"\n.num            parse string to number: \"42\" -> .num  # 42\n\nLIST/DICT METHODS\n-----------------\n\n.len            length\n.empty          is empty\n.head           first element\n.tail           last element\n.at(i)          element at index\n.has(val)       check if list contains value (deep equality)\n.has_any(list)  check if list contains any value from candidates\n.has_all(list)  check if list contains all values from candidates\n.keys           dict keys as list\n.values         dict values as list\n.entries        dict as list of [key: k, value: v]\n\nPARSING FUNCTIONS (for LLM output)\n----------------------------------\n\nparse_auto(str)           auto-detect format\nparse_json(str)           parse JSON (repairs common errors)\nparse_xml(str, tag?)      extract XML tag content\nparse_fence(str, lang?)   extract fenced code block\nparse_fences(str)         all fenced blocks as list\nparse_frontmatter(str)    parse --- delimited YAML + body\nparse_checklist(str)      parse markdown task lists\n\nGLOBAL FUNCTIONS\n----------------\n\ntype(val)                 returns type name\nlog(val)                  print and pass through\njson(val)                 convert to JSON string\nidentity(val)             returns input unchanged\nrange(start, end, step?)  number sequence\nrepeat(val, count)        repeat value n times\nenumerate(coll)           add index to elements\n\nITERATORS\n---------\n\nLazy sequence generation. Collection operators auto-expand iterators.\n\nBuilt-in iterators:\n  range(0, 5) -> each { $ * 2 }        # [0, 2, 4, 6, 8]\n  repeat(\"x\", 3) -> each { $ }         # [\"x\", \"x\", \"x\"]\n\n.first() method (returns iterator for any collection):\n  [1, 2, 3] -> .first()                # iterator at 1\n  \"abc\" -> .first()                     # iterator at \"a\"\n  [] -> .first()                        # [done: true, ...]\n\nIterator protocol (dict with value, done, next):\n  $it.done                              # bool: is exhausted?\n  $it.value                             # current element\n  $it.next()                            # returns new iterator at next position\n\nITERATION LIMITS\n----------------\n\nDefault: 10,000 iterations max for loops.\nOverride: ^(limit: N) statement\n\nExample:\n  ^(limit: 100) 0 -> ($ < 50) @ { $ + 1 }\n\nConcurrency limit for map (controls parallel concurrency):\n  ^(limit: 3) $items -> map { slow_process($) }\n\nCOMMON MISTAKES\n---------------\n\n1. Using = for assignment          -> use :> instead\n2. Using || for defaults           -> use ?? instead\n3. Assuming truthiness             -> explicit boolean checks required\n4. Breaking from map/filter        -> only works in each/fold\n5. Modifying outer vars in loops   -> use fold/$@ or $ as state dict (see LOOP STATE PATTERNS)\n6. Expecting variables to leak     -> block scope is strict\n7. Forgetting () on methods        -> .upper() not .upper (unless property)\n8. Reassigning different type      -> variables lock to first type\n9. Using while/for keywords        -> use (cond) @ { } or -> each { } instead\n\nSCRIPT RETURN VALUES\n--------------------\n\ntrue / non-empty string -> exit code 0\nfalse / empty string    -> exit code 1\n[0, \"message\"]          -> exit code 0 with message\n[1, \"message\"]          -> exit code 1 with message\n\nMAINSTREAM TO RILL TRANSLATION\n------------------------------\n\n| Mainstream               | Rill                                      |\n|--------------------------|-----------------------------------------  |\n| x = value                | value :> $x                               |\n| null / undefined         | ?? default, .? existence check             |\n| if \"\" (truthiness)       | .empty, == 0, :?type                      |\n| try { } catch { }        | assert, conditionals, error                |\n| for (i = 0; ...)         | each, map, filter, fold                   |\n| count += 1 in loop       | fold(0) { $@ + 1 } or $ accumulator      |\n| a === b (reference)      | == always compares by value               |\n| a = b (shared ref)       | :> always deep-copies                     |\n";
+export declare const LANGUAGE_REFERENCE = "RILL LANGUAGE REFERENCE\n=======================\n\nRill is designed to be generated by LLMs and understood by humans. The focus is\non auditable LLM output, not ergonomic human authoring.\n\nESSENTIALS\n----------\n1. Variables use $ prefix ALWAYS:  5 => $x  (no assignment operator =)\n2. Pipe with ->, capture with =>:  \"hello\" => $x -> .upper => $y\n3. No null/undefined, no try/catch, no truthiness (conditions must be boolean)\n4. Variables lock to first type:   \"hi\" => $x; 42 => $x  # ERROR\n5. Loops cannot modify outer vars: use fold, each(init), or $ as state dict\n\nSTRENGTHS AND USE CASES\n-----------------------\nStrengths:\n  - Unambiguous syntax: $ prefix, explicit operators, no implicit coercion\n  - Single-pass parseable: LLMs generate correct code without symbol tables\n  - Readable by humans: pipe chains show data flow left-to-right\n  - Safe defaults: immutable values, type locking, no null/undefined\n\nUse cases:\n  - Workflow orchestration: chain LLM calls, API requests, transformations\n  - State machines: (cond) @ { } loops with $ as state dict\n  - Data pipelines: each/map/filter/fold process collections declaratively\n  - Prompt engineering: parse LLM output with parse_json, parse_xml, parse_fence\n\nState machine pattern ($ carries state through iterations):\n  [state: \"init\", data: $input]\n    -> ($.state != \"done\") @ {\n      $.state -> [\n        init: { [state: \"process\", data: transform($.data)] },\n        process: { [state: \"done\", data: finalize($.data)] }\n      ]\n    }\n\nNAMING CONVENTION: snake_case\n-----------------------------\nUse snake_case for all identifiers:\n  $user_name, $item_list, $is_valid    # variables\n  $double_value, $cleanup_text         # closures\n  [first_name: \"x\", last_name: \"y\"]    # dict keys\n\nWHY VARIABLES USE $ PREFIX\n--------------------------\nThe $ prefix enables single-pass parsing without a symbol table:\n\n  name()    -> host function call\n  $name()   -> closure invocation\n  $name     -> variable reference\n  name      -> dict key literal\n\nWithout $, \"process(data)\" is ambiguous: is process a host function or stored\nclosure? Is data a variable or key? This would require tracking all declarations.\n\nSPACING RULES\n-------------\nOperators:    space both sides       5 + 3, $x -> .upper, \"a\" => $b\nParentheses:  no inner space         ($x + 1), ($ > 3) ? \"yes\"\nBraces:       space inside           { $x + 1 }, each { $ * 2 }\nBrackets:     no inner space         $list[0], $dict.items[1]\nLiterals:     space after , and :    [1, 2, 3], [name: \"x\", age: 30]\nClosures:     space after params     |x| ($x * 2), |a, b| { $a + $b }\nMethods:      no space before . or ( $str.upper(), $list.join(\", \")\nPipes:        space both sides       \"x\" -> .upper -> .len\nContinuations: indent 2 spaces       $data\n                                       -> .filter { $.active }\n                                       -> map { $.name }\n\nIMPLICIT $ SHORTHAND (always prefer)\n------------------------------------\n$.method()  ->  .method            \"x\" -> .upper  (not $.upper())\nfunc($)     ->  func               \"x\" -> log     (not log($))\n$fn($)      ->  $fn                5 -> $double   (not $double($))\n\nDon't capture just to continue - use line continuation instead:\n  # avoid                          # good\n  \"x\" => $a                        \"x\"\n  $a -> .upper => $b                 -> .upper\n  $b -> .len                         -> .len\n\nOnly capture when the variable is reused later in the code.\n\nCRITICAL DIFFERENCES FROM MAINSTREAM LANGUAGES\n----------------------------------------------\n\n1. NO ASSIGNMENT OPERATOR\n   Wrong: x = 5           Mainstream: x = value\n   Right: 5 => $x         Rill: value => $x\n\n   Pipe (->): passes value to next operation\n   Capture (=>): stores value AND continues chain\n   Example: \"hello\" => $x -> .upper => $y   # $x=\"hello\", $y=\"HELLO\"\n\n2. NO NULL/UNDEFINED\n   Empty values (\"\", [], [:]) exist. \"No value\" cannot be represented.\n   Use ?? for defaults: $dict.field ?? \"default\"\n   Use .empty to check: $str -> .empty ? \"was empty\"\n   Mainstream: null/undefined      Rill: ?? default, .? existence check\n\n3. NO TRUTHINESS\n   Conditions MUST be boolean. No implicit coercion.\n   Wrong: \"\" ? \"yes\" ! \"no\"       Right: \"\" -> .empty ? \"yes\" ! \"no\"\n   Wrong: 0 ? \"yes\" ! \"no\"        Right: (0 == 0) ? \"yes\" ! \"no\"\n   Negation (!) also requires boolean:\n   Right: !true                          # false\n   Right: \"hello\" -> .empty -> (!$)      # true (negates boolean from .empty)\n   Wrong: !\"hello\"                       # ERROR: Negation requires boolean\n   Mainstream: if \"\" / if 0              Rill: .empty, == 0, :?type\n\n4. VARIABLES LOCK TO FIRST TYPE\n   \"hello\" => $x\n   42 => $x        # ERROR: cannot assign number to string variable\n\n5. NO VARIABLE SHADOWING (CRITICAL FOR LOOPS)\n   Child scopes can READ parent variables but cannot WRITE or redeclare them.\n   Variables created inside blocks/loops do NOT leak out.\n\n   WRONG - outer variable modification (NEVER works):\n     0 => $count\n     [1, 2, 3] -> each { $count + 1 => $count }  # creates LOCAL $count\n     $count                                       # still 0!\n\n   WRONG - \"while\" keyword does not exist:\n     while ($i < 10) { $i + 1 => $i }            # SYNTAX ERROR\n\n   RIGHT - use fold for reduction:\n     [1, 2, 3] -> fold(0) { $@ + $ }             # 6 ($@ is accumulator)\n\n   RIGHT - use each(init) for results AND accumulator:\n     [1, 2, 3] -> each(0) { $@ + $ }             # [1, 3, 6] (running totals)\n\n   RIGHT - use (cond) @ { } with $ as state dict for multiple values:\n     [iter: 0, max: 3, text: $input, done: false]\n       -> (!$.done && $.iter < $.max) @ {\n         $.iter + 1 => $i\n         process($.text) => $result\n         $result.finished ? [iter: $i, max: $.max, text: $.text, done: true]\n                          ! [iter: $i, max: $.max, text: $result.text, done: false]\n       }\n\n   Pattern summary:\n     Single value accumulation     -> fold(init) { $@ + $ }\n     Per-item results + running    -> each(init) { ... $@ ... }\n     Multiple state values / while -> (cond) @ { } with $ as state dict\n     \"while\" and \"for\" keywords    -> DO NOT EXIST\n   Mainstream: count += 1 in loop    Rill: fold(0) { $@ + 1 } or $ accumulator\n\n6. NO EXCEPTIONS\n   Errors halt execution. No try/catch. Use conditionals for error handling.\n   Built-in: assert (validate condition), error (halt with message).\n   Mainstream: try { } catch { }     Rill: assert, conditionals, error\n\n7. VALUE SEMANTICS (no references)\n   All copies are deep. All comparisons are by value. No object identity.\n   [1, 2, 3] == [1, 2, 3]   # true (content equality)\n   [1, 2] => $a\n   $a => $b                  # $b is an independent deep copy\n   Mainstream: a === b (reference)   Rill: == always compares by value\n   Mainstream: a = b (shared ref)    Rill: => always deep-copies\n\nSYNTAX QUICK REFERENCE\n----------------------\n\nVariables:     $name (always prefixed with $)\nStrings:       \"hello {$var}\"          # interpolation with {}\n               \"\"\"...\"\"\"               # multiline (also interpolates)\nNumbers:       42, 3.14, -7\nBooleans:      true, false\nLists:         [1, 2, 3]\n               [...$list, 4]               # spread: inline list elements\nDicts:         [name: \"alice\", age: 30]    # identifier keys\n               [1: \"one\", 2: \"two\"]        # number keys (incl. negative: [-1: \"neg\"])\n               [true: \"yes\", false: \"no\"]  # boolean keys\n               [[\"a\", \"b\"]: 1]             # multi-key: [a: 1, b: 1]\n               [$keyVar: value]            # variable key (must eval to string)\n               [($expr): value]            # computed key (must eval to string)\nTuples:        *[1, 2, 3]              # for argument unpacking\nClosures:      |x|($x + 1)             # like lambda/arrow functions\nType annot:    \"hi\" => $x:string       # lock type on capture\nComments:      # single line only\n\nPIPES AND $ BINDING\n-------------------\n\n$ is the current piped value. Its meaning depends on context:\n\n| Context                    | $ contains              |\n|----------------------------|-------------------------|\n| -> { body }                | piped value             |\n| -> each { }                | current item            |\n| (cond) @ { }               | accumulated value       |\n| @ { } ? cond               | accumulated value       |\n| cond ? { } ! { }           | tested value            |\n| -> ? { } ! { }             | piped value             |\n| ||{ $.field } in dict      | the containing dict     |\n| |x|{ } stored closure      | N/A - use parameters    |\n\nImplied $: bare .method() means $ -> .method()\nExample: \"hello\" -> .upper   # same as \"hello\" -> $.upper()\n\nCONTROL FLOW\n------------\n\nConditional (if-else):\n  cond ? then_expr ! else_expr\n  cond ? then_expr                    # else returns \"\"\n\nPiped conditional ($ becomes condition):\n  value -> ? then_expr ! else_expr\n\nCondition loop (NO \"while\" keyword - use @ operator):\n  init_value -> ($ < 10) @ { $ + 1 }  # $ is accumulator\n\nDo-condition loop (body runs at least once):\n  init_value -> @ { $ + 1 } ? ($ < 10)\n\nBreak (exits loop, returns collected results before break):\n  [1,2,3,4,5] -> each { ($ == 3) ? break; $ }  # returns [1, 2]\n\nReturn (exits block or script with value):\n  { 5 => $x; ($x > 3) ? (\"big\" -> return); \"small\" }  # returns \"big\"\n  \"done\" -> return                                     # exits script with \"done\"\n\nAssert (validate condition, halt if false, pass through if true):\n  5 -> assert ($ > 0)                   # returns 5\n  -1 -> assert ($ > 0)                  # ERROR: Assertion failed\n  \"\" -> assert !.empty \"Input required\" # ERROR: Input required\n  $val -> assert $:?list \"Expected list\" # type validation\n\nError (halt execution immediately with message):\n  error \"Something went wrong\"           # halt with message\n  \"Operation failed\" -> error            # piped form (must be string)\n  error \"Status: {$code}\"               # interpolation works\n\nPass (returns $ unchanged, explicit no-op):\n  cond ? pass ! \"fallback\"               # preserve $ when condition true\n  cond ? \"value\" ! pass                  # preserve $ when condition false\n  \"data\" -> { [status: pass] }           # include $ in dict: [status: \"data\"]\n  [1, -2, 3] -> map { ($ > 0) ? pass ! 0 }  # [1, 0, 3]\n  Note: pass requires pipe context. Using pass without $ throws error.\n\nCOLLECTION OPERATORS\n--------------------\n\n| Operator           | Execution  | Returns              | Break? |\n|--------------------|------------|----------------------|--------|\n| -> each { }        | sequential | all body results     | yes    |\n| -> each(i) { $@+$} | sequential | all with accumulator | yes    |\n| -> map { }         | parallel   | all body results     | NO     |\n| -> filter { }      | parallel   | matching elements    | NO     |\n| -> fold(i) { $@+$} | sequential | final result only    | yes    |\n\n$@ is the accumulator in each(init) and fold(init).\n\nMethod shorthand in collection operators:\n  [\"a\", \"b\"] -> map .upper            # [\"A\", \"B\"]\n  [\"\", \"x\"] -> filter (!.empty)       # [\"x\"]\n  [\"a\", \"b\"] -> map .pad_start(3, \"0\") # [\"00a\", \"00b\"] (with args)\n  [\"  HI  \"] -> map .trim.lower       # [\"hi\"] (chained methods)\n\nBody forms (all operators accept these):\n  -> each { $ * 2 }                   # block ($ is current element)\n  -> each ($ + 10)                    # grouped expression\n  -> each |x| ($x * 2)               # inline closure\n  -> each $double                     # variable closure\n  -> each .upper                      # method shorthand\n  -> each log                         # host function\n\nDict iteration ($ contains key and value fields):\n  [a: 1, b: 2] -> each { \"{$.key}={$.value}\" }   # [\"a=1\", \"b=2\"]\n  [a: 1, b: 5] -> filter { $.value > 2 }          # entries where value > 2\n\nString iteration (iterates over characters):\n  \"abc\" -> each { \"{$}!\" }            # [\"a!\", \"b!\", \"c!\"]\n  \"hello\" -> filter { $ != \"l\" }      # [\"h\", \"e\", \"o\"]\n\nCLOSURES\n--------\n\nBLOCK-CLOSURES vs EXPLICIT CLOSURES:\n\nTwo ways to create closures:\n\n1. Block-closures: { body } in expression position\n   { $ + 1 } => $inc                  # implicit $ parameter\n   $inc(5)                            # 6\n   5 -> $inc                          # 6 (pipe invocation)\n   [x: { $ * 2 }]                     # dict value is closure\n   type({ \"hi\" })                     # \"closure\"\n\n2. Explicit closures: |params| body\n   |x|($x + 1) => $inc                # named parameter\n   |a, b|($a + $b) => $add            # multiple params\n   |x = 0|($x + 1) => $inc_or_one     # default value\n   |x: number|($x + 1) => $typed      # type annotation\n\nCRITICAL: { } vs ( ) distinction\n\n| Syntax       | Semantics              | Example                    |\n|--------------|------------------------|----------------------------|\n| { body }     | Deferred (closure)     | { $ + 1 } => $fn  # closure |\n| ( expr )     | Eager (immediate eval) | ( 5 + 1 ) => $x  # 6        |\n\nWhen to use:\n  { body } => $fn     # store closure for later use\n  ( expr ) => $x      # store result value immediately\n\nPIPE TARGET: { } creates closure then immediately invokes it:\n  5 -> { $ + 1 }      # 6 (create closure, invoke with 5)\n  5 -> ($ + 1)        # 6 (evaluate expression with $=5)\n  Same observable result, different mechanism. Error messages differ.\n\nBlock-closure invocation:\n  { $ + 1 } => $inc\n  $inc(5)                             # direct call: 6\n  5 -> $inc                           # pipe call: 6\n  [1,2,3] -> map $inc                 # in collection op\n\nLATE BINDING: closures capture scope, not values. Variables resolve at call time.\n\n$ vs named params:\n  Use $ in inline pipes and loops:     \"hello\" -> { .upper }\n  Use named params in stored closures: |x| ($x * 2) => $double\n  $ is undefined when a stored closure is called later \u2014 always use params.\n\nZero-param dict closures (methods):\n  [count: 3, double: ||{ $.count * 2 }] => $obj\n  $obj.double                         # 6 ($ is bound to dict)\n\nPROPERTY ACCESS\n---------------\n\n$data.field                           # dict field\n$data[0], $data[-1]                   # list index (negative from end)\n$data.$key                            # variable as key\n$data.($i + 1)                        # computed key\n$data.(a || b)                        # try keys left-to-right\n$data.field ?? \"default\"              # default if missing\n$data.?field                          # existence check (boolean)\n$data.?$keyVar                        # variable existence check\n$data.?($expr)                        # computed existence check\n$data.?field&string                   # existence AND type check\n$data.?$key&number                    # variable existence + type check\n$data.?($a -> \"{$}_b\")&list           # computed existence + type check\n\nDISPATCH OPERATORS\n------------------\n\nDICT DISPATCH (single key):\nPipe a value to a dict to match keys and return associated values:\n  $val -> [apple: \"fruit\", carrot: \"veg\"]        # returns \"fruit\" if $val is \"apple\"\n  $val -> [apple: \"fruit\"] ?? \"not found\"         # default if no match\n  $method -> [[\"GET\", \"HEAD\"]: \"safe\", [\"POST\", \"PUT\"]: \"unsafe\"]  # multi-key dispatch\n\nType-aware matching (keys matched by value AND type):\n  1 -> [1: \"number\", \"1\": \"string\"]              # \"number\" (number key matches)\n  \"1\" -> [1: \"number\", \"1\": \"string\"]            # \"string\" (string key matches)\n  true -> [true: \"bool\", \"true\": \"str\"]          # \"bool\" (boolean key matches)\n\nLIST DISPATCH (index):\nPipe a number to a list to get element at index:\n  0 -> [\"first\", \"second\"]                        # \"first\"\n  -1 -> [\"first\", \"second\"]                       # \"second\" (last)\n  5 -> [\"a\", \"b\"] ?? \"not found\"                  # default if out of bounds\n\nHIERARCHICAL DISPATCH (path navigation):\nPipe a list of keys/indexes to navigate nested structures:\n  [\"name\", \"first\"] -> [name: [first: \"Alice\"]]   # \"Alice\" (dict path)\n  [0, 1] -> [[1, 2, 3], [4, 5, 6]]                 # 2 (list path)\n  [\"users\", 0, \"name\"] -> [users: [[name: \"Alice\"]]] # \"Alice\" (mixed)\n  [] -> [a: 1]                                    # [a: 1] (empty path = unchanged)\n  [\"a\", \"missing\"] -> [a: [x: 1]] ?? \"default\"    # \"default\" (missing key)\n\nTYPE OPERATIONS\n---------------\n\n:type   - assert type (error if wrong): 42:number passes; \"x\":number errors\n:?type  - check type (boolean): 42:?number is true; \"x\":?number is false\n\nTypes: string, number, boolean, list, dict, tuple, closure\n\nComparison methods (for readable conditionals):\n  .eq(val) ==   .ne(val) !=   .lt(val) <   .gt(val) >   .le(val) <=   .ge(val) >=\n  Example: $age -> .ge(18) ? \"adult\" ! \"minor\"\n\nOPERATOR PRECEDENCE (highest to lowest)\n---------------------------------------\n\n1.  Member access:   .field, [index]\n2.  Type operators:  :type, :?type\n3.  Unary:           -, !\n4.  Multiplicative:  *, /, %\n5.  Additive:        +, -\n6.  Comparison:      ==, !=, <, >, <=, >=\n7.  Logical AND:     &&\n8.  Logical OR:      ||\n9.  Default:         ??\n10. Pipe:            ->\n11. Capture:         =>\n\nUse parentheses to override: (2 + 3) * 4\n\nEXTRACTION OPERATORS\n--------------------\n\nDestructure (*<>):\n  [1, 2, 3] -> *<$a, $b, $c>          # $a=1, $b=2, $c=3\n  [x: 1, y: 2] -> *<x: $a, y: $b>     # $a=1, $b=2\n  [1, 2, 3] -> *<$first, _, $third>   # _ skips element\n\nSlice (/<start:stop:step>):\n  [0,1,2,3,4] -> /<1:3>               # [1, 2]\n  [0,1,2,3,4] -> /<-2:>               # [3, 4]\n  [0,1,2,3,4] -> /<::-1>              # [4,3,2,1,0] (reverse)\n  \"hello\" -> /<1:4>                   # \"ell\"\n\nLIST SPREAD IN LITERALS\n-----------------------\n\nInline list elements into a new list using ... (spread operator):\n  [1, 2] => $a\n  [...$a, 3]                          # [1, 2, 3]\n  [...$a, ...$b]                      # concatenate lists\n  [...($nums -> map {$ * 2})]         # spread expression result\n\nMULTI-KEY DICT LITERALS\n-----------------------\n\nMap multiple keys to the same value using list syntax:\n  [[\"a\", \"b\"]: 1]                     # [a: 1, b: 1]\n  [[1, \"1\"]: \"x\"]                     # [1: \"x\", \"1\": \"x\"] (mixed types)\n  [a: 0, [\"b\", \"c\"]: 1]               # [a: 0, b: 1, c: 1] (mixed entries)\n\nTUPLES FOR ARGUMENT UNPACKING\n-----------------------------\n\n*[1, 2, 3] -> $fn()                   # positional: $fn(1, 2, 3)\n*[b: 2, a: 1] -> $fn()                # named: $fn(a=1, b=2)\n*[...$list, 3] -> $fn()               # spread in tuple: combines elements\n\nCLOSURE CHAIN (@)\n-----------------\n\nChains closures sequentially (each receives previous result):\n  5 -> @[$inc, $double, $add10]       # (5+1)*2+10 = 22\n\nSTRING METHODS\n--------------\n\n.len            length                    .empty          is empty string\n.trim           remove whitespace         .upper          uppercase\n.lower          lowercase                 .str            convert to string\n.num            parse to number           .head           first character\n.tail           last character            .at(i)          character at index\n.split(sep)     split into list (default: newline)\n.lines          split on newlines         .join(sep)      join list with separator\n.contains(s)    substring check           .starts_with(s) prefix check\n.ends_with(s)   suffix check              .index_of(s)    first match position (-1 if none)\n.replace(p,r)   replace first regex match\n.replace_all(p,r) replace all regex matches\n.match(regex)   first match info (dict with matched, index, groups)\n.is_match(regex) boolean regex check\n.repeat(n)      repeat n times: \"ab\" -> .repeat(3)  # \"ababab\"\n.pad_start(n,f) pad start: \"42\" -> .pad_start(5, \"0\")  # \"00042\"\n.pad_end(n,f)   pad end: \"42\" -> .pad_end(5, \"0\")  # \"42000\"\n\nLIST/DICT METHODS\n-----------------\n\n.len            length                    .empty          is empty\n.head           first element             .tail           last element\n.at(i)          element at index          .keys           dict keys as list\n.values         dict values as list       .entries        dict as list of [k, v] tuples\n.has(val)       list contains value (deep equality)\n.has_any(list)  list contains any value from candidates\n.has_all(list)  list contains all values from candidates\n\nPARSING FUNCTIONS (for LLM output)\n----------------------------------\n\nparse_auto(str)           auto-detect format\nparse_json(str)           parse JSON (repairs common errors)\nparse_xml(str, tag?)      extract XML tag content\nparse_fence(str, lang?)   extract fenced code block\nparse_fences(str)         all fenced blocks as list\nparse_frontmatter(str)    parse --- delimited YAML + body\nparse_checklist(str)      parse markdown task lists\n\nGLOBAL FUNCTIONS\n----------------\n\ntype(val)                 returns type name (string, number, boolean, list, dict, closure, tuple)\nlog(val)                  print and pass through\njson(val)                 convert to JSON string\nidentity(val)             returns input unchanged\nrange(start, end, step?)  number sequence (iterator)\nrepeat(val, count)        repeat value n times (iterator)\nenumerate(coll)           lists: [index, value]; dicts: [index, key, value]\n\nITERATORS\n---------\n\nLazy sequence generation. Collection operators auto-expand iterators.\n\nBuilt-in iterators:\n  range(0, 5) -> each { $ * 2 }        # [0, 2, 4, 6, 8]\n  repeat(\"x\", 3) -> each { $ }         # [\"x\", \"x\", \"x\"]\n\n.first() method (returns iterator for any collection):\n  [1, 2, 3] -> .first()                # iterator at 1\n  \"abc\" -> .first()                     # iterator at \"a\"\n\nIterator protocol (dict with value, done, next):\n  $it.done                              # bool: is exhausted?\n  $it.value                             # current element\n  $it.next()                            # returns new iterator at next position\n\nITERATION LIMITS\n----------------\n\nDefault: 10,000 iterations max for loops.\nOverride: ^(limit: N) statement\n\n  ^(limit: 100) 0 -> ($ < 50) @ { $ + 1 }\n  ^(limit: 3) $items -> map { slow_process($) }  # concurrency limit\n\nSCRIPT RETURN VALUES\n--------------------\n\ntrue / non-empty string -> exit code 0\nfalse / empty string    -> exit code 1\n[0, \"message\"]          -> exit code 0 with message\n[1, \"message\"]          -> exit code 1 with message\n";
 //# sourceMappingURL=introspection-data.d.ts.map

package/dist/generated/introspection-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"introspection-data.d.ts","sourceRoot":"","sources":["../../src/generated/introspection-data.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,kBAAkB,suyBAsmB9B,CAAC"}
+{"version":3,"file":"introspection-data.d.ts","sourceRoot":"","sources":["../../src/generated/introspection-data.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,kBAAkB,q+sBAuhB9B,CAAC"}