tjs-lang 0.8.6 → 0.9.0

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
+    }
+  }
+}

package/src/lang/redos-lint.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Regex ReDoS linting in the predicate verifier. A regex match is opaque to the
+ * fuel counter (a single `.test`/`.match` can't be interrupted mid-backtrack),
+ * so a catastrophic-backtracking pattern can't be certified predicate-safe. The
+ * verifier flags the exponential star-height≥2 class (`(a+)+`, `(a*)*`, …) and
+ * fails closed: over-flagging only costs the "verified" badge (the predicate
+ * still runs), whereas certifying a dangerous one would be a broken promise.
+ */
+import { describe, it, expect } from 'bun:test'
+import { verifyPredicate, emitVerifiedPredicate } from './predicate'
+import { preprocess } from './parser'
+
+/** Verify a single predicate whose body uses the given regex literal. */
+const verifyRe = (re: string) =>
+  verifyPredicate(`function p(s) { return ${re}.test(s) }`)
+
+describe('ReDoS linting: dangerous patterns are not predicate-safe', () => {
+  const dangerous: Array<[string, string]> = [
+    ['nested +', '/(a+)+$/'],
+    ['nested *', '/(a*)*/'],
+    ['plus-in-star', '/([a-z]+)*/'],
+    ['dot-star star', '/(.*)*/'],
+    ['digit nest', '/(\\d+)+/'],
+    ['unbounded brace nest', '/(a{2,})+/'],
+    ['doubly nested group', '/((a+))+/'],
+  ]
+  for (const [label, re] of dangerous) {
+    it(`flags ${label}: ${re}`, () => {
+      const r = verifyRe(re)
+      expect(r.safe).toBe(false)
+      expect(
+        r.diagnostics.some((d) => /redos|backtrack/i.test(d.message))
+      ).toBe(true)
+    })
+  }
+})
+
+describe('ReDoS linting: safe patterns still verify', () => {
+  const safe: Array<[string, string]> = [
+    ['char class +', '/[a-z]+/'],
+    ['bounded braces', '/\\d{3}-\\d{4}/'],
+    ['group repeated, no inner quantifier', '/(abc)+/'],
+    ['alternation repeated', '/(foo|bar)+/'],
+    ['anchored hex', '/^#[0-9a-f]{6}$/'],
+    ['single star', '/foo.*bar/'],
+    ['optional group', '/(ab)?c+/'],
+  ]
+  for (const [label, re] of safe) {
+    it(`accepts ${label}: ${re}`, () => {
+      const r = verifyRe(re)
+      expect(r.safe).toBe(true)
+      expect(r.diagnostics).toEqual([])
+    })
+  }
+})
+
+describe('ReDoS linting: end-to-end', () => {
+  it('emitVerifiedPredicate refuses a ReDoS regex (no code)', () => {
+    const r = emitVerifiedPredicate(
+      'function p(s) { return /(a+)+$/.test(s) }',
+      'p'
+    )
+    expect(r.safe).toBe(false)
+    expect(r.code).toBeUndefined()
+  })
+
+  it('a Type predicate with a ReDoS regex falls back (no verified guard)', () => {
+    const out = preprocess(
+      `Type Bad 'bad' { predicate(s) { return /(a+)+$/.test(s) } }`
+    ).source
+    expect(out).not.toContain('__fuel') // not certified → raw fallback
+    expect(out).toContain('(a+)+') // raw body preserved
+  })
+
+  it('a Type predicate with a safe regex compiles to a verified guard', () => {
+    const out = preprocess(
+      `Type Hex 'hex' { predicate(s) { return /^#[0-9a-f]{6}$/.test(s) } }`
+    ).source
+    expect(out).toContain('__fuel') // certified safe → fuel-bounded guard
+  })
+})

package/src/lang/transpiler.ts

@@ -28,6 +28,8 @@ export {
 export {
   verifyPredicate,
   compilePredicate,
+  emitVerifiedPredicate,
+  createPredicateEvaluator,
   suggest,
   effectfulFromAtoms,
   formatPredicateDiagnostics,
@@ -36,6 +38,8 @@ export {
   type PredicateVerifyResult,
   type VerifyPredicateOptions,
   type CompilePredicateOptions,
+  type EmitPredicateResult,
+  type PredicateEvaluatorOptions,
   type Suggestion,
   type SuggestOptions,
 } from './predicate'
@@ -53,6 +57,14 @@ export {
 // AST emitter
 export { transformFunction } from './emitters/ast'
 
+// .d.ts emitter — the express-controlled migration bridge for a TS importer
+// graph (see ../tosijs/TJS-PORT-DX.md). Needs to be reachable from `tjs-lang/lang`.
+export {
+  generateDTS,
+  typeDescriptorToTS,
+  type GenerateDTSOptions,
+} from './emitters/dts'
+
 // JS emitter (TJS -> JS)
 export { transpileToJS } from './emitters/js'
 export type {
@@ -107,4 +119,5 @@ export type {
   TranspileOptions,
   TranspileResult,
   TranspileWarning,
+  PredicateVerification,
 } from './types'

package/src/lang/type-verified-predicate.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Integration: `Type … { predicate(x){…} }` bodies that verify as predicate-safe
+ * compile to a self-contained, fuel-bounded native guard (the `emitVerifiedPredicate`
+ * path); unverifiable ones fall back to the raw arrow (never rejected — TJS ⊇ JS).
+ *
+ * We assert against the preprocessed source: `__fuel` present ⇔ the verified
+ * guard was emitted. Runtime guard behavior is covered by
+ * `emit-verified-predicate.test.ts`.
+ */
+import { describe, it, expect } from 'bun:test'
+import { preprocess } from './parser'
+import { tjs } from './index'
+
+const src = (s: string) => preprocess(s).source
+
+describe('multiple verified predicates in one module (no name collision)', () => {
+  // Regression: each verified guard used a fixed `function __pred`, so two in
+  // one module collided — the polymorphic-merge transform saw duplicate names
+  // and either errored ("ambiguous signatures") or renamed to `__pred$1`,
+  // breaking the guard IIFE at runtime. Names are now per-declaration.
+  it('transpiles two Type predicates without a `__pred` clash', () => {
+    const out = tjs(
+      `Type A 'a' { predicate(x) { return x > 0 } }\n` +
+        `Type B 'b' { predicate(x) { return x < 0 } }`
+    )
+    expect(out.code).not.toContain('__pred$')
+    expect(out.code).toContain('__pred_A')
+    expect(out.code).toContain('__pred_B')
+  })
+
+  it('transpiles a Type + Generic predicate together', () => {
+    const out = tjs(
+      `Type Pos 'positive' { predicate(x) { return x > 0 } }\n` +
+        `Generic Box<T> { description: 'b', predicate(x, T) { return T(x.value) } }`
+    )
+    expect(out.code).not.toContain('__pred$')
+    expect(out.code).toContain('__pred_Pos')
+    expect(out.code).toContain('__pred_Box')
+  })
+})
+
+describe('Type predicate → verified fuel-bounded guard', () => {
+  it('compiles a safe predicate-only Type to a fuel-bounded guard', () => {
+    const out = src(`Type Pos 'positive' { predicate(x) { return x > 0 } }`)
+    expect(out).toContain(`const Pos = Type('positive'`)
+    expect(out).toContain('__fuel') // verified + fuel-injected
+    expect(out).toContain('x > 0') // original body preserved inside the guard
+  })
+
+  it('compiles a safe predicate+example Type, keeping the example schema gate', () => {
+    const out = src(
+      `Type EvenNum 'even' { example: 2, predicate(x) { return x % 2 === 0 } }`
+    )
+    expect(out).toContain(`const EvenNum = Type('even'`)
+    expect(out).toContain('__fuel') // verified
+    expect(out).toContain('__tjs?.validate') // example schema still gates
+    expect(out).toContain('x % 2 === 0')
+  })
+
+  it('verifies a native-TJS predicate using == (rewritten to Eq)', () => {
+    // `==` → `Eq(...)`; Eq is whitelisted pure, so the predicate still verifies.
+    const out = src(`Type Five 'five' { predicate(x) { return x == 5 } }`)
+    expect(out).toContain('Eq(') // proves the equality rewrite ran
+    expect(out).toContain('__fuel') // ...and it still verified as safe
+  })
+
+  it('falls back to the raw arrow for an unverifiable predicate (loop)', () => {
+    const out = src(
+      `Type AllPos 'all positive' { example: [1], predicate(xs) { for (const x of xs) { if (x <= 0) return false } return true } }`
+    )
+    expect(out).not.toContain('__fuel') // NOT verified → no fuel guard
+    expect(out).toContain('for (const x of xs)') // raw body preserved
+    expect(out).toContain('__tjs?.validate') // example gate still present
+  })
+
+  it('falls back for an impure predicate (effectful call)', () => {
+    const out = src(
+      `Type Reachable 'reachable' { predicate(url) { return fetch(url) } }`
+    )
+    expect(out).not.toContain('__fuel')
+    expect(out).toContain('fetch(url)') // raw body preserved
+  })
+})

package/src/lang/types.ts

@@ -97,6 +97,23 @@ export interface TranspileWarning {
   source?: string
 }
 
+/**
+ * Per-declaration report of whether a `Type`/`Generic` predicate body verified
+ * as predicate-safe (→ compiled to a fuel-bounded, DoS-safe native guard) or
+ * fell back to a plain unverified function (still valid — TJS ⊇ JS — but not
+ * fuel-bounded or safe to run on untrusted data). Surfaced on the transpile
+ * result so tools can flag unverifiable predicates.
+ */
+export interface PredicateVerification {
+  /** The `Type` / `Generic` declaration name. */
+  name: string
+  kind: 'Type' | 'Generic'
+  /** True → verified + compiled to a native guard; false → raw-function fallback. */
+  verified: boolean
+  /** When `!verified`, the verifier's reason(s). */
+  reason?: string
+}
+
 /** Source map for debugging */
 export interface SourceMap {
   version: 3

package/src/lang/typescript-syntax.test.ts

@@ -13,7 +13,8 @@
  */
 
 import { describe, test, expect } from 'bun:test'
-import { transpileToJS, fromTS, tjs } from './index'
+import { transpileToJS, tjs } from './index'
+import { fromTS } from './emitters/from-ts'
 
 // Helper to get the first function's metadata from the Record
 function getFirstFunc(metadata: Record<string, any>) {

package/src/schema/index.ts

@@ -0,0 +1,62 @@
+/**
+ * `tjs-lang/schema` — tosijs-schema, pre-wired with predicate support.
+ *
+ * A drop-in for `tosijs-schema` that additionally evaluates the `$predicate`
+ * keyword: importing this module registers tjs-lang's verified predicate engine
+ * as the evaluator, so JSON-Schema validation is predicate-aware **out of the
+ * box** — no manual `setPredicateEvaluator` call. Everything tosijs-schema
+ * exports is re-exported here, so this is the only import a consumer needs:
+ *
+ * ```ts
+ * import { s, validate } from 'tjs-lang/schema'
+ * // a schema whose node carries `$predicate` now validates computationally
+ * ```
+ *
+ * Why it lives here and not in tosijs-schema: tjs-lang depends on tosijs-schema,
+ * so the reverse would be a circular dependency. This entry sits on the side of
+ * the graph that may know about both — it's the "batteries-included" packaging
+ * of the two.
+ *
+ * Registration is a global (tosijs-schema keeps one evaluator), so importing
+ * this module makes `$predicate` work for tosijs-schema usage app-wide, even in
+ * code that imports `tosijs-schema` directly. Call `setPredicateEvaluator(null)`
+ * to opt back out, or `installPredicateSupport(opts)` to re-install with custom
+ * options (fuel budget, atom-aware effects, etc.).
+ */
+import { setPredicateEvaluator, getPredicateEvaluator } from 'tosijs-schema'
+import {
+  createPredicateEvaluator,
+  type PredicateEvaluatorOptions,
+} from '../lang/predicate'
+
+// The full tosijs-schema surface (s, validate, filter, diff, types,
+// setPredicateEvaluator, getPredicateEvaluator, PredicateEvaluator, …).
+export * from 'tosijs-schema'
+// The evaluator factory, for advanced/custom wiring.
+export {
+  createPredicateEvaluator,
+  type PredicateEvaluatorOptions,
+} from '../lang/predicate'
+
+let installed = false
+
+/**
+ * Register tjs-lang's predicate engine as tosijs-schema's `$predicate` evaluator.
+ * Called automatically when this module is imported; exposed so callers can
+ * re-install with custom {@link PredicateEvaluatorOptions} (e.g. a smaller fuel
+ * budget, or an atom-aware effectful set) after opting out.
+ */
+export function installPredicateSupport(
+  opts?: PredicateEvaluatorOptions
+): void {
+  setPredicateEvaluator(createPredicateEvaluator(opts))
+  installed = true
+}
+
+/** True once predicate support has been installed (and not since cleared). */
+export function predicateSupportInstalled(): boolean {
+  return installed && getPredicateEvaluator() !== null
+}
+
+// Batteries included: wire the engine up on import.
+installPredicateSupport()

package/src/schema/schema.test.ts

@@ -0,0 +1,66 @@
+/**
+ * `tjs-lang/schema` — tosijs-schema pre-wired with predicate support. Importing
+ * the module should make `$predicate` validation work with no manual wiring, and
+ * re-export the whole tosijs-schema surface. Runs against the real published
+ * tosijs-schema (node_modules), so it also guards the version/API contract.
+ */
+import { describe, it, expect, afterAll } from 'bun:test'
+import {
+  validate,
+  s,
+  setPredicateEvaluator,
+  getPredicateEvaluator,
+  installPredicateSupport,
+  predicateSupportInstalled,
+  createPredicateEvaluator,
+} from './index'
+import { cssStyleSchema, cssColorSchema } from '../css'
+
+// Leave the global evaluator registered for other suites (import order is
+// nondeterministic); this module's contract is "installed after import".
+afterAll(() => installPredicateSupport())
+
+describe('tjs-lang/schema is batteries-included', () => {
+  it('registers the predicate evaluator on import', () => {
+    expect(predicateSupportInstalled()).toBe(true)
+    expect(typeof getPredicateEvaluator()).toBe('function')
+  })
+
+  it('re-exports the tosijs-schema surface', () => {
+    expect(typeof validate).toBe('function')
+    expect(typeof s).toBe('object') // the builder proxy
+    expect(typeof setPredicateEvaluator).toBe('function')
+    expect(typeof createPredicateEvaluator).toBe('function')
+  })
+
+  it('validates a $predicate node out of the box (CSS color)', () => {
+    const color = cssColorSchema()
+    expect(validate('#3a3', color)).toBe(true)
+    expect(validate('notacolor', color)).toBe(false) // predicate ran, no manual wiring
+  })
+
+  it('validates the recursive CSS style structure', () => {
+    const style = cssStyleSchema()
+    expect(
+      validate({ color: 'red', '&:hover': { color: 'var(--accent)' } }, style)
+    ).toBe(true)
+    expect(validate({ '  bad key  ': 'red' }, style)).toBe(false)
+    expect(validate('not-an-object', style)).toBe(false)
+  })
+
+  it('opting out (setPredicateEvaluator(null)) falls back to structural only', () => {
+    setPredicateEvaluator(null)
+    const color = cssColorSchema()
+    // naive: only `type: string` is checked, so a non-color string passes
+    expect(validate('notacolor', color)).toBe(true)
+    // re-install for the remaining assertions
+    installPredicateSupport()
+    expect(validate('notacolor', color)).toBe(false)
+  })
+
+  it('installPredicateSupport accepts custom options (fuel budget)', () => {
+    installPredicateSupport({ fuel: 500_000 })
+    expect(predicateSupportInstalled()).toBe(true)
+    expect(validate('#fff', cssColorSchema())).toBe(true)
+  })
+})