pyric 0.0.1 → 0.1.0-alpha.10

package/dist/rules/simulator/expression/parser.js

@@ -0,0 +1,329 @@
+/**
+ * Item 4.1.3 — Recursive-descent parser for the transaction-tool
+ * expression language.
+ *
+ * `parse(tokens)` consumes a token stream from `tokenize()` and returns
+ * a single `AstNode` representing the whole expression. The parser
+ * implements the corrected grammar (see types.ts header for the four
+ * supersedence corrections):
+ *
+ *   Expression  = Ternary
+ *   Ternary     = LogicalOr ( "?" Expression ":" Expression )?
+ *   LogicalOr   = LogicalAnd ( "||" LogicalAnd )*
+ *   LogicalAnd  = Comparison ( "&&" Comparison )*
+ *   Comparison  = Sum ( ("==" | "!=" | "<" | "<=" | ">" | ">=") Sum )*
+ *   Sum         = Product ( ("+" | "-") Product )*
+ *   Product     = Unary ( ("*" | "/" | "%") Unary )*
+ *   Unary       = ("-" | "!") Unary | Postfix
+ *   Postfix     = Primary ("." Identifier | "[" Expression "]")*
+ *   Primary     = Number | String | Boolean | Null
+ *               | Reference | SentinelCall | "(" Expression ")"
+ *
+ * Defensive choices, mirrored from the pre-mortem:
+ *  - Comparison and arithmetic chains are LEFT-associative; ternary is
+ *    RIGHT-associative. Both are tested explicitly so a future refactor
+ *    can't silently flip them.
+ *  - `&&` and `||` are SPLIT into LogicalAnd / LogicalOr so `a || b && c`
+ *    parses as `a || (b && c)` (mainstream-language convention, matches
+ *    Firestore Rules).
+ *  - Sentinels MUST have a name on the whitelist, MUST have parens, and
+ *    MUST satisfy arity at parse time. Failure is a loud
+ *    `ExpressionParseError` before evaluation begins.
+ *  - AST depth (root-to-leaf, counting every node) is enforced after
+ *    parsing in a single O(n) walk. The 256-char source cap bounds the
+ *    AST size globally, so the depth check is correctness-only, not a
+ *    DoS gate.
+ */
+import { EXPRESSION_LIMITS, ExpressionParseError, isSentinelName, SENTINEL_ARITY, } from './types.js';
+export function parse(tokens) {
+    const p = new Parser(tokens);
+    const node = p.parseExpression();
+    p.expect('eof', 'unexpected trailing tokens');
+    enforceDepthCap(node);
+    return node;
+}
+class Parser {
+    tokens;
+    cursor = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    // ----- top of the grammar -----
+    parseExpression() {
+        return this.parseTernary();
+    }
+    /**
+     * Ternary is RIGHT-associative: `a ? b : c ? d : e` → `a ? b : (c ? d : e)`.
+     * Both branches are full Expressions, so the recursion is natural.
+     */
+    parseTernary() {
+        const cond = this.parseLogicalOr();
+        if (this.peek().kind !== 'question')
+            return cond;
+        const q = this.consume();
+        const whenTrue = this.parseExpression();
+        this.expect('colon', `expected ':' in ternary`);
+        const whenFalse = this.parseExpression();
+        return {
+            kind: 'ternary',
+            cond,
+            whenTrue,
+            whenFalse,
+            pos: q.pos,
+        };
+    }
+    /**
+     * LogicalOr — split out from LogicalAnd so `||` binds LOOSER than `&&`.
+     * `a && b || c && d` parses as `(a && b) || (c && d)`.
+     */
+    parseLogicalOr() {
+        let left = this.parseLogicalAnd();
+        while (this.peek().kind === 'or') {
+            const op = this.consume();
+            const right = this.parseLogicalAnd();
+            left = { kind: 'logical', op: '||', left, right, pos: op.pos };
+        }
+        return left;
+    }
+    parseLogicalAnd() {
+        let left = this.parseComparison();
+        while (this.peek().kind === 'and') {
+            const op = this.consume();
+            const right = this.parseComparison();
+            left = { kind: 'logical', op: '&&', left, right, pos: op.pos };
+        }
+        return left;
+    }
+    /**
+     * Comparison chains are syntactically allowed (`1 < 2 < 3` parses)
+     * but semantically nonsense — `(1 < 2) < 3` evaluates `bool < number`,
+     * which the strict-typing evaluator rejects. Loud at eval, not parse.
+     */
+    parseComparison() {
+        let left = this.parseSum();
+        while (true) {
+            const op = comparisonOp(this.peek().kind);
+            if (!op)
+                break;
+            const tok = this.consume();
+            const right = this.parseSum();
+            left = { kind: 'binary', op, left, right, pos: tok.pos };
+        }
+        return left;
+    }
+    parseSum() {
+        let left = this.parseProduct();
+        while (true) {
+            const k = this.peek().kind;
+            if (k !== 'plus' && k !== 'minus')
+                break;
+            const tok = this.consume();
+            const right = this.parseProduct();
+            const op = k === 'plus' ? '+' : '-';
+            left = { kind: 'binary', op, left, right, pos: tok.pos };
+        }
+        return left;
+    }
+    parseProduct() {
+        let left = this.parseUnary();
+        while (true) {
+            const k = this.peek().kind;
+            if (k !== 'star' && k !== 'slash' && k !== 'percent')
+                break;
+            const tok = this.consume();
+            const right = this.parseUnary();
+            const op = k === 'star' ? '*' : k === 'slash' ? '/' : '%';
+            left = { kind: 'binary', op, left, right, pos: tok.pos };
+        }
+        return left;
+    }
+    parseUnary() {
+        const k = this.peek().kind;
+        if (k === 'minus' || k === 'bang') {
+            const tok = this.consume();
+            const operand = this.parseUnary();
+            return {
+                kind: 'unary',
+                op: k === 'minus' ? '-' : '!',
+                operand,
+                pos: tok.pos,
+            };
+        }
+        return this.parsePostfix();
+    }
+    /**
+     * Postfix: dot-access and bracket-access chain on any Primary.
+     * `$a.b[0].c["k"]` is a four-link chain.
+     */
+    parsePostfix() {
+        let target = this.parsePrimary();
+        while (true) {
+            const k = this.peek().kind;
+            if (k === 'dot') {
+                const tok = this.consume();
+                const ident = this.expect('identifier', `expected identifier after '.'`);
+                target = {
+                    kind: 'fieldAccess',
+                    target,
+                    field: ident.value,
+                    pos: tok.pos,
+                };
+            }
+            else if (k === 'lbracket') {
+                const tok = this.consume();
+                const index = this.parseExpression();
+                this.expect('rbracket', `expected ']'`);
+                target = { kind: 'indexAccess', target, index, pos: tok.pos };
+            }
+            else {
+                break;
+            }
+        }
+        return target;
+    }
+    parsePrimary() {
+        const tok = this.peek();
+        switch (tok.kind) {
+            case 'number':
+                this.consume();
+                return { kind: 'literal', value: tok.value, pos: tok.pos };
+            case 'string':
+                this.consume();
+                return { kind: 'literal', value: tok.value, pos: tok.pos };
+            case 'true':
+                this.consume();
+                return { kind: 'literal', value: true, pos: tok.pos };
+            case 'false':
+                this.consume();
+                return { kind: 'literal', value: false, pos: tok.pos };
+            case 'null':
+                this.consume();
+                return { kind: 'literal', value: null, pos: tok.pos };
+            case 'reference':
+                this.consume();
+                return { kind: 'reference', alias: tok.value, pos: tok.pos };
+            case 'sentinel':
+                return this.parseSentinelCall();
+            case 'lparen': {
+                this.consume();
+                const inner = this.parseExpression();
+                this.expect('rparen', `expected ')'`);
+                return inner;
+            }
+            case 'identifier':
+                // Bare identifiers are not values in this grammar. Common
+                // typo pattern: writing `increment(1)` instead of `@increment(1)`.
+                throw new ExpressionParseError(`bare identifier '${tok.value}' is not a value (did you mean '$${tok.value}' or '@${tok.value}'?)`, tok.pos);
+            case 'eof':
+                throw new ExpressionParseError(`unexpected end of expression`, tok.pos);
+            default:
+                throw new ExpressionParseError(`unexpected token`, tok.pos);
+        }
+    }
+    parseSentinelCall() {
+        const tok = this.consume();
+        const name = tok.value;
+        if (!isSentinelName(name)) {
+            throw new ExpressionParseError(`unknown sentinel '@${name}' (allowed: serverTimestamp, increment, arrayUnion, arrayRemove, deleteField)`, tok.pos);
+        }
+        // Parens REQUIRED — see Q3 sign-off in the design doc.
+        this.expect('lparen', `expected '(' after sentinel '@${name}'`);
+        const args = [];
+        if (this.peek().kind !== 'rparen') {
+            args.push(this.parseExpression());
+            while (this.peek().kind === 'comma') {
+                this.consume();
+                args.push(this.parseExpression());
+            }
+        }
+        this.expect('rparen', `expected ')' after sentinel arguments`);
+        const arity = SENTINEL_ARITY[name];
+        if (args.length < arity.min || args.length > arity.max) {
+            const expectStr = arity.max === Infinity
+                ? `at least ${arity.min}`
+                : arity.min === arity.max
+                    ? `exactly ${arity.min}`
+                    : `${arity.min}..${arity.max}`;
+            throw new ExpressionParseError(`sentinel '@${name}' expects ${expectStr} argument(s), got ${args.length}`, tok.pos);
+        }
+        return { kind: 'sentinel', name: name, args, pos: tok.pos };
+    }
+    // ----- token-stream primitives -----
+    peek() {
+        return this.tokens[this.cursor];
+    }
+    consume() {
+        const t = this.tokens[this.cursor];
+        this.cursor += 1;
+        return t;
+    }
+    expect(kind, message) {
+        const t = this.peek();
+        if (t.kind !== kind) {
+            throw new ExpressionParseError(`${message} (got ${describeToken(t)})`, t.pos);
+        }
+        return this.consume();
+    }
+}
+function comparisonOp(kind) {
+    switch (kind) {
+        case 'eq': return '==';
+        case 'neq': return '!=';
+        case 'lt': return '<';
+        case 'lte': return '<=';
+        case 'gt': return '>';
+        case 'gte': return '>=';
+        default: return null;
+    }
+}
+function describeToken(t) {
+    if (t.kind === 'eof')
+        return 'end of expression';
+    if (t.value !== undefined)
+        return `${t.kind} ${JSON.stringify(t.value)}`;
+    return t.kind;
+}
+/**
+ * Walk the AST once, checking that no root-to-leaf path exceeds the
+ * depth cap. We compute depth bottom-up; if any node's max child depth
+ * + 1 would exceed the cap, throw at that node's position.
+ */
+function enforceDepthCap(root) {
+    walk(root);
+    function walk(n) {
+        let childDepth = 0;
+        switch (n.kind) {
+            case 'literal':
+            case 'reference':
+                childDepth = 0;
+                break;
+            case 'unary':
+                childDepth = walk(n.operand);
+                break;
+            case 'binary':
+            case 'logical':
+                childDepth = Math.max(walk(n.left), walk(n.right));
+                break;
+            case 'ternary':
+                childDepth = Math.max(walk(n.cond), walk(n.whenTrue), walk(n.whenFalse));
+                break;
+            case 'fieldAccess':
+                childDepth = walk(n.target);
+                break;
+            case 'indexAccess':
+                childDepth = Math.max(walk(n.target), walk(n.index));
+                break;
+            case 'sentinel':
+                childDepth = n.args.length === 0
+                    ? 0
+                    : Math.max(...n.args.map(walk));
+                break;
+        }
+        const depth = childDepth + 1;
+        if (depth > EXPRESSION_LIMITS.maxAstDepth) {
+            throw new ExpressionParseError(`expression AST exceeds depth cap of ${EXPRESSION_LIMITS.maxAstDepth}`, n.pos);
+        }
+        return depth;
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/rules/simulator/expression/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../../src/rules/simulator/expression/parser.ts"],"names":[],"mappings":"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"}

package/dist/rules/simulator/expression/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Item 4.1.1 — AST node types, token kinds, error classes, and the
+ * sentinel arity table for the `firestore_simulator_transaction` MCP
+ * tool's expression language.
+ *
+ * The expression language is a bounded, side-effect-free arithmetic +
+ * boolean DSL evaluated server-side against a captured read-set. It
+ * exists so an agent can write `{ "$expr": "$src.balance - 30" }`
+ * without ever seeing `$src.balance`'s value (context-cost
+ * minimisation, see the design rationale).
+ *
+ * This module is pure types + constants — no logic. The lexer
+ * (Item 4.1.2) and parser (Item 4.1.3) import from here; the
+ * evaluator (Item 4.2) imports the AST shape; the tool layer
+ * (Item 4.4) imports the error classes for surface-level catches.
+ *
+ * Four corrections to the design doc's literal EBNF live in its
+ * Decisions Log; this module IS the corrected spec:
+ *   1. `&&` binds tighter than `||` (split LogicalAnd / LogicalOr).
+ *   2. Numeric literals are unsigned; `-` is always an operator.
+ *   3. Sentinel parens are required.
+ *   4. AST depth counts AST nodes, not parser recursion.
+ */
+export declare const EXPRESSION_LIMITS: {
+    /** Max characters in the source expression. Checked BEFORE tokenising. */
+    readonly maxExpressionLength: 256;
+    /** Max characters in any single string literal token. Checked at lex time. */
+    readonly maxStringLiteralLength: 1024;
+    /** Max AST node depth from root. Checked during parser construction. */
+    readonly maxAstDepth: 16;
+};
+export interface Position {
+    /** 0-based offset into the source string. */
+    offset: number;
+    /** 1-based column number (we don't track lines — expressions are one-line). */
+    column: number;
+}
+export type TokenKind = 'number' | 'string' | 'true' | 'false' | 'null' | 'identifier' | 'reference' | 'sentinel' | 'lparen' | 'rparen' | 'lbracket' | 'rbracket' | 'comma' | 'dot' | 'question' | 'colon' | 'plus' | 'minus' | 'star' | 'slash' | 'percent' | 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'and' | 'or' | 'bang' | 'eof';
+export interface Token {
+    kind: TokenKind;
+    pos: Position;
+    /**
+     * For `number`: the parsed numeric value (already validated finite +
+     * within safe-integer for ints).
+     * For `string`: the unescaped string contents (escapes processed).
+     * For `identifier` | `reference` | `sentinel`: the identifier text
+     * (without the `$` or `@` prefix).
+     * For everything else: undefined.
+     */
+    value?: string | number;
+}
+export type BinaryOp = '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '<' | '<=' | '>' | '>=';
+export type UnaryOp = '-' | '!';
+export type LogicalOp = '&&' | '||';
+export type AstNode = LiteralNode | ReferenceNode | SentinelNode | UnaryNode | BinaryNode | LogicalNode | TernaryNode | FieldAccessNode | IndexAccessNode;
+export interface LiteralNode {
+    kind: 'literal';
+    value: number | string | boolean | null;
+    pos: Position;
+}
+export interface ReferenceNode {
+    kind: 'reference';
+    alias: string;
+    pos: Position;
+}
+export interface SentinelNode {
+    kind: 'sentinel';
+    name: SentinelName;
+    args: AstNode[];
+    pos: Position;
+}
+export interface UnaryNode {
+    kind: 'unary';
+    op: UnaryOp;
+    operand: AstNode;
+    pos: Position;
+}
+export interface BinaryNode {
+    kind: 'binary';
+    op: BinaryOp;
+    left: AstNode;
+    right: AstNode;
+    pos: Position;
+}
+/**
+ * Logical operators are split out from `BinaryNode` because they
+ * short-circuit (eval-only concern) and because their precedence is
+ * different from arithmetic comparisons. Keeping them as a distinct
+ * node forces the evaluator to reach a separate handler — easy to
+ * audit, hard to silently regress.
+ */
+export interface LogicalNode {
+    kind: 'logical';
+    op: LogicalOp;
+    left: AstNode;
+    right: AstNode;
+    pos: Position;
+}
+export interface TernaryNode {
+    kind: 'ternary';
+    cond: AstNode;
+    whenTrue: AstNode;
+    whenFalse: AstNode;
+    pos: Position;
+}
+export interface FieldAccessNode {
+    kind: 'fieldAccess';
+    target: AstNode;
+    field: string;
+    pos: Position;
+}
+export interface IndexAccessNode {
+    kind: 'indexAccess';
+    target: AstNode;
+    index: AstNode;
+    pos: Position;
+}
+export declare const SENTINEL_NAMES: readonly ["serverTimestamp", "increment", "arrayUnion", "arrayRemove", "deleteField"];
+export type SentinelName = typeof SENTINEL_NAMES[number];
+export interface SentinelArity {
+    min: number;
+    /** `Infinity` for variadic. */
+    max: number;
+}
+export declare const SENTINEL_ARITY: Record<SentinelName, SentinelArity>;
+export declare function isSentinelName(name: string): name is SentinelName;
+export declare class ExpressionLexError extends Error {
+    readonly code: "invalid-argument";
+    readonly pos: Position;
+    constructor(message: string, pos: Position);
+}
+export declare class ExpressionParseError extends Error {
+    readonly code: "invalid-argument";
+    readonly pos: Position;
+    constructor(message: string, pos: Position);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rules/simulator/expression/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/rules/simulator/expression/types.ts"],"names":[],"mappings":"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"}

package/dist/rules/simulator/expression/types.js

@@ -0,0 +1,90 @@
+/**
+ * Item 4.1.1 — AST node types, token kinds, error classes, and the
+ * sentinel arity table for the `firestore_simulator_transaction` MCP
+ * tool's expression language.
+ *
+ * The expression language is a bounded, side-effect-free arithmetic +
+ * boolean DSL evaluated server-side against a captured read-set. It
+ * exists so an agent can write `{ "$expr": "$src.balance - 30" }`
+ * without ever seeing `$src.balance`'s value (context-cost
+ * minimisation, see the design rationale).
+ *
+ * This module is pure types + constants — no logic. The lexer
+ * (Item 4.1.2) and parser (Item 4.1.3) import from here; the
+ * evaluator (Item 4.2) imports the AST shape; the tool layer
+ * (Item 4.4) imports the error classes for surface-level catches.
+ *
+ * Four corrections to the design doc's literal EBNF live in its
+ * Decisions Log; this module IS the corrected spec:
+ *   1. `&&` binds tighter than `||` (split LogicalAnd / LogicalOr).
+ *   2. Numeric literals are unsigned; `-` is always an operator.
+ *   3. Sentinel parens are required.
+ *   4. AST depth counts AST nodes, not parser recursion.
+ */
+// ---------------------------------------------------------------------
+// Bounded-eval limits.
+// Defense-in-depth caps; first hit at the tool layer (input length),
+// then in the lexer (string-literal length, total token count
+// derivative), then in the parser (AST depth on construction).
+// ---------------------------------------------------------------------
+export const EXPRESSION_LIMITS = {
+    /** Max characters in the source expression. Checked BEFORE tokenising. */
+    maxExpressionLength: 256,
+    /** Max characters in any single string literal token. Checked at lex time. */
+    maxStringLiteralLength: 1024,
+    /** Max AST node depth from root. Checked during parser construction. */
+    maxAstDepth: 16,
+};
+// ---------------------------------------------------------------------
+// Sentinel whitelist + arity.
+// Locked in design doc (Decisions Log): five user-callable sentinels,
+// 1:1 name match with `value-resolver.ts`'s registered converters.
+// `Infinity` for `max` denotes variadic; the parser checks `args.length
+// >= min && args.length <= max`.
+// ---------------------------------------------------------------------
+export const SENTINEL_NAMES = [
+    'serverTimestamp',
+    'increment',
+    'arrayUnion',
+    'arrayRemove',
+    'deleteField',
+];
+export const SENTINEL_ARITY = {
+    serverTimestamp: { min: 0, max: 0 },
+    increment: { min: 1, max: 1 },
+    arrayUnion: { min: 1, max: Infinity },
+    arrayRemove: { min: 1, max: Infinity },
+    deleteField: { min: 0, max: 0 },
+};
+export function isSentinelName(name) {
+    return SENTINEL_NAMES.includes(name);
+}
+// ---------------------------------------------------------------------
+// Errors.
+// Two distinct classes so the tool layer can switch behaviour:
+//   - LexError: produced before tokens (unterminated string, bad char).
+//   - ParseError: produced from a token stream (bad shape, depth cap,
+//     unknown sentinel, wrong arity, oversize expression).
+// Both carry a `Position` so the response can point to the offending
+// column. Both inherit a `code` matching `FIRESTORE_ERROR_CODES` so
+// the tool maps them to `invalid-argument` without a separate switch.
+// ---------------------------------------------------------------------
+export class ExpressionLexError extends Error {
+    code = 'invalid-argument';
+    pos;
+    constructor(message, pos) {
+        super(message);
+        this.name = 'ExpressionLexError';
+        this.pos = pos;
+    }
+}
+export class ExpressionParseError extends Error {
+    code = 'invalid-argument';
+    pos;
+    constructor(message, pos) {
+        super(message);
+        this.name = 'ExpressionParseError';
+        this.pos = pos;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/rules/simulator/expression/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/rules/simulator/expression/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wEAAwE;AACxE,uBAAuB;AACvB,qEAAqE;AACrE,8DAA8D;AAC9D,+DAA+D;AAC/D,wEAAwE;AAExE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,0EAA0E;IAC1E,mBAAmB,EAAE,GAAG;IACxB,8EAA8E;IAC9E,sBAAsB,EAAE,IAAI;IAC5B,wEAAwE;IACxE,WAAW,EAAE,EAAE;CACP,CAAC;AAoJX,wEAAwE;AACxE,8BAA8B;AAC9B,sEAAsE;AACtE,mEAAmE;AACnE,wEAAwE;AACxE,iCAAiC;AACjC,wEAAwE;AAExE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,iBAAiB;IACjB,WAAW;IACX,YAAY;IACZ,aAAa;IACb,aAAa;CACL,CAAC;AAUX,MAAM,CAAC,MAAM,cAAc,GAAwC;IACjE,eAAe,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;IACnC,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;IAC7B,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE;IACrC,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE;IACtC,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;CAChC,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAQ,cAAoC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED,wEAAwE;AACxE,UAAU;AACV,+DAA+D;AAC/D,wEAAwE;AACxE,sEAAsE;AACtE,2DAA2D;AAC3D,qEAAqE;AACrE,oEAAoE;AACpE,sEAAsE;AACtE,wEAAwE;AAExE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,kBAA2B,CAAC;IACnC,GAAG,CAAW;IACvB,YAAY,OAAe,EAAE,GAAa;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,kBAA2B,CAAC;IACnC,GAAG,CAAW;IACvB,YAAY,OAAe,EAAE,GAAa;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF"}

package/dist/rules/simulator/expression/walk-data.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Item 4.3 — Recursive walker that resolves `{ $expr: "..." }`
+ * wrappers anywhere in a write `data` tree.
+ *
+ * Contract:
+ *  - Walks the input tree once. Returns a NEW tree (the input is
+ *    never mutated).
+ *  - A wrapper is exactly an object whose ONLY key is `$expr` and
+ *    whose `$expr` value is a string. Any other shape with `$expr`
+ *    (extra keys, non-string value) throws `ExpressionWalkError`
+ *    with `code: 'invalid-argument'`.
+ *  - Arrays preserve length and order; wrappers inside arrays are
+ *    resolved in place.
+ *  - The walker DOES NOT recurse into eval results. If `$expr`
+ *    resolves to an object containing a `$expr` key (e.g. from a
+ *    doc read), that nested key is treated as data — not a wrapper.
+ *  - Errors include a path string (`users.0.balance`) so agents can
+ *    locate the offending leaf.
+ *
+ * Pre-mortem-locked behaviors:
+ *  - `null` is a literal value, NOT a target for descent.
+ *  - Top-level `{ $expr: ... }` is allowed. The tool layer enforces
+ *    that the *resolved* top-level data is a plain object before
+ *    handing to the simulator.
+ *  - Sentinel passthrough objects (`{ __type: '...' }`) returned by
+ *    eval are leaf values — the walker doesn't descend into them.
+ */
+import { type Position } from './types.js';
+import { type EvalEnv } from './eval-errors.js';
+/**
+ * Errors raised by the walker for shape violations (ambiguous wrapper,
+ * non-string `$expr` value). Distinct from `EvalError` so the tool
+ * layer can label the failure precisely.
+ */
+export declare class ExpressionWalkError extends Error {
+    readonly code: "invalid-argument";
+    /** Dotted path to the offending node, e.g. `users.0.balance`. */
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Returned alongside throws so the tool layer can map a walker /
+ * eval failure to a position-bearing response.
+ */
+export interface WalkContext {
+    /** Source-string of the most recently parsed expression, if any. */
+    lastExpressionSource?: string;
+    /** Source position within `lastExpressionSource`, if applicable. */
+    lastExpressionPosition?: Position;
+}
+export declare function resolveExpressionsInData(data: unknown, env: EvalEnv): unknown;
+//# sourceMappingURL=walk-data.d.ts.map

package/dist/rules/simulator/expression/walk-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-data.d.ts","sourceRoot":"","sources":["../../../../src/rules/simulator/expression/walk-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAEL,KAAK,QAAQ,EAGd,MAAM,YAAY,CAAC;AAIpB,OAAO,EAEL,KAAK,OAAO,EAEb,MAAM,kBAAkB,CAAC;AAI1B;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAU;IAC5C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAK1C;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,sBAAsB,CAAC,EAAE,QAAQ,CAAC;CACnC;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,OAAO,GACX,OAAO,CAET"}