tjs-lang 0.8.7 → 0.9.0

package/src/lang/parser-transforms.ts

@@ -42,6 +42,57 @@ import type {
   TokenizerState,
 } from './parser-types'
 import { extractJSValue } from './parser-params'
+import { emitVerifiedPredicate, formatPredicateDiagnostics } from './predicate'
+import type { PredicateVerification } from './types'
+
+/**
+ * If a `Type`/`FunctionPredicate` predicate body verifies as predicate-safe
+ * (pure, synchronous, no loops/IO), return a self-contained fuel-bounded guard
+ * **expression** to inline in place of the raw arrow; otherwise return null so
+ * the caller falls back to the unverified body (never rejects — see
+ * PRINCIPLES.md, TJS ⊇ JS). This is the transpile-time consumer of the predicate
+ * engine: a safe predicate "earns" the native fast path and DoS-safe validation.
+ */
+function verifiedGuardExpr(
+  name: string,
+  kind: 'Type' | 'Generic',
+  params: string,
+  body: string,
+  knownPredicates?: string[],
+  report?: PredicateVerification[]
+): string | null {
+  // Synthesize a named declaration the verifier can analyze. The body has
+  // already been through the TJS equality/typeof rewrites (Eq/NotEq/Is/IsNot/
+  // TypeOf), all whitelisted as pure in the verifier. `knownPredicates` lets a
+  // Generic predicate compose with its type-param checks (`checkT(x[0])`) — the
+  // verifier treats those calls as composition with another safe predicate.
+  //
+  // The entry function is named per-declaration (`__pred_<Type>`), not a fixed
+  // `__pred`: the guard IIFEs are inlined into the module, and two identically-
+  // named nested `function __pred`s would be picked up by the polymorphic-merge
+  // transform (which runs after this one) as ambiguous overloads. Type/Generic
+  // names are unique within a module, so this is collision-free and deterministic.
+  const entry = `__pred_${name}`
+  const fnSource = `function ${entry}(${params}) { ${body} }`
+  const r = emitVerifiedPredicate(
+    fnSource,
+    entry,
+    knownPredicates ? { knownPredicates: new Set(knownPredicates) } : {}
+  )
+  if (r.safe) {
+    report?.push({ name, kind, verified: true })
+    return r.code!
+  }
+  report?.push({
+    name,
+    kind,
+    verified: false,
+    // The verifier names the synthesized entry `__pred_<Name>`; surface the
+    // declaration name in the user-facing reason instead.
+    reason: formatPredicateDiagnostics(r.diagnostics).replace(/__pred_/g, ''),
+  })
+  return null
+}
 
 export function transformTryWithoutCatch(source: string): string {
   let result = ''
@@ -1127,12 +1178,15 @@ function transformTypeofKeyword(source: string): string {
 }
 
 /**
- * Transform == and != to Is() and IsNot() calls
+ * Transform == and != to Eq() and NotEq() calls
  *
  * In TJS normal mode:
- *   a == b   -> Is(a, b)     (structural equality)
- *   a != b   -> IsNot(a, b)  (structural inequality)
+ *   a == b   -> Eq(a, b)     (footgun-free ===: unwraps boxed primitives,
+ *                             null == undefined, but does NOT coerce types and
+ *                             is NOT structural — see PRINCIPLES/guides)
+ *   a != b   -> NotEq(a, b)
  *   a === b  -> a === b      (identity, unchanged)
+ * (For deep structural equality use the explicit `Is`/`IsNot` operators.)
  *
  * Uses a two-pass algorithm:
  * 1. Find all == and != positions (outside strings/comments/regex)
@@ -1620,7 +1674,10 @@ function findRightOperandBoundary(
  *
  * When predicate + example: auto-generate type guard from example
  */
-export function transformTypeDeclarations(source: string): string {
+export function transformTypeDeclarations(
+  source: string,
+  report?: PredicateVerification[]
+): string {
   let result = ''
   let i = 0
 
@@ -1737,17 +1794,41 @@ export function transformTypeDeclarations(source: string): string {
         // Build Type() call with appropriate arguments
         // Type(description, predicateOrExample, example?, default?)
         if (predicateMatch && example) {
-          // Predicate + example
+          // Predicate + example: the example is the base schema, the predicate
+          // refines it. Verify the predicate → fuel-bounded native guard; the
+          // example schema check stays as an outer gate (constructed once via an
+          // IIFE, not per call). Falls back to the raw arrow when unverifiable.
           const params = predicateMatch[1].trim()
           const body = predicateMatch[2].trim()
           const defaultArg = defaultValue ? `, ${defaultValue}` : ''
-          result += `const ${typeName} = Type('${description}', (${params}) => { if (!globalThis.__tjs?.validate(${params}, globalThis.__tjs?.infer(${example}))) return false; ${body} }, ${example}${defaultArg})`
+          const schemaGate = `globalThis.__tjs?.validate(${params}, globalThis.__tjs?.infer(${example}))`
+          const guard = verifiedGuardExpr(
+            typeName,
+            'Type',
+            params,
+            body,
+            undefined,
+            report
+          )
+          const fn = guard
+            ? `(__g => (${params}) => (${schemaGate} ? __g(${params}) : false))(${guard})`
+            : `(${params}) => { if (!${schemaGate}) return false; ${body} }`
+          result += `const ${typeName} = Type('${description}', ${fn}, ${example}${defaultArg})`
         } else if (predicateMatch) {
-          // Predicate only
+          // Predicate only: verify → fuel-bounded native guard, else raw arrow.
           const params = predicateMatch[1].trim()
           const body = predicateMatch[2].trim()
           const defaultArg = defaultValue ? `, undefined, ${defaultValue}` : ''
-          result += `const ${typeName} = Type('${description}', (${params}) => { ${body} }${defaultArg})`
+          const guard = verifiedGuardExpr(
+            typeName,
+            'Type',
+            params,
+            body,
+            undefined,
+            report
+          )
+          const fn = guard ?? `(${params}) => { ${body} }`
+          result += `const ${typeName} = Type('${description}', ${fn}${defaultArg})`
         } else if (example) {
           // Example only (becomes validation schema)
           const defaultArg = defaultValue ? `, ${defaultValue}` : ''
@@ -1938,7 +2019,10 @@ export function transformFunctionPredicateDeclarations(source: string): string {
  *   const Pair = Generic(['T', 'U'], (obj, checkT, checkU) => { ... }, '...')
  *   const Container = Generic(['T', ['U', '']], (obj, checkT, checkU) => { ... }, '...')
  */
-export function transformGenericDeclarations(source: string): string {
+export function transformGenericDeclarations(
+  source: string,
+  report?: PredicateVerification[]
+): string {
   let result = ''
   let i = 0
 
@@ -2034,11 +2118,21 @@ export function transformGenericDeclarations(source: string): string {
           )
         })
 
+        // Verify the (type-param-rewritten) body, composing with the type-param
+        // checks; safe → fuel-bounded native guard, else the raw arrow.
+        const paramList = [valueParam, ...typeCheckParams].join(', ')
+        const guard = verifiedGuardExpr(
+          genericName,
+          'Generic',
+          paramList,
+          body,
+          typeCheckParams,
+          report
+        )
+        const fn = guard ?? `(${paramList}) => { ${body} }`
         result += `const ${genericName} = Generic([${typeParams.join(
           ', '
-        )}], (${valueParam}, ${typeCheckParams.join(
-          ', '
-        )}) => { ${body} }, '${description}')`
+        )}], ${fn}, '${description}')`
       } else {
         // No predicate - create a generic that always passes
         result += `const ${genericName} = Generic([${typeParams.join(
@@ -3542,11 +3636,12 @@ export function validateNoDate(source: string): string {
     {
       pattern: /\bnew\s+Date\b/,
       message:
-        'new Date() is not allowed in TjsDate mode. Use Timestamp.now() or Timestamp.from()',
+        'new Date() is not allowed in TjsDate mode. Use Timestamp.now()/Timestamp.from() for wall-clock dates, or performance.now() for a monotonic counter (timing, id generation)',
     },
     {
       pattern: /\bDate\.now\b/,
-      message: 'Date.now() is not allowed in TjsDate mode. Use Timestamp.now()',
+      message:
+        'Date.now() is not allowed in TjsDate mode. Use Timestamp.now() for a wall-clock date, or performance.now() for a monotonic counter (timing, id generation)',
     },
     {
       pattern: /\bDate\.parse\b/,

package/src/lang/parser.ts

@@ -8,6 +8,7 @@
 import * as acorn from 'acorn'
 import type { Program, FunctionDeclaration } from 'acorn'
 import { SyntaxError } from './types'
+import type { PredicateVerification } from './types'
 
 // Re-export types so external callers don't need to change imports
 export type {
@@ -124,6 +125,7 @@ export function preprocess(
   polymorphicNames: Set<string>
   extensions: Map<string, Set<string>>
   letAnnotations: Map<string, string>
+  predicates: PredicateVerification[]
 } {
   const originalSource = source
   let moduleSafety: 'none' | 'inputs' | 'all' | undefined
@@ -298,8 +300,12 @@ export function preprocess(
   // Generic Bar<T, U> { ... } -> const Bar = Generic(...)
   // Union Dir 'up' | 'down' -> const Dir = Union(...)
   // Enum Status { Pending, Active, Done } -> const Status = Enum(...)
-  source = transformTypeDeclarations(source)
-  source = transformGenericDeclarations(source)
+  // Collect per-predicate verification status (Type/Generic predicate bodies:
+  // verified → native guard, or fell back to a raw function). Surfaced on the
+  // transpile result so tools can flag unverifiable predicates.
+  const predicates: PredicateVerification[] = []
+  source = transformTypeDeclarations(source, predicates)
+  source = transformGenericDeclarations(source, predicates)
   source = transformFunctionPredicateDeclarations(source)
   source = transformUnionDeclarations(source)
   source = transformEnumDeclarations(source)
@@ -437,6 +443,7 @@ export function preprocess(
     polymorphicNames: polyResult.polymorphicNames,
     extensions: extResult.extensions,
     letAnnotations,
+    predicates,
   }
 }
 

package/src/lang/predicate-evaluator.test.ts

@@ -0,0 +1,49 @@
+/**
+ * `createPredicateEvaluator` — the pluggable `(source, value) => boolean` bridge
+ * a zero-dep, predicate-aware JSON-Schema validator (tosijs-schema) injects to
+ * run `$predicate` sources. Compiles+caches per source; fails closed on an
+ * unverifiable source (never a thrown error, never a silent pass).
+ */
+import { describe, it, expect } from 'bun:test'
+import { createPredicateEvaluator } from './predicate'
+
+const POS = 'function isPos(x) { return typeof x === "number" && x > 0 }'
+const LOOPY =
+  'function bad(xs) { for (const x of xs) { if (x < 0) return false } return true }'
+
+describe('createPredicateEvaluator', () => {
+  it('evaluates a safe source against values', () => {
+    const evaluate = createPredicateEvaluator()
+    expect(evaluate(POS, 5)).toBe(true)
+    expect(evaluate(POS, -1)).toBe(false)
+    expect(evaluate(POS, 'x')).toBe(false)
+  })
+
+  it('caches: compiles a source once, reuses across calls', () => {
+    let unsafeCalls = 0
+    const evaluate = createPredicateEvaluator({
+      onUnsafe: () => unsafeCalls++,
+    })
+    // many evaluations of the same source — still one compile, zero warnings
+    for (let i = 0; i < 100; i++) expect(evaluate(POS, i + 1)).toBe(true)
+    expect(unsafeCalls).toBe(0)
+  })
+
+  it('fails closed on an unverifiable source (returns false, warns once)', () => {
+    const unsafe: string[] = []
+    const evaluate = createPredicateEvaluator({
+      onUnsafe: (src) => unsafe.push(src),
+    })
+    // a loop can't be certified predicate-safe → every value is invalid
+    expect(evaluate(LOOPY, [1, 2, 3])).toBe(false)
+    expect(evaluate(LOOPY, [1, 2, 3])).toBe(false)
+    // ...and the failure is reported exactly once (cached)
+    expect(unsafe.length).toBe(1)
+  })
+
+  it('fails closed on a runaway (fuel) rather than throwing', () => {
+    const evaluate = createPredicateEvaluator({ fuel: 100 })
+    const recur = 'function deep(n) { return deep(n + 1) }'
+    expect(evaluate(recur, 0)).toBe(false)
+  })
+})

package/src/lang/predicate-report.test.ts

@@ -0,0 +1,54 @@
+/**
+ * The `tjs()` result surfaces per-`Type`/`Generic` predicate verification status
+ * (`result.predicates`) so tools can flag unverifiable predicates, and mirrors
+ * the unverified ones into `result.warnings`. (#9 / the #5 warn-on-fallback tail.)
+ */
+import { describe, it, expect } from 'bun:test'
+import { tjs } from './index'
+
+describe('predicate verification is reported on the transpile result', () => {
+  it('a safe Type predicate → verified, no warning', () => {
+    const r = tjs("Type Pos 'positive' { predicate(x) { return x > 0 } }")
+    expect(r.predicates).toEqual([
+      { name: 'Pos', kind: 'Type', verified: true },
+    ])
+    expect(r.warnings).toBeUndefined()
+  })
+
+  it('an unverifiable Type predicate → not verified + reason + warning', () => {
+    const r = tjs(
+      "Type Bad 'bad' { predicate(xs) { for (const x of xs) { if (x<0) return false } return true } }"
+    )
+    const p = r.predicates?.[0]
+    expect(p).toMatchObject({ name: 'Bad', kind: 'Type', verified: false })
+    expect(p?.reason).toMatch(/loop/i)
+    expect(p?.reason).not.toContain('__pred_') // internal name not leaked
+    expect(r.warnings?.some((w) => /Bad.*not verifiable/.test(w))).toBe(true)
+  })
+
+  it('reports Generic predicates too', () => {
+    const r = tjs(
+      "Generic Box<T> { description: 'b', predicate(x, T) { return T(x.value) } }"
+    )
+    expect(r.predicates?.[0]).toMatchObject({
+      name: 'Box',
+      kind: 'Generic',
+      verified: true,
+    })
+  })
+
+  it('reports each predicate in a multi-predicate module', () => {
+    const r = tjs(
+      "Type A 'a' { predicate(x) { return x > 0 } }\n" +
+        "Type B 'b' { predicate(xs) { for (const x of xs) {} return true } }"
+    )
+    const byName = Object.fromEntries(
+      (r.predicates ?? []).map((p) => [p.name, p.verified])
+    )
+    expect(byName).toEqual({ A: true, B: false })
+  })
+
+  it('omits `predicates` when there are none', () => {
+    expect(tjs('function f() { return 1 }').predicates).toBeUndefined()
+  })
+})

package/src/lang/predicate.ts

@@ -67,6 +67,16 @@ const PURE_GLOBALS = new Set([
   'Boolean',
   'Array',
   'Object',
+  // TJS-injected pure helpers. Native-TJS predicate bodies are rewritten before
+  // they reach the verifier: `==`/`!=` → `Eq`/`NotEq`, the explicit `Is`/`IsNot`
+  // operators → `Is`/`IsNot`, `typeof x` → `TypeOf(x)`. All are pure, total
+  // functions (footgun-free equality / structural equality / safe typeof), so a
+  // predicate that uses TJS equality still verifies as predicate-safe.
+  'Eq',
+  'NotEq',
+  'Is',
+  'IsNot',
+  'TypeOf',
 ])
 
 /** Namespaces whose static methods are pure (with effectful exceptions below). */
@@ -82,6 +92,101 @@ const PURE_NAMESPACES = new Set([
 /** Static members that are NOT pure even on a pure namespace. */
 const EFFECTFUL_STATICS = new Set(['Math.random', 'Date.now'])
 
+/**
+ * A match at `pattern[pos]` for an *unbounded* quantifier (`*`, `+`, `{n,}` and
+ * their lazy `?` variants) — the repetitions that drive backtracking blowups.
+ * `?`, `{n}` and `{n,m}` are bounded, so they don't count. Returns the consumed
+ * length, or 0 if there's no unbounded quantifier here.
+ */
+function unboundedQuantifierLen(pattern: string, pos: number): number {
+  const c = pattern[pos]
+  let len = 0
+  if (c === '*' || c === '+') {
+    len = 1
+  } else if (c === '{') {
+    // `{n,}` is unbounded; `{n}` / `{n,m}` are bounded.
+    const m = pattern.slice(pos).match(/^\{\d+,\}/)
+    if (m) len = m[0].length
+  }
+  if (len === 0) return 0
+  // A trailing `?` makes it lazy — still unbounded, still backtracks.
+  if (pattern[pos + len] === '?') len++
+  return len
+}
+
+/**
+ * Conservative ReDoS detector: flags a regex whose **star height is ≥ 2** — an
+ * unbounded quantifier nested inside a group that is itself unbounded-quantified
+ * (the classic `(a+)+`, `(a*)*`, `([a-z]+)*`, `(.*)*` exponential-backtracking
+ * shapes). A predicate verifier should fail closed: over-flagging a safe pattern
+ * only costs it its "verified" badge (it still runs), whereas certifying a
+ * dangerous one is a broken safety promise.
+ *
+ * Not caught (known limitation, documented): *polynomial* ReDoS from adjacent
+ * overlapping quantifiers (`\d+\d+$`, `a.*a.*a`) and alternation-overlap
+ * (`(a|a)*`). The exponential class above is the one the safety story commits to.
+ *
+ * @returns a reason string if risky, else null.
+ */
+function reDoSRisk(pattern: string): string | null {
+  // Per-group frame: did this group contain an unbounded quantifier?
+  const stack: Array<{ hadUnbounded: boolean }> = []
+  let i = 0
+  let inClass = false
+  while (i < pattern.length) {
+    const c = pattern[i]
+    if (c === '\\') {
+      i += 2 // skip an escaped char (regex escapes are 2 chars here)
+      continue
+    }
+    if (inClass) {
+      if (c === ']') inClass = false
+      i++
+      continue
+    }
+    if (c === '[') {
+      inClass = true
+      i++
+      continue
+    }
+    if (c === '(') {
+      stack.push({ hadUnbounded: false })
+      i++
+      continue
+    }
+    if (c === ')') {
+      const frame = stack.pop() ?? { hadUnbounded: false }
+      const qlen = unboundedQuantifierLen(pattern, i + 1)
+      if (qlen > 0) {
+        // This group is itself unbounded-repeated. If it already contained an
+        // unbounded quantifier, that's star height ≥ 2 → catastrophic.
+        if (frame.hadUnbounded)
+          return 'an unbounded quantifier is nested inside another (e.g. `(a+)+`)'
+        // The parent group now contains an unbounded repetition (this group).
+        if (stack.length) stack[stack.length - 1].hadUnbounded = true
+        i += 1 + qlen
+        continue
+      }
+      // No quantifier on this group, but if it contained an unbounded
+      // repetition, that repetition lives in the parent's scope too — propagate
+      // so `((a+))+` is caught the same as `(a+)+`.
+      if (frame.hadUnbounded && stack.length)
+        stack[stack.length - 1].hadUnbounded = true
+      i++
+      continue
+    }
+    // An unbounded quantifier on a plain atom at the current nesting level.
+    const qlen = unboundedQuantifierLen(pattern, i)
+    if (qlen > 0) {
+      if (stack.length) stack[stack.length - 1].hadUnbounded = true
+      i += qlen
+      continue
+    }
+    i++
+  }
+  return null
+}
+
 /**
  * Instance methods known to be pure regardless of receiver type. A method call
  * whose method name isn't here (and whose receiver isn't a pure namespace) is
@@ -255,6 +360,22 @@ export function verifyPredicate(
       ForStatement: loop,
       ForInStatement: loop,
       ForOfStatement: loop,
+      Literal(n: any) {
+        // Regex literals are the one primitive fuel can't bound: a single
+        // `.match`/`.test`/`.replace` is opaque to the function-entry fuel hook,
+        // so a catastrophic-backtracking pattern could hang on hostile input.
+        // Certifying it "safe" would be a false guarantee, so flag it. (Dynamic
+        // `RegExp(...)` is already rejected — `RegExp` isn't a pure global and
+        // `new` is banned — so only literals need analysis.)
+        if (n.regex && typeof n.regex.pattern === 'string') {
+          const risk = reDoSRisk(n.regex.pattern)
+          if (risk)
+            flag(
+              `regex /${n.regex.pattern}/ risks catastrophic backtracking (ReDoS): ${risk}. A single match is not fuel-bounded, so it can't be certified predicate-safe — simplify the pattern or validate without it.`,
+              n
+            )
+        }
+      },
       CallExpression(n: any) {
         const callee = n.callee
         // Bare call: f(...)
@@ -548,3 +669,150 @@ export function compilePredicate(
   }
   return wrapped
 }
+
+export interface EmitPredicateResult {
+  /** True iff the cluster passed predicate-safety verification. */
+  safe: boolean
+  /**
+   * When `safe`, a self-contained JS **expression** that evaluates to the guard
+   * function `(...args) => boolean`. Inline it directly into transpiler output —
+   * it carries its own fuel counter (no global `__fuel`, no runtime dependency
+   * on the predicate engine or the `PredicateFuelExhausted` class). Undefined
+   * when `!safe`.
+   */
+  code?: string
+  /** Verifier diagnostics (the reasons, when `!safe`). */
+  diagnostics: PredicateDiagnostic[]
+}
+
+/**
+ * Verify a predicate cluster and, if safe, emit a **self-contained source
+ * expression** for its guard — the transpile-time counterpart to
+ * `compilePredicate` (which evals to live closures). This is what lets a
+ * verified `Type`/`FunctionPredicate` predicate compile to a fuel-bounded native
+ * guard in standalone output: no import of this module, no shared runtime.
+ *
+ * Fuel model mirrors `compilePredicate` (function-entry `__fuel()` bounds all
+ * iteration since loops are rejected), but because a guard answers a boolean
+ * question, a runaway input **returns `false`** ("not a valid instance of this
+ * type") instead of throwing — DoS-safe validation that never crashes the caller.
+ * A deep-recursion stack overflow is the same runaway signal, normalized the
+ * same way.
+ *
+ * The runtime effectful-global shadow that `compilePredicate` applies is omitted
+ * here on purpose: a `safe` cluster provably references no effectful global (the
+ * static verifier guarantees it), so the shadow would only bloat emitted output.
+ *
+ * @param source      the predicate cluster (one or more `function` declarations)
+ * @param entryName   which declared function is the guard entry point
+ * @param opts        verify options + `fuel` budget (default 1,000,000)
+ */
+export function emitVerifiedPredicate(
+  source: string,
+  entryName: string,
+  opts: CompilePredicateOptions = {}
+): EmitPredicateResult {
+  const result = verifyPredicate(source, opts)
+  if (!result.safe) {
+    return { safe: false, diagnostics: result.diagnostics }
+  }
+  if (!result.predicates.includes(entryName)) {
+    return {
+      safe: false,
+      diagnostics: [
+        {
+          predicate: entryName,
+          message: `entry predicate '${entryName}' not found in the verified cluster`,
+          line: 0,
+          column: 0,
+        },
+      ],
+    }
+  }
+
+  const budget = opts.fuel ?? 1_000_000
+  const instrumented = injectFuel(source)
+
+  // A self-contained IIFE: fuel counter in a closure, guard entry re-armed per
+  // top-level call, runaway (fuel or stack) → `false`.
+  const code =
+    `(() => {` +
+    `let __f = 0;` +
+    `const __fuel = () => { if (--__f < 0) throw new RangeError('tjs:predicate-fuel'); };` +
+    `${instrumented}` +
+    `return (...__a) => {` +
+    `__f = ${budget};` +
+    `try { return !!${entryName}(...__a); }` +
+    `catch (e) {` +
+    `if (e instanceof RangeError && /tjs:predicate-fuel|stack/i.test(e.message)) return false;` +
+    `throw e;` +
+    `}` +
+    `};` +
+    `})()`
+
+  return { safe: true, code, diagnostics: [] }
+}
+
+// --- $predicate evaluator (#6: the tosijs-schema integration point) ---------
+
+export interface PredicateEvaluatorOptions extends CompilePredicateOptions {
+  /**
+   * Called once per source that fails to verify/compile. Default: `console.warn`.
+   * The evaluator fails **closed** on such a source (returns `false`), so an
+   * unverifiable `$predicate` can never validate a value as `true`.
+   */
+  onUnsafe?: (source: string, error: Error) => void
+}
+
+/**
+ * Build a pluggable `$predicate` evaluator: `(source, value) => boolean`.
+ *
+ * This is the bridge for a predicate-aware JSON-Schema validator that lives in
+ * another package (e.g. `tosijs-schema`, which cannot depend on `tjs-lang` — the
+ * dependency runs the other way). Such a validator stays zero-dep and exposes a
+ * hook; a consumer that has this engine injects an evaluator built here.
+ *
+ * Each distinct source is verified + compiled **once** and cached, so repeated
+ * validation is just a native call. Semantics match `compilePredicateSchema`:
+ * the LAST top-level function is the entry; a source that isn't predicate-safe
+ * (or throws / exhausts fuel at runtime) yields `false` — never a thrown error
+ * mid-validation, never a silent pass.
+ */
+export function createPredicateEvaluator(
+  opts: PredicateEvaluatorOptions = {}
+): (source: string, value: unknown) => boolean {
+  const { onUnsafe, ...compileOpts } = opts
+  const cache = new Map<string, ((value: unknown) => boolean) | null>()
+  const warned = new Set<string>()
+
+  return (source: string, value: unknown): boolean => {
+    let fn = cache.get(source)
+    if (fn === undefined) {
+      try {
+        const names = verifyPredicate(source, compileOpts).predicates
+        const entry = names[names.length - 1]
+        if (!entry) throw new Error('$predicate declares no function')
+        const mod = compilePredicate(source, [entry], compileOpts)
+        fn = mod[entry] as (value: unknown) => boolean
+      } catch (e) {
+        fn = null // fail closed
+        if (!warned.has(source)) {
+          warned.add(source)
+          const err = e instanceof Error ? e : new Error(String(e))
+          if (onUnsafe) onUnsafe(source, err)
+          else
+            console.warn(
+              `[tjs-lang] $predicate not verifiable — failing closed: ${err.message}`
+            )
+        }
+      }
+      cache.set(source, fn)
+    }
+    if (fn === null) return false
+    try {
+      return fn(value) === true
+    } catch {
+      return false // fuel exhaustion / runtime miss → not valid
+    }
+  }
+}