@softize/opus 8.6.6

package/src/data/drivers/kysely.ts

@@ -0,0 +1,389 @@
+/**
+ * @softize/opus/data/kysely — Kysely driver
+ *
+ * Implementa `DataAdapter` envolvendo uma instância `Kysely<DB>`.
+ * Expõe `ctx.db` tipado pros handlers e implementa `healthCheck()`
+ * via `SELECT 1`.
+ *
+ * Uso:
+ *   import { Kysely, PostgresDialect } from 'kysely'
+ *   import { kyselyData } from '@softize/opus/data/kysely'
+ *
+ *   const db = new Kysely<DB>({ dialect: new PostgresDialect({ pool }) })
+ *
+ *   createRuntime({
+ *     data: kyselyData({ db }),
+ *     ...
+ *   })
+ *
+ *   // No handler:
+ *   handler: async (ctx) => {
+ *     const deals = await (ctx.db as Kysely<DB>).selectFrom('deals')...
+ *   }
+ */
+
+import { randomUUID } from 'node:crypto'
+
+import { z } from 'zod'
+import { defineAction, error, type ActionDef, type AuthorizeFn } from '../../core/index.ts'
+import type { DataAdapter, HealthStatus, Paginated } from '../../core/index.ts'
+import {
+  desiredColumns,
+  diffColumns,
+  entityTable,
+  entityPk,
+  entityRowSchema,
+  entityInsertSchema,
+  entityUpdateSchema,
+  resolveNaming,
+  type DriftFinding,
+  type EntityConfig,
+  type EntityRow,
+  type EntityInsert,
+  type EntityUpdate,
+  type NamingStrategy,
+} from '../../schema/entity.ts'
+import { type Kysely, sql } from 'kysely'
+
+export interface KyselyDataOptions<DB> {
+  /** Instância Kysely já configurada com dialect e pool. */
+  db: Kysely<DB>
+
+  /**
+   * Query usada pelo healthCheck. Default `SELECT 1`.
+   * Útil customizar pra dialects exóticos ou pra checks mais profundos.
+   */
+  healthQuery?: string
+}
+
+export function kyselyData<DB>(options: KyselyDataOptions<DB>): DataAdapter {
+  const { db, healthQuery = 'SELECT 1' } = options
+
+  return {
+    name: 'kysely',
+    kind: 'data',
+
+    contextExtension() {
+      return { db }
+    },
+
+    async healthCheck(): Promise<HealthStatus> {
+      try {
+        const start = performance.now()
+        await sql.raw(healthQuery).execute(db)
+        const latencyMs = performance.now() - start
+        return { ok: true, details: { latencyMs: round(latencyMs) } }
+      } catch (err) {
+        return { ok: false, details: { error: String(err) } }
+      }
+    },
+
+    async dispose() {
+      await db.destroy()
+    },
+  }
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100
+}
+
+// =============================================================================
+// Repo tipado a partir de uma entidade
+// =============================================================================
+
+/** Params de busca: paginação offset + filtros de igualdade (v1). */
+export interface ListParams {
+  limit?: number
+  offset?: number
+  /** Filtros de igualdade por coluna: `{ status: 'open' }`. */
+  where?: Record<string, unknown>
+}
+
+/** CRUD tipado sobre uma entidade, projetado nos tipos do `defineEntity`. */
+export interface Repo<E extends EntityConfig> {
+  insert(values: EntityInsert<E>): Promise<EntityRow<E>>
+  findById(id: string): Promise<EntityRow<E> | null>
+  update(id: string, patch: EntityUpdate<E>): Promise<EntityRow<E>>
+  /** Soft-delete (seta `deletedAt`) se a entidade tem `softDelete`; senão DELETE. */
+  remove(id: string): Promise<void>
+  /** Lista tudo, cru (exclui soft-deleted quando aplicável). */
+  all(): Promise<EntityRow<E>[]>
+  /** A listagem paginada (offset) com filtros de igualdade. Retorna `Paginated`. */
+  list(params?: ListParams): Promise<Paginated<EntityRow<E>>>
+}
+
+export interface KyselyRepoOptions {
+  /** Relógio injetável (testes). Default `() => new Date().toISOString()`. */
+  now?: () => string
+  /** Gerador de id pra pk auto. Default `randomUUID`. */
+  genId?: () => string
+}
+
+/**
+ * Constrói um `Repo` tipado sobre Kysely a partir de uma entidade. Casca fina —
+ * não é ORM: gera id (pk auto), preenche timestamps, respeita soft-delete,
+ * marshalla campo `t.json()` (objeto→jsonb, guiado pela declaração), e deixa o
+ * resto pro Kysely. Tipos vêm do `defineEntity` (`EntityRow/Insert/Update`).
+ */
+export function kyselyRepo<E extends EntityConfig>(
+  db: Kysely<unknown>,
+  entity: E,
+  options: KyselyRepoOptions = {},
+): Repo<E> {
+  const table = entityTable(entity)
+  const pk = entityPk(entity)
+  const now = options.now ?? (() => new Date().toISOString())
+  const genId = options.genId ?? (() => randomUUID())
+  const hasTimestamps = entity.timestamps === true
+  const hasSoftDelete = entity.softDelete === true
+  // Campos t.json(): o repo serializa NA ESCRITA (insert/update). Sem isso, o pg
+  // até stringifica objeto plano sozinho — mas ARRAY vira literal de array PG
+  // (errado pra jsonb) sem quebrar typecheck. A declaração já sabe o tipo; a
+  // dupla ColumnType<unknown, string, never> + JSON.stringify na mão morre aqui.
+  // String passa DIRETO (quem já mandava pré-serializado segue valendo — sem
+  // double-encode na migração). Na leitura o pg devolve objeto — nada a fazer.
+  const jsonFields = Object.entries(entity.fields)
+    .filter(([, f]) => f.meta?.logicalType === 'json')
+    .map(([name]) => name)
+  const marshalJson = (row: Record<string, unknown>): Record<string, unknown> => {
+    for (const name of jsonFields) {
+      const v = row[name]
+      if (v !== undefined && v !== null && typeof v !== 'string') row[name] = JSON.stringify(v)
+    }
+    return row
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const qb = db as Kysely<any>
+
+  return {
+    async insert(values) {
+      const row: Record<string, unknown> = marshalJson({ ...(values as Record<string, unknown>) })
+      if (pk.auto && row[pk.name] === undefined) row[pk.name] = genId()
+      if (hasTimestamps) {
+        const ts = now()
+        row.createdAt = ts
+        row.updatedAt = ts
+      }
+      const inserted = await qb
+        .insertInto(table)
+        .values(row)
+        .returningAll()
+        .executeTakeFirstOrThrow()
+      return inserted as EntityRow<E>
+    },
+
+    async findById(id) {
+      let q = qb.selectFrom(table).selectAll().where(pk.name, '=', id)
+      if (hasSoftDelete) q = q.where('deletedAt', 'is', null)
+      const found = await q.executeTakeFirst()
+      return (found ?? null) as EntityRow<E> | null
+    },
+
+    async update(id, patch) {
+      const values: Record<string, unknown> = marshalJson({ ...(patch as Record<string, unknown>) })
+      if (hasTimestamps) values.updatedAt = now()
+      const updated = await qb
+        .updateTable(table)
+        .set(values)
+        .where(pk.name, '=', id)
+        .returningAll()
+        .executeTakeFirstOrThrow()
+      return updated as EntityRow<E>
+    },
+
+    async remove(id) {
+      if (hasSoftDelete) {
+        await qb.updateTable(table).set({ deletedAt: now() }).where(pk.name, '=', id).execute()
+        return
+      }
+      await qb.deleteFrom(table).where(pk.name, '=', id).execute()
+    },
+
+    async all() {
+      let q = qb.selectFrom(table).selectAll()
+      if (hasSoftDelete) q = q.where('deletedAt', 'is', null)
+      const rows = await q.execute()
+      return rows as EntityRow<E>[]
+    },
+
+    async list(params = {}) {
+      const limit = params.limit ?? 50
+      const offset = params.offset ?? 0
+      const applyFilters = (query: any): any => {
+        let out = hasSoftDelete ? query.where('deletedAt', 'is', null) : query
+        if (params.where !== undefined) {
+          for (const [col, value] of Object.entries(params.where)) {
+            out = out.where(col, '=', value)
+          }
+        }
+        return out
+      }
+
+      const countRow = await applyFilters(
+        qb.selectFrom(table).select((eb: any) => eb.fn.countAll().as('count')),
+      ).executeTakeFirstOrThrow()
+      const total = Number((countRow as { count: number | string | bigint }).count)
+
+      const items = await applyFilters(qb.selectFrom(table).selectAll())
+        .limit(limit)
+        .offset(offset)
+        .execute()
+
+      const next = offset + limit < total ? String(offset + limit) : null
+      return { items: items as EntityRow<E>[], cursor: { next }, total }
+    },
+  }
+}
+
+// =============================================================================
+// crudActions — gera as actions de CRUD a partir de uma entidade
+// =============================================================================
+
+export type CrudOp = 'view' | 'create' | 'update' | 'delete' | 'list'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** Authorize por operação. Só as operações declaradas são geradas (fail-closed). */
+export type CrudAuthorize = { [K in CrudOp]?: AuthorizeFn<any, any> }
+
+/**
+ * Gera as opus actions de CRUD a partir de uma entidade, com handlers backed por
+ * `kyselyRepo(ctx.db, entity)` e input/output derivados do `defineEntity`. Só
+ * gera as ops cujo `authorize` foi fornecido (fail-closed). Nomes seguem
+ * `<entity>.<verb>` (passam no `opus check`). Composição, não core — vive no
+ * driver Kysely (ver `docs/data-layer.md`, peça 7).
+ */
+export function crudActions<E extends EntityConfig>(
+  entity: E,
+  authorize: CrudAuthorize,
+): Record<string, ActionDef> {
+  const name = entity.name
+  const pk = entityPk(entity)
+  const repoOf = (ctx: { db: unknown }): Repo<E> => kyselyRepo(ctx.db as Kysely<unknown>, entity)
+  const idInput = z.object({ [pk.name]: z.string() })
+  const labelFields = (): Record<string, { label: string }> => {
+    const f: Record<string, { label: string }> = {}
+    for (const key of Object.keys(entity.fields)) f[key] = { label: key }
+    return f
+  }
+  const out: Record<string, ActionDef> = {}
+
+  if (authorize.view !== undefined) {
+    out.view = defineAction({
+      name: `${name}.view`,
+      kind: 'view',
+      input: idInput,
+      output: entityRowSchema(entity),
+      authorize: authorize.view,
+      projection: [],
+      handler: async (ctx: any, input: any) => {
+        const row = await repoOf(ctx).findById(input[pk.name])
+        if (row === null) {
+          throw error({
+            code: `${name}.view.notFound`,
+            category: 'not_found',
+            message: `${name} não encontrado`,
+          })
+        }
+        return row
+      },
+    } as any)
+  }
+
+  if (authorize.create !== undefined) {
+    out.create = defineAction({
+      name: `${name}.create`,
+      kind: 'form',
+      input: entityInsertSchema(entity),
+      output: entityRowSchema(entity),
+      authorize: authorize.create,
+      fields: labelFields(),
+      handler: async (ctx: any, input: any) => repoOf(ctx).insert(input),
+    } as any)
+  }
+
+  if (authorize.update !== undefined) {
+    out.update = defineAction({
+      name: `${name}.update`,
+      kind: 'form',
+      input: entityUpdateSchema(entity).extend({ [pk.name]: z.string() }),
+      output: entityRowSchema(entity),
+      authorize: authorize.update,
+      fields: labelFields(),
+      handler: async (ctx: any, input: any) => {
+        const { [pk.name]: id, ...patch } = input
+        return repoOf(ctx).update(id, patch as EntityUpdate<E>)
+      },
+    } as any)
+  }
+
+  if (authorize.list !== undefined) {
+    out.list = defineAction({
+      name: `${name}.list`,
+      kind: 'list',
+      input: z.object({
+        limit: z.number().int().positive().optional(),
+        offset: z.number().int().nonnegative().optional(),
+        where: z.record(z.unknown()).optional(),
+      }),
+      output: z.object({
+        items: z.array(entityRowSchema(entity)),
+        cursor: z.object({ next: z.string().nullable() }),
+        total: z.number(),
+      }),
+      authorize: authorize.list,
+      handler: async (ctx: any, input: any) => repoOf(ctx).list(input),
+    } as any)
+  }
+
+  if (authorize.delete !== undefined) {
+    out.delete = defineAction({
+      name: `${name}.delete`,
+      kind: 'simple',
+      input: idInput,
+      output: z.object({ ok: z.literal(true) }),
+      authorize: authorize.delete,
+      handler: async (ctx: any, input: any) => {
+        await repoOf(ctx).remove(input[pk.name])
+        return { ok: true as const }
+      },
+    } as any)
+  }
+
+  return out
+}
+
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+/**
+ * Drift-check: compara as entidades (`defineEntity`) com o schema real do banco
+ * via introspecção do Kysely. Read-only — não muta nada. Pensado pra rodar no
+ * `opus check` e falhar o build se a migration divergir do `defineEntity`.
+ *
+ * v1: nível-coluna (presença + nullable). O `naming` (default `snake`) mapeia os
+ * nomes desejados pra bater com a introspecção crua — o `CamelCasePlugin` do
+ * Kysely não toca introspecção. Ver `docs/data-layer.md`.
+ */
+export async function kyselyDriftCheck<DB>(
+  db: Kysely<DB>,
+  entities: EntityConfig[],
+  options: { naming?: NamingStrategy } = {},
+): Promise<DriftFinding[]> {
+  const naming = options.naming ?? 'snake'
+  const map = resolveNaming(naming)
+  const tables = await db.introspection.getTables()
+  const byName = new Map(tables.map((meta) => [meta.name, meta]))
+
+  const findings: DriftFinding[] = []
+  for (const entity of entities) {
+    const table = map(entityTable(entity))
+    const meta = byName.get(table)
+    const actual =
+      meta === undefined
+        ? null
+        : meta.columns.map((c) => ({ name: c.name, nullable: c.isNullable }))
+    findings.push(...diffColumns(table, desiredColumns(entity, naming), actual))
+  }
+  return findings
+}

package/src/data/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @softize/opus/data — shared helpers/types for data drivers.
+ *
+ * Empty for now — drivers (kysely, drizzle) são thin wrappers que apenas
+ * implementam o contrato `DataAdapter` do core. Quando aparecer código
+ * compartilhado (helpers de transação, observability hooks, etc),
+ * mora aqui.
+ */
+
+export {}

package/src/data/readonly-pool.ts

@@ -0,0 +1,160 @@
+/**
+ * @softize/opus/data/readonly-pool — `readOnlyContextPool`: SQL escrito por LLM
+ * executado com as QUATRO defesas do padrão da casa (ADRs 0003/0007 do 1º app real),
+ * todas no BANCO — não em regex sobre o texto da query:
+ *
+ *   1. **Pool com teto** — crie o `Pool` com `max` (e/ou use `maxConcurrent` aqui):
+ *      query de LLM não esgota as conexões do app.
+ *   2. **Transação READ ONLY** — `BEGIN TRANSACTION READ ONLY`: escrita morre no
+ *      servidor, qualquer que seja o SQL.
+ *   3. **`SET LOCAL ROLE` por transação** — o alcance é do contexto: com grants
+ *      default-fechado, `sales_read` não enxerga `hr_employees.salary` nem por
+ *      SELECT criativo. (Criar os roles/grants é migração sua; aqui só se assume.)
+ *   4. **Protocolo estendido contra multi-sentença** — o SQL do LLM roda SEMPRE
+ *      com array de valores (protocolo estendido do PG, que recusa `;` composto)
+ *      — `SELECT 1; DROP TABLE x` nem chega a executar.
+ *
+ * Saindo, `DISCARD ALL` devolve a conexão limpa ao pool (role/settings zerados);
+ * se a limpeza falhar, a conexão é DESTRUÍDA (release com erro), nunca reusada suja.
+ *
+ * Uso (o caso action `ai: true` que executa SQL livre):
+ *
+ *   import { Pool } from 'pg'
+ *   import { readOnlyContextPool } from '@softize/opus/data/readonly-pool'
+ *
+ *   const bi = readOnlyContextPool({ pool: new Pool({ connectionString, max: 4 }) })
+ *   const { rows } = await bi.query(sqlDoLlm, { role: roleFor(ctx), params: [] })
+ */
+
+// =============================================================================
+// Tipos estruturais (sem dep direta de `pg` — aceita pool-like)
+// =============================================================================
+
+/** Cliente dedicado obtido do pool (subset do `pg.PoolClient`). */
+export interface ReadOnlyPoolClient {
+  query(text: string, values?: unknown[]): Promise<unknown>
+  /** `release(err)` com erro DESTRÓI a conexão em vez de devolvê-la ao pool. */
+  release(err?: Error | boolean): void
+}
+
+/** Subset de `pg.Pool` que precisamos: só `connect()`. */
+export interface ReadOnlyConnectPool {
+  connect(): Promise<ReadOnlyPoolClient>
+}
+
+export interface ReadOnlyContextPoolOptions {
+  /** Pool pg-compatível. Crie COM teto (`new Pool({ max })`) — 1ª defesa. */
+  pool: ReadOnlyConnectPool
+  /**
+   * Teto de queries simultâneas DESTE wrapper (as demais enfileiram). Além do
+   * `max` do pool: segura a fila aqui em vez de disputar conexão com o app.
+   */
+  maxConcurrent?: number
+  /** `SET LOCAL statement_timeout` por transação (ms). Default 15000. */
+  statementTimeoutMs?: number
+}
+
+export interface ReadOnlyQueryOptions {
+  /**
+   * Role de ALCANCE da transação (`SET LOCAL ROLE`) — derive do contexto
+   * (ex.: `sales_read`). Sem role, a query roda com o alcance da conexão.
+   */
+  role?: string
+  /** Parâmetros posicionais (`$1`, `$2`…). Sempre enviados (mesmo vazios) — 4ª defesa. */
+  params?: unknown[]
+}
+
+/** Resultado mínimo (shape do `pg.Result`). */
+export interface ReadOnlyQueryResult {
+  rows: unknown[]
+  rowCount?: number | null
+}
+
+// =============================================================================
+// Fábrica
+// =============================================================================
+
+// Identificador de role: sem quoting exótico, minúsculo/underscore, limite do PG.
+const ROLE_RE = /^[a-z_][a-z0-9_]{0,62}$/
+
+export function readOnlyContextPool(options: ReadOnlyContextPoolOptions): {
+  query(sql: string, opts?: ReadOnlyQueryOptions): Promise<ReadOnlyQueryResult>
+} {
+  const { pool, maxConcurrent, statementTimeoutMs = 15_000 } = options
+  if (maxConcurrent !== undefined && (!Number.isInteger(maxConcurrent) || maxConcurrent < 1)) {
+    throw new Error(`readOnlyContextPool: maxConcurrent inválido (${maxConcurrent}) — inteiro ≥ 1.`)
+  }
+  if (!Number.isInteger(statementTimeoutMs) || statementTimeoutMs < 1) {
+    throw new Error(`readOnlyContextPool: statementTimeoutMs inválido (${statementTimeoutMs}).`)
+  }
+  const acquireSlot = maxConcurrent === undefined ? null : makeSemaphore(maxConcurrent)
+
+  return {
+    async query(sql, opts = {}) {
+      const { role, params = [] } = opts
+      // Valida ANTES de tomar conexão — role ruim nem toca o pool.
+      if (role !== undefined && !ROLE_RE.test(role)) {
+        throw new Error(
+          `readOnlyContextPool: role "${role}" inválido (esperado /${ROLE_RE.source}/ — o alcance vem de roles seus, não de texto livre).`,
+        )
+      }
+
+      const releaseSlot = acquireSlot === null ? null : await acquireSlot()
+      try {
+        const client = await pool.connect()
+        let inTx = false
+        try {
+          await client.query('BEGIN TRANSACTION READ ONLY')
+          inTx = true
+          // SET não aceita parâmetro — os dois valores são validados acima.
+          await client.query(`SET LOCAL statement_timeout = ${statementTimeoutMs}`)
+          if (role !== undefined) await client.query(`SET LOCAL ROLE "${role}"`)
+          // O SQL do LLM: SEMPRE com values → protocolo estendido → sem multi-sentença.
+          const result = (await client.query(sql, params)) as ReadOnlyQueryResult
+          await client.query('COMMIT')
+          inTx = false
+          return { rows: result.rows ?? [], rowCount: result.rowCount ?? null }
+        } finally {
+          // Limpeza best-effort; se falhar, release COM erro → a conexão morre
+          // em vez de voltar suja (com role/settings trocados) pro pool.
+          let cleanupError: Error | undefined
+          try {
+            if (inTx) await client.query('ROLLBACK')
+            await client.query('DISCARD ALL')
+          } catch (err) {
+            cleanupError = err instanceof Error ? err : new Error(String(err))
+          }
+          client.release(cleanupError)
+        }
+      } finally {
+        releaseSlot?.()
+      }
+    },
+  }
+}
+
+// =============================================================================
+// Semáforo (fila FIFO, zero-dep)
+// =============================================================================
+
+function makeSemaphore(limit: number): () => Promise<() => void> {
+  let active = 0
+  const waiting: Array<() => void> = []
+  const release = (): void => {
+    active -= 1
+    const next = waiting.shift()
+    if (next !== undefined) next()
+  }
+  return function acquire(): Promise<() => void> {
+    if (active < limit) {
+      active += 1
+      return Promise.resolve(release)
+    }
+    return new Promise((resolve) => {
+      waiting.push(() => {
+        active += 1
+        resolve(release)
+      })
+    })
+  }
+}

package/src/dsl/eval.ts

@@ -0,0 +1,136 @@
+/**
+ * @softize/opus/dsl — Runtime evaluator.
+ *
+ * Avalia AST contra um contexto (`{ user, input, loaded, ... }`) e retorna
+ * o resultado. Usado pra `authorize` (boolean) e em outros casos onde
+ * precisa rodar a expressão direto em JS.
+ */
+
+import type { AstNode } from './types.ts'
+
+export type EvalContext = Record<string, unknown>
+
+export function evalExpression(node: AstNode, ctx: EvalContext): unknown {
+  switch (node.kind) {
+    case 'literal':
+      return node.value
+    case 'array':
+      return node.items.map((i) => evalExpression(i, ctx))
+    case 'identifier':
+      return ctx[node.name]
+    case 'member': {
+      const obj = evalExpression(node.object, ctx)
+      if (obj === null || obj === undefined) return undefined
+      return (obj as Record<string, unknown>)[node.property]
+    }
+    case 'unary': {
+      const v = evalExpression(node.operand, ctx)
+      return node.op === 'NOT' ? !v : -(v as number)
+    }
+    case 'binary': {
+      // Curto-circuito pra AND/OR
+      if (node.op === 'AND') {
+        const left = evalExpression(node.left, ctx)
+        if (!left) return false
+        return Boolean(evalExpression(node.right, ctx))
+      }
+      if (node.op === 'OR') {
+        const left = evalExpression(node.left, ctx)
+        if (left) return true
+        return Boolean(evalExpression(node.right, ctx))
+      }
+      const left = evalExpression(node.left, ctx) as number | string | null
+      const right = evalExpression(node.right, ctx) as number | string | null
+      switch (node.op) {
+        case '==':
+          return left === right
+        case '!=':
+          return left !== right
+        case '<':
+          return (left as number) < (right as number)
+        case '<=':
+          return (left as number) <= (right as number)
+        case '>':
+          return (left as number) > (right as number)
+        case '>=':
+          return (left as number) >= (right as number)
+        case '+':
+          return (left as number) + (right as number)
+        case '-':
+          return (left as number) - (right as number)
+        case '*':
+          return (left as number) * (right as number)
+        case '/':
+          return (left as number) / (right as number)
+        /* v8 ignore next 2 */
+        default:
+          throw new Error(`DSL eval: unknown binary op ${node.op as string}`)
+      }
+    }
+    case 'in': {
+      const v = evalExpression(node.left, ctx)
+      const arr = evalExpression(node.values, ctx) as unknown[]
+      const found = Array.isArray(arr) && arr.includes(v)
+      return node.negated ? !found : found
+    }
+    case 'between': {
+      const v = evalExpression(node.subject, ctx) as number
+      const lo = evalExpression(node.low, ctx) as number
+      const hi = evalExpression(node.high, ctx) as number
+      const within = v >= lo && v <= hi
+      return node.negated ? !within : within
+    }
+    case 'like': {
+      const v = evalExpression(node.subject, ctx)
+      const pat = evalExpression(node.pattern, ctx) as string
+      const matched = sqlLikeMatch(
+        String(v ?? ''),
+        pat,
+        node.caseInsensitive,
+      )
+      return node.negated ? !matched : matched
+    }
+    case 'isNull': {
+      const v = evalExpression(node.subject, ctx)
+      const isNullish = v === null || v === undefined
+      return node.negated ? !isNullish : isNullish
+    }
+    case 'call':
+      return callFunction(node.name, node.args.map((a) => evalExpression(a, ctx)))
+  }
+}
+
+// =============================================================================
+// SQL LIKE matcher
+// =============================================================================
+
+function sqlLikeMatch(s: string, pat: string, ci: boolean): boolean {
+  const regexSrc = pat.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/%/g, '.*').replace(/_/g, '.')
+  const regex = new RegExp(`^${regexSrc}$`, ci ? 'i' : undefined)
+  return regex.test(s)
+}
+
+// =============================================================================
+// Built-in functions
+// =============================================================================
+
+function callFunction(name: string, args: unknown[]): unknown {
+  switch (name) {
+    case 'NOW':
+      return new Date().toISOString()
+    case 'TODAY':
+      return new Date().toISOString().slice(0, 10)
+    case 'LOWER':
+      return String(args[0] ?? '').toLowerCase()
+    case 'UPPER':
+      return String(args[0] ?? '').toUpperCase()
+    case 'LENGTH':
+      return String(args[0] ?? '').length
+    case 'COALESCE':
+      for (const a of args) {
+        if (a !== null && a !== undefined) return a
+      }
+      return null
+  }
+  throw new Error(`DSL eval: unknown function '${name}'`)
+}