@statedelta-libs/expressions 2.3.0 → 3.1.0

package/README.md

@@ -5,868 +5,227 @@
 [![npm version](https://img.shields.io/npm/v/@statedelta-libs/expressions.svg)](https://www.npmjs.com/package/@statedelta-libs/expressions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Características
-
-- **DSL Puro** - 100% JSON-serializável, sem callbacks inline
-- **Compilação** - Compila uma vez, executa milhões de vezes
-- **Alta performance** - ~25-30M ops/s após compilação
-- **Scope externo** - Funções puras vêm via scope, não hardcoded
-- **Context externo** - HOCs de continuidade via context (`tryCatch`, `transaction`, etc.)
-- **RuntimeCtx unificado** - Contexto de runtime limpo com `{ data, get }`
-- **Accessor customizado** - Suporte a `ctx.get(path)` para objetos especiais
-- **$pipe** - Composição com valor inicial (sintaxe DSL)
-- **$cb** - Callback expressions para HOCs de continuidade
-- **Path syntax** - Suporte a wildcards (`items[*].price`)
-- **Dependency extraction** - Para dirty tracking/reatividade
-- **Conditions nativo** - Condicionais integradas com expressions nos lados
-- **normalize()** - Helper externo para custom transforms (`$query`, `$mapper`, etc.)
-- **resolveBoundaries()** - Resolve boundaries customizados (`$simulate`, `$context`, etc.) com compilação independente
-- **Type-safe** - TypeScript nativo com inferência
+## O que é
+
+Um compilador que transforma expressões declarativas em JSON puro em funções JavaScript de alta performance. A entrada é sempre JSON serializável. A saída é sempre uma `(data) => result`.
+
+O compilador não conhece nenhuma função — todas vêm via `scope` fornecido pelo consumer. O mesmo motor serve para matemática, queries de game engine, ETL, NoCode, ou qualquer domínio.
 
 ## Instalação
 
 ```bash
-npm install @statedelta-libs/expressions
-# ou
 pnpm add @statedelta-libs/expressions
 ```
 
 ## Quick Start
 
 ```typescript
-import { compile } from '@statedelta-libs/expressions';
-
-// Define o scope com funções disponíveis
-const scope = {
-  filter: (pred) => (arr) => arr?.filter(pred),
-  map: (fn) => (arr) => arr?.map(fn),
-  sum: (arr) => arr?.reduce((a, b) => a + b, 0),
-  isActive: (item) => item.active,
-  getPrice: (item) => item.price,
-};
+import { ExpressionCompiler } from '@statedelta-libs/expressions';
+
+const compiler = new ExpressionCompiler({
+  scope: {
+    add: (a, b) => a + b,
+    multiply: (a, b) => a * b,
+    filter: (pred) => (arr) => arr.filter(pred),
+    sum: (arr) => arr.reduce((a, b) => a + b, 0),
+  },
+});
 
-// Compilar expressão com $pipe (DSL puro)
-const expr = compile({
+// Compila uma vez
+const compiled = compiler.compile({
   $pipe: [
     { $: "items" },
-    { $fn: "filter", args: [{ $fn: "isActive" }] },
-    { $fn: "map", args: [{ $fn: "getPrice" }] },
+    { $fn: "filter", args: [{ $arrow: { $: "item.active" }, args: ["item"] }] },
     { $fn: "sum" }
   ]
-}, { scope });
-
-// Executar (muito rápido!)
-const data = {
-  items: [
-    { name: "A", price: 10, active: true },
-    { name: "B", price: 20, active: false },
-    { name: "C", price: 30, active: true }
-  ]
-};
+});
 
-expr.fn(data);  // 40
-expr.deps;      // ["items"]
+// Executa milhões de vezes
+compiled.fn({ items: [{ active: true, price: 10 }, { active: false, price: 20 }] });
+compiled.deps;  // ["items"]
 ```
 
-## API
-
-### compile()
-
-Compila expressão JSON DSL para função otimizada usando closures.
+## Os 5 Primitivos
 
-```typescript
-const { fn, deps, hash } = compile(expression, { scope });
-
-fn(data);     // Executa
-deps;         // Paths que a expressão depende
-hash;         // Hash único (para cache)
-```
+| Primitivo | O que faz | Exemplo DSL | JS equivalente |
+|-----------|-----------|-------------|----------------|
+| `$` | Referência a path | `{ $: "user.name" }` | `data.user.name` |
+| `$fn` | Invocação/referência de função | `{ $fn: "add", args: [...] }` | `add(a, b)` |
+| `$if` | Condicional | `{ $if: cond, then: a, else: b }` | `cond ? a : b` |
+| `$pipe` | Composição left-to-right | `{ $pipe: [x, f, g] }` | `g(f(x))` |
+| `$arrow` | Closure deferida | `{ $arrow: body, args: ["x"] }` | `(x) => body` |
 
-### compileAST()
+Tudo 100% JSON-serializável. Funções nunca aparecem no DSL — são referenciadas por nome e resolvidas contra o scope em runtime.
 
-Compila usando AST + `new Function()`. **Mais rápido na execução**, ideal para expressões executadas muitas vezes.
+## Dois Modos de Compilação
 
 ```typescript
-import { compileAST } from '@statedelta-libs/expressions';
-
-const { fn, deps, hash } = compileAST(expression, { scope });
-
-fn(data);     // Executa (mais rápido que compile())
+compiler.compile(expr);     // closures — compilação rápida, ~9-20M ops/s
+compiler.jit(expr);         // JIT — compilação lenta, ~25-27M ops/s de execução
 ```
 
-**Quando usar cada um:**
+**Closures** compõe funções JavaScript aninhadas. Ideal para expressões executadas poucas vezes ou ambientes com CSP restritivo.
 
-| Cenário | Recomendação | Por quê |
-|---------|--------------|---------|
-| Execução única | `compile()` | Compilação mais rápida |
-| Poucas execuções (<8x) | `compile()` | Overhead de AST não compensa |
-| Muitas execuções (>8x) | `compileAST()` | Execução ~25-170% mais rápida |
-| Hot path crítico | `compileAST()` | V8 JIT otimiza melhor |
-| Expressões complexas | `compileAST()` | Ganho maior em nested calls |
+**JIT** gera código JavaScript via AST e `new Function()`. Ideal para hot paths executados muitas vezes. Break-even em ~8 execuções.
 
-#### useAccessor (compileAST)
+## Extensibilidade
 
-Para contextos inteligentes (ex: `TickContext`), use `useAccessor: true` para gerar `accessor(path, data)` ao invés de acesso direto:
+### Scope — funções disponíveis
 
 ```typescript
-const ctx = new TickContext();
-
-const { fn } = compileAST(
-  { $fn: "add", args: [{ $: "hp" }, { $: "mp" }] },
-  {
-    scope: {
-      add,
-      accessor: (path) => ctx.get(path)  // closure que captura ctx
+const compiler = new ExpressionCompiler({
+  scope: {
+    add: (a, b) => a + b,
+    filter: (pred) => (arr) => arr.filter(pred),
+    tryCatch: (arrow, params) => {
+      try { return arrow(); }
+      catch { return params?.fallback ?? null; }
     },
-    useAccessor: true
-  }
-);
-
-fn();  // usa ctx.get("hp") + ctx.get("mp")
-```
-
-#### lexicalPrefix (compileAST)
-
-Para máxima performance em paths específicos, use `lexicalPrefix` para acesso direto via destructuring:
-
-```typescript
-const ctx = new TickContext();
-
-const { fn } = compileAST(
-  { $fn: "add", args: [{ $: "hp" }, { $: "params.damage" }] },
-  {
-    scope: {
-      add,
-      accessor: (path) => ctx.get(path)
-    },
-    useAccessor: true,
-    lexicalPrefix: "params"  // params.* vai direto, resto via accessor
-  }
-);
-
-fn({ params: { damage: 25 } });  // ctx.get("hp") + params.damage
-```
-
-### evaluate() / evaluateAST()
-
-Compila e executa em um passo.
-
-```typescript
-const result = evaluate(
-  { $fn: "add", args: [{ $: "a" }, { $: "b" }] },
-  { a: 1, b: 2 },
-  { scope: { add: (a, b) => a + b } }
-);
-// 3
-
-// Versão AST
-const result = evaluateAST(expression, data, { scope });
-```
-
-### extractDeps()
-
-Extrai dependências sem compilar.
-
-```typescript
-const deps = extractDeps({
-  $if: "$isVip",
-  then: { $: "price.vip" },
-  else: { $: "price.regular" }
+  },
 });
-// ["$isVip", "price.vip", "price.regular"]
 ```
 
-### normalize()
+### Normalize — DSL customizado
 
-Normaliza expressões customizadas para DSL puro **antes** da compilação.
+Transforma sugar syntax em DSL puro **antes** da compilação. Para quando o resultado é expression DSL válido.
 
 ```typescript
-import { normalize, type Transforms } from '@statedelta-libs/expressions';
-
-const transforms: Transforms = {
-  $query: (node) => ({
-    $fn: "__query",
-    args: [node.$query as string, (node.params ?? {}) as Expression],
-  }),
+const transforms = {
+  $double: (node) => ({ $fn: "multiply", args: [node.$double, 2] }),
 };
 
-// Converte expressão customizada para DSL puro
-const pure = normalize(
-  { $query: "isAttacked", params: { row: { $: "kingRow" } } },
-  transforms
-);
-// → { $fn: "__query", args: ["isAttacked", { row: { $: "kingRow" } }] }
-
-// Agora pode compilar normalmente
-const { fn } = compile(pure, { scope });
+const pure = compiler.normalize({ $double: { $: "value" } }, transforms);
+compiler.compile(pure);
 ```
 
-## Tipos de Expressão
-
-### Literal
+### Boundaries — compiladores externos
 
-```typescript
-42
-"hello"
-true
-[1, 2, 3]
-{ a: 1 }
-```
-
-### Reference ($)
+Intercepta nós **durante** a compilação e terceiriza para outro algoritmo. Para quando o nó precisa de um compilador completamente diferente.
 
 ```typescript
-{ $: "user.name" }           // Acessa user.name
-{ $: "items[0].price" }      // Acessa índice
-{ $: "items[*].price" }      // Wildcard → [10, 20, 30]
-```
-
-### Conditional ($if)
-
-```typescript
-{
-  $if: { left: { $: "age" }, op: "gte", right: 18 },
-  then: "adult",
-  else: "minor"
-}
-
-// Shorthand
-{ $if: "$isVip", then: 0.2, else: 0 }
-{ $if: "!$isBlocked", then: "allowed" }
-```
-
-### Pipe ($pipe)
-
-Composição com valor inicial - o valor passa por cada função em sequência.
-
-```typescript
-{
-  $pipe: [
-    { $: "items" },                                   // Valor inicial
-    { $fn: "filter", args: [{ $fn: "isActive" }] },   // Curried filter
-    { $fn: "map", args: [{ $fn: "getPrice" }] },      // Curried map
-    { $fn: "sum" }                                    // Referência à função
-  ]
-}
-```
-
-### Function Call ($fn)
-
-Chama função do scope com argumentos compilados.
-
-```typescript
-// Com args: chama a função
-{ $fn: "add", args: [{ $: "a" }, { $: "b" }] }
-// → scope.add(data.a, data.b)
-
-// Sem args: retorna referência à função (útil em $pipe)
-{ $fn: "sum" }
-// → scope.sum
-
-// Com args vazio: chama função sem argumentos
-{ $fn: "getTimestamp", args: [] }
-// → scope.getTimestamp()
-
-// Passando função como argumento (referência via $fn)
-{ $fn: "filter", args: [{ $fn: "isActive" }] }
-// → scope.filter(scope.isActive)
-```
-
-### Condition
-
-Condicionais compiladas internamente. Ambos os lados aceitam qualquer expressão:
-
-```typescript
-// Ref vs literal (básico)
-{ left: { $: "user.age" }, op: "gte", right: 18 }
-
-// Ref vs Ref
-{ left: { $: "price" }, op: "lte", right: { $: "budget" } }
-
-// $fn nos lados
-{ left: { $fn: "add", args: [{ $: "a" }, { $: "b" }] }, op: "gt", right: 100 }
-
-// $pipe no lado
-{ left: { $pipe: [{ $: "name" }, { $fn: "upper" }] }, op: "eq", right: "ADMIN" }
-
-// Condition group
-{
-  logic: "AND",
-  conditions: [
-    { left: { $: "active" }, op: "eq", right: true },
-    { left: { $fn: "len", args: [{ $: "items" }] }, op: "gte", right: 3 }
-  ]
-}
-```
-
-**Operadores:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `contains`, `notContains`, `exists`, `notExists`, `matches`, `notMatches`, `startsWith`, `endsWith`
-
-### Callback ($cb)
-
-HOC de continuidade - executa body dentro de um context function.
-
-```typescript
-// Básico - tryCatch
-{ $cb: "tryCatch", body: { $fn: "query" } }
-
-// Com parâmetros
-{ $cb: "transaction", body: { $fn: "save" }, params: { isolation: "serializable" } }
-
-// Aninhado
-{
-  $cb: "tryCatch",
-  body: {
-    $cb: "transaction",
-    body: { $fn: "save" }
-  }
-}
-```
-
-## Context
-
-O context define HOCs disponíveis para `$cb`. Diferente de scope (funções puras), context functions controlam a execução do body.
-
-### RuntimeCtx
-
-O context recebe um `RuntimeCtx` unificado com `{ data, get }`:
-
-```typescript
-interface RuntimeCtx<T> {
-  data: T;                         // Dados do runtime
-  get: (path: string) => unknown;  // Accessor de paths
-}
-```
-
-### ContextFn
+import type { BoundaryDef } from '@statedelta-libs/expressions';
 
-```typescript
-type ContextFn<T, R> = (
-  cb: (ctx: RuntimeCtx<T>) => R,   // Body compilado
-  ctx: RuntimeCtx<T>,              // Contexto de runtime
-  params?: unknown                  // Parâmetros do $cb (opcional)
-) => R;
-```
-
-### Exemplos
-
-```typescript
-import type { Context, ContextFn, RuntimeCtx } from '@statedelta-libs/expressions';
-
-// tryCatch - captura erros
-const tryCatch: ContextFn = (cb, ctx, params) => {
-  try {
-    return cb(ctx);
-  } catch {
-    return (params as { fallback?: unknown })?.fallback ?? null;
-  }
+// $raw — passthrough, nada é compilado
+const rawBoundary: BoundaryDef = {
+  check: (node) => "$raw" in node,
+  handle: (node) => () => node.$raw,
 };
 
-// transaction - modifica data para o body
-const transaction: ContextFn = (cb, ctx, params) => {
-  const tx = db.beginTransaction(params);
-  try {
-    // Cria novo ctx com tx no data
-    const result = cb({ ...ctx, data: { ...ctx.data, tx } });
-    tx.commit();
-    return result;
-  } catch (e) {
-    tx.rollback();
-    throw e;
-  }
-};
-
-// cached - pode ignorar o cb e retornar outro valor
-const cached: ContextFn = (cb, ctx, params) => {
-  const key = (params as { key: string })?.key;
-  if (cache.has(key)) {
-    return cache.get(key);  // Não executa cb
-  }
-  const result = cb(ctx);
-  cache.set(key, result);
-  return result;
-};
-
-// simulate - injeta accessor customizado
-const simulate: ContextFn = (cb, ctx, params) => {
-  // Cria get que lê de store simulado
-  const simulatedGet = (path: string) => store.getSimulated(path);
-  // Body usa simulatedGet ao invés do get padrão
-  return cb({ ...ctx, get: simulatedGet });
+// $rules — DSL estrangeiro com compilador próprio
+const rulesBoundary: BoundaryDef = {
+  check: (node) => "$rules" in node,
+  handle: (node) => {
+    const compiled = ruleEngine.compile(node.$rules);
+    return (data) => compiled.evaluate(data);
+  },
 };
 
-const context: Context = { tryCatch, transaction, cached, simulate };
+const compiler = new ExpressionCompiler({
+  scope,
+  boundaries: [rawBoundary, rulesBoundary],
+});
 
-compile(expression, { scope, context });
+// $rules é interceptado pelo boundary, compilado pelo ruleEngine
+compiler.compile({
+  $fn: "add",
+  args: [{ $: "base" }, { $rules: { when: "vip", then: 20 } }]
+});
 ```
 
-### O que o Context pode fazer
-
-| Ação | Exemplo |
-|------|---------|
-| **Executar normalmente** | `return cb(ctx)` |
-| **Modificar data** | `return cb({ ...ctx, data: { ...ctx.data, extra } })` |
-| **Injetar accessor** | `return cb({ ...ctx, get: customGet })` |
-| **Ignorar body** | `return cachedValue` (não chama cb) |
-| **Capturar erros** | `try { cb(ctx) } catch { ... }` |
-| **Usar ctx.get** | `const val = ctx.get("user.name")` |
-
-## Scope
-
-O scope define quais funções estão disponíveis para `$fn`:
-
-```typescript
-import * as R from '@statedelta-libs/operators';
-
-// Todas as funções do operators
-const scope = R;
-
-// Ou seleção específica
-const scope = {
-  add: R.add,
-  filter: R.filter,
-  map: R.map,
-  sum: R.sum,
-  // Funções custom (predicados, mappers, etc.)
-  double: (n) => n * 2,
-  isActive: (item) => item.active,
-  getPrice: (item) => item.price,
-};
+O handler é uma closure auto-suficiente — captura o que precisa (outros compiladores, databases, etc.) por fora. Zero overhead quando não há boundaries registrados.
 
-const { fn } = compile(expression, { scope });
-```
+| | `normalize()` | `BoundaryDef` |
+|---|---|---|
+| **Quando roda** | Antes da compilação | Durante a compilação (no walk) |
+| **Retorno** | `Expression` (DSL puro) | `CompiledFn` (função pronta) |
+| **Uso típico** | Sugar syntax | DSL estrangeiro, `$raw`, rule engines |
 
-## Custom Transforms (normalize)
+### Handlers — services com contexto
 
-Para tipos de expressão customizados (`$query`, `$mapper`, etc.), use `normalize()` para convertê-los em DSL puro **antes** da compilação:
+O `scope` é para funções puras e stateless. Quando o consumer precisa de **services inteligentes** que acessam o sistema (accessor, outros handlers, o compilador, o scope), usa `handlers`.
 
 ```typescript
-import { normalize, compile, type Transforms, type Expression } from '@statedelta-libs/expressions';
-
-// Define transforms
-const transforms: Transforms = {
-  $query: (node) => ({
-    $fn: "__query",
-    args: [node.$query as string, (node.params ?? {}) as Expression],
-  }),
-  $mapper: (node) => ({
-    $fn: "__mapper",
-    args: [node.$mapper as string],
-  }),
-};
+import type { HandlerContext } from '@statedelta-libs/expressions';
 
-// Define scope com as funções de runtime
-const scope = {
-  __query: (name, params) => queryEngine.run(name, params),
-  __mapper: (name) => mapperRegistry.get(name),
-};
-
-// 1. Normalize (converte para DSL puro)
-const pure = normalize(
-  { $query: "isAttacked", params: { row: { $: "kingRow" } } },
-  transforms
-);
-
-// 2. Compile (DSL puro)
-const { fn } = compile(pure, { scope });
-
-// 3. Execute
-fn({ kingRow: 0 });
-```
-
-### Aninhamento
-
-O `normalize` percorre toda a árvore, então transforms funcionam em qualquer posição:
-
-```typescript
-normalize(
-  {
-    $if: {
-      left: { $query: "isAttacked", params: { row: 0 } },
-      op: "eq",
-      right: true
+const compiler = new ExpressionCompiler({
+  scope: { add: (a, b) => a + b },
+  handlers: {
+    query: {
+      find(key: string) {
+        return db.find(key);
+      },
+      findAll() {
+        // chamar outro handler
+        const valid = this.handlers.validation.check("all");
+        return valid ? db.findAll() : [];
+      },
+    },
+    validation: {
+      check(value: unknown) {
+        // chamar scope fn
+        return this.scope.add(value != null ? 1 : 0, 0) > 0;
+      },
     },
-    then: "check",
-    else: "safe"
   },
-  transforms
-);
-```
-
-### Proteção contra loops
-
-Se um transform retornar objeto com a mesma chave, erro é lançado:
-
-```typescript
-const badTransforms = {
-  $loop: (node) => ({ $loop: node.$loop }),  // mesma chave!
-};
-
-normalize({ $loop: "test" }, badTransforms);
-// Error: Transform "$loop" returned object with same key — infinite loop
+});
 ```
 
-## Boundaries (resolveBoundaries)
-
-Para DSL customizados que precisam de **compilação independente** dos slots internos, use `resolveBoundaries()`. Diferente de `normalize()` (que apenas transforma), boundaries param o fluxo de compilação e delegam para um resolver externo.
-
-### Conceito
-
-Um **boundary** é um "corpo estranho" no DSL que:
-1. **Para** o fluxo normal de compilação
-2. **Delega** para um resolver customizado
-3. O resolver **compila slots internos** independentemente
-4. **Substitui** por uma referência no scope
+Handlers são invocados via `$fn` com sintaxe `"namespace:method"`:
 
+```json
+{ "$fn": "query:find", "args": [{ "$": "userId" }] }
+{ "$fn": "validation:check", "args": [{ "$": "value" }] }
 ```
-DSL "rico"                    DSL puro
-{ $simulate: {...} }    →    { $fn: "__simulate_0", args: [] }
-                              + scope["__simulate_0"] = fn compilada
-```
-
-### Uso básico
 
-```typescript
-import { resolveBoundaries, compile, type BoundaryResolvers } from '@statedelta-libs/expressions';
-
-const resolvers: BoundaryResolvers = {
-  $context: (node, { compile: compileFn, genId, scope }) => {
-    const id = `__context_${genId()}`;
-    const body = (node.$context as { body: Expression }).body;
-
-    // Compila o body internamente
-    const bodyFn = compileFn(body, { scope }).fn;
-
-    // Retorna função com lifecycle begin/end
-    const contextFn = () => (data: unknown) => {
-      console.log("begin");
-      try {
-        return bodyFn(data);
-      } finally {
-        console.log("end");
-      }
-    };
-
-    return {
-      expr: { $fn: id, args: [] },
-      scopeEntry: [id, contextFn],
-    };
-  },
-};
+O contexto é acessado via `this`, injetado automaticamente via `.bind()` no construtor. O `HandlerContext` é criado **uma vez** — zero alocação por chamada:
 
-// 1. Resolve boundaries (extrai e compila internamente)
-const { expr, scope } = resolveBoundaries(
-  { $context: { body: { $fn: "add", args: [{ $: "a" }, { $: "b" }] } } },
-  { resolvers, scope: { add: (a, b) => a + b } }
-);
+| Campo | O que contém |
+|-------|-------------|
+| `this.accessor` | Resolver de paths customizado |
+| `this.handlers` | Todos os handlers (wrapped) — permite composição entre handlers |
+| `this.compiler` | Instância do compilador — permite compilar sub-expressões |
+| `this.scope` | Funções puras do scope |
 
-// 2. Compila DSL puro resultante
-const { fn } = compile(expr, { scope });
-
-// 3. Executa
-const contextFn = fn({});           // Retorna a função com lifecycle
-const result = contextFn({ a: 1, b: 2 });  // "begin" → 3 → "end"
-```
-
-### Caso de uso: $simulate com múltiplos slots
+Handlers **devem** ser regular functions ou method shorthand (arrow functions ignoram `.bind()`):
 
 ```typescript
-interface SimulateNode {
-  $simulate: {
-    effects: Expression[];
-    query: Expression;
-  };
-}
-
-const resolvers: BoundaryResolvers = {
-  $simulate: (node, { compile: compileFn, genId, scope }) => {
-    const id = `__simulate_${genId()}`;
-    const sim = (node as unknown as SimulateNode).$simulate;
-
-    // Compila cada slot independentemente
-    const effectFns = sim.effects.map((e) => compileFn(e, { scope }).fn);
-    const queryFn = compileFn(sim.query, { scope }).fn;
-
-    // Cria função que orquestra a execução
-    const simulateFn = () => (data: unknown) => {
-      const effects = effectFns.map((fn) => fn(data));
-      const query = queryFn(data);
-      return { effects, query };
-    };
-
-    return {
-      expr: { $fn: id, args: [] },
-      scopeEntry: [id, simulateFn],
-    };
-  },
-};
+// method shorthand — funciona
+handlers: { query: { find(key) { this.scope... } } }
 
-const { expr, scope } = resolveBoundaries(
-  {
-    $simulate: {
-      effects: [
-        { $fn: "increment", args: [{ $: "hp" }] },
-        { $fn: "decrement", args: [{ $: "mp" }] },
-      ],
-      query: { $fn: "isAlive", args: [{ $: "hp" }] },
-    },
-  },
-  { resolvers, scope: myScope }
-);
-```
-
-### Contexto do resolver
-
-O resolver recebe um contexto com:
-
-| Propriedade | Tipo | Descrição |
-|-------------|------|-----------|
-| `compile` | `typeof compile` | Mesmo compilador do fluxo principal |
-| `genId` | `() => string` | Gerador de IDs únicos |
-| `scope` | `Scope` | Scope atual (read-only) |
-| `options` | `CompileOptions` | Opções de compilação |
+// regular function — funciona
+handlers: { query: { find: function(key) { this.scope... } } }
 
-### ID Generator customizado
-
-Por padrão, IDs são gerados como `"0"`, `"1"`, `"2"`... Para IDs únicos globais, passe um `genId` customizado:
-
-```typescript
-import { nanoid } from 'nanoid';
-
-const { expr, scope } = resolveBoundaries(expr, {
-  resolvers,
-  scope: baseScope,
-  genId: () => nanoid(),  // IDs únicos globais
-});
+// arrow function — NÃO funciona (this é undefined)
+handlers: { query: { find: (key) => { this.scope... } } }
 ```
 
-### Diferença entre normalize e resolveBoundaries
-
-| | `normalize()` | `resolveBoundaries()` |
+| | `scope` | `handlers` |
 |---|---|---|
-| **Propósito** | Transformar sintaxe | Compilação independente |
-| **Retorno** | `Expression` | `{ expr, scope }` |
-| **Compila slots** | Não | Sim (via `ctx.compile`) |
-| **Acumula scope** | Não | Sim |
-| **Uso típico** | `$query` → `$fn` | `$simulate`, `$context` |
-
-Use `normalize()` para sugar syntax simples. Use `resolveBoundaries()` quando precisar:
-- Compilar múltiplos slots independentemente
-- Controlar ordem/momento de execução
-- Adicionar lógica de lifecycle (begin/end, try/finally)
-- DSL completamente diferente internamente
+| **Natureza** | Funções puras (Ramda-style) | Services com contexto |
+| **Acessa** | Apenas args compilados | `this` (HandlerContext) + args |
+| **DSL** | `{ $fn: "add", args: [...] }` | `{ $fn: "query:find", args: [...] }` |
+| **Binding** | Nenhum | `.bind(ctx)` uma vez no construtor |
+| **Overhead** | Zero | Zero (ctx e bindings criados uma vez) |
 
-## Builders
+Zero overhead quando nenhum handler é registrado.
 
-Funções declarativas para construir expressões:
+### Accessor — objetos inteligentes
 
 ```typescript
-import { builders } from '@statedelta-libs/expressions';
-
-const { $, $fn, $if, $pipe, $cond, $cb } = builders;
-
-// Path reference
-$("player.hp")                    // { $: "player.hp" }
-
-// Function call
-$fn("add", [$("a"), $("b")])      // { $fn: "add", args: [...] }
-$fn("sum")                        // { $fn: "sum" }
-
-// Conditional
-$if($("isVip"), 0.2, 0)           // { $if: ..., then: 0.2, else: 0 }
-
-// Pipe
-$pipe(
-  $("items"),
-  $fn("filter", [$fn("isActive")]),
-  $fn("sum")
-)
-
-// Condition
-$cond($("age"), "gte", 18)        // { left: ..., op: "gte", right: 18 }
-
-// Callback (context)
-$cb("tryCatch", $fn("query"))     // { $cb: "tryCatch", body: {...} }
-$cb("transaction", $fn("save"), { isolation: "serializable" })
-```
-
-## TypeScript
-
-```typescript
-import type {
-  Expression,
-  CompiledExpression,
-  RefExpr,
-  ConditionalExpr,
-  FnExpr,
-  PipeExpr,
-  CbExpr,
-  Condition,
-  ConditionGroup,
-  ConditionExpr,
-  ConditionOp,
-  Scope,
-  Context,
-  ContextFn,
-  RuntimeCtx,
-  PathGetterFn,
-  CompileOptions,
-  AccessorFn,
-  TransformFn,
-  Transforms,
-  // Boundaries
-  BoundaryResolver,
-  BoundaryResolvers,
-  ResolverContext,
-  ResolverResult,
-  ResolveBoundariesOptions,
-  ResolveBoundariesResult,
-  IdGenerator,
-} from '@statedelta-libs/expressions';
-
-// Type guards
-import {
-  isRef,
-  isConditional,
-  isFn,
-  isPipe,
-  isCb,
-  isCondition,
-  isLiteral,
-} from '@statedelta-libs/expressions';
+const compiler = new ExpressionCompiler({
+  scope,
+  accessor: (path) => tickContext.get(path),  // closure auto-suficiente
+});
 ```
 
-## Performance
-
-### Comparação Execução
-
-| Cenário | Closures | AST | Ganho AST |
-|---------|----------|-----|-----------|
-| fn nested | 9M ops/s | 25M ops/s | **+169%** |
-| ref 4 níveis | 16M ops/s | 27M ops/s | **+69%** |
-| conditional nested | 20M ops/s | 25M ops/s | **+25%** |
-
-**Break-even:** ~8 execuções - após isso, `compileAST()` compensa o tempo extra de compilação.
-
-## Segurança
-
-Ambas as abordagens são **seguras contra injeção de código**:
-
-| Método | Proteção |
-|--------|----------|
-| `compile()` | Não gera código string - apenas compõe funções |
-| `compileAST()` | Usa destructuring que valida identificadores automaticamente |
-
-Funções só são acessíveis se existirem no `scope` fornecido pelo desenvolvedor.
-
-## Migração
+## Documentação
 
-### v1.1 → v1.2
-
-1. **DSL Puro**: `FnExpr.args` agora é `Expression[]` (removido suporte a callbacks inline). Funções devem ser passadas via scope:
-   ```typescript
-   // Antes (callbacks inline - não funciona mais)
-   { $fn: "filter", args: [(item) => item.active] }
-
-   // Depois (referência via scope)
-   { $fn: "filter", args: [{ $fn: "isActive" }] }
-   // Com scope: { isActive: (item) => item.active, filter: ... }
-   ```
-
-2. **Removidos**: `CallbackFn`, `FnArg` types
-
-3. **normalize()**: Custom transforms agora são externos via `normalize()`, não mais dentro de `CompileOptions`:
-   ```typescript
-   // Antes
-   compile(expr, { scope, transforms });
-
-   // Depois
-   const pure = normalize(expr, transforms);
-   compile(pure, { scope });
-   ```
-
-4. **Novos tipos**: `Transforms` (alias para `Record<string, TransformFn>`)
-
-### v1.2 → v2.0
-
-1. **Novo tipo `$cb`**: HOC de continuidade para wrapping contextual:
-   ```typescript
-   // tryCatch, transaction, cached, etc.
-   { $cb: "tryCatch", body: { $fn: "query" }, params: { fallback: [] } }
-   ```
-
-2. **Novo `context` em CompileOptions**: Separado de `scope` para HOCs:
-   ```typescript
-   compile(expr, { scope, context });
-   compileAST(expr, { scope, context });
-   ```
-
-3. **Novos tipos**: `CbExpr`, `Context`, `ContextFn`, `PathGetterFn`
-
-4. **Novo type guard**: `isCb()`
-
-5. **Novo builder**: `$cb(name, body, params?)`
-
-6. **Novo extractor**: `extractContextFns()`
-
-7. **Novo `resolveBoundaries()`**: Para DSL customizados com compilação independente de slots:
-   ```typescript
-   const { expr, scope } = resolveBoundaries(richExpr, {
-     resolvers: { $simulate: (node, ctx) => ... },
-     scope: baseScope,
-     genId: () => nanoid(),  // opcional
-   });
-   compile(expr, { scope });
-   ```
-
-8. **Novos tipos**: `BoundaryResolver`, `BoundaryResolvers`, `ResolverContext`, `ResolverResult`, `ResolveBoundariesOptions`, `ResolveBoundariesResult`, `IdGenerator`
-
-### v2.0 → v2.1
-
-1. **Nova API do ContextFn**: Agora usa `RuntimeCtx` unificado ao invés de parâmetros separados:
-   ```typescript
-   // Antes (v2.0)
-   const tryCatch: ContextFn = (cb, data, get, params) => {
-     try {
-       return cb(data, get);
-     } catch {
-       return params?.fallback;
-     }
-   };
-
-   // Depois (v2.1)
-   const tryCatch: ContextFn = (cb, ctx, params) => {
-     try {
-       return cb(ctx);
-     } catch {
-       return params?.fallback;
-     }
-   };
-   ```
-
-2. **RuntimeCtx**: Novo tipo que agrupa `data` e `get`:
-   ```typescript
-   interface RuntimeCtx<T> {
-     data: T;
-     get: (path: string) => unknown;
-   }
-   ```
-
-3. **Injeção de accessor**: Context pode injetar `get` customizado:
-   ```typescript
-   const simulate: ContextFn = (cb, ctx) => {
-     const customGet = (path) => store.getSimulated(path);
-     return cb({ ...ctx, get: customGet });
-   };
-   ```
-
-4. **Modificar data**: Agora via spread do ctx:
-   ```typescript
-   // Antes
-   cb({ ...data, tx }, get)
-
-   // Depois
-   cb({ ...ctx, data: { ...ctx.data, tx } })
-   ```
+| Doc | Conteúdo |
+|-----|----------|
+| [docs/EXPRESSIONS-API.md](docs/EXPRESSIONS-API.md) | Referência completa da API pública |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Visão geral da infraestrutura |
+| [docs/COMPILE.md](docs/COMPILE.md) | Internals do pipeline closures |
+| [docs/JIT.md](docs/JIT.md) | Internals do pipeline JIT |
 
 ## Licença