conjure-js 0.0.11 → 0.0.13

package/src/core/evaluator/special-forms.ts

@@ -1,32 +1,24 @@
+import { is } from '../assertions'
 import {
-  isAFunction,
-  isEqual,
-  isFalsy,
-  isKeyword,
-  isList,
-  isMap,
-  isMultiMethod,
-  isSymbol,
-  isTruthy,
-  isVector,
-} from '../assertions'
-import { define, extend, getNamespaceEnv, getRootEnv, lookup, lookupVar } from '../env'
+  define,
+  extend,
+  getNamespaceEnv,
+  internVar,
+  lookup,
+  lookupVar,
+  makeEnv,
+} from '../env'
 import { CljThrownSignal, EvaluationError } from '../errors'
-import {
-  cljKeyword,
-  cljMap,
-  cljMultiArityFunction,
-  cljMultiArityMacro,
-  cljMultiMethod,
-  cljNativeFunction,
-  cljNil,
-  cljString,
-  cljVar,
-} from '../factories'
+import { v } from '../factories'
+// --- ASYNC (experimental) ---
+import { createAsyncEvalCtx } from './async-evaluator'
+// --- END ASYNC ---
+import { getLineCol, getPos } from '../positions'
 import type {
   CljFunction,
   CljKeyword,
   CljList,
+  CljMap,
   CljMultiMethod,
   CljNativeFunction,
   CljValue,
@@ -35,8 +27,29 @@ import type {
 } from '../types'
 import { parseArities, RecurSignal } from './arity'
 import { destructureBindings } from './destructure'
+import { evaluateDot, evaluateNew } from './js-interop'
 import { evaluateQuasiquote } from './quasiquote'
 import { assertRecurInTailPosition } from './recur-check'
+import {
+  matchesDiscriminator,
+  parseTryStructure,
+  validateBindingVector,
+} from './form-parsers'
+
+function hasDynamicMeta(meta: CljMap | undefined): boolean {
+  if (!meta) return false
+  for (const [k, v] of meta.entries) {
+    if (
+      is.keyword(k) &&
+      k.name === ':dynamic' &&
+      is.boolean(v) &&
+      v.value === true
+    ) {
+      return true
+    }
+  }
+  return false
+}
 
 export const specialFormKeywords = {
   quote: 'quote',
@@ -54,14 +67,26 @@ export const specialFormKeywords = {
   defmethod: 'defmethod',
   try: 'try',
   var: 'var',
+  binding: 'binding',
+  'set!': 'set!',
+  letfn: 'letfn',
+  delay: 'delay',
+  'lazy-seq': 'lazy-seq',
+  // --- ASYNC (experimental) ---
+  async: 'async',
+  // --- END ASYNC ---
+  // --- JS INTEROP ---
+  '.': '.',
+  'js/new': 'js/new',
+  // --- END JS INTEROP ---
 } as const
 
 function keywordToDispatchFn(kw: CljKeyword): CljNativeFunction {
-  return cljNativeFunction(`kw:${kw.name}`, (...args: CljValue[]) => {
+  return v.nativeFn(`kw:${kw.name}`, (...args: CljValue[]) => {
     const target = args[0]
-    if (!isMap(target)) return cljNil()
-    const entry = target.entries.find(([k]) => isEqual(k, kw))
-    return entry ? entry[1] : cljNil()
+    if (!is.map(target)) return v.nil()
+    const entry = target.entries.find(([k]) => is.equal(k, kw))
+    return entry ? entry[1] : v.nil()
   })
 }
 
@@ -70,83 +95,12 @@ function evaluateTry(
   env: Env,
   ctx: EvaluationContext
 ): CljValue {
-  const forms = list.value.slice(1)
-  const bodyForms: CljValue[] = []
-  const catchClauses: Array<{
-    discriminator: CljValue
-    binding: string
-    body: CljValue[]
-  }> = []
-  let finallyForms: CljValue[] | null = null
-
-  for (let i = 0; i < forms.length; i++) {
-    const form = forms[i]
-    if (isList(form) && form.value.length > 0 && isSymbol(form.value[0])) {
-      const head = form.value[0].name
-      if (head === 'catch') {
-        if (form.value.length < 3) {
-          throw new EvaluationError(
-            'catch requires a discriminator and a binding symbol',
-            { form, env }
-          )
-        }
-        const discriminator = form.value[1]
-        const bindingSym = form.value[2]
-        if (!isSymbol(bindingSym)) {
-          throw new EvaluationError('catch binding must be a symbol', {
-            form,
-            env,
-          })
-        }
-        catchClauses.push({
-          discriminator,
-          binding: bindingSym.name,
-          body: form.value.slice(3),
-        })
-        continue
-      }
-      if (head === 'finally') {
-        if (i !== forms.length - 1) {
-          throw new EvaluationError(
-            'finally clause must be the last in try expression',
-            {
-              form,
-              env,
-            }
-          )
-        }
-        finallyForms = form.value.slice(1)
-        continue
-      }
-    }
-    bodyForms.push(form)
-  }
-
-  function matchesDiscriminator(
-    discriminator: CljValue,
-    thrown: CljValue
-  ): boolean {
-    const disc = ctx.evaluate(discriminator, env)
-    if (isKeyword(disc)) {
-      if (disc.name === ':default') return true
-      if (!isMap(thrown)) return false
-      const typeEntry = thrown.entries.find(
-        ([k]) => isKeyword(k) && k.name === ':type'
-      )
-      if (!typeEntry) return false
-      return isEqual(typeEntry[1], disc)
-    }
-    if (isAFunction(disc)) {
-      const result = ctx.applyFunction(disc, [thrown], env)
-      return isTruthy(result)
-    }
-    throw new EvaluationError(
-      'catch discriminator must be a keyword or a predicate function',
-      { discriminator: disc, env }
-    )
-  }
+  const { bodyForms, catchClauses, finallyForms } = parseTryStructure(
+    list,
+    env
+  )
 
-  let result: CljValue = cljNil()
+  let result: CljValue = v.nil()
   let pendingThrow: unknown = null
 
   try {
@@ -158,9 +112,9 @@ function evaluateTry(
     if (e instanceof CljThrownSignal) {
       thrownValue = e.value
     } else if (e instanceof EvaluationError) {
-      thrownValue = cljMap([
-        [cljKeyword(':type'), cljKeyword(':error/runtime')],
-        [cljKeyword(':message'), cljString(e.message)],
+      thrownValue = v.map([
+        [v.keyword(':type'), v.keyword(':error/runtime')],
+        [v.keyword(':message'), v.string(e.message)],
       ])
     } else {
       throw e
@@ -168,7 +122,7 @@ function evaluateTry(
 
     let handled = false
     for (const clause of catchClauses) {
-      if (matchesDiscriminator(clause.discriminator, thrownValue)) {
+      if (matchesDiscriminator(clause.discriminator, thrownValue, env, ctx)) {
         const catchEnv = extend([clause.binding], [thrownValue], env)
         result = ctx.evaluateForms(clause.body, catchEnv)
         handled = true
@@ -205,6 +159,46 @@ function evalQuasiquote(
   return evaluateQuasiquote(list.value[1], env, new Map(), ctx)
 }
 
+/**
+ * Merge reader-attached symbol metadata with source-position metadata
+ * (:line, :column, :file) derived from the current evaluation context.
+ * Returns undefined if there is nothing to attach.
+ */
+function buildVarMeta(
+  symMeta: CljMap | undefined,
+  ctx: EvaluationContext,
+  nameVal?: CljValue
+): CljMap | undefined {
+  const pos = nameVal ? getPos(nameVal) : undefined
+  const hasPosInfo = pos && ctx.currentSource
+
+  if (!symMeta && !hasPosInfo) return undefined
+
+  const posEntries: [CljValue, CljValue][] = []
+  if (hasPosInfo) {
+    const { line, col } = getLineCol(ctx.currentSource!, pos!.start)
+    const lineOffset = ctx.currentLineOffset ?? 0
+    const colOffset = ctx.currentColOffset ?? 0
+    posEntries.push([v.keyword(':line'), v.number(line + lineOffset)])
+    posEntries.push([
+      v.keyword(':column'),
+      v.number(line === 1 ? col + colOffset : col),
+    ])
+    if (ctx.currentFile) {
+      posEntries.push([v.keyword(':file'), v.string(ctx.currentFile)])
+    }
+  }
+
+  // Preserve all existing symMeta entries except the three we're stamping.
+  const POS_KEYS = new Set([':line', ':column', ':file'])
+  const baseEntries = (symMeta?.entries ?? []).filter(
+    ([k]) => !(k.kind === 'keyword' && POS_KEYS.has(k.name))
+  )
+
+  const allEntries = [...baseEntries, ...posEntries]
+  return allEntries.length > 0 ? v.map(allEntries) : undefined
+}
+
 function evaluateDef(
   list: CljList,
   env: Env,
@@ -221,19 +215,28 @@ function evaluateDef(
   // (def name) with no value is a bare declaration — a no-op in the evaluator.
   // This lets .clj source files declare runtime-injected symbols so that
   // clojure-lsp can resolve them, without clobbering the native binding.
-  if (list.value[2] === undefined) return cljNil()
+  if (list.value[2] === undefined) return v.nil()
 
   const nsEnv = getNamespaceEnv(env)
   const cljNs = nsEnv.ns!
   const newValue = ctx.evaluate(list.value[2], env)
 
+  // Compute source position metadata (:line/:column/:file) if available.
+  const varMeta = buildVarMeta(name.meta, ctx, name)
+
   const existing = cljNs.vars.get(name.name)
   if (existing) {
     existing.value = newValue
+    if (varMeta) {
+      existing.meta = varMeta
+      if (hasDynamicMeta(varMeta)) existing.dynamic = true
+    }
   } else {
-    cljNs.vars.set(name.name, cljVar(cljNs.name, name.name, newValue))
+    const newVar = v.var(cljNs.name, name.name, newValue, varMeta)
+    if (hasDynamicMeta(varMeta)) newVar.dynamic = true
+    cljNs.vars.set(name.name, newVar)
   }
-  return cljNil()
+  return v.nil()
 }
 
 const evaluateNs = (
@@ -241,16 +244,16 @@ const evaluateNs = (
   _env: Env,
   _ctx: EvaluationContext
 ): CljValue => {
-  return cljNil() // special form handled by the environment, no effects here
+  return v.nil() // special form handled by the environment, no effects here
 }
 
 function evaluateIf(list: CljList, env: Env, ctx: EvaluationContext): CljValue {
   const condition = ctx.evaluate(list.value[1], env)
-  if (!isFalsy(condition)) {
+  if (!is.falsy(condition)) {
     return ctx.evaluate(list.value[2], env)
   }
   if (!list.value[3]) {
-    return cljNil() // no-else case, return nil
+    return v.nil() // no-else case, return nil
   }
   return ctx.evaluate(list.value[3], env)
 }
@@ -265,18 +268,7 @@ function evaluateLet(
   ctx: EvaluationContext
 ): CljValue {
   const bindings = list.value[1]
-  if (!isVector(bindings)) {
-    throw new EvaluationError('Bindings must be a vector', {
-      bindings,
-      env,
-    })
-  }
-  if (bindings.value.length % 2 !== 0) {
-    throw new EvaluationError(
-      'Bindings must be a balanced pair of keys and values',
-      { bindings, env }
-    )
-  }
+  validateBindingVector(bindings, 'let', env)
   const body = list.value.slice(2)
   let localEnv = env
   for (let i = 0; i < bindings.value.length; i += 2) {
@@ -298,30 +290,112 @@ function evaluateFn(
   env: Env,
   _ctx: EvaluationContext
 ): CljValue {
-  const arities = parseArities(list.value.slice(1), env)
+  const rest = list.value.slice(1)
+  // (fn name [...] ...) — optional name symbol before the param vector/arities
+  let fnName: string | undefined
+  let arityForms = rest
+  if (rest[0]?.kind === 'symbol') {
+    fnName = rest[0].name
+    arityForms = rest.slice(1)
+  }
+  const arities = parseArities(arityForms, env)
   for (const arity of arities) {
     assertRecurInTailPosition(arity.body)
   }
-  return cljMultiArityFunction(arities, env)
+  const fn = v.multiArityFunction(arities, env)
+  if (fnName) {
+    fn.name = fnName
+    // Bind the name in the fn's closure env so the body can call itself by name.
+    // We wrap the captured env in a new frame containing name → fn, then point
+    // fn.env at that frame so the binding is visible during application.
+    const selfEnv = makeEnv(env)
+    selfEnv.bindings.set(fnName, fn)
+    fn.env = selfEnv
+  }
+  return fn
+}
+
+function evaluateLetfn(
+  list: CljList,
+  env: Env,
+  ctx: EvaluationContext
+): CljValue {
+  // (letfn [(f1 [x] ...) (f2 [x] ...)] body...)
+  const fnSpecs = list.value[1]
+  if (!is.vector(fnSpecs)) {
+    throw new EvaluationError('letfn binding specs must be a vector', {
+      fnSpecs,
+      env,
+    })
+  }
+  const body = list.value.slice(2)
+
+  // Create a shared env frame for all the fns to close over
+  const sharedEnv = makeEnv(env)
+
+  // First pass: create all fn objects in the shared env
+  for (const spec of fnSpecs.value) {
+    if (!is.list(spec) || spec.value.length < 2 || !is.symbol(spec.value[0])) {
+      throw new EvaluationError(
+        'letfn specs must be (name [params] body...) forms',
+        { spec }
+      )
+    }
+    const name = spec.value[0].name
+    const arityForms = spec.value.slice(1)
+    const arities = parseArities(arityForms, sharedEnv)
+    for (const arity of arities) {
+      assertRecurInTailPosition(arity.body)
+    }
+    const fn = v.multiArityFunction(arities, sharedEnv)
+    fn.name = name
+    sharedEnv.bindings.set(name, fn)
+  }
+
+  // Second pass: point all fn envs to the shared env so they can see each other
+  for (const spec of fnSpecs.value) {
+    const name = (spec as CljList).value[0] as { name: string }
+    const fn = sharedEnv.bindings.get(name.name) as CljFunction
+    fn.env = sharedEnv
+  }
+
+  return ctx.evaluateForms(body, sharedEnv)
+}
+
+function mergeDocIntoMeta(base: CljMap | undefined, docstring: string): CljMap {
+  const docEntry: [CljValue, CljValue] = [
+    v.keyword(':doc'),
+    v.string(docstring),
+  ]
+  const existing = (base?.entries ?? []).filter(
+    ([k]) => !(k.kind === 'keyword' && k.name === ':doc')
+  )
+  return { kind: 'map', entries: [...existing, docEntry] }
 }
 
 function evaluateDefmacro(
   list: CljList,
   env: Env,
-  _ctx: EvaluationContext
+  ctx: EvaluationContext
 ): CljValue {
   const name = list.value[1]
-  if (!isSymbol(name)) {
+  if (!is.symbol(name)) {
     throw new EvaluationError('First element of defmacro must be a symbol', {
       name,
       list,
       env,
     })
   }
-  const arities = parseArities(list.value.slice(2), env)
-  const macro = cljMultiArityMacro(arities, env)
-  define(name.name, macro, getRootEnv(env))
-  return cljNil()
+  const rest = list.value.slice(2)
+  const docstring = rest[0]?.kind === 'string' ? rest[0].value : undefined
+  const arityForms = docstring ? rest.slice(1) : rest
+  const arities = parseArities(arityForms, env)
+  const macro = v.multiArityMacro(arities, env)
+  macro.name = name.name
+  const varMeta = buildVarMeta(name.meta, ctx, name)
+  const finalMeta = docstring ? mergeDocIntoMeta(varMeta, docstring) : varMeta
+  internVar(name.name, macro, getNamespaceEnv(env), finalMeta)
+  return v.nil()
 }
 
 function evaluateLoop(
@@ -330,18 +404,7 @@ function evaluateLoop(
   ctx: EvaluationContext
 ): CljValue {
   const loopBindings = list.value[1]
-  if (!isVector(loopBindings)) {
-    throw new EvaluationError('loop bindings must be a vector', {
-      loopBindings,
-      env,
-    })
-  }
-  if (loopBindings.value.length % 2 !== 0) {
-    throw new EvaluationError(
-      'loop bindings must be a balanced pair of keys and values',
-      { loopBindings, env }
-    )
-  }
+  validateBindingVector(loopBindings, 'loop', env)
   const loopBody = list.value.slice(2)
   assertRecurInTailPosition(loopBody)
 
@@ -413,7 +476,7 @@ function evaluateDefmulti(
   ctx: EvaluationContext
 ): CljValue {
   const mmName = list.value[1]
-  if (!isSymbol(mmName)) {
+  if (!is.symbol(mmName)) {
     throw new EvaluationError('defmulti: first argument must be a symbol', {
       list,
       env,
@@ -421,11 +484,11 @@ function evaluateDefmulti(
   }
   const dispatchFnExpr = list.value[2]
   let dispatchFn: CljFunction | CljNativeFunction
-  if (isKeyword(dispatchFnExpr)) {
+  if (is.keyword(dispatchFnExpr)) {
     dispatchFn = keywordToDispatchFn(dispatchFnExpr)
   } else {
     const evaluated = ctx.evaluate(dispatchFnExpr, env)
-    if (!isAFunction(evaluated)) {
+    if (!is.aFunction(evaluated)) {
       throw new EvaluationError(
         'defmulti: dispatch-fn must be a function or keyword',
         { list, env }
@@ -433,9 +496,9 @@ function evaluateDefmulti(
     }
     dispatchFn = evaluated
   }
-  const mm = cljMultiMethod(mmName.name, dispatchFn, [])
-  define(mmName.name, mm, getNamespaceEnv(env))
-  return cljNil()
+  const mm = v.multiMethod(mmName.name, dispatchFn, [])
+  internVar(mmName.name, mm, getNamespaceEnv(env))
+  return v.nil()
 }
 
 function evaluateDefmethod(
@@ -444,7 +507,7 @@ function evaluateDefmethod(
   ctx: EvaluationContext
 ): CljValue {
   const mmName = list.value[1]
-  if (!isSymbol(mmName)) {
+  if (!is.symbol(mmName)) {
     throw new EvaluationError('defmethod: first argument must be a symbol', {
       list,
       env,
@@ -452,18 +515,18 @@ function evaluateDefmethod(
   }
   const dispatchVal = ctx.evaluate(list.value[2], env)
   const existing = lookup(mmName.name, env)
-  if (!isMultiMethod(existing)) {
+  if (!is.multiMethod(existing)) {
     throw new EvaluationError(
       `defmethod: ${mmName.name} is not a multimethod`,
       { list, env }
     )
   }
   const arities = parseArities([list.value[3], ...list.value.slice(4)], env)
-  const methodFn = cljMultiArityFunction(arities, env)
-  const isDefault = isKeyword(dispatchVal) && dispatchVal.name === ':default'
+  const methodFn = v.multiArityFunction(arities, env)
+  const isDefault = is.keyword(dispatchVal) && dispatchVal.name === ':default'
   let updated: CljMultiMethod
   if (isDefault) {
-    updated = cljMultiMethod(
+    updated = v.multiMethod(
       existing.name,
       existing.dispatchFn,
       existing.methods,
@@ -471,24 +534,30 @@ function evaluateDefmethod(
     )
   } else {
     const filtered = existing.methods.filter(
-      (m) => !isEqual(m.dispatchVal, dispatchVal)
+      (m) => !is.equal(m.dispatchVal, dispatchVal)
     )
-    updated = cljMultiMethod(existing.name, existing.dispatchFn, [
+    updated = v.multiMethod(existing.name, existing.dispatchFn, [
       ...filtered,
       { dispatchVal, fn: methodFn },
     ])
   }
-  define(mmName.name, updated, getNamespaceEnv(env))
-  return cljNil()
+  // Update the var's value in place if possible, otherwise fall back to define
+  const eVar = lookupVar(mmName.name, env)
+  if (eVar) {
+    eVar.value = updated
+  } else {
+    define(mmName.name, updated, getNamespaceEnv(env))
+  }
+  return v.nil()
 }
 
 function evaluateVar(
   list: CljList,
   env: Env,
-  _ctx: EvaluationContext
+  ctx: EvaluationContext
 ): CljValue {
   const sym = list.value[1]
-  if (!isSymbol(sym)) {
+  if (!is.symbol(sym)) {
     throw new EvaluationError('var expects a symbol', { list })
   }
 
@@ -497,19 +566,13 @@ function evaluateVar(
     const alias = sym.name.slice(0, slashIdx)
     const localName = sym.name.slice(slashIdx + 1)
     const nsEnv = getNamespaceEnv(env)
-    // Try alias lookup (CljNamespace) first
-    const aliasCljNs = nsEnv.ns?.aliases.get(alias)
-    if (aliasCljNs) {
-      const v = aliasCljNs.vars.get(localName)
-      if (!v) throw new EvaluationError(`Var ${sym.name} not found`, { sym })
-      return v
-    }
-    // Fall back to full namespace Env chain (handles clojure.core/sym etc.)
-    const targetEnv = getRootEnv(env).resolveNs?.(alias) ?? null
-    if (!targetEnv) {
+    // Resolve alias: local :as alias first, then full namespace name
+    const targetNs =
+      nsEnv.ns?.aliases.get(alias) ?? ctx.resolveNs(alias) ?? null
+    if (!targetNs) {
       throw new EvaluationError(`No such namespace: ${alias}`, { sym })
     }
-    const v = lookupVar(localName, targetEnv)
+    const v = targetNs.vars.get(localName)
     if (!v) throw new EvaluationError(`Var ${sym.name} not found`, { sym })
     return v
   }
@@ -524,6 +587,138 @@ function evaluateVar(
   return v
 }
 
+function evaluateBinding(
+  list: CljList,
+  env: Env,
+  ctx: EvaluationContext
+): CljValue {
+  const bindings = list.value[1]
+  if (!is.vector(bindings)) {
+    throw new EvaluationError('binding requires a vector of bindings', {
+      list,
+      env,
+    })
+  }
+  if (bindings.value.length % 2 !== 0) {
+    throw new EvaluationError(
+      'binding vector must have an even number of forms',
+      { list, env }
+    )
+  }
+  const body = list.value.slice(2)
+  const boundVars: import('../types').CljVar[] = []
+
+  for (let i = 0; i < bindings.value.length; i += 2) {
+    const sym = bindings.value[i]
+    if (!is.symbol(sym)) {
+      throw new EvaluationError('binding left-hand side must be a symbol', {
+        sym,
+      })
+    }
+    const newVal = ctx.evaluate(bindings.value[i + 1], env)
+    const v = lookupVar(sym.name, env)
+    if (!v) {
+      throw new EvaluationError(
+        `No var found for symbol '${sym.name}' in binding form`,
+        { sym }
+      )
+    }
+    if (!v.dynamic) {
+      throw new EvaluationError(
+        `Cannot use binding with non-dynamic var ${v.ns}/${v.name}. Mark it dynamic with (def ^:dynamic ${sym.name} ...)`,
+        { sym }
+      )
+    }
+    v.bindingStack ??= []
+    v.bindingStack.push(newVal)
+    boundVars.push(v)
+  }
+
+  try {
+    return ctx.evaluateForms(body, env)
+  } finally {
+    for (const v of boundVars) {
+      v.bindingStack!.pop()
+    }
+  }
+}
+
+function evaluateSet(
+  list: CljList,
+  env: Env,
+  ctx: EvaluationContext
+): CljValue {
+  if (list.value.length !== 3) {
+    throw new EvaluationError(
+      `set! requires exactly 2 arguments, got ${list.value.length - 1}`,
+      { list, env }
+    )
+  }
+  const symForm = list.value[1]
+  if (!is.symbol(symForm)) {
+    throw new EvaluationError(
+      `set! first argument must be a symbol, got ${symForm.kind}`,
+      { symForm, env }
+    )
+  }
+  const v = lookupVar(symForm.name, env)
+  if (!v) {
+    throw new EvaluationError(
+      `Unable to resolve var: ${symForm.name} in this context`,
+      { symForm, env }
+    )
+  }
+  if (!v.dynamic) {
+    throw new EvaluationError(
+      `Cannot set! non-dynamic var ${v.ns}/${v.name}. Mark it with ^:dynamic.`,
+      { symForm, env }
+    )
+  }
+  if (!v.bindingStack || v.bindingStack.length === 0) {
+    throw new EvaluationError(
+      `Cannot set! ${v.ns}/${v.name} — no active binding. Use set! only inside a (binding [...] ...) form.`,
+      { symForm, env }
+    )
+  }
+  const newVal = ctx.evaluate(list.value[2], env)
+  v.bindingStack[v.bindingStack.length - 1] = newVal
+  return newVal
+}
+
+function evaluateDelay(
+  list: CljList,
+  env: Env,
+  ctx: EvaluationContext
+): CljValue {
+  const body = list.value.slice(1)
+  return v.delay(() => ctx.evaluateForms(body, env))
+}
+
+function evaluateLazySeqForm(
+  list: CljList,
+  env: Env,
+  ctx: EvaluationContext
+): CljValue {
+  const body = list.value.slice(1)
+  return v.lazySeq(() => ctx.evaluateForms(body, env))
+}
+
+// --- ASYNC BLOCK HANDLER (experimental) ---
+// Gateway into the async sub-evaluator. See async-evaluator.ts.
+// To revert: remove this function, the `async` case below, and the import above.
+function evaluateAsyncBlock(
+  list: CljList,
+  env: Env,
+  ctx: EvaluationContext
+): CljValue {
+  const body = list.value.slice(1)
+  if (body.length === 0) return v.pending(Promise.resolve(v.nil()))
+  const asyncCtx = createAsyncEvalCtx(ctx)
+  const promise = asyncCtx.evaluateForms(body, env)
+  return v.pending(promise)
+}
+// --- END ASYNC BLOCK HANDLER ---
+
 type SpecialFormEvaluatorFn = (
   list: CljList,
   env: Env,
@@ -546,6 +741,18 @@ const specialFormEvaluatorEntries = {
   defmulti: evaluateDefmulti,
   defmethod: evaluateDefmethod,
   var: evaluateVar,
+  binding: evaluateBinding,
+  'set!': evaluateSet,
+  letfn: evaluateLetfn,
+  delay: evaluateDelay,
+  'lazy-seq': evaluateLazySeqForm,
+  // --- ASYNC (experimental) ---
+  async: evaluateAsyncBlock,
+  // --- END ASYNC ---
+  // --- JS INTEROP ---
+  '.': evaluateDot,
+  'js/new': evaluateNew,
+  // --- END JS INTEROP ---
 } as const satisfies Record<
   keyof typeof specialFormKeywords,
   SpecialFormEvaluatorFn