@aigne/ash 0.0.1

package/src/parser.ts

@@ -0,0 +1,835 @@
+import type { Token, TokenType } from "./lexer.js";
+import type { Program, JobDeclaration, PipelineStage, Annotation, WhereClause, QueryCondition, TopLevelStatement, LetStatement, CountExpression, GroupByExpression, ActionExpression, Expression, MapExpression, RouteExpression, RouteBranch, LookupExpression, ParamDeclaration, TriggerDeclaration } from "./ast.js";
+
+/** Annotation names that are script-level: propagate to all jobs when declared before any statement. */
+const SCRIPT_LEVEL_ANNOTATIONS = new Set(["caps", "budget"]);
+
+/** Merge script-level annotations with job-specific ones. Job overrides script-level by name. */
+function mergeAnnotations(script: Annotation[], job: Annotation[]): Annotation[] {
+  if (script.length === 0) return job;
+  if (job.length === 0) return [...script];
+  const jobNames = new Set(job.map(a => a.name));
+  return [...script.filter(a => !jobNames.has(a.name)), ...job];
+}
+
+export class AshParser {
+  private tokens: Token[] = [];
+  private pos = 0;
+
+  private letNames = new Set<string>();
+  private paramNames = new Set<string>();
+  private static readonly RESERVED_KEYWORDS = new Set(["job", "find", "where", "map", "save", "publish", "tee", "fanout", "input", "output", "let", "action", "route", "lookup", "param", "on"]);
+
+  parse(tokens: Token[]): Program {
+    this.tokens = tokens;
+    this.pos = 0;
+    this.letNames = new Set();
+    this.paramNames = new Set();
+    const statements: TopLevelStatement[] = [];
+
+    this.skipNewlines();
+
+    // Collect initial annotations (before any statement).
+    // Split into script-level (caps, budget → propagate to all jobs) and first-job-specific.
+    const initialAnnotations = this.parseAnnotations();
+    const scriptAnnotations = initialAnnotations.filter(a => SCRIPT_LEVEL_ANNOTATIONS.has(a.name));
+    const firstJobOnly = initialAnnotations.filter(a => !SCRIPT_LEVEL_ANNOTATIONS.has(a.name));
+    let firstStatement = true;
+
+    while (!this.isAtEnd()) {
+      const jobAnnotations = this.parseAnnotations();
+      if (this.isAtEnd()) break;
+
+      const t = this.peek();
+      if (t.type === "JOB") {
+        const extra = firstStatement ? [...firstJobOnly, ...jobAnnotations] : jobAnnotations;
+        const merged = mergeAnnotations(scriptAnnotations, extra);
+        firstStatement = false;
+        statements.push(this.parseJob(merged));
+      } else if (t.type === "OUTPUT" && jobAnnotations.length === 0) {
+        firstStatement = false;
+        this.advance(); // output
+        const msg = this.expect("STRING", "Expected string after 'output'");
+        statements.push({ kind: "output", message: msg.value });
+      } else if (t.type === "LET" && jobAnnotations.length === 0) {
+        firstStatement = false;
+        statements.push(this.parseLet());
+      } else if (t.type === "PARAM" && jobAnnotations.length === 0) {
+        firstStatement = false;
+        statements.push(this.parseParam());
+      } else {
+        throw new Error(`Expected 'job', 'output', 'let', or 'param' at top level, got ${t.type} at line ${t.line}, column ${t.column}`);
+      }
+      this.skipNewlines();
+    }
+
+    const jobs = statements.filter((s): s is JobDeclaration => s.kind === "job");
+    return { statements, jobs };
+  }
+
+  private parseParam(): ParamDeclaration {
+    const paramToken = this.advance(); // param
+    if (this.isAtEnd()) {
+      throw new Error(`Expected parameter name after 'param' at line ${paramToken.line}, column ${paramToken.column}`);
+    }
+    const nameToken = this.peek();
+    if (nameToken.type !== "IDENTIFIER") {
+      throw new Error(`Cannot use reserved keyword '${nameToken.value}' as param name at line ${nameToken.line}, column ${nameToken.column}`);
+    }
+    this.advance();
+    if (AshParser.RESERVED_KEYWORDS.has(nameToken.value)) {
+      throw new Error(`Cannot use reserved keyword '${nameToken.value}' as param name at line ${nameToken.line}, column ${nameToken.column}`);
+    }
+    if (this.paramNames.has(nameToken.value)) {
+      throw new Error(`Duplicate param name '${nameToken.value}' at line ${nameToken.line}, column ${nameToken.column}`);
+    }
+    if (this.letNames.has(nameToken.value)) {
+      throw new Error(`Param '${nameToken.value}' conflicts with existing let variable at line ${nameToken.line}, column ${nameToken.column}`);
+    }
+    this.expect("ASSIGN", "Expected '=' after param name");
+    const valToken = this.advance();
+    let defaultValue: string | number;
+    if (valToken.type === "NUMBER") {
+      defaultValue = parseFloat(valToken.value);
+    } else if (valToken.type === "STRING") {
+      defaultValue = valToken.value;
+    } else if (valToken.type === "PATH") {
+      defaultValue = valToken.value;
+    } else if (valToken.type === "IDENTIFIER") {
+      defaultValue = valToken.value;
+    } else {
+      throw new Error(`Expected default value after '=' at line ${valToken.line}, column ${valToken.column}`);
+    }
+    this.paramNames.add(nameToken.value);
+    return { kind: "param", name: nameToken.value, defaultValue };
+  }
+
+  private static readonly PIPELINE_STARTERS = new Set(["FIND", "ACTION", "LOOKUP", "INPUT"]);
+
+  private parseLet(): LetStatement {
+    const letToken = this.advance(); // let
+    if (this.isAtEnd() || this.peek().type !== "IDENTIFIER") {
+      throw new Error(`Expected variable name after 'let' at line ${letToken.line}, column ${letToken.column}`);
+    }
+    const nameToken = this.advance();
+    if (AshParser.RESERVED_KEYWORDS.has(nameToken.value)) {
+      throw new Error(`Cannot use reserved keyword '${nameToken.value}' as variable name at line ${nameToken.line}, column ${nameToken.column}`);
+    }
+    if (this.letNames.has(nameToken.value)) {
+      throw new Error(`Duplicate variable name '${nameToken.value}' at line ${nameToken.line}, column ${nameToken.column}`);
+    }
+    if (this.paramNames.has(nameToken.value)) {
+      throw new Error(`Let variable '${nameToken.value}' conflicts with existing param at line ${nameToken.line}, column ${nameToken.column}`);
+    }
+    this.expect("ASSIGN", "Expected '=' after variable name");
+
+    // Check if the value is a pipeline (starts with find, action, etc.)
+    if (!this.isAtEnd() && AshParser.PIPELINE_STARTERS.has(this.peek().type)) {
+      const pipeline = this.parseLetPipeline();
+      this.letNames.add(nameToken.value);
+      return { kind: "let", name: nameToken.value, value: 0, pipeline };
+    }
+
+    const valToken = this.advance();
+    let value: string | number;
+    if (valToken.type === "NUMBER") {
+      value = parseFloat(valToken.value);
+    } else if (valToken.type === "STRING") {
+      value = valToken.value;
+    } else if (valToken.type === "IDENTIFIER") {
+      value = valToken.value;
+    } else {
+      throw new Error(`Expected value after '=' at line ${valToken.line}, column ${valToken.column}`);
+    }
+    this.letNames.add(nameToken.value);
+    return { kind: "let", name: nameToken.value, value };
+  }
+
+  private parseLetPipeline(): PipelineStage[] {
+    // Parse pipeline stages until NEWLINE, EOF, or JOB/LET/OUTPUT (top-level)
+    const stages: PipelineStage[] = [];
+    while (!this.isAtEnd()) {
+      const t = this.peek();
+      // Stop at newline or top-level keywords
+      if (t.type === "NEWLINE" || t.type === "JOB" || t.type === "LET" || t.type === "OUTPUT" || t.type === "AT") break;
+
+      if (t.type === "PIPE") {
+        this.advance(); // |
+        continue;
+      }
+
+      stages.push(this.parseStage());
+    }
+    return stages;
+  }
+
+  private parseAnnotations(): Annotation[] {
+    const annotations: Annotation[] = [];
+    while (!this.isAtEnd() && this.peek().type === "AT") {
+      const at = this.advance(); // @
+      if (this.isAtEnd() || this.peek().type !== "IDENTIFIER") {
+        throw new Error(`Expected annotation name after '@' at line ${at.line}, column ${at.column}`);
+      }
+      const nameToken = this.advance();
+      const args: string[] = [];
+
+      if (!this.isAtEnd() && this.peek().type === "LPAREN") {
+        this.advance(); // (
+        while (!this.isAtEnd() && this.peek().type !== "RPAREN") {
+          const arg = this.advance();
+          args.push(arg.value);
+          if (!this.isAtEnd() && this.peek().type === "COMMA") {
+            this.advance();
+          }
+        }
+        if (this.isAtEnd()) {
+          throw new Error(`Unclosed annotation parenthesis at line ${at.line}, column ${at.column}`);
+        }
+        this.advance(); // )
+      }
+
+      annotations.push({ name: nameToken.value, args, line: at.line, column: at.column });
+      this.skipNewlines();
+    }
+    return annotations;
+  }
+
+  private parseJob(annotations: Annotation[]): JobDeclaration {
+    this.advance(); // 'job'
+    this.skipNewlines();
+
+    if (this.isAtEnd()) {
+      throw new Error("Expected job name");
+    }
+    const nameToken = this.advance();
+    if (AshParser.RESERVED_KEYWORDS.has(nameToken.value)) {
+      throw new Error(`Cannot use reserved keyword '${nameToken.value}' as job name at line ${nameToken.line}, column ${nameToken.column}`);
+    }
+    this.skipNewlines();
+
+    // Optional trigger: `on /path:event` or `on cron("expr")`
+    let trigger: TriggerDeclaration | undefined;
+    if (!this.isAtEnd() && this.peek().type === "ON") {
+      const onToken = this.advance(); // on
+
+      if (!this.isAtEnd() && this.peek().type === "IDENTIFIER" && this.peek().value === "cron") {
+        // Cron trigger: on cron("*/5 * * * *")
+        this.advance(); // cron
+        if (this.isAtEnd() || this.peek().type !== "LPAREN") {
+          throw new Error(`Expected '(' after 'cron' at line ${onToken.line}, column ${onToken.column}`);
+        }
+        this.advance(); // (
+        if (this.isAtEnd() || this.peek().type !== "STRING") {
+          throw new Error(`Expected cron expression string after 'cron(' at line ${onToken.line}, column ${onToken.column}`);
+        }
+        const exprToken = this.advance();
+        if (this.isAtEnd() || this.peek().type !== "RPAREN") {
+          throw new Error(`Expected ')' after cron expression at line ${onToken.line}, column ${onToken.column}`);
+        }
+        this.advance(); // )
+        trigger = { kind: "cron", expression: exprToken.value };
+      } else {
+        // Event trigger: on /path:event
+        if (this.isAtEnd() || this.peek().type !== "PATH") {
+          throw new Error(`Expected path after 'on' at line ${onToken.line}, column ${onToken.column}`);
+        }
+        const pathToken = this.advance();
+        if (this.isAtEnd() || this.peek().type !== "COLON") {
+          throw new Error(`Expected ':event' after trigger path at line ${pathToken.line}, column ${pathToken.column}`);
+        }
+        this.advance(); // :
+        if (this.isAtEnd() || this.peek().type !== "IDENTIFIER") {
+          throw new Error(`Expected event name after ':' at line ${pathToken.line}, column ${pathToken.column}`);
+        }
+        const eventToken = this.advance();
+        trigger = { kind: "event", path: pathToken.value, event: eventToken.value };
+      }
+      this.skipNewlines();
+    }
+
+    if (this.isAtEnd() || this.peek().type !== "LBRACE") {
+      const t = this.isAtEnd() ? nameToken : this.peek();
+      throw new Error(`Expected '{' after job name at line ${t.line}, column ${t.column}`);
+    }
+    this.advance(); // {
+    this.skipNewlines();
+
+    const pipeline = this.parsePipeline();
+    this.skipNewlines();
+
+    if (this.isAtEnd() || this.peek().type !== "RBRACE") {
+      throw new Error("Expected '}' to close job body");
+    }
+    this.advance(); // }
+
+    return { kind: "job", name: nameToken.value, annotations, pipeline, trigger };
+  }
+
+  private parsePipeline(): PipelineStage[] {
+    const stages: PipelineStage[] = [];
+
+    while (!this.isAtEnd() && this.peek().type !== "RBRACE") {
+      if (this.peek().type === "PIPE") {
+        if (stages.length === 0) {
+          const t = this.peek();
+          throw new Error(`Unexpected PIPE at line ${t.line}, column ${t.column}`);
+        }
+        this.advance(); // |
+        this.skipNewlines();
+        if (this.isAtEnd() || this.peek().type === "RBRACE") {
+          throw new Error("Unexpected end after pipe operator");
+        }
+      }
+
+      this.skipNewlines();
+      if (this.isAtEnd() || this.peek().type === "RBRACE") break;
+
+      const stage = this.parseStage();
+      stages.push(stage);
+      this.skipNewlines();
+    }
+
+    return stages;
+  }
+
+  private parseStage(): PipelineStage {
+    const t = this.peek();
+
+    switch (t.type) {
+      case "FIND": {
+        this.advance();
+        const path = this.expect("PATH", "Expected path after 'find'");
+        // Check for inline where: `find /path where condition`
+        let query: QueryCondition | undefined;
+        if (!this.isAtEnd() && this.peek().type === "WHERE") {
+          this.advance(); // consume WHERE
+          const where = this.parseWhere();
+          query = { field: where.left, op: where.op, value: where.right };
+        }
+        return { kind: "find", path: path.value, query };
+      }
+      case "WHERE": {
+        this.advance();
+        return this.parseWhere();
+      }
+      case "MAP": {
+        this.advance();
+        return this.parseMapBody();
+      }
+      case "SAVE": {
+        this.advance();
+        const path = this.expect("PATH", "Expected path after 'save'");
+        return { kind: "save", path: path.value };
+      }
+      case "PUBLISH": {
+        this.advance();
+        const path = this.expect("PATH", "Expected path after 'publish'");
+        return { kind: "publish", path: path.value };
+      }
+      case "TEE": {
+        this.advance();
+        const path = this.expect("PATH", "Expected path after 'tee'");
+        return { kind: "tee", path: path.value };
+      }
+      case "FANOUT": {
+        this.advance();
+        return this.parseFanout();
+      }
+      case "OUTPUT": {
+        this.advance();
+        // Try parsing as expression (supports field access, binary, string literals)
+        const expr = this.parseExpression();
+        if (expr.kind === "literal" && typeof expr.value === "string") {
+          // Backward compatible: string literal → use message field
+          return { kind: "output", message: expr.value };
+        }
+        // Expression mode: evaluate per stream item at runtime
+        return { kind: "output", message: "", expression: expr };
+      }
+      case "INPUT": {
+        this.advance();
+        const prompt = this.expect("STRING", "Expected string after 'input'");
+        return { kind: "input", prompt: prompt.value };
+      }
+      case "COUNT": {
+        this.advance();
+        return { kind: "count" } as CountExpression;
+      }
+      case "GROUP_BY": {
+        this.advance();
+        if (this.isAtEnd() || this.peek().type === "PIPE" || this.peek().type === "RBRACE" || this.peek().type === "NEWLINE") {
+          throw new Error("Expected field name after 'group-by'");
+        }
+        const field = this.parseFieldAccess();
+        return { kind: "group-by", field } as GroupByExpression;
+      }
+      case "ACTION": {
+        return this.parseAction();
+      }
+      case "ROUTE": {
+        return this.parseRoute();
+      }
+      case "LOOKUP": {
+        return this.parseLookup();
+      }
+      default:
+        throw new Error(`Unexpected token ${t.type} "${t.value}" at line ${t.line}, column ${t.column}`);
+    }
+  }
+
+  private parseWhere(): WhereClause {
+    const left = this.parseFieldAccess();
+    const opToken = this.advance();
+    const opMap: Record<string, WhereClause["op"]> = {
+      "==": "==", "!=": "!=", ">": ">", "<": "<", ">=": ">=", "<=": "<=",
+    };
+    const op = opMap[opToken.value];
+    if (!op) {
+      throw new Error(`Expected comparison operator, got ${opToken.type} at line ${opToken.line}, column ${opToken.column}`);
+    }
+
+    let right: string | number;
+    // Check for $variable reference
+    if (!this.isAtEnd() && this.peek().type === "DOLLAR") {
+      this.advance(); // $
+      const varName = this.advance();
+      right = "$" + varName.value;
+    } else {
+      const rightToken = this.advance();
+      if (rightToken.type === "NUMBER") {
+        right = parseFloat(rightToken.value);
+      } else if (rightToken.type === "STRING") {
+        right = rightToken.value;
+      } else if (rightToken.type === "IDENTIFIER" || rightToken.type === "PATH") {
+        let val = rightToken.value;
+        while (!this.isAtEnd() && this.peek().type === "DOT") {
+          this.advance();
+          const next = this.advance();
+          val += "." + next.value;
+        }
+        right = val;
+      } else {
+        right = rightToken.value;
+      }
+    }
+
+    return { kind: "where", left, op, right };
+  }
+
+  private parseFieldAccess(): string {
+    const first = this.advance();
+    let field = first.value;
+    while (!this.isAtEnd() && this.peek().type === "DOT") {
+      this.advance(); // .
+      const next = this.advance();
+      field += "." + next.value;
+    }
+    return field;
+  }
+
+  private parseMapBody(): MapExpression {
+    // map without braces: either simple field or expression
+    if (this.isAtEnd() || this.peek().type === "PIPE" || this.peek().type === "RBRACE" || this.peek().type === "NEWLINE") {
+      throw new Error("Expected field or expression after 'map'");
+    }
+
+    if (this.peek().type !== "LBRACE") {
+      // map field or map expr (no braces)
+      // Try to parse as expression; if it's just a field access, use backward-compat field mode
+      const expr = this.parseExpression();
+      if (expr.kind === "field_access") {
+        return { kind: "map", field: expr.path };
+      }
+      return { kind: "map", field: "", expression: expr };
+    }
+
+    // map { ... }
+    this.advance(); // {
+    this.skipNewlines();
+
+    // Detect mode: peek ahead to see if first pair uses COLON (expression) or not (legacy)
+    if (this.isAtEnd() || this.peek().type === "RBRACE") {
+      this.advance(); // }
+      return { kind: "map", field: "" };
+    }
+
+    // Save position to peek ahead
+    const savedPos = this.pos;
+    // Skip the first key token
+    this.advance();
+    const hasColon = !this.isAtEnd() && this.peek().type === "COLON";
+    this.pos = savedPos; // restore
+
+    if (hasColon) {
+      // Expression mode: map { key: expr, ... }
+      // Use Object.create(null) to prevent __proto__ pollution
+      const exprMappings: Record<string, Expression> = Object.create(null);
+      const seenExprKeys = new Set<string>();
+      while (!this.isAtEnd() && this.peek().type !== "RBRACE") {
+        const keyToken = this.expect("IDENTIFIER", "Expected key in map expression");
+        if (seenExprKeys.has(keyToken.value)) {
+          throw new Error(`Duplicate map key '${keyToken.value}' at line ${keyToken.line}, column ${keyToken.column}`);
+        }
+        seenExprKeys.add(keyToken.value);
+        this.expect("COLON", "Expected ':' after key in map expression");
+        const expr = this.parseExpression();
+        exprMappings[keyToken.value] = expr;
+        this.skipNewlines();
+        if (!this.isAtEnd() && this.peek().type === "COMMA") {
+          this.advance();
+          this.skipNewlines();
+        }
+      }
+      if (this.isAtEnd()) throw new Error("Expected '}' to close map expression");
+      this.advance(); // }
+      return { kind: "map", field: "", exprMappings };
+    }
+
+    // Legacy mode: map { outputKey inputField, outputKey inputField }
+    // Use Object.create(null) to prevent __proto__ pollution
+    const mappings: Record<string, string> = Object.create(null);
+    const seenMapKeys = new Set<string>();
+    while (!this.isAtEnd() && this.peek().type !== "RBRACE") {
+      const key = this.advance();
+      if (seenMapKeys.has(key.value)) {
+        throw new Error(`Duplicate map key '${key.value}' at line ${key.line}, column ${key.column}`);
+      }
+      seenMapKeys.add(key.value);
+      const field = this.advance();
+      mappings[key.value] = field.value;
+      this.skipNewlines();
+      if (!this.isAtEnd() && this.peek().type === "COMMA") {
+        this.advance();
+        this.skipNewlines();
+      }
+    }
+    if (this.isAtEnd()) throw new Error("Expected '}' to close map object");
+    this.advance(); // }
+    const firstKey = Object.keys(mappings)[0] ?? "";
+    return { kind: "map", field: firstKey, mappings };
+  }
+
+  // ── Expression parsing (recursive descent with precedence) ──
+  // expr = term (('+' | '-') term)*
+  // term = factor (('*' | '/') factor)*
+  // factor = '(' expr ')' | $var | literal | fieldAccess
+
+  private parseExpression(): Expression {
+    let left = this.parseTerm();
+    while (!this.isAtEnd() && (this.peek().type === "PLUS" || this.peek().type === "MINUS")) {
+      const opToken = this.advance();
+      const right = this.parseTerm();
+      left = { kind: "binary", op: opToken.value as "+" | "-", left, right };
+    }
+    return left;
+  }
+
+  private parseTerm(): Expression {
+    let left = this.parseFactor();
+    while (!this.isAtEnd() && (this.peek().type === "STAR" || this.peek().type === "SLASH")) {
+      const opToken = this.advance();
+      const right = this.parseFactor();
+      left = { kind: "binary", op: opToken.value as "*" | "/", left, right };
+    }
+    return left;
+  }
+
+  private parseFactor(): Expression {
+    if (this.isAtEnd()) {
+      throw new Error("Expected expression");
+    }
+    const t = this.peek();
+
+    // Parenthesized expression
+    if (t.type === "LPAREN") {
+      this.advance(); // (
+      const expr = this.parseExpression();
+      this.expect("RPAREN", "Expected ')' after expression");
+      return expr;
+    }
+
+    // Variable reference: $name
+    if (t.type === "DOLLAR") {
+      this.advance(); // $
+      const nameToken = this.expect("IDENTIFIER", "Expected variable name after '$'");
+      return { kind: "var_ref", name: nameToken.value };
+    }
+
+    // String literal
+    if (t.type === "STRING") {
+      this.advance();
+      return { kind: "literal", value: t.value };
+    }
+
+    // Number literal
+    if (t.type === "NUMBER") {
+      this.advance();
+      return { kind: "literal", value: parseFloat(t.value) };
+    }
+
+    // Field access: identifier (possibly dotted)
+    if (t.type === "IDENTIFIER") {
+      let field = this.advance().value;
+      while (!this.isAtEnd() && this.peek().type === "DOT") {
+        this.advance(); // .
+        const next = this.advance();
+        field += "." + next.value;
+      }
+      return { kind: "field_access", path: field };
+    }
+
+    throw new Error(`Unexpected token in expression: ${t.type} "${t.value}" at line ${t.line}, column ${t.column}`);
+  }
+
+  private parseAction(): ActionExpression {
+    const actionToken = this.advance(); // action
+    if (this.isAtEnd()) {
+      throw new Error(`Expected path or action name after 'action' at line ${actionToken.line}, column ${actionToken.column}`);
+    }
+
+    const nextToken = this.peek();
+    let path: string;
+    let relative: boolean | undefined;
+
+    if (nextToken.type === "PATH") {
+      // Absolute action: action /tesla/.actions/honk
+      path = this.advance().value;
+    } else if (nextToken.type === "IDENTIFIER") {
+      // Relative action: action turn_off
+      path = this.advance().value;
+      relative = true;
+    } else {
+      throw new Error(`Expected path or action name after 'action' at line ${actionToken.line}, column ${actionToken.column}`);
+    }
+
+    let params: Record<string, unknown> | undefined;
+
+    // Optional params: { key: value, ... }
+    if (!this.isAtEnd() && this.peek().type === "LBRACE") {
+      this.advance(); // {
+      params = {};
+      this.skipNewlines();
+      while (!this.isAtEnd() && this.peek().type !== "RBRACE") {
+        const keyToken = this.expect("IDENTIFIER", "Expected parameter name in action params");
+        this.expect("COLON", "Expected ':' after parameter name");
+        if (this.isAtEnd()) {
+          throw new Error(`Expected value after ':' at line ${keyToken.line}, column ${keyToken.column}`);
+        }
+        // Check for json() wrapper
+        if (this.peek().type === "IDENTIFIER" && this.peek().value === "json") {
+          const jsonToken = this.advance(); // consume "json"
+          this.expect("LPAREN", `Expected '(' after json at line ${jsonToken.line}, column ${jsonToken.column}`);
+          params[keyToken.value] = this.parseJsonValue();
+          this.expect("RPAREN", "Expected ')' to close json()");
+        } else {
+          const valToken = this.advance();
+          if (valToken.type === "STRING") {
+            params[keyToken.value] = valToken.value;
+          } else if (valToken.type === "NUMBER") {
+            params[keyToken.value] = parseFloat(valToken.value);
+          } else {
+            throw new Error(`Expected string or number value for parameter '${keyToken.value}' at line ${valToken.line}, column ${valToken.column}`);
+          }
+        }
+        this.skipNewlines();
+        if (!this.isAtEnd() && this.peek().type === "COMMA") {
+          this.advance();
+          this.skipNewlines();
+        }
+      }
+      if (this.isAtEnd()) throw new Error("Expected '}' to close action params");
+      this.advance(); // }
+    }
+
+    return { kind: "action", path, relative, params };
+  }
+
+  private parseRoute(): RouteExpression {
+    const routeToken = this.advance(); // route
+    if (this.isAtEnd() || (this.peek().type !== "IDENTIFIER" && this.peek().type !== "DOT")) {
+      throw new Error(`Expected field name after 'route' at line ${routeToken.line}, column ${routeToken.column}`);
+    }
+    const field = this.parseFieldAccess();
+    this.expect("LBRACE", "Expected '{' after route field");
+    this.skipNewlines();
+
+    const branches: RouteBranch[] = [];
+    let fallback: string | undefined;
+
+    while (!this.isAtEnd() && this.peek().type !== "RBRACE") {
+      // Each branch: "value" -> job target  OR  _ -> job target
+      let value: string;
+      if (this.peek().type === "STRING") {
+        value = this.advance().value;
+      } else if (this.peek().type === "IDENTIFIER" && this.peek().value === "_") {
+        value = "_";
+        this.advance();
+      } else {
+        throw new Error(`Expected string value or '_' in route branch at line ${this.peek().line}, column ${this.peek().column}`);
+      }
+
+      this.expect("ARROW", "Expected '->' in route branch");
+      this.expect("JOB", "Expected 'job' keyword in route branch target");
+      const targetToken = this.advance(); // job name
+
+      if (value === "_") {
+        fallback = targetToken.value;
+      } else {
+        branches.push({ value, targetJob: targetToken.value });
+      }
+
+      this.skipNewlines();
+      if (!this.isAtEnd() && this.peek().type === "COMMA") {
+        this.advance();
+        this.skipNewlines();
+      }
+    }
+
+    if (branches.length === 0 && !fallback) {
+      throw new Error(`Route must have at least one branch at line ${routeToken.line}, column ${routeToken.column}`);
+    }
+
+    if (this.isAtEnd()) throw new Error("Expected '}' to close route");
+    this.advance(); // }
+
+    return { kind: "route", field, branches, fallback };
+  }
+
+  private parseLookup(): LookupExpression {
+    const lookupToken = this.advance(); // lookup
+    if (this.isAtEnd() || this.peek().type !== "PATH") {
+      throw new Error(`Expected path after 'lookup' at line ${lookupToken.line}, column ${lookupToken.column}`);
+    }
+    const pathToken = this.advance();
+    // Expect "on" keyword
+    if (this.isAtEnd() || this.peek().type !== "ON") {
+      throw new Error(`Expected 'on' keyword after lookup path at line ${lookupToken.line}, column ${lookupToken.column}`);
+    }
+    this.advance(); // on
+    const joinKey = this.parseFieldAccess();
+    return { kind: "lookup", path: pathToken.value, joinKey };
+  }
+
+  private parseFanout(): PipelineStage {
+    this.expect("LBRACE", "Expected '{' after 'fanout'");
+    const branches: PipelineStage[][] = [];
+
+    this.skipNewlines();
+    while (!this.isAtEnd() && this.peek().type !== "RBRACE") {
+      // Each branch is a pipeline until COMMA or RBRACE
+      const branch: PipelineStage[] = [];
+      while (!this.isAtEnd() && this.peek().type !== "COMMA" && this.peek().type !== "RBRACE" && this.peek().type !== "NEWLINE") {
+        if (this.peek().type === "PIPE") {
+          this.advance();
+        }
+        branch.push(this.parseStage());
+      }
+      branches.push(branch);
+      this.skipNewlines();
+      if (!this.isAtEnd() && this.peek().type === "COMMA") {
+        this.advance();
+        this.skipNewlines();
+      }
+    }
+
+    if (this.isAtEnd()) throw new Error("Expected '}' to close fanout");
+    this.advance(); // }
+
+    return { kind: "fanout", branches };
+  }
+
+  /** Recursive descent JSON value parser using existing lexer tokens. */
+  private parseJsonValue(): unknown {
+    if (this.isAtEnd()) throw new Error("Expected JSON value (unexpected EOF)");
+    const t = this.peek();
+
+    // Object: { ... }
+    if (t.type === "LBRACE") {
+      this.advance(); // {
+      const obj: Record<string, unknown> = {};
+      this.skipNewlines();
+      while (!this.isAtEnd() && this.peek().type !== "RBRACE") {
+        const keyToken = this.advance();
+        if (keyToken.type !== "STRING" && keyToken.type !== "IDENTIFIER") {
+          throw new Error(`Expected string key in JSON object at line ${keyToken.line}, column ${keyToken.column}`);
+        }
+        this.expect("COLON", "Expected ':' after key in JSON object");
+        obj[keyToken.value] = this.parseJsonValue();
+        this.skipNewlines();
+        if (!this.isAtEnd() && this.peek().type === "COMMA") {
+          this.advance();
+          this.skipNewlines();
+        }
+      }
+      if (this.isAtEnd()) throw new Error("Expected '}' to close JSON object");
+      this.advance(); // }
+      return obj;
+    }
+
+    // Array: [ ... ]
+    if (t.type === "LBRACKET") {
+      this.advance(); // [
+      const arr: unknown[] = [];
+      this.skipNewlines();
+      while (!this.isAtEnd() && this.peek().type !== "RBRACKET") {
+        arr.push(this.parseJsonValue());
+        this.skipNewlines();
+        if (!this.isAtEnd() && this.peek().type === "COMMA") {
+          this.advance();
+          this.skipNewlines();
+        }
+      }
+      if (this.isAtEnd()) throw new Error("Expected ']' to close JSON array");
+      this.advance(); // ]
+      return arr;
+    }
+
+    // String
+    if (t.type === "STRING") {
+      this.advance();
+      return t.value;
+    }
+
+    // Number
+    if (t.type === "NUMBER") {
+      this.advance();
+      return parseFloat(t.value);
+    }
+
+    // Boolean / null: true, false, null are lexed as IDENTIFIER
+    if (t.type === "IDENTIFIER") {
+      if (t.value === "true") { this.advance(); return true; }
+      if (t.value === "false") { this.advance(); return false; }
+      if (t.value === "null") { this.advance(); return null; }
+    }
+
+    throw new Error(`Unexpected token in json(): ${t.type} "${t.value}" at line ${t.line}, column ${t.column}`);
+  }
+
+  private peek(): Token {
+    return this.tokens[this.pos];
+  }
+
+  private advance(): Token {
+    return this.tokens[this.pos++];
+  }
+
+  private expect(type: TokenType, message: string): Token {
+    if (this.isAtEnd()) throw new Error(message + " (unexpected EOF)");
+    const t = this.peek();
+    if (t.type !== type) {
+      throw new Error(`${message}, got ${t.type} at line ${t.line}, column ${t.column}`);
+    }
+    return this.advance();
+  }
+
+  private isAtEnd(): boolean {
+    return this.pos >= this.tokens.length || this.tokens[this.pos].type === "EOF";
+  }
+
+  private skipNewlines(): void {
+    while (!this.isAtEnd() && this.peek().type === "NEWLINE") {
+      this.pos++;
+    }
+  }
+}