@rcrsr/rill 0.4.5 → 0.5.0

package/docs/05_control-flow.md

@@ -562,6 +562,67 @@ Error halts the loop immediately:
 
 ---
 
+## Pass
+
+The `pass` keyword returns the current pipe value (`$`) unchanged. Use it for explicit identity pass-through in conditional branches and dict values.
+
+### In Conditionals
+
+Use `pass` when one branch should preserve the piped value:
+
+```rill
+"input" -> .contains("in") ? pass ! "fallback"
+# Returns "input" (condition true, pass preserves $)
+```
+
+```rill
+"data" -> .empty ? { error "Empty input" } ! pass
+# Returns "data" (condition false, pass preserves $)
+```
+
+### In Dict Values
+
+Use `pass` to include the piped value in dict construction:
+
+```rill
+"success" -> { [status: pass, code: 0] }
+# Returns [status: "success", code: 0]
+```
+
+### In Collection Operators
+
+Preserve elements conditionally:
+
+```rill
+[1, -2, 3, -4] -> map { ($ > 0) ? pass ! 0 }
+# Returns [1, 0, 3, 0]
+```
+
+### Why Use Pass?
+
+The `pass` keyword provides clearer intent than bare `$`:
+
+```text
+# Less clear - what does $ mean here?
+$cond ? do_something() ! $
+
+# More explicit - reader knows this is intentional no-op
+$cond ? do_something() ! pass
+```
+
+### Pass Behavior
+
+| Pattern | Returns | Context |
+|---------|---------|---------|
+| `cond ? pass ! alt` | `$` if true, `alt` if false | Conditional branch |
+| `cond ? alt ! pass` | `alt` if true, `$` if false | Conditional branch |
+| `[key: pass]` | Dict with `$` as value | Dict construction |
+| `-> { pass }` | `$` | Block body |
+
+**Note:** `pass` requires pipe context. Using `pass` without `$` bound throws an error.
+
+---
+
 ## Control Flow Summary
 
 | Statement | Scope | Effect |
@@ -570,6 +631,7 @@ Error halts the loop immediately:
 | `$val -> break` | Loop | Exit loop with value |
 | `return` | Block/Script | Exit block or script with current `$` |
 | `$val -> return` | Block/Script | Exit block or script with value |
+| `pass` | Any | Returns current `$` unchanged |
 | `assert cond` | Any | Halt if condition false, pass through on success |
 | `assert cond "msg"` | Any | Halt with custom message if condition false |
 | `error "msg"` | Any | Always halt with error message |

package/docs/11_reference.md

@@ -1,10 +1,10 @@
-# rill Core Language Specification v0.4.5
+# rill Core Language Specification v0.5.0
 
 *From prompts to workflows*
 
 rill is a pipe-based scripting language for orchestrating workflows.
 
-> **Experimental (v0.4.5).** Active development. Breaking changes until v1.0.
+> **Experimental (v0.5.0).** Active development. Breaking changes until v1.0.
 
 ## Overview
 
@@ -60,6 +60,7 @@ See [Operators](04_operators.md) for detailed documentation.
 | `@ body ? cond` | Do-while |
 | `break` / `$val -> break` | Exit loop |
 | `return` / `$val -> return` | Exit block or script |
+| `pass` | Returns current `$` unchanged (use in conditionals, dicts) |
 | `assert cond` / `assert cond "msg"` | Validate condition, halt on failure |
 | `error "msg"` / `$val -> error` | Halt execution with error message |
 

package/docs/12_examples.md

@@ -75,7 +75,7 @@ $verification -> ?(.contains("PASS")) {
 
 Works through a checklist until complete.
 
-```rill
+```text
 ---
 args: plan: string
 ---
@@ -84,7 +84,7 @@ args: plan: string
 app::prompt("Read {$plan} and find the first unchecked item (- [ ])") :> $status
 
 # Work loop
-(!$status -> .contains("ALL COMPLETE")) @ {
+$status -> (!.contains("ALL COMPLETE")) @ {
   """
 Based on this status:
 {$}
@@ -387,7 +387,7 @@ Items {$start} through {$end}
 
 Uses explicit signals for workflow control.
 
-```rill
+```text
 ---
 args: task: string
 exceptions:
@@ -404,7 +404,7 @@ Rules:
 - Output :::DONE::: when complete
 """ -> app::prompt() :> $result
 
-(!$result -> .contains(":::DONE:::")) @ {
+$result -> (!.contains(":::DONE:::")) @ {
   """
 Continue working on: {$task}
 

package/docs/14_host-integration.md

@@ -593,6 +593,150 @@ interface ExecutionResult {
 }
 ```
 
+## Introspection
+
+Discover available functions, access language documentation, and check runtime version at runtime.
+
+### getFunctions()
+
+Enumerate all callable functions registered in the runtime context:
+
+```typescript
+import { createRuntimeContext, getFunctions } from '@rcrsr/rill';
+
+const ctx = createRuntimeContext({
+  functions: {
+    greet: {
+      params: [
+        { name: 'name', type: 'string', description: 'Person to greet' },
+      ],
+      description: 'Generate a greeting message',
+      fn: (args) => `Hello, ${args[0]}!`,
+    },
+  },
+});
+
+const functions = getFunctions(ctx);
+// [
+//   {
+//     name: 'greet',
+//     description: 'Generate a greeting message',
+//     params: [{ name: 'name', type: 'string', description: 'Person to greet', defaultValue: undefined }]
+//   },
+//   ... built-in functions
+// ]
+```
+
+Returns `FunctionMetadata[]` combining:
+1. Host functions (with full parameter metadata)
+2. Built-in functions
+3. Script closures (reads `^(doc: "...")` annotation for description)
+
+### getLanguageReference()
+
+Access the bundled rill language reference for LLM prompt context:
+
+```typescript
+import { getLanguageReference } from '@rcrsr/rill';
+
+const reference = getLanguageReference();
+// Returns complete language reference text (syntax, operators, types, etc.)
+
+// Use in LLM system prompts:
+const systemPrompt = `You are a rill script assistant.
+
+${reference}
+
+Help the user write rill scripts.`;
+```
+
+### VERSION and VERSION_INFO
+
+Access runtime version information for logging, diagnostics, or version checks:
+
+```typescript
+import { VERSION, VERSION_INFO } from '@rcrsr/rill';
+
+// VERSION: Semver string for display
+console.log(`Running rill ${VERSION}`);  // "Running rill 0.5.0"
+
+// VERSION_INFO: Structured components for programmatic comparison
+if (VERSION_INFO.major === 0 && VERSION_INFO.minor < 4) {
+  console.warn('Rill version too old, upgrade required');
+}
+
+// Log full version info
+console.log('Runtime:', {
+  version: VERSION,
+  major: VERSION_INFO.major,
+  minor: VERSION_INFO.minor,
+  patch: VERSION_INFO.patch,
+  prerelease: VERSION_INFO.prerelease,
+});
+```
+
+**VERSION Constant:**
+- Type: `string`
+- Format: Semver (e.g., `"0.5.0"`, `"1.0.0-beta.1"`)
+- Use: Display in logs, error messages, diagnostics
+
+**VERSION_INFO Constant:**
+- Type: `VersionInfo`
+- Fields:
+  - `major: number` - Major version (breaking changes)
+  - `minor: number` - Minor version (new features)
+  - `patch: number` - Patch version (bug fixes)
+  - `prerelease?: string` - Prerelease tag if present
+- Use: Programmatic version comparison, compatibility checks
+
+**Version Comparison Example:**
+
+```typescript
+import { VERSION_INFO } from '@rcrsr/rill';
+
+function checkCompatibility(): boolean {
+  const required = { major: 0, minor: 4, patch: 0 };
+
+  if (VERSION_INFO.major !== required.major) {
+    return false; // Breaking change
+  }
+
+  if (VERSION_INFO.minor < required.minor) {
+    return false; // Missing features
+  }
+
+  return true;
+}
+
+if (!checkCompatibility()) {
+  throw new Error(`Requires rill >= 0.4.0, found ${VERSION}`);
+}
+```
+
+### Introspection Types
+
+```typescript
+interface FunctionMetadata {
+  readonly name: string;        // Function name (e.g., "math::add")
+  readonly description: string; // Human-readable description
+  readonly params: readonly ParamMetadata[];
+}
+
+interface ParamMetadata {
+  readonly name: string;                    // Parameter name
+  readonly type: string;                    // Type constraint (e.g., "string")
+  readonly description: string;             // Parameter description
+  readonly defaultValue: RillValue | undefined; // Default if optional
+}
+
+interface VersionInfo {
+  readonly major: number;        // Major version (breaking changes)
+  readonly minor: number;        // Minor version (new features)
+  readonly patch: number;        // Patch version (bug fixes)
+  readonly prerelease?: string;  // Prerelease tag if present
+}
+```
+
 ## I/O Callbacks
 
 Handle script I/O through callbacks:
@@ -813,6 +957,14 @@ export { validateHostFunctionArgs };
 // Value types
 export type { RillValue, RillArgs };
 
+// Introspection
+export { getFunctions, getLanguageReference };
+export type { FunctionMetadata, ParamMetadata };
+
+// Version information
+export { VERSION, VERSION_INFO };
+export type { VersionInfo };
+
 // Callbacks
 export type { RuntimeCallbacks, ObservabilityCallbacks };
 export type { StepStartEvent, StepEndEvent, FunctionCallEvent, FunctionReturnEvent };

package/docs/15_grammar.ebnf

@@ -128,6 +128,10 @@ comparison    = additive , [ comparison-op , additive ] ;
 additive      = multiplicative , { ( "+" | "-" ) , multiplicative } ;
 multiplicative = unary , { ( "*" | "/" | "%" ) , unary } ;
 unary         = [ "-" | "!" ] , postfix-expr ;
+              (* Semantic: "!" requires boolean operand. No truthiness coercion.
+                 !true -> false, !false -> true
+                 !"string" -> RUNTIME_TYPE_ERROR (Negation requires boolean, got string)
+                 !0 -> RUNTIME_TYPE_ERROR (Negation requires boolean, got number) *)
 
 comparison-op = "==" | "!=" | "<" | ">" | "<=" | ">=" ;
 
@@ -151,7 +155,21 @@ primary       = literal
               | loop
               | block
               | grouped-expr
-              | spread ;           (* *expr - convert list/dict to tuple *)
+              | spread              (* *expr - convert list/dict to tuple *)
+              | pass ;
+
+(* Pass: returns current pipe value ($) unchanged.
+   Used for explicit identity pass-through in conditionals and dict values.
+
+   Examples:
+     cond ? pass ! "fallback"      -- preserve $ when condition true
+     cond ? "value" ! pass         -- preserve $ when condition false
+     [key: pass]                   -- include $ as dict value
+     -> { pass }                   -- block returns $
+
+   Semantic: pass requires pipe context. Using pass without $ bound
+   throws RUNTIME_UNDEFINED_VARIABLE: Variable '$' not defined *)
+pass          = "pass" ;
 
 (* implicit-primary: used in contexts where implicit $ is available (body, pipe targets).
    Includes method-call because .method() expands to $ -> .method().