tjs-lang 0.8.2 → 0.8.3

package/editors/codemirror/completion-source.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Drives the REAL completion source the playground uses (tjsCompletionSource),
+ * headlessly — its APIs (matchBefore / state.doc / pos / explicit) are DOM-free.
+ *
+ * Regression for the bug where the regex extractor missed destructuring, so the
+ * tosijs todo example (everything bound via destructuring) suggested nothing.
+ */
+import { describe, it, expect } from 'bun:test'
+import { EditorState } from '@codemirror/state'
+import { CompletionContext } from '@codemirror/autocomplete'
+import { tjsCompletionSource } from './ajs-language'
+import type { AutocompleteConfig } from './ajs-language'
+
+const TODO = `import { elements, tosi } from 'tosijs'
+const { todoApp } = tosi({ todoApp: { items: [], newItem: '' } })
+const { h1, ul, template, li, label, input, button } = elements
+`
+
+async function optionsFor(
+  source: string,
+  pos: number = source.length,
+  config: AutocompleteConfig = {}
+) {
+  const state = EditorState.create({ doc: source })
+  const ctx = new CompletionContext(state, pos, /* explicit */ true)
+  const result = await tjsCompletionSource(config)(ctx)
+  return result?.options ?? []
+}
+const labelsFor = async (...args: Parameters<typeof optionsFor>) =>
+  (await optionsFor(...args)).map((o) => o.label)
+
+describe('tjsCompletionSource — scope-aware locals (live provider)', () => {
+  it('suggests destructured bindings from the real todo example', async () => {
+    const labels = await labelsFor(TODO)
+    expect(labels).toContain('todoApp')
+    expect(labels).toContain('h1')
+    expect(labels).toContain('button')
+    expect(labels).toContain('elements')
+  })
+
+  it('completes `tod` to todoApp', async () => {
+    expect(await labelsFor(TODO + 'tod')).toContain('todoApp')
+  })
+
+  it('annotates a destructured binding with its source (∈ elements)', async () => {
+    const opts = await optionsFor(TODO)
+    expect(opts.find((o) => o.label === 'h1')?.detail).toBe('∈ elements')
+  })
+})
+
+describe('tjsCompletionSource — member completion via live bindings (1b-i)', () => {
+  // Stand in for the user's executed scope, live (resolved imports path).
+  const liveBindings = {
+    todoApp: { items: ['bathe the cat'], newItem: '', addItem() {} },
+  }
+  const member = (tail: string) =>
+    labelsFor(`const x = 1\n${tail}`, undefined, {
+      getLiveBindings: () => liveBindings,
+    })
+
+  it('todoApp. → its real properties (items, newItem, addItem)', async () => {
+    const labels = await member('todoApp.')
+    expect(labels).toContain('items')
+    expect(labels).toContain('newItem')
+    expect(labels).toContain('addItem')
+  })
+
+  it('todoApp.items. → array methods (push, map) — nested path resolves', async () => {
+    const labels = await member('todoApp.items.')
+    expect(labels).toContain('push')
+    expect(labels).toContain('map')
+  })
+
+  it('unknown path resolves to nothing (no crash)', async () => {
+    expect(await member('todoApp.nope.')).toEqual([])
+  })
+})
+
+describe('tjsCompletionSource — member completion via the bridge (1b-ii)', () => {
+  // The introspection bridge: async, returns the REAL runtime members for a path
+  // the sync bindings don't know about (the user's own executed scope).
+  const getMembers = async (path: string) => {
+    if (path === 'todoApp')
+      return [
+        { label: 'items', type: 'property' as const, detail: 'object' },
+        { label: 'addItem', type: 'method' as const, detail: '()' },
+      ]
+    if (path === 'todoApp.items')
+      return [{ label: 'push', type: 'method' as const, detail: '(arg1)' }]
+    return []
+  }
+
+  it('falls back to the bridge when sync bindings miss the path', async () => {
+    const labels = await labelsFor('const x = 1\ntodoApp.', undefined, {
+      getMembers,
+    })
+    expect(labels).toContain('items')
+    expect(labels).toContain('addItem')
+  })
+
+  it('bridge resolves a nested path (todoApp.items.push)', async () => {
+    const labels = await labelsFor('const x = 1\ntodoApp.items.', undefined, {
+      getMembers,
+    })
+    expect(labels).toContain('push')
+  })
+
+  it('a method member becomes a callable completion', async () => {
+    const opts = await optionsFor('const x = 1\ntodoApp.', undefined, {
+      getMembers,
+    })
+    expect(opts.find((o) => o.label === 'addItem')?.type).toBe('method')
+  })
+})

package/editors/introspect-value.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'bun:test'
+import { introspectValue, INTROSPECT_VALUE_SOURCE } from './introspect-value'
+
+const labels = (v: unknown) => introspectValue(v).map((m) => m.label)
+const member = (v: unknown, name: string) =>
+  introspectValue(v).find((m) => m.label === name)
+
+describe('introspectValue — serializable runtime introspection', () => {
+  it('object → own properties and methods, typed', () => {
+    const todoApp = { items: [], newItem: '', addItem() {} }
+    const ls = labels(todoApp)
+    expect(ls).toContain('items')
+    expect(ls).toContain('newItem')
+    expect(ls).toContain('addItem')
+    expect(member(todoApp, 'addItem')?.type).toBe('method')
+    expect(member(todoApp, 'newItem')?.type).toBe('property')
+    expect(member(todoApp, 'newItem')?.detail).toBe('string')
+  })
+
+  it('array → inherited methods from the prototype (push, map)', () => {
+    const ls = labels([1, 2, 3])
+    expect(ls).toContain('push')
+    expect(ls).toContain('map')
+    expect(ls).toContain('filter')
+    expect(member([1], 'push')?.type).toBe('method')
+  })
+
+  it('method arity becomes an arg hint', () => {
+    const o = { f(a: unknown, b: unknown) {} }
+    void o.f
+    expect(member(o, 'f')?.detail).toBe('(arg1, arg2)')
+  })
+
+  it('skips constructor and underscore-prefixed members', () => {
+    const ls = labels({ _private: 1, visible: 2 })
+    expect(ls).toContain('visible')
+    expect(ls).not.toContain('_private')
+    expect(ls).not.toContain('constructor')
+  })
+
+  it('introspects a Proxy via own keys (tosijs `elements` shape)', () => {
+    // a proxy that materialises keys on access but DOES report own keys
+    const backing: Record<string, unknown> = { h1: () => {}, div: () => {} }
+    const proxy = new Proxy(backing, {})
+    const ls = labels(proxy)
+    expect(ls).toContain('h1')
+    expect(ls).toContain('div')
+  })
+
+  it('non-objects → nothing; never throws', () => {
+    expect(introspectValue(null)).toEqual([])
+    expect(introspectValue(42)).toEqual([])
+    expect(introspectValue(undefined)).toEqual([])
+  })
+
+  it('is self-contained source (injectable into the sandbox iframe)', () => {
+    // no outer references that would break when eval-ed in another realm
+    expect(INTROSPECT_VALUE_SOURCE).toContain('function introspectValue')
+    expect(INTROSPECT_VALUE_SOURCE).not.toMatch(/\bimport\b/)
+  })
+})

package/editors/introspect-value.ts

@@ -0,0 +1,86 @@
+/**
+ * Serializable runtime introspection — the in-sandbox half of the introspection
+ * bridge. Given a live value, produce a flat list of member descriptors that
+ * survive `postMessage` (plain strings, no functions). The introspection bridge
+ * injects this function's SOURCE into the sandbox iframe (via `.toString()`), so
+ * it must be **self-contained** — no imports, no outer references.
+ *
+ * It mirrors the editor's own `introspectObject` (own keys first — important for
+ * proxies that cache accesses, like tosijs `elements` — then the prototype
+ * chain), but returns data instead of CodeMirror completions. The provider maps
+ * these descriptors back into completions on the parent side.
+ */
+
+export interface IntrospectMember {
+  label: string
+  /** 'method' for callables, else 'property'. */
+  type: 'method' | 'property'
+  /** typeof for properties, an arg hint for methods. */
+  detail: string
+}
+
+export function introspectValue(value: unknown): IntrospectMember[] {
+  if (
+    value == null ||
+    (typeof value !== 'object' && typeof value !== 'function')
+  ) {
+    return []
+  }
+
+  const out: IntrospectMember[] = []
+  const seen = new Set<string>()
+
+  const push = (key: string, v: unknown) => {
+    if (key === 'constructor' || key.startsWith('_') || seen.has(key)) return
+    seen.add(key)
+    if (typeof v === 'function') {
+      const arity = (v as { length?: number }).length ?? 0
+      const params =
+        arity > 0
+          ? Array.from({ length: arity }, (_, i) => `arg${i + 1}`).join(', ')
+          : ''
+      out.push({ label: key, type: 'method', detail: `(${params})` })
+    } else {
+      out.push({ label: key, type: 'property', detail: typeof v })
+    }
+  }
+
+  // Own enumerable keys first — handles Proxies that materialise on access.
+  try {
+    for (const key of Object.keys(value as object)) {
+      try {
+        push(key, (value as Record<string, unknown>)[key])
+      } catch {
+        /* getter threw — skip */
+      }
+    }
+  } catch {
+    /* Object.keys failed — continue with the prototype walk */
+  }
+
+  // Own properties + prototype chain (inherited methods like Array#push).
+  let current: any = value
+  while (
+    current &&
+    current !== Object.prototype &&
+    current !== Function.prototype
+  ) {
+    for (const key of Object.getOwnPropertyNames(current)) {
+      if (key === 'constructor' || key.startsWith('_') || seen.has(key))
+        continue
+      try {
+        const d = Object.getOwnPropertyDescriptor(current, key)
+        const v = d?.value ?? (d?.get ? '[getter]' : undefined)
+        push(key, v)
+      } catch {
+        /* property threw on access — skip */
+      }
+    }
+    current = Object.getPrototypeOf(current)
+  }
+
+  return out
+}
+
+/** The function source, for injection into the sandbox iframe. */
+export const INTROSPECT_VALUE_SOURCE = introspectValue.toString()

package/editors/scope-symbols.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'bun:test'
+import { collectScopeSymbols, type ScopeSymbol } from './scope-symbols'
+
+// `|` marks the cursor; returns source without it + the offset.
+function at(src: string): { source: string; position: number } {
+  const position = src.indexOf('|')
+  if (position === -1) return { source: src, position: src.length }
+  return { source: src.slice(0, position) + src.slice(position + 1), position }
+}
+
+const names = (syms: ScopeSymbol[]) => syms.map((s) => s.name).sort()
+const find = (syms: ScopeSymbol[], n: string) => syms.find((s) => s.name === n)
+
+describe('collectScopeSymbols — destructuring-aware scope', () => {
+  it('object destructuring from a call (the bug: `const { todoApp } = tosi(...)`)', () => {
+    const { source } = at(`const { todoApp } = tosi({ items: [] })`)
+    const syms = collectScopeSymbols(source)
+    expect(names(syms)).toContain('todoApp')
+    expect(find(syms, 'todoApp')?.origin?.via).toBe('destructure')
+    expect(find(syms, 'todoApp')?.origin?.expr).toBe('tosi({ items: [] })')
+  })
+
+  it('multiple names destructured from an identifier carry member + source', () => {
+    const { source } = at(`const { h1, ul, button } = elements`)
+    const syms = collectScopeSymbols(source)
+    expect(names(syms)).toEqual(['button', 'h1', 'ul'])
+    // origin is the introspection hook: `elements.h1`
+    expect(find(syms, 'h1')?.origin?.expr).toBe('elements')
+    expect(find(syms, 'h1')?.origin?.member).toBe('h1')
+  })
+
+  it('array destructuring, holes skipped', () => {
+    const { source } = at(`const [first, , third] = items`)
+    expect(names(collectScopeSymbols(source))).toEqual(['first', 'third'])
+  })
+
+  it('rename binds the new name, records the source key', () => {
+    const { source } = at(`const { color: c } = theme`)
+    const syms = collectScopeSymbols(source)
+    expect(names(syms)).toEqual(['c'])
+    expect(find(syms, 'c')?.origin?.member).toBe('color')
+  })
+
+  it('defaults and rest', () => {
+    const a = collectScopeSymbols(at(`const { x = 1, ...rest } = o`).source)
+    expect(names(a)).toEqual(['rest', 'x'])
+    const b = collectScopeSymbols(at(`const [head, ...tail] = xs`).source)
+    expect(names(b)).toEqual(['head', 'tail'])
+  })
+
+  it('imports (named, default, namespace, renamed)', () => {
+    const { source } = at(
+      `import def, { tosi, elements as els } from 'tosijs'\nimport * as ns from 'x'`
+    )
+    const syms = collectScopeSymbols(source)
+    expect(names(syms)).toEqual(['def', 'els', 'ns', 'tosi'])
+    expect(find(syms, 'tosi')?.origin?.module).toBe('tosijs')
+    expect(find(syms, 'els')?.kind).toBe('import')
+  })
+
+  it('function name in scope; params only inside the body', () => {
+    const inside = at(`function ship(to, qty) {\n  |\n}`)
+    const syms = collectScopeSymbols(inside.source, inside.position)
+    expect(names(syms)).toEqual(['qty', 'ship', 'to'])
+
+    const outside = at(`function ship(to, qty) {}\n|`)
+    const syms2 = collectScopeSymbols(outside.source, outside.position)
+    expect(names(syms2)).toContain('ship')
+    expect(names(syms2)).not.toContain('to')
+  })
+
+  it('destructured params too', () => {
+    const inside = at(`function render({ title, items }) {\n  |\n}`)
+    const syms = collectScopeSymbols(inside.source, inside.position)
+    expect(names(syms)).toEqual(['items', 'render', 'title'])
+  })
+
+  it('position-scoped: declarations after the cursor are excluded', () => {
+    const { source, position } = at(`const before = 1\n|\nconst after = 2`)
+    const syms = collectScopeSymbols(source, position)
+    expect(names(syms)).toContain('before')
+    expect(names(syms)).not.toContain('after')
+  })
+
+  it('resilient to mid-edit / not-yet-valid source (acorn-loose)', () => {
+    // trailing incomplete line shouldn't blank out the earlier bindings
+    const { source, position } = at(`const { todoApp } = tosi({})\ntodoApp.i|`)
+    const syms = collectScopeSymbols(source, position)
+    expect(names(syms)).toContain('todoApp')
+  })
+
+  it('the real tosijs todo example surfaces every binding', () => {
+    const src = `import { elements, tosi } from 'tosijs'
+const { todoApp } = tosi({ todoApp: { items: [], newItem: '' } })
+const { h1, ul, template, li, label, input, button } = elements
+`
+    const got = names(collectScopeSymbols(src))
+    for (const n of [
+      'elements',
+      'tosi',
+      'todoApp',
+      'h1',
+      'ul',
+      'template',
+      'li',
+      'label',
+      'input',
+      'button',
+    ]) {
+      expect(got).toContain(n)
+    }
+  })
+})

package/editors/scope-symbols.ts

@@ -0,0 +1,173 @@
+/**
+ * Scope-aware symbol collection for autocomplete.
+ *
+ * Replaces the regex `const NAME =` scraping (which missed ALL destructuring —
+ * and the tosijs examples bind everything via destructuring, so nothing was
+ * suggested). This parses the source (acorn, falling back to acorn-loose for
+ * mid-edit / not-yet-valid source) and walks binding patterns properly:
+ * `const { todoApp } = tosi(...)`, `const { h1, ul } = elements`,
+ * `const [a, , b] = xs`, rename, defaults, rest — all yield their bound names.
+ *
+ * Each symbol also records its **origin** (the initializer expression text, and
+ * for object-destructuring the key it came from). That origin is the hook the
+ * runtime-introspection layer uses: to introspect `h1` it can evaluate
+ * `elements.h1` in the live scope. Names are plumbing; the *types* come from
+ * introspecting real values (see the introspection bridge), not from this parse.
+ */
+import * as acorn from 'acorn'
+import * as acornLoose from 'acorn-loose'
+import * as walk from 'acorn-walk'
+
+export interface SymbolOrigin {
+  /** How the binding was produced. */
+  via: 'init' | 'destructure' | 'param' | 'import' | 'function'
+  /** Source text of the initializer expression (e.g. `elements`, `tosi({...})`). */
+  expr?: string
+  /** For object-destructuring: the key on `expr` this name came from (`elements.h1` → `h1`). */
+  member?: string
+  /** Module specifier, for imports. */
+  module?: string
+}
+
+export interface ScopeSymbol {
+  name: string
+  kind: 'variable' | 'function' | 'parameter' | 'import'
+  origin?: SymbolOrigin
+}
+
+function parse(source: string): any {
+  try {
+    return acorn.parse(source, { ecmaVersion: 'latest' })
+  } catch {
+    try {
+      // Best-effort AST from incomplete / not-yet-valid source.
+      return acornLoose.parse(source, { ecmaVersion: 'latest' })
+    } catch {
+      return null
+    }
+  }
+}
+
+type NameSink = (name: string, member?: string) => void
+
+/** Walk a binding pattern, emitting each bound name (and, one level deep for
+ *  object patterns, the source key it came from). */
+function collectPattern(pat: any, onName: NameSink, member?: string): void {
+  if (!pat) return
+  switch (pat.type) {
+    case 'Identifier':
+      onName(pat.name, member)
+      return
+    case 'ObjectPattern':
+      for (const p of pat.properties) {
+        if (p.type === 'RestElement') {
+          collectPattern(p.argument, onName)
+        } else {
+          const key = p.key && (p.key.name ?? p.key.value)
+          collectPattern(
+            p.value,
+            onName,
+            typeof key === 'string' ? key : undefined
+          )
+        }
+      }
+      return
+    case 'ArrayPattern':
+      for (const el of pat.elements) collectPattern(el, onName)
+      return
+    case 'AssignmentPattern':
+      collectPattern(pat.left, onName, member)
+      return
+    case 'RestElement':
+      collectPattern(pat.argument, onName)
+      return
+  }
+}
+
+const inRange = (node: any, position: number) =>
+  typeof node.start === 'number' &&
+  typeof node.end === 'number' &&
+  node.start <= position &&
+  position <= node.end
+
+/**
+ * Collect the symbols in scope at `position` (defaults to end of source):
+ * variable/function/import bindings declared before the cursor, plus the
+ * parameters of any function whose body the cursor sits inside. Destructuring
+ * is fully handled; results are de-duplicated by name (last declaration wins).
+ */
+export function collectScopeSymbols(
+  source: string,
+  position: number = source.length
+): ScopeSymbol[] {
+  const ast = parse(source)
+  if (!ast) return []
+
+  const byName = new Map<string, ScopeSymbol>()
+  const add = (s: ScopeSymbol) => byName.set(s.name, s)
+
+  walk.full(ast, (node: any) => {
+    switch (node.type) {
+      case 'VariableDeclaration': {
+        // Only count declarations that appear before the cursor.
+        if (node.start >= position) return
+        for (const decl of node.declarations) {
+          const initText =
+            decl.init && typeof decl.init.start === 'number'
+              ? source.slice(decl.init.start, decl.init.end)
+              : undefined
+          collectPattern(decl.id, (name, member) =>
+            add({
+              name,
+              kind: 'variable',
+              origin: {
+                via: member != null ? 'destructure' : 'init',
+                expr: initText,
+                member,
+              },
+            })
+          )
+        }
+        return
+      }
+      case 'FunctionDeclaration': {
+        if (node.id && node.start < position)
+          add({
+            name: node.id.name,
+            kind: 'function',
+            origin: { via: 'function' },
+          })
+        // params only in scope when the cursor is inside the function
+        if (inRange(node, position))
+          for (const p of node.params)
+            collectPattern(p, (name) =>
+              add({ name, kind: 'parameter', origin: { via: 'param' } })
+            )
+        return
+      }
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression': {
+        if (inRange(node, position))
+          for (const p of node.params)
+            collectPattern(p, (name) =>
+              add({ name, kind: 'parameter', origin: { via: 'param' } })
+            )
+        return
+      }
+      case 'ImportDeclaration': {
+        const module = String(node.source?.value ?? '')
+        for (const spec of node.specifiers) {
+          // local name is spec.local.name for all specifier kinds
+          add({
+            name: spec.local.name,
+            kind: 'import',
+            origin: { via: 'import', module },
+          })
+        }
+        return
+      }
+    }
+  })
+
+  return [...byName.values()]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "typescript",
@@ -161,6 +161,7 @@
   },
   "dependencies": {
     "acorn": "^8.15.0",
+    "acorn-loose": "^8.5.2",
     "acorn-walk": "^8.3.4",
     "tosijs-schema": "^1.3.0"
   }

package/src/lang/index.ts

@@ -44,6 +44,28 @@ export {
   type Dialect,
   type SourceKind,
 } from './dialect'
+export {
+  verifyPredicate,
+  compilePredicate,
+  suggest,
+  effectfulFromAtoms,
+  formatPredicateDiagnostics,
+  PredicateFuelExhausted,
+  type PredicateDiagnostic,
+  type PredicateVerifyResult,
+  type VerifyPredicateOptions,
+  type CompilePredicateOptions,
+  type Suggestion,
+  type SuggestOptions,
+} from './predicate'
+export {
+  compilePredicateSchema,
+  validatePredicateSchema,
+  type PredicateSchema,
+  type SchemaError,
+  type SchemaValidationResult,
+  type PredicateSchemaOptions,
+} from './predicate-schema'
 export { transformFunction } from './emitters/ast'
 export {
   transpileToJS,

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

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'bun:test'
+import {
+  compilePredicateSchema,
+  validatePredicateSchema,
+  type PredicateSchema,
+} from './predicate-schema'
+
+// A composable color predicate cluster (entry = last function, takes the value).
+const COLOR = `
+  function isHex(v){ return typeof v == 'string' && /^#[0-9a-f]{3,8}$/i.test(v) }
+  function isVar(v){ return typeof v == 'string' && v.startsWith('var(--') && v.endsWith(')') }
+  function isCalc(v){ return typeof v == 'string' && v.startsWith('calc(') && v.endsWith(')') }
+  function isColor(v){ return isHex(v) || isVar(v) || isCalc(v) }
+`
+
+// A recursive predicate cluster — validates a tree of string/number leaves.
+// Note the `!Array.isArray(o)` guard: arrays are objects in JS, so a node check
+// must exclude them explicitly (a real predicate-authoring nuance).
+const TREE = `
+  function isLeaf(v){ return typeof v == 'string' || typeof v == 'number' }
+  function isEntry(pair){ var val = pair[1]; return isLeaf(val) || isNode(val) }
+  function isNode(o){ return typeof o == 'object' && o != null && !Array.isArray(o) && Object.entries(o).every(isEntry) }
+`
+
+const colorSchema: PredicateSchema = {
+  type: 'object',
+  required: ['color'],
+  properties: {
+    color: { type: 'string', description: 'a CSS color', $predicate: COLOR },
+  },
+}
+
+describe('predicate-schema — the computational half of JSON-Schema', () => {
+  it('a predicate-aware validator validates the value grammar', () => {
+    const validate = compilePredicateSchema(colorSchema)
+    expect(validate({ color: '#3a3' }).valid).toBe(true)
+    expect(validate({ color: 'var(--brand)' }).valid).toBe(true) // TS/JSON-Schema can't
+    expect(validate({ color: 'calc(1px + 1em)' }).valid).toBe(true)
+
+    const bad = validate({ color: 'notacolor' })
+    expect(bad.valid).toBe(false)
+    expect(bad.errors[0].path).toBe('/color')
+  })
+
+  it('still does structural validation (type / required)', () => {
+    const validate = compilePredicateSchema(colorSchema)
+    expect(validate({ color: 123 }).errors[0].message).toMatch(
+      /expected string/
+    )
+    expect(validate({}).errors[0].message).toMatch(/missing required 'color'/)
+  })
+
+  it('progressive enhancement: a naive validator ignores `$predicate`', () => {
+    // ignorePredicates models any standard JSON-Schema validator that doesn't
+    // know the keyword — it sees only `type: string`.
+    const naive = compilePredicateSchema(colorSchema, {
+      ignorePredicates: true,
+    })
+    expect(naive({ color: 'notacolor' }).valid).toBe(true) // string → passes
+    // …while the aware validator catches it:
+    expect(
+      compilePredicateSchema(colorSchema)({ color: 'notacolor' }).valid
+    ).toBe(false)
+  })
+
+  it('the schema is plain serializable JSON — code travels as data', () => {
+    const roundTripped: PredicateSchema = JSON.parse(
+      JSON.stringify(colorSchema)
+    )
+    expect(roundTripped).toEqual(colorSchema)
+    // and it still validates after a serialize/deserialize round-trip
+    const validate = compilePredicateSchema(roundTripped)
+    expect(validate({ color: '#abc' }).valid).toBe(true)
+    expect(validate({ color: 'nope' }).valid).toBe(false)
+  })
+
+  it('a `$predicate` can recurse into open nested structure', () => {
+    const schema: PredicateSchema = { type: 'object', $predicate: TREE }
+    const validate = compilePredicateSchema(schema)
+    expect(validate({ a: 1, b: { c: 'x', d: { e: 2 } } }).valid).toBe(true)
+    expect(validate({ a: 1, bad: { nope: [] } }).valid).toBe(false) // array leaf
+  })
+
+  it('rejects an unsafe predicate at compile time (IO never embeds)', () => {
+    const evil: PredicateSchema = {
+      type: 'string',
+      $predicate: `function check(v){ return fetch(v) }`,
+    }
+    expect(() => compilePredicateSchema(evil)).toThrow(/Not predicate-safe/)
+  })
+
+  it('one-shot helper works too', () => {
+    expect(validatePredicateSchema(colorSchema, { color: '#fff' }).valid).toBe(
+      true
+    )
+  })
+})