novac 2.0.1 → 2.2.0

package/src/core/executor.js

@@ -1,9 +1,15 @@
 const {
   NovaValue, NovaNumber, NovaString, NovaArray, NovaObject,
   NovaFunction, NovaTemplateString, NovaPointer, NovaBool, NovaNull, NovaRange,
-  NovaStruct, NovaEnum,
+  NovaStruct, NovaEnum, NOVA_META,
 } = require('./types.js');
 const { CustomError, formatError, NovaException } = require('./error');
+const { atob } = require('buffer');
+
+// ── Default sentinel ─────────────────────────────────────────────────────────
+// When `default` is passed as a function argument, the parameter's declared
+// default value is used instead (same effect as omitting the argument).
+const DEFAULT_SENTINEL = Symbol('nova:default');
 
 // ══════════════ TypeRegistry ══════════════
 class TypeRegistry {
@@ -44,7 +50,21 @@ class TypeRegistry {
         if (this.enums.has(n)) return value && value.__enum_type__ === n;
         return true;
       }
-      case 'union_type': return typeExpr.variants.some(v => this.check(value, v));
+      case 'value_type': {
+        // Literal value type: exact equality
+        const lv = typeExpr.value;
+        const raw = value instanceof NovaValue ? value.valueOf() : value;
+        if (lv === Symbol.for('NOVA_TRUE') || lv?.toString?.() === 'Symbol(NOVA_TRUE)') return raw === true;
+        if (lv === Symbol.for('NOVA_FALSE') || lv?.toString?.() === 'Symbol(NOVA_FALSE)') return raw === false;
+        if (lv === Symbol.for('NOVA_NULL') || lv?.toString?.() === 'Symbol(NOVA_NULL)') return raw == null;
+        return raw === lv;
+      }
+      case 'union_type': {
+        // If all variants are named_type with literal-looking names, treat as type union
+        // But if any variant is a value literal (STRING/NUMBER/BOOL from parser value node),
+        // treat as value union — checked in executor via modifiers
+        return typeExpr.variants.some(v => this.check(value, v));
+      }
       case 'array_type': return value instanceof NovaArray;
       case 'shape_type': return value instanceof NovaObject;
       case 'intersect_type': return typeExpr.parts.every(p => this.check(value, p));
@@ -85,8 +105,9 @@ class TypeRegistry {
 // ══════════════ Scope ══════════════
 class Scope {
   constructor(kind = 'block', parent = null, globalScope = null) {
+    const self = this;
     this.kind = kind; this.parent = parent; this.globalScope = globalScope;
-    this.variables = { scope: this, array: { toCallable: () => (vals) => new NovaArray(vals) } };
+    this.variables = { globalScope, parent, scope: this, array: { toCallable: () => (vals) => new NovaArray(vals) } };
     this.consts = {}; this.prototypes = [];
   }
   get(name) {
@@ -105,14 +126,14 @@ class Scope {
       }
     }
     // Scope chain
-    if (this.globalScope) {
-      const gv = this.globalScope.get(name);
-      if (gv !== null && gv !== undefined) return gv;
-    }
     if (this.parent) {
       const pv = this.parent.get(name);
       if (pv !== null && pv !== undefined) return pv;
     }
+    if (this.globalScope) {
+      const gv = this.globalScope.get(name);
+      if (gv !== null && gv !== undefined) return gv;
+    }
     return null;
   }
   delete(name) {
@@ -144,6 +165,13 @@ class Scope {
     return value;
   }
   has(name) { return name in this.variables; }
+  // Always write to this scope's own variables — used by 'let'/'const' declarations
+  // so that re-declaring a name in a child scope shadows the parent instead of updating it.
+  setOwn(name, value, isConst) {
+    if (isConst) { this.consts[name] = value; }
+    this.variables[name] = value;
+    return value;
+  }
   toString() { return this.kind.toUpperCase(); }
 }
 
@@ -164,25 +192,84 @@ class Executor {
     this.resus = new Map();
     this.namespaces = new Map();
     this.novaServers = new Map();   // port -> routes[], for in-process dispatch
+    this.dot_commands = {
+      print: (...args) => {
+        console.log(...args.map(a => _self.evaluate(a)));
+      },
+      clear: () => process.stdout.write('\x1Bc'),
+      code: () => 0, // no-op, used for doc comments that should be ignored by the executor but visible to external tools
+      zap: (target) => {
+        const t = this.evaluate(target);
+        if (t instanceof NovaObject) {
+          for (const k of Object.keys(t.inner)) delete t.inner[k];
+        } else if (t instanceof NovaStruct) {
+          for (const k of Object.keys(t.inner)) delete t.inner[k];
+        } else if (t && typeof t === 'object') {
+          for (const k of Object.keys(t)) delete t[k];
+        } else {
+          throw new Error('.zap target must be an object or struct instance');
+        }
+      },
+      cookie() {
+        const asciiCookie = `(\\_/)
+( •_•)
+/ >🍪   Here's a cookie for you!`;
+        console.log(asciiCookie);
+      },
+      js: (code) => {
+        const codeStr = this.evaluate(code);
+        if (typeof codeStr === 'string') eval(codeStr);
+        else if (codeStr instanceof NovaString) eval(codeStr.value);
+        else throw new Error('.js command requires a string argument');
+      },
+    }
     this.moduleExportsStack = [];
-    this.awaiting = false;           // true while an await is resolving; blocks all scheduling
     this.options = {};
     this.optionDecls = {};
     this.descriptions = [];
     this.globalScope.variables.std = stdlib;
     const self = this;
 
-    this.globalScope.set('setTimeout', (fn, delay) => {
-      const wrapped = () => {
-        if (self.awaiting) { setTimeout(wrapped, 0); return; } // re-queue until clear
-        if (typeof fn === 'function') fn();
-        else if (fn && fn.body) self.runFunctionNode(fn, self.globalScope, []);
-      };
-      setTimeout(wrapped, delay);
-    });
+    this.globalScope.set('avaibleKits', (() => {
+      const kits = [];
+      const kitsDir = require('path').join(__dirname, '../..', 'kits');
+      try {
+        const fs = require('fs');
+        for (const kitName of fs.readdirSync(kitsDir)) {
+          kits.push(kitName)
+        }
+      } catch (e) {
+        console.warn('Could not load kits:', e.message);
+      }
+      return kits;
+    })());
+    this.globalScope.set('setTimeout', setTimeout);
+    this.globalScope.set('clearTimeout', clearTimeout);
+    this.globalScope.set('setInterval', setInterval);
+    this.globalScope.set('clearInterval', clearInterval);
+    this.globalScope.set('setImmediate', setImmediate);
+    this.globalScope.set('clearImmediate', clearImmediate);
+    this.globalScope.set('queueMicrotask', queueMicrotask);
+    this.globalScope.set('parseInt', parseInt);
+    this.globalScope.set('parseFloat', parseFloat);
+    this.globalScope.set('isNaN', isNaN);
+    this.globalScope.set('isFinite', isFinite);
+    this.globalScope.set('sleepAsync', (ms) => new Promise(r => setTimeout(r, ms)));
+    this.globalScope.set('Scope', Scope);
+    this.globalScope.set('Atomics', Atomics);
+    this.globalScope.set('SharedArrayBuffer', SharedArrayBuffer);
+    this.globalScope.set('Buffer', Buffer);
+    this.globalScope.set('CError', CustomError);
+    this.globalScope.set('Error', Error);
+    //remaining built in nodejs variables and objects excluding global, process, console (which we want to control access to), and a few others for safety
+    this.globalScope.set('textEncoder', TextEncoder);
+    this.globalScope.set('textDecoder', TextDecoder);
+    this.globalScope.set('Util', require('util'));
+    this.globalScope.set('Date', Date);
+    // Expose the default sentinel so runtime code can detect it
+    this.globalScope.set('__DEFAULT_SENTINEL__', DEFAULT_SENTINEL);
 
     this.globalScope.set('core', {
-      test: { object: { foo: 42 } },
       getAst: () => this.ast,
       json: JSON,
       print: (v) => { process.stdout.write(this.stringify(v) + '\n'); return ''; },
@@ -277,7 +364,7 @@ class Executor {
       check: (a, pred) => typeof pred === 'function' ? pred(a) : (_qae[pred] ? _qae[pred](a) : false),
     };
     this.globalScope.set('qae', _qae);
-    this.globalScope.set('novaRegex', (pattern, flags) => this._novaRegex(pattern, flags || ''));
+    this.globalScope.set('cregex', (pattern, flags) => this._novaRegex(pattern, flags || ''));
 
     // ── Sync HTTP fetch ──
     const _self = this;
@@ -386,6 +473,1594 @@ class Executor {
       info: (msg) => process.stdout.write('INFO: ' + String(msg) + '\n'),
     };
     this.globalScope.set('nvk', nvk);
+    this.globalScope.set('charAt', String.fromCharCode);
+    // ── waitsync(fn, ...args) ─────────────────────────────────────────────
+    // Calls fn(...args) and blocks synchronously until the result settles,
+    // whether the function is:
+    //   • a plain sync nova/JS function  → returns immediately
+    //   • an `async` nova function       → returns a Promise from runFunctionNode
+    //   • any JS function returning a Promise
+    //
+    // For Promise-returning cases we CANNOT use Atomics.wait on the main thread
+    // because that blocks the event loop, starving microtasks and causing a
+    // deadlock.  Instead we offload the Promise resolution to a disposable
+    // worker_threads Worker that has its own event loop, wait on a
+    // SharedArrayBuffer signal, and read the result back via a shared buffer.
+    this.globalScope.set('waitsync', (fn, ...args) => {
+      // Call the function — may return a plain value or a Promise
+      let result;
+      if (fn && fn.body !== undefined) {
+        result = _self.runFunctionNode(fn, _self.globalScope, args);
+      } else if (typeof fn === 'function') {
+        result = fn(...args);
+      } else {
+        throw new Error('waitsync: first argument must be a function');
+      }
+
+      // Non-Promise: return immediately
+      if (!(result instanceof Promise)) return result;
+
+      // Promise path: spin up a worker to resolve it without blocking the
+      // main thread's event loop.
+      const { Worker } = require('worker_threads');
+
+      // Shared memory layout (Int32Array, 3 slots):
+      //   [0]  flag:   0=pending, 1=resolved, 2=rejected
+      //   [1-2] unused (value is passed via a separate Buffer)
+      const sab = new SharedArrayBuffer(4);
+      const flag = new Int32Array(sab);
+
+      // We pass the resolved/rejected value as a JSON string through a
+      // larger shared buffer (up to 4 MB).  For values that can't be
+      // JSON-serialised we fall back to null.
+      const valueBufSize = 4 * 1024 * 1024; // 4 MB
+      const valueSab = new SharedArrayBuffer(valueBufSize + 4); // +4 for length prefix
+      const valueMeta = new Int32Array(valueSab, 0, 1);  // [0] = byte length
+      const valueData = new Uint8Array(valueSab, 4);     // rest = UTF-8 bytes
+
+      // Inline worker script — keeps everything self-contained, no extra file.
+      const workerSrc = `
+const { workerData, parentPort } = require('worker_threads');
+const { sab, valueSab, promiseSrc } = workerData;
+const flag      = new Int32Array(sab);
+const valueMeta = new Int32Array(valueSab, 0, 1);
+const valueData = new Uint8Array(valueSab, 4);
+
+// Reconstruct the Promise from its serialised form.
+// The main thread serialises the promise via a tiny wrapper function source.
+let p;
+try { p = eval('(' + promiseSrc + ')')(); } catch(e) { p = Promise.reject(e); }
+
+p.then((v) => {
+  try {
+    const json = JSON.stringify(v === undefined ? null : v);
+    const bytes = Buffer.from(json, 'utf8');
+    const len   = Math.min(bytes.length, valueData.length);
+    bytes.copy(Buffer.from(valueData.buffer, valueData.byteOffset), 0, 0, len);
+    Atomics.store(valueMeta, 0, len);
+    Atomics.store(flag, 0, 1);
+    Atomics.notify(flag, 0);
+  } catch(e) {
+    Atomics.store(valueMeta, 0, 0);
+    Atomics.store(flag, 0, 1);
+    Atomics.notify(flag, 0);
+  }
+}).catch((e) => {
+  try {
+    const msg = e && e.message ? e.message : String(e);
+    const bytes = Buffer.from(JSON.stringify(msg), 'utf8');
+    const len   = Math.min(bytes.length, valueData.length);
+    bytes.copy(Buffer.from(valueData.buffer, valueData.byteOffset), 0, 0, len);
+    Atomics.store(valueMeta, 0, len);
+  } catch(_) { Atomics.store(valueMeta, 0, 0); }
+  Atomics.store(flag, 0, 2);
+  Atomics.notify(flag, 0);
+});
+`;
+      // We can't pass a live Promise across the worker boundary via structured
+      // clone (Promises aren't clonable).  Instead we wrap it in an immediately-
+      // invoked function string that the worker evals.  For our async nova
+      // functions the Promise is already resolving in the main thread's
+      // microtask queue — the worker just needs to `.then()` it, but that
+      // requires a reference.  Solution: we resolve the promise in the main
+      // thread itself via a bridge, and the worker just waits on the SAB.
+      //
+      // Bridge: attach .then/.catch in the main thread, write result to SAB.
+      // Worker is only used to give us a non-main-thread event loop for the
+      // Atomics.wait call.  The main thread does the actual resolution.
+      result.then((v) => {
+        try {
+          const json = JSON.stringify(v === undefined ? null : v);
+          const bytes = Buffer.from(json, 'utf8');
+          const len = Math.min(bytes.length, valueData.length);
+          bytes.copy(Buffer.from(valueData.buffer, valueData.byteOffset), 0, 0, len);
+          Atomics.store(valueMeta, 0, len);
+          Atomics.store(flag, 0, 1);
+          Atomics.notify(flag, 0);
+        } catch (_) {
+          Atomics.store(valueMeta, 0, 0);
+          Atomics.store(flag, 0, 1);
+          Atomics.notify(flag, 0);
+        }
+      }).catch((e) => {
+        try {
+          const msg = e && e.message ? e.message : String(e);
+          const bytes = Buffer.from(JSON.stringify(msg), 'utf8');
+          const len = Math.min(bytes.length, valueData.length);
+          bytes.copy(Buffer.from(valueData.buffer, valueData.byteOffset), 0, 0, len);
+          Atomics.store(valueMeta, 0, len);
+        } catch (_) { Atomics.store(valueMeta, 0, 0); }
+        Atomics.store(flag, 0, 2);
+        Atomics.notify(flag, 0);
+      });
+
+      // Spin up a minimal worker whose only job is to Atomics.wait so the
+      // main thread's call stack can unwind and drain microtasks.
+      // The worker itself does nothing but park; all the real work happens
+      // in the .then/.catch we attached above in the main thread.
+      const waiterSrc = `
+const { workerData } = require('worker_threads');
+const { sab } = workerData;
+const flag = new Int32Array(sab);
+// Park until the main thread signals resolution
+Atomics.wait(flag, 0, 0);
+// Done — worker exits, main thread was already notified via notify()
+`;
+      const waiter = new Worker(waiterSrc, {
+        eval: true,
+        workerData: { sab },
+      });
+
+      // Block main thread here — the .then() attached above fires in the same
+      // microtask queue because Atomics.wait in a Worker does NOT block the
+      // main thread event loop; only this synchronous call frame is suspended
+      // until Atomics.notify() fires from the .then().
+      Atomics.wait(flag, 0, 0);
+      waiter.terminate();
+
+      const status = Atomics.load(flag, 0);
+      const byteLen = Atomics.load(valueMeta, 0);
+      let parsed = null;
+      if (byteLen > 0) {
+        try {
+          const json = Buffer.from(valueData.buffer, valueData.byteOffset, byteLen).toString('utf8');
+          parsed = JSON.parse(json);
+        } catch (_) { parsed = null; }
+      }
+
+      if (status === 2) throw new Error(parsed || 'waitsync: async function rejected');
+      return parsed;
+    });
+
+    // ── awaitsync(promise) ────────────────────────────────────────────────
+    // Takes an already-created Promise (e.g. the return value of an async nova
+    // function call) and blocks synchronously until it resolves, then returns
+    // the resolved value.  This is the "top-level await" escape hatch for
+    // synchronous code that needs to wait on a promise it already has.
+    //
+    // Unlike waitsync() which calls a function, awaitsync() just waits on a
+    // value.  Non-Promise values pass straight through unchanged.
+    //
+    // Internally uses the same SAB+Worker bridge as waitsync so the main
+    // thread's microtask queue stays live during the wait.
+    this.globalScope.set('awaitsync', (promise) => {
+      if (!(promise instanceof Promise)) return promise;
+
+      const { Worker } = require('worker_threads');
+
+      const sab = new SharedArrayBuffer(4);
+      const flag = new Int32Array(sab);
+      const valueBufSize = 4 * 1024 * 1024;
+      const valueSab = new SharedArrayBuffer(valueBufSize + 4);
+      const valueMeta = new Int32Array(valueSab, 0, 1);
+      const valueData = new Uint8Array(valueSab, 4);
+
+      // Attach resolution handlers in the main thread — microtasks fire here
+      promise.then((v) => {
+        try {
+          const json = JSON.stringify(v === undefined ? null : v);
+          const bytes = Buffer.from(json, 'utf8');
+          const len = Math.min(bytes.length, valueData.length);
+          bytes.copy(Buffer.from(valueData.buffer, valueData.byteOffset), 0, 0, len);
+          Atomics.store(valueMeta, 0, len);
+          Atomics.store(flag, 0, 1);
+          Atomics.notify(flag, 0);
+        } catch (_) {
+          Atomics.store(valueMeta, 0, 0);
+          Atomics.store(flag, 0, 1);
+          Atomics.notify(flag, 0);
+        }
+      }).catch((e) => {
+        try {
+          const msg = e && e.message ? e.message : String(e);
+          const bytes = Buffer.from(JSON.stringify(msg), 'utf8');
+          const len = Math.min(bytes.length, valueData.length);
+          bytes.copy(Buffer.from(valueData.buffer, valueData.byteOffset), 0, 0, len);
+          Atomics.store(valueMeta, 0, len);
+        } catch (_) { Atomics.store(valueMeta, 0, 0); }
+        Atomics.store(flag, 0, 2);
+        Atomics.notify(flag, 0);
+      });
+
+      // Worker parks on the SAB; this unblocks the main thread event loop
+      // so the .then/.catch above can fire while we wait.
+      const waiterSrc = `
+const { workerData } = require('worker_threads');
+const flag = new Int32Array(workerData.sab);
+Atomics.wait(flag, 0, 0);
+`;
+      const waiter = new Worker(waiterSrc, { eval: true, workerData: { sab } });
+      Atomics.wait(flag, 0, 0);
+      waiter.terminate();
+
+      const status = Atomics.load(flag, 0);
+      const byteLen = Atomics.load(valueMeta, 0);
+      let parsed = null;
+      if (byteLen > 0) {
+        try {
+          const json = Buffer.from(valueData.buffer, valueData.byteOffset, byteLen).toString('utf8');
+          parsed = JSON.parse(json);
+        } catch (_) { parsed = null; }
+      }
+
+      if (status === 2) throw new Error(parsed || 'awaitsync: promise rejected');
+      return parsed;
+    });
+
+    // ── _processKitMod(mod) ───────────────────────────────────────────────
+    // Process a loaded kitdef.js module. Handles all recognised metadata fields:
+    //   kitdef    — namespace of values/functions to inject into scope (required)
+    //   events    — { eventName: handler } — register event listeners
+    //   dvars     — { name: fn() } — register custom dynamic variables
+    //   hooks     — { 'before:exec': fn, 'after:exec': fn, ... }
+    //   constants — { NAME: value } — inject as frozen scope constants
+    //   aliases   — { alias: existingName } — create name aliases in scope
+    //   init      — fn() — called once when kit is loaded
+    //   teardown  — fn() — registered for process exit
+    //   namespace — string — wrap kitdef under this namespace name
+    //   commands  — { name: fn } — register as nova dot-commands
+    //   types     — { TypeName: validator } — register custom types
+    //   config    — { key: defaultValue } — merge into nova.config
+    //   docs      — { name: string } — documentation strings (meta only)
+    //   meta      — arbitrary metadata object (stored, not executed)
+    //   on        — alias for events
+    //   provides  — string[] — feature flags this kit provides (informational)
+    //   setup     — alias for init
+    //   macros    — { NAME: value } — register as nova macros
+    //   filters   — { name: fn } — register filter functions in scope
+    //   transforms — { name: fn } — register transform functions in scope
+    //   validators — { name: fn } — register validator functions in scope
+    //   decorators — { name: fn } — register decorator functions in scope
+    //   schemas    — { name: schemaDef } — register schema objects in scope
+    //   reducers   — { name: fn } — register reducer functions in scope
+    //   effects    — { name: fn } — register effect functions in scope
+    //   plugins    — [ fn ] — call each plugin(executor) at load time
+    //   guards     — { name: fn } — register guard functions in scope
+    //   interceptors — { name: fn } — register interceptor functions in scope
+    //   tasks      — { name: fn } — register named tasks in scope
+    //   jobs       — alias for tasks
+    //   routes     — { pattern: fn } — register router routes
+    //   handlers   — { name: fn } — register named handler functions in scope
+    //   services   — { name: obj } — register service objects in scope
+    //   resources  — { name: value } — register named resources in scope
+    //   middleware — [ fn ] — register middleware array (stored under kit name)
+    //   permissions — string[] — declared permissions (informational)
+    //   dependencies — string[] — kit dependencies (informational)
+    //   exports    — object — additional exports (merged same as kitdef)
+    //   namespace  — when a string, wraps the kitdef namespace under that name
+    this._processKitMod = (mod, kitName) => {
+      if (!mod || typeof mod !== 'object') return;
+
+      const ns = mod.kitdef || {};
+
+      // Determine injection namespace
+      const nsName = typeof mod.namespace === 'string' ? mod.namespace : null;
+      if (nsName) {
+        // Wrap under namespace
+        _self.globalScope.set(nsName, new NovaObject({ ...ns }));
+        _self.namespaces.set(nsName, ns);
+      } else {
+        for (const [k, v] of Object.entries(ns)) _self.globalScope.set(k, v);
+      }
+
+      // exports — additional names to inject
+      if (mod.exports && typeof mod.exports === 'object') {
+        for (const [k, v] of Object.entries(mod.exports)) _self.globalScope.set(k, v);
+      }
+
+      // constants — injected as scope constants
+      const consts = mod.constants || {};
+      for (const [k, v] of Object.entries(consts)) {
+        _self.globalScope.set(k, v, true); // isConst=true
+      }
+
+      // aliases — { alias: existingName }
+      const aliases = mod.aliases || {};
+      for (const [alias, target] of Object.entries(aliases)) {
+        const val = _self.globalScope.get(target);
+        if (val !== null && val !== undefined) _self.globalScope.set(alias, val);
+      }
+
+      // events / on — { eventName: handler | handler[] }
+      const evMap = mod.events || mod.on || {};
+      for (const [evName, handler] of Object.entries(evMap)) {
+        const handlers = Array.isArray(handler) ? handler : [handler];
+        for (const h of handlers) {
+          if (typeof h === 'function') {
+            if (!_self.eventBus.has(evName)) _self.eventBus.set(evName, []);
+            _self.eventBus.get(evName).push({ body: null, _native: h });
+          }
+        }
+      }
+
+      // dvars — { varName: fn() } — custom dynamic variables
+      // Stored globally; resolved in the 'dvar' evaluate case via _customDvars map.
+      const dvars = mod.dvars || {};
+      if (!_self._customDvars) _self._customDvars = new Map();
+      for (const [dname, dfn] of Object.entries(dvars)) {
+        if (typeof dfn === 'function') _self._customDvars.set(dname, dfn);
+      }
+
+      // macros — { NAME: value }
+      const macros = mod.macros || {};
+      for (const [mname, mval] of Object.entries(macros)) {
+        _self.macros.set(mname, mval);
+        _self.globalScope.set(mname, mval);
+      }
+
+      // commands — { name: fn } — nova dot-commands
+      const cmds = mod.commands || {};
+      for (const [cname, cfn] of Object.entries(cmds)) {
+        if (typeof cfn === 'function') _self.dot_commands[cname] = cfn;
+      }
+
+      // types — { TypeName: validator } — register custom named types
+      const types = mod.types || {};
+      for (const [tname, tval] of Object.entries(types)) {
+        if (typeof tval === 'function') {
+          _self.types.registerType(tname, { name: tname, kind: 'custom', check: tval });
+          _self.globalScope.set(tname, tval);
+        }
+      }
+
+      // filters, transforms, validators, decorators, reducers, effects,
+      // guards, interceptors, tasks/jobs, handlers, services, resources,
+      // schemas — all injected as plain named functions/objects in scope
+      const injectGroups = [
+        'filters', 'transforms', 'validators', 'decorators', 'reducers', 'effects',
+        'guards', 'interceptors', 'handlers', 'services', 'resources', 'schemas',
+      ];
+      for (const group of injectGroups) {
+        const g = mod[group] || {};
+        for (const [k, v] of Object.entries(g)) _self.globalScope.set(k, v);
+      }
+
+      // tasks and jobs (aliases)
+      const tasks = { ...(mod.tasks || {}), ...(mod.jobs || {}) };
+      for (const [k, v] of Object.entries(tasks)) _self.globalScope.set(k, v);
+
+      // routes — register via nova's Router if one is active; otherwise just inject
+      const routes = mod.routes || {};
+      for (const [pattern, handler] of Object.entries(routes)) {
+        _self.globalScope.set('__route_' + pattern.replace(/[^a-zA-Z0-9]/g, '_'), handler);
+      }
+
+      // middleware — stored as array under kit name
+      if (Array.isArray(mod.middleware)) {
+        const mwKey = (kitName || 'kit') + ':middleware';
+        _self.globalScope.set(mwKey, new NovaArray(mod.middleware));
+      }
+
+      // plugins — called with executor at load time
+      if (Array.isArray(mod.plugins)) {
+        for (const plugin of mod.plugins) {
+          if (typeof plugin === 'function') {
+            try { plugin(_self); } catch (e) { /* plugin errors are non-fatal */ }
+          }
+        }
+      }
+
+      // init / setup — called once at load time
+      const initFn = mod.init || mod.setup;
+      if (typeof initFn === 'function') {
+        try { initFn(_self); } catch (_) { }
+      }
+
+      // teardown — called at process exit
+      const teardownFn = mod.teardown;
+      if (typeof teardownFn === 'function') {
+        process.on('exit', () => { try { teardownFn(); } catch (_) { } });
+      }
+
+      // meta / docs / provides / permissions / dependencies — informational only
+      // Stored on the executor for inspection via nova.kitMeta
+      if (!_self._kitMeta) _self._kitMeta = {};
+      if (kitName) {
+        _self._kitMeta[kitName] = {
+          meta: mod.meta || null,
+          docs: mod.docs || null,
+          provides: mod.provides || [],
+          permissions: mod.permissions || [],
+          dependencies: mod.dependencies || [],
+          config: mod.config || null,
+        };
+      }
+    };
+
+    // ── include(path) ────────────────────────────────────────────────────
+    // Shorthand for `import "path"`.  Runs the file in the current scope and
+    // merges any exported names directly into it (same as a bare import).
+    // Accepts .nova / .nv (parsed + executed) or .js (require()'d as a JS kit).
+    this.globalScope.set('include', (filePath) => {
+      const _fs = require('fs');
+      const _pth = require('path');
+      const src = String(filePath);
+      const abs = _pth.isAbsolute(src)
+        ? src
+        : _pth.resolve(process.cwd(), src);
+
+      if (src.endsWith('.js')) {
+        // JS file — require it and merge exported keys into global scope
+        const mod = require(abs);
+        if (mod && typeof mod === 'object' && (mod.kitdef || mod.events || mod.dvars || mod.init)) {
+          // Looks like a kit module — process all metadata fields
+          _self._processKitMod(mod, _pth.basename(abs, '.js'));
+        } else if (mod && typeof mod === 'object') {
+          const ns = mod.kitdef || mod;
+          for (const [k, v] of Object.entries(ns)) _self.globalScope.set(k, v);
+        }
+        return mod;
+      }
+
+      // Nova file — parse and run in a module scope, then merge exports
+      const content = _fs.readFileSync(abs, 'utf8');
+      const moduleScope = new Scope('module', null, _self.globalScope);
+      const exports = {};
+      _self.moduleExportsStack.push(exports);
+      try {
+        const { Parser } = require('./parser');
+        _self.run(new Parser(content).parse(), moduleScope);
+      } catch (e) {
+        if (!(e && '__return' in e)) throw e;
+      } finally {
+        _self.moduleExportsStack.pop();
+      }
+      // Merge all module-scope variables + any explicit exports into caller scope
+      for (const [k, v] of Object.entries(moduleScope.variables)) {
+        _self.globalScope.set(k, v);
+      }
+      for (const [k, v] of Object.entries(exports)) {
+        _self.globalScope.set(k, v);
+      }
+      return exports;
+    });
+
+    // ── includeKit(kitName) ──────────────────────────────────────────────
+    // Loads a kit from ../../kits/<kitName>/kitdef.js (relative to executor.js),
+    // falling back to index.nova if no kitdef.js exists.
+    // The kit's exported namespace is merged into global scope AND returned.
+    this.globalScope.set('includeKit', (kitName) => {
+      const _fs = require('fs');
+      const _pth = require('path');
+      const name = String(kitName);
+      const kitsRoot = _pth.join(__dirname, '..', '..', 'kits');
+      const kitDir = _pth.join(kitsRoot, name);
+
+      if (!_fs.existsSync(kitDir)) {
+        throw new Error(`includeKit: kit "${name}" not found at ${kitDir}`);
+      }
+
+      const kitdefPath = _pth.join(kitDir, 'kitdef.js');
+      const indexNova = _pth.join(kitDir, 'index.nova');
+      const indexNv = _pth.join(kitDir, 'index.nv');
+
+      if (_fs.existsSync(kitdefPath)) {
+        // JS kit — load via require and process all metadata fields
+        const mod = require(kitdefPath);
+        if (!mod || !mod.kitdef) throw new Error(`includeKit: "${name}/kitdef.js" must export { kitdef }`);
+        return new NovaObject(mod.kitdef);
+      }
+
+      // Nova kit entry point
+      const novaEntry = _fs.existsSync(indexNova) ? indexNova : (_fs.existsSync(indexNv) ? indexNv : null);
+      if (!novaEntry) {
+        throw new Error(`includeKit: kit "${name}" has no kitdef.js, index.nova, or index.nv`);
+      }
+      const content = _fs.readFileSync(novaEntry, 'utf8');
+      const moduleScope = new Scope('module', null, _self.globalScope);
+      const exports = {};
+      _self.moduleExportsStack.push(exports);
+      try {
+        const { Parser } = require('./parser');
+        _self.run(new Parser(content).parse(), moduleScope);
+      } catch (e) {
+        if (!(e && '__return' in e)) throw e;
+      } finally {
+        _self.moduleExportsStack.pop();
+      }
+      for (const [k, v] of Object.entries(moduleScope.variables)) _self.globalScope.set(k, v);
+      for (const [k, v] of Object.entries(exports)) _self.globalScope.set(k, v);
+      return exports;
+    });
+
+    // ── print(...args) ───────────────────────────────────────────────────
+    // Top-level shorthand for core.print — prints all args space-separated.
+    this.globalScope.set('print', (...args) => {
+      process.stdout.write(args.map(a => _self.stringify(a)).join(' ') + '\n');
+      return '';
+    });
+
+    this.globalScope.set('printr', (...args) => {
+      process.stdout.write(args.join(' ') + '\n');
+      return '';
+    });
+
+    this.globalScope.set('eprintr', (...args) => {
+      process.stderr.write(args.join(' ') + '\n');
+      return '';
+    });
+
+    // ── println(...args) / eprint(...args) ──────────────────────────────
+    this.globalScope.set('println', (...args) => {
+      process.stdout.write(args.map(a => _self.stringify(a)).join(' ') + '\n');
+      return '';
+    });
+    this.globalScope.set('eprint', (...args) => {
+      process.stderr.write(args.map(a => _self.stringify(a)).join(' ') + '\n');
+      return '';
+    });
+
+    // ── dump(value) ──────────────────────────────────────────────────────
+    // Pretty-prints a value with type info — useful for debugging.
+    this.globalScope.set('dump', (v) => {
+      const type = _self._typeOf(v);
+      const str = _self.stringify(v);
+      process.stdout.write(`[${type}] ${str}\n`);
+      return v;
+    });
+
+    this.globalScope.set('Promise', Promise);
+
+    // ── ensure(cond, msg?) ───────────────────────────────────────────────
+    // Like assert but callable as a function (the `assert` keyword is reserved
+    // for the nova assert statement).
+    this.globalScope.set('ensure', (cond, msg) => {
+      const raw = cond instanceof NovaBool ? cond.valueOf() : cond;
+      if (!raw) throw new Error('Assertion failed' + (msg ? ': ' + String(msg) : ''));
+      return true;
+    });
+
+    // ── range(start, end, step?) ─────────────────────────────────────────
+    // Returns a NovaArray of numbers.  Matches Python range() semantics.
+    this.globalScope.set('range', (start, end, step) => {
+      const s = Number(start), e = Number(end), st = step !== undefined ? Number(step) : 1;
+      if (st === 0) throw new Error('range: step cannot be 0');
+      const out = [];
+      if (st > 0) { for (let i = s; i < e; i += st) out.push(i); }
+      else { for (let i = s; i > e; i += st) out.push(i); }
+      return new NovaArray(out);
+    });
+
+    // ── sleep(ms) ────────────────────────────────────────────────────────
+    // Sync sleep using Atomics — same as the wait_stmt implementation.
+    this.globalScope.set('sleep', (ms) => {
+      try {
+        const sab = new SharedArrayBuffer(4);
+        Atomics.wait(new Int32Array(sab), 0, 0, Number(ms));
+      } catch {
+        require('child_process').execSync(`node -e "setTimeout(()=>{},${Number(ms)})"`, { timeout: Number(ms) + 5000 });
+      }
+    });
+
+    // ── env(key?, fallback?) ─────────────────────────────────────────────
+    // Read process environment variables.  env() returns full env object,
+    // env("KEY") returns that var (or null), env("KEY", "default") with fallback.
+    this.globalScope.set('env', (key, fallback) => {
+      if (key === undefined) return new NovaObject({ ...process.env });
+      const val = process.env[String(key)];
+      return val !== undefined ? val : (fallback !== undefined ? fallback : null);
+    });
+
+    // ── args() ───────────────────────────────────────────────────────────
+    // Returns the CLI arguments passed after the script name as a NovaArray.
+    this.globalScope.set('args', () => new NovaArray(process.argv.slice(2)));
+
+    // ── exit(code?) ──────────────────────────────────────────────────────
+    this.globalScope.set('exit', (code) => process.exit(Number(code ?? 0)));
+
+    // ── parseInt / parseFloat / isNaN / isFinite ─────────────────────────
+    // Expose JS globals directly so Nova scripts can use them without prefix.
+    this.globalScope.set('parseInt', (v, radix) => parseInt(String(v), radix));
+    this.globalScope.set('parseFloat', (v) => parseFloat(String(v)));
+    this.globalScope.set('isNaN', (v) => isNaN(v));
+    this.globalScope.set('isFinite', (v) => isFinite(v));
+
+    // ── keys(obj) / values(obj) / entries(obj) ──────────────────────────
+    this.globalScope.set('keys', (o) => {
+      const raw = o instanceof NovaObject ? o.inner : o;
+      return new NovaArray(Object.keys(raw ?? {}));
+    });
+    this.globalScope.set('values', (o) => {
+      const raw = o instanceof NovaObject ? o.inner : o;
+      return new NovaArray(Object.values(raw ?? {}));
+    });
+    this.globalScope.set('entries', (o) => {
+      const raw = o instanceof NovaObject ? o.inner : o;
+      return new NovaArray(Object.entries(raw ?? {}).map(([k, v]) => new NovaArray([k, v])));
+    });
+
+    // ── Wasm ──────────────────────────────────────────────────────────────
+    // Wasm object with many methods
+    this.globalScope.set('Wasm', {
+      run: async (bytes, imports) => {
+        const module = await WebAssembly.compile(bytes instanceof NovaArray ? new Uint8Array(bytes.inner) : bytes);
+        const instance = await WebAssembly.instantiate(module, imports instanceof NovaObject ? imports.inner : imports);
+        if (instance.exports && typeof instance.exports._start === 'function') {
+          return instance.exports._start();
+        }
+        return instance;
+      },
+      ...WebAssembly, // re-export all WebAssembly static methods/properties
+    })
+    // ── len(v) ───────────────────────────────────────────────────────────
+    this.globalScope.set('len', (v) => {
+      if (v instanceof NovaArray) return v.length;
+      if (v instanceof NovaObject) return Object.keys(v.inner).length;
+      if (typeof v === 'string') return v.length;
+      if (v && v.length !== undefined) return v.length;
+      return 0;
+    });
+    // ── new WaiterObject() ───────────────────────────────────────────────────
+    // Expose the WaiterObject class so Nova scripts can create waiters directly.
+    class WaiterObject { // a waiter is an object like this: { state: Int, value: any }
+      constructor() {
+        this._state = 0; // 0 = pending, 1 = resolved, 2 = rejected
+        this.value = null;
+        this.onStateChange = (newState) => newState; // override this to react to state changes
+      }
+      get state() { return this._state; }
+      set state(v) { this._state = this.onStateChange(Number(v)); }
+    }
+    this.globalScope.set('WaiterObject', WaiterObject);
+    // ── new Mutex() ───────────────────────────────────────────────────────────
+    // Expose a simple Mutex class for mutual exclusion in async code.
+    class Mutex {
+      constructor(...waiters) {
+        this._locked = false;
+        this._waiters = waiters;
+      }
+      lock() {
+        if (!this._locked) {
+          this._locked = true;
+          return Promise.resolve();
+        }
+        return new Promise(resolve => this._waiters.push(resolve));
+      }
+      unlock() {
+        if (this._waiters.length > 0) {
+          const next = this._waiters.shift();
+          next();
+        } else {
+          this._locked = false;
+        }
+      }
+    }
+    this.globalScope.set('Mutex', Mutex);
+    // ── typeOf_(v) ───────────────────────────────────────────────────────
+    // Returns a string type name for any nova value.
+    // Named typeOf_ to avoid collision with the `type` keyword (type declarations).
+    // Note: `typeOf` (no underscore) is already registered above as a type intrinsic.
+    this.globalScope.set('typeOf_', (v) => _self._typeOf(v));
+
+    // ── str(v) / num(v) / bool(v) ────────────────────────────────────────
+    this.globalScope.set('str', (v) => _self.stringify(v));
+    this.globalScope.set('num', (v) => Number(v instanceof NovaValue ? v.valueOf() : v));
+    this.globalScope.set('bool', (v) => {
+      const raw = v instanceof NovaBool ? v.valueOf() : v;
+      return !!raw;
+    });
+
+    // ── clamp(val, min, max) ─────────────────────────────────────────────
+    this.globalScope.set('clamp', (v, lo, hi) => Math.min(Math.max(Number(v), Number(lo)), Number(hi)));
+
+    // ── zipArrays(...arrays) ─────────────────────────────────────────────
+    // Like Python zip() — pairs elements across arrays into a NovaArray of NovaArrays.
+    // Named zipArrays to avoid collision with nova's infix `zip` operator.
+    this.globalScope.set('zipArrays', (...arrays) => {
+      const arrs = arrays.map(a => a instanceof NovaArray ? a.inner : a);
+      const len = Math.min(...arrs.map(a => a.length));
+      const out = [];
+      for (let i = 0; i < len; i++) out.push(new NovaArray(arrs.map(a => a[i])));
+      return new NovaArray(out);
+    });
+
+    // ── flat(arr, depth?) ────────────────────────────────────────────────
+    this.globalScope.set('flat', (arr, depth) => {
+      const raw = arr instanceof NovaArray ? arr.inner : arr;
+      return new NovaArray(raw.flat(depth !== undefined ? Number(depth) : 1));
+    });
+
+    // ── unique(arr) ──────────────────────────────────────────────────────
+    this.globalScope.set('unique', (arr) => {
+      const raw = arr instanceof NovaArray ? arr.inner : arr;
+      return new NovaArray([...new Set(raw)]);
+    });
+
+    // ── sum(arr) / minimum(arr) / maximum(arr) / average(arr) ──────────────
+    // sum works fine; min/max use variadic form that avoids keyword issues.
+    // avg is a nova infix operator so we expose it as average().
+    this.globalScope.set('sum', (arr) => {
+      const raw = arr instanceof NovaArray ? arr.inner : arr;
+      return raw.reduce((a, b) => a + Number(b), 0);
+    });
+    this.globalScope.set('min', (...args) => {
+      if (args.length === 1 && (args[0] instanceof NovaArray || Array.isArray(args[0]))) {
+        const raw = args[0] instanceof NovaArray ? args[0].inner : args[0];
+        return Math.min(...raw.map(Number));
+      }
+      return Math.min(...args.map(Number));
+    });
+    this.globalScope.set('max', (...args) => {
+      if (args.length === 1 && (args[0] instanceof NovaArray || Array.isArray(args[0]))) {
+        const raw = args[0] instanceof NovaArray ? args[0].inner : args[0];
+        return Math.max(...raw.map(Number));
+      }
+      return Math.max(...args.map(Number));
+    });
+    this.globalScope.set('average', (arr) => {
+      const raw = arr instanceof NovaArray ? arr.inner : arr;
+      if (!raw.length) return 0;
+      return raw.reduce((a, b) => a + Number(b), 0) / raw.length;
+    });
+
+    // ══════════════════════════════════════════════════════════════════════
+    // ── SCOPE UTILITIES ──────────────────────────────────────────────────
+    // ══════════════════════════════════════════════════════════════════════
+
+    // ── deepClone(value) ─────────────────────────────────────────────────
+    // Recursively clones any Nova value into a structurally identical but
+    // fully independent copy.  Handles circular refs via a WeakMap.
+    const _deepClone = (v, seen = new WeakMap()) => {
+      if (v === null || v === undefined) return v;
+      const t = typeof v;
+      if (t === 'number' || t === 'string' || t === 'boolean' || t === 'bigint') return v;
+      if (t === 'function') return v; // functions are immutable — share reference
+      if (t === 'symbol') return v;
+      if (t !== 'object') return v;
+      if (seen.has(v)) return seen.get(v);
+      if (v instanceof NovaBool) return new NovaBool(v.valueOf());
+      if (v instanceof NovaNull) return new NovaNull();
+      if (v instanceof NovaNumber) return new NovaNumber(v.valueOf());
+      if (v instanceof NovaString) return new NovaString(v.valueOf());
+      if (v instanceof NovaRange) return new NovaRange(v.start, v.end, v.step);
+      if (v instanceof NovaPointer) return new NovaPointer(_deepClone(v.inner, seen), v.readFn, v.writeFn, v.address);
+      if (v instanceof NovaEnum) { const e = new NovaEnum(v.typeName, v.variant, _deepClone(v.inner, seen)); e.value = _deepClone(v.value, seen); return e; }
+      if (v instanceof NovaStruct) {
+        const inner = {};
+        seen.set(v, inner); // register early to handle circular refs
+        for (const [k, val] of Object.entries(v.inner)) inner[k] = _deepClone(val, seen);
+        const s = new NovaStruct(v.typeName, inner);
+        seen.set(v, s);
+        return s;
+      }
+      if (v instanceof NovaArray) {
+        const placeholder = new NovaArray([]);
+        seen.set(v, placeholder);
+        placeholder.inner = v.inner.map(x => _deepClone(x, seen));
+        return placeholder;
+      }
+      if (v instanceof NovaObject) {
+        const placeholder = new NovaObject({});
+        seen.set(v, placeholder);
+        for (const [k, val] of Object.entries(v.inner)) placeholder.inner[k] = _deepClone(val, seen);
+        return placeholder;
+      }
+      if (v instanceof Scope) {
+        // Clone a Scope — see saveCurrentScope below
+        const cloned = new Scope(v.kind, v.parent, v.globalScope);
+        seen.set(v, cloned);
+        for (const [k, val] of Object.entries(v.variables)) {
+          if (k === 'scope' || k === 'array') continue;
+          cloned.variables[k] = _deepClone(val, seen);
+        }
+        for (const k of Object.keys(v.consts)) cloned.consts[k] = cloned.variables[k];
+        return cloned;
+      }
+      // Plain JS object / AST node
+      if (Array.isArray(v)) {
+        const arr = [];
+        seen.set(v, arr);
+        for (const x of v) arr.push(_deepClone(x, seen));
+        return arr;
+      }
+      const out = {};
+      seen.set(v, out);
+      for (const [k, val] of Object.entries(v)) out[k] = _deepClone(val, seen);
+      return out;
+    };
+    _self._deepClone = _deepClone;
+    this.globalScope.set('deepClone', (v) => _deepClone(v));
+
+    // ── shallowClone(value) ───────────────────────────────────────────────
+    // One-level clone — top container is new but inner values are shared.
+    this.globalScope.set('shallowClone', (v) => {
+      if (v instanceof NovaArray) return new NovaArray([...v.inner]);
+      if (v instanceof NovaObject) return new NovaObject({ ...v.inner });
+      if (v instanceof NovaStruct) return new NovaStruct(v.typeName, { ...v.inner });
+      if (Array.isArray(v)) return [...v];
+      if (v && typeof v === 'object') return { ...v };
+      return v;
+    });
+
+    // ── saveCurrentScope() ───────────────────────────────────────────────
+    // Returns a deep-cloned, fully independent copy of the current global
+    // scope (all user-defined variables).  The clone is a live Scope object
+    // you can pass to scopeEnter / scopeExec.
+    // NOTE: called as a zero-arg function; the scope at call-time is the
+    // executor's globalScope since Nova scripts can't pass their own scope ref.
+    this.globalScope.set('saveCurrentScope', () => {
+      const snap = new Scope('saved', null, _self.globalScope);
+      const SKIP = new Set(['scope', 'array', 'std', 'globalScope', 'parent']);
+      for (const [k, v] of Object.entries(_self.globalScope.variables)) {
+        if (SKIP.has(k)) continue;
+        try { snap.variables[k] = _deepClone(v); } catch { snap.variables[k] = v; }
+      }
+      for (const k of Object.keys(_self.globalScope.consts)) {
+        if (!SKIP.has(k) && snap.variables.hasOwnProperty(k)) snap.consts[k] = snap.variables[k];
+      }
+      return snap;
+    });
+
+    // ── saveScope(scope) ─────────────────────────────────────────────────
+    // Like saveCurrentScope() but the caller chooses which Scope to clone.
+    // Accepts any Scope object (e.g. one returned by scopeNew, scopeChain,
+    // scopeParent, or a previously saved scope) and returns a fully
+    // independent deep-cloned copy — changes to either one never affect
+    // the other.
+    this.globalScope.set('saveScope', (scope) => {
+      if (!(scope instanceof Scope))
+        throw new Error('saveScope: argument must be a Scope (got ' + _self._typeOf(scope) + ')');
+      const snap = new Scope('saved', null, _self.globalScope);
+      const SKIP = new Set(['scope', 'array', 'std', 'globalScope', 'parent']);
+      for (const [k, v] of Object.entries(scope.variables)) {
+        if (SKIP.has(k)) continue;
+        try { snap.variables[k] = _deepClone(v); } catch { snap.variables[k] = v; }
+      }
+      for (const k of Object.keys(scope.consts)) {
+        if (!SKIP.has(k) && snap.variables.hasOwnProperty(k)) snap.consts[k] = snap.variables[k];
+      }
+      return snap;
+    });
+
+    // ── scopeSnapshot(scope?) ─────────────────────────────────────────────
+    // Returns a plain NovaObject snapshot (key→value) of the given scope or
+    // the current global scope.  Good for inspection / serialization.
+    this.globalScope.set('scopeSnapshot', (scope) => {
+      const src = (scope instanceof Scope) ? scope : _self.globalScope;
+      const SKIP = new Set(['scope', 'array', 'std', 'globalScope', 'parent']);
+      const out = {};
+      for (const [k, v] of Object.entries(src.variables)) {
+        if (SKIP.has(k)) continue;
+        try { out[k] = _deepClone(v); } catch { out[k] = v; }
+      }
+      return new NovaObject(out);
+    });
+
+    // ── scopeEnter(scope) ────────────────────────────────────────────────
+    // Replaces the executor's globalScope with the given scope so that all
+    // subsequent variable lookups / assignments happen in that context.
+    // Returns the previous scope so you can restore it.
+    this.globalScope.set('scopeEnter', (scope) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeEnter: argument must be a Scope');
+      const prev = _self.globalScope;
+      _self.globalScope = scope;
+      return prev;
+    });
+
+    // ── scopeExit(savedScope) ────────────────────────────────────────────
+    // Restore a previously saved scope (the value returned by scopeEnter).
+    this.globalScope.set('scopeExit', (prev) => {
+      if (!(prev instanceof Scope)) throw new Error('scopeExit: argument must be a Scope');
+      _self.globalScope = prev;
+      return prev;
+    });
+
+    // ── scopeExec(scope, fn) ─────────────────────────────────────────────
+    // Run fn() with globalScope temporarily swapped to scope, then restore.
+    // Returns fn's return value.  Safe even if fn throws.
+    this.globalScope.set('scopeExec', (scope, fn) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeExec: first arg must be a Scope');
+      const prev = _self.globalScope;
+      _self.globalScope = scope;
+      try {
+        if (typeof fn === 'function') return fn();
+        if (fn && fn.body !== undefined) return _self.runFunctionNode(fn, scope, []);
+      } finally {
+        _self.globalScope = prev;
+      }
+    });
+
+    // ── scopeNew(parent?) ─────────────────────────────────────────────────
+    // Create a fresh empty child scope.  parent defaults to globalScope.
+    this.globalScope.set('scopeNew', (parent) => {
+      const p = (parent instanceof Scope) ? parent : _self.globalScope;
+      return new Scope('user', p, _self.globalScope);
+    });
+
+    // ── scopeMerge(target, source) ───────────────────────────────────────
+    // Copy all user variables from source into target (shallow).
+    this.globalScope.set('scopeMerge', (target, source) => {
+      if (!(target instanceof Scope) || !(source instanceof Scope))
+        throw new Error('scopeMerge: both args must be Scopes');
+      const SKIP = new Set(['scope', 'array', 'std', 'globalScope', 'parent']);
+      for (const [k, v] of Object.entries(source.variables)) {
+        if (SKIP.has(k)) continue;
+        target.variables[k] = v;
+      }
+      return target;
+    });
+
+    // ── scopeGet(scope, name) ─────────────────────────────────────────────
+    // Read a variable from any scope by name.
+    this.globalScope.set('scopeGet', (scope, name) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeGet: first arg must be a Scope');
+      return scope.get(String(name));
+    });
+
+    // ── scopeSet(scope, name, value) ─────────────────────────────────────
+    // Write a variable into any scope by name.
+    this.globalScope.set('scopeSet', (scope, name, value) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeSet: first arg must be a Scope');
+      scope.set(String(name), value);
+      return value;
+    });
+
+    // ── scopeHas(scope, name) ─────────────────────────────────────────────
+    // Check whether a variable exists in scope (own variables only).
+    this.globalScope.set('scopeHas', (scope, name) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeHas: first arg must be a Scope');
+      return scope.has(String(name));
+    });
+
+    // ── scopeDelete(scope, name) ──────────────────────────────────────────
+    // Remove a variable from a scope.
+    this.globalScope.set('scopeDelete', (scope, name) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeDelete: first arg must be a Scope');
+      scope.delete(String(name));
+    });
+
+    // ── scopeKeys(scope) ─────────────────────────────────────────────────
+    // List all user-defined variable names in a scope (own only).
+    this.globalScope.set('scopeKeys', (scope) => {
+      const src = (scope instanceof Scope) ? scope : _self.globalScope;
+      const SKIP = new Set(['scope', 'array', 'std', 'globalScope', 'parent']);
+      return new NovaArray(Object.keys(src.variables).filter(k => !SKIP.has(k)));
+    });
+
+    // ── scopeParent(scope) ───────────────────────────────────────────────
+    // Return the parent scope of a given scope.
+    this.globalScope.set('scopeParent', (scope) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeParent: arg must be a Scope');
+      return scope.parent ?? null;
+    });
+
+    // ── scopeDepth(scope) ────────────────────────────────────────────────
+    // How many parents deep is this scope from a root (no parent)?
+    this.globalScope.set('scopeDepth', (scope) => {
+      if (!(scope instanceof Scope)) return 0;
+      let d = 0, cur = scope;
+      while (cur.parent) { d++; cur = cur.parent; }
+      return d;
+    });
+
+    // ── scopeChain(scope) ────────────────────────────────────────────────
+    // Returns a NovaArray of all scopes from this one up to the root.
+    this.globalScope.set('scopeChain', (scope) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeChain: arg must be a Scope');
+      const chain = [];
+      let cur = scope;
+      while (cur) { chain.push(cur); cur = cur.parent; }
+      return new NovaArray(chain);
+    });
+
+    // ── currentScope() ───────────────────────────────────────────────────
+    // Returns the executor's current globalScope reference.
+    this.globalScope.set('currentScope', () => _self.globalScope);
+
+    // ── freezeScope(scope) ───────────────────────────────────────────────
+    // Freeze all current variables in scope as constants (no further writes).
+    this.globalScope.set('freezeScope', (scope) => {
+      const src = (scope instanceof Scope) ? scope : _self.globalScope;
+      const SKIP = new Set(['scope', 'array', 'std', 'globalScope', 'parent']);
+      for (const k of Object.keys(src.variables)) {
+        if (!SKIP.has(k)) src.consts[k] = src.variables[k];
+      }
+      return src;
+    });
+
+    // ── scopeDiff(scopeA, scopeB) ─────────────────────────────────────────
+    // Returns a NovaObject describing keys that differ between two scopes:
+    //   { onlyInA: [...], onlyInB: [...], different: [...] }
+    this.globalScope.set('scopeDiff', (a, b) => {
+      if (!(a instanceof Scope) || !(b instanceof Scope))
+        throw new Error('scopeDiff: both args must be Scopes');
+      const SKIP = new Set(['scope', 'array', 'std', 'globalScope', 'parent']);
+      const keysA = new Set(Object.keys(a.variables).filter(k => !SKIP.has(k)));
+      const keysB = new Set(Object.keys(b.variables).filter(k => !SKIP.has(k)));
+      const onlyInA = [...keysA].filter(k => !keysB.has(k));
+      const onlyInB = [...keysB].filter(k => !keysA.has(k));
+      const different = [];
+      for (const k of keysA) {
+        if (keysB.has(k) && a.variables[k] !== b.variables[k]) different.push(k);
+      }
+      return new NovaObject({
+        onlyInA: new NovaArray(onlyInA),
+        onlyInB: new NovaArray(onlyInB),
+        different: new NovaArray(different),
+      });
+    });
+
+    // ── scopeWatch(scope, name, fn) ───────────────────────────────────────
+    // Install a getter/setter descriptor on scope.variables[name] that calls
+    // fn(newValue, oldValue) on every write.  Returns an unwatch() function.
+    this.globalScope.set('scopeWatch', (scope, name, fn) => {
+      if (!(scope instanceof Scope)) throw new Error('scopeWatch: first arg must be a Scope');
+      const n = String(name);
+      let _val = scope.variables[n];
+      const descriptor = {
+        read: () => _val,
+        write: (v) => {
+          const old = _val; _val = v;
+          try {
+            if (typeof fn === 'function') fn(v, old);
+            else if (fn && fn.body !== undefined) _self.runFunctionNode(fn, _self.globalScope, [v, old]);
+          } catch (_) { }
+        },
+      };
+      scope.variables[n] = descriptor;
+      // return unwatch function
+      return () => { scope.variables[n] = _val; };
+    });
+
+    // ══════════════════════════════════════════════════════════════════════
+    // ── GENERAL UTILITIES ────────────────────────────────────────────────
+    // ══════════════════════════════════════════════════════════════════════
+
+    // ── deepEqual(a, b) ───────────────────────────────────────────────────
+    // Structural deep equality — returns true if a and b are value-identical
+    // at every level.  Handles all Nova types.
+    const _deepEqual = (a, b, seen = new Set()) => {
+      if (a === b) return true;
+      if (a === null || b === null) return a === b;
+      if (typeof a !== typeof b) return false;
+      if (typeof a !== 'object') return a === b;
+      // cycle guard
+      const key = `${Object.prototype.toString.call(a)};${Object.prototype.toString.call(b)}`;
+      if (seen.has(a)) return true;
+      seen.add(a);
+      if (a instanceof NovaArray && b instanceof NovaArray) {
+        if (a.inner.length !== b.inner.length) return false;
+        return a.inner.every((v, i) => _deepEqual(v, b.inner[i], seen));
+      }
+      if (a instanceof NovaObject && b instanceof NovaObject) {
+        const ka = Object.keys(a.inner), kb = Object.keys(b.inner);
+        if (ka.length !== kb.length) return false;
+        return ka.every(k => kb.includes(k) && _deepEqual(a.inner[k], b.inner[k], seen));
+      }
+      if (a instanceof NovaStruct && b instanceof NovaStruct) {
+        if (a.typeName !== b.typeName) return false;
+        return _deepEqual(new NovaObject(a.inner), new NovaObject(b.inner), seen);
+      }
+      if (a instanceof NovaRange && b instanceof NovaRange)
+        return a.start === b.start && a.end === b.end && a.step === b.step;
+      if (a instanceof NovaValue && b instanceof NovaValue)
+        return a.valueOf() === b.valueOf();
+      if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) return false;
+        return a.every((v, i) => _deepEqual(v, b[i], seen));
+      }
+      const ak = Object.keys(a), bk = Object.keys(b);
+      if (ak.length !== bk.length) return false;
+      return ak.every(k => bk.includes(k) && _deepEqual(a[k], b[k], seen));
+    };
+    this.globalScope.set('deepEqual', (a, b) => _deepEqual(a, b));
+
+    // ── deepFreeze(value) ─────────────────────────────────────────────────
+    // Recursively freeze a Nova object/array so no inner values can be mutated.
+    const _deepFreeze = (v, seen = new WeakSet()) => {
+      if (!v || typeof v !== 'object' || seen.has(v)) return v;
+      seen.add(v);
+      if (v instanceof NovaArray) { Object.freeze(v.inner); v.inner.forEach(x => _deepFreeze(x, seen)); }
+      if (v instanceof NovaObject) { Object.freeze(v.inner); Object.values(v.inner).forEach(x => _deepFreeze(x, seen)); }
+      if (v instanceof NovaStruct) { Object.freeze(v.inner); Object.values(v.inner).forEach(x => _deepFreeze(x, seen)); }
+      return v;
+    };
+    this.globalScope.set('deepFreeze', (v) => _deepFreeze(v));
+
+    // ── deepMerge(target, ...sources) ─────────────────────────────────────
+    // Recursively merge source objects into target.  Arrays are concatenated.
+    // Returns the merged object (target is mutated).
+    const _deepMerge = (target, source) => {
+      if (!(source instanceof NovaObject) && typeof source !== 'object') return target;
+      const srcInner = source instanceof NovaObject ? source.inner : source;
+      const tgtInner = target instanceof NovaObject ? target.inner : target;
+      for (const [k, v] of Object.entries(srcInner)) {
+        if (v instanceof NovaObject && tgtInner[k] instanceof NovaObject) {
+          _deepMerge(tgtInner[k], v);
+        } else if (v instanceof NovaArray && tgtInner[k] instanceof NovaArray) {
+          tgtInner[k] = new NovaArray([...tgtInner[k].inner, ...v.inner]);
+        } else {
+          tgtInner[k] = _deepClone(v);
+        }
+      }
+      return target;
+    };
+    this.globalScope.set('deepMerge', (target, ...sources) => {
+      for (const s of sources) _deepMerge(target, s);
+      return target;
+    });
+
+    // ── pick(obj, ...keys) ────────────────────────────────────────────────
+    // Return a new NovaObject with only the specified keys from obj.
+    this.globalScope.set('pick', (obj, ...keys) => {
+      const src = obj instanceof NovaObject ? obj.inner : obj instanceof NovaStruct ? obj.inner : (obj || {});
+      const flatKeys = keys.flatMap(k => k instanceof NovaArray ? k.inner : k);
+      const out = {};
+      for (const k of flatKeys) if (k in src) out[String(k)] = src[String(k)];
+      return new NovaObject(out);
+    });
+
+    // ── omit(obj, ...keys) ────────────────────────────────────────────────
+    // Return a new NovaObject with the specified keys removed.
+    this.globalScope.set('omit', (obj, ...keys) => {
+      const src = obj instanceof NovaObject ? obj.inner : obj instanceof NovaStruct ? obj.inner : (obj || {});
+      const flatKeys = new Set(keys.flatMap(k => k instanceof NovaArray ? k.inner.map(String) : [String(k)]));
+      const out = {};
+      for (const [k, v] of Object.entries(src)) if (!flatKeys.has(k)) out[k] = v;
+      return new NovaObject(out);
+    });
+
+    // ── mapObj(obj, fn) ───────────────────────────────────────────────────
+    // Like Array.map but over object entries: fn(value, key) → new value.
+    this.globalScope.set('mapObj', (obj, fn) => {
+      const src = obj instanceof NovaObject ? obj.inner : obj;
+      const out = {};
+      for (const [k, v] of Object.entries(src))
+        out[k] = (typeof fn === 'function') ? fn(v, k) : _self.runFunctionNode(fn, _self.globalScope, [v, k]);
+      return new NovaObject(out);
+    });
+
+    // ── filterObj(obj, fn) ────────────────────────────────────────────────
+    // Keep only entries where fn(value, key) is truthy.
+    this.globalScope.set('filterObj', (obj, fn) => {
+      const src = obj instanceof NovaObject ? obj.inner : obj;
+      const out = {};
+      for (const [k, v] of Object.entries(src)) {
+        const keep = (typeof fn === 'function') ? fn(v, k) : _self.runFunctionNode(fn, _self.globalScope, [v, k]);
+        if (keep) out[k] = v;
+      }
+      return new NovaObject(out);
+    });
+
+    // ── reduceObj(obj, fn, init) ──────────────────────────────────────────
+    // Reduce over object entries: fn(accumulator, value, key) → accumulator.
+    this.globalScope.set('reduceObj', (obj, fn, init) => {
+      const src = obj instanceof NovaObject ? obj.inner : obj;
+      let acc = init;
+      for (const [k, v] of Object.entries(src))
+        acc = (typeof fn === 'function') ? fn(acc, v, k) : _self.runFunctionNode(fn, _self.globalScope, [acc, v, k]);
+      return acc;
+    });
+
+    // ── groupBy(arr, fn) ─────────────────────────────────────────────────
+    // Group array elements by the key returned by fn(element).
+    this.globalScope.set('groupBy', (arr, fn) => {
+      const inner = arr instanceof NovaArray ? arr.inner : (Array.isArray(arr) ? arr : []);
+      const groups = {};
+      for (const v of inner) {
+        const key = String((typeof fn === 'function') ? fn(v) : _self.runFunctionNode(fn, _self.globalScope, [v]));
+        if (!groups[key]) groups[key] = [];
+        groups[key].push(v);
+      }
+      const out = {};
+      for (const [k, arr2] of Object.entries(groups)) out[k] = new NovaArray(arr2);
+      return new NovaObject(out);
+    });
+
+    // ── chunk(arr, size) ─────────────────────────────────────────────────
+    // Split array into chunks of at most `size` elements.
+    this.globalScope.set('chunk', (arr, size) => {
+      const inner = arr instanceof NovaArray ? arr.inner : (Array.isArray(arr) ? arr : []);
+      const n = Math.max(1, Number(size));
+      const out = [];
+      for (let i = 0; i < inner.length; i += n) out.push(new NovaArray(inner.slice(i, i + n)));
+      return new NovaArray(out);
+    });
+
+    // ── flatten(arr, depth?) ──────────────────────────────────────────────
+    // Flatten nested arrays.  depth defaults to Infinity (fully flat).
+    this.globalScope.set('flatten', (arr, depth) => {
+      const inner = arr instanceof NovaArray ? arr.inner : (Array.isArray(arr) ? arr : []);
+      const d = depth !== undefined ? Number(depth) : Infinity;
+      const flatInner = (a, remaining) => {
+        const out = [];
+        for (const v of a) {
+          if (remaining > 0 && (v instanceof NovaArray || Array.isArray(v))) {
+            out.push(...flatInner(v instanceof NovaArray ? v.inner : v, remaining - 1));
+          } else out.push(v);
+        }
+        return out;
+      };
+      return new NovaArray(flatInner(inner, d));
+    });
+
+    // ── zip(...arrays) ────────────────────────────────────────────────────
+    // Alias for zipArrays but accepting a single array-of-arrays or varargs.
+    this.globalScope.set('zip', (...arrays) => {
+      const arrs = arrays.length === 1 && arrays[0] instanceof NovaArray
+        ? arrays[0].inner.map(a => a instanceof NovaArray ? a.inner : a)
+        : arrays.map(a => a instanceof NovaArray ? a.inner : a);
+      const len = Math.min(...arrs.map(a => a.length));
+      return new NovaArray(Array.from({ length: len }, (_, i) => new NovaArray(arrs.map(a => a[i]))));
+    });
+
+    // ── unzip(arr) ────────────────────────────────────────────────────────
+    // Inverse of zip: [[a1,b1],[a2,b2]] → [[a1,a2],[b1,b2]]
+    this.globalScope.set('unzip', (arr) => {
+      const rows = arr instanceof NovaArray ? arr.inner : [];
+      if (!rows.length) return new NovaArray([]);
+      const cols = (rows[0] instanceof NovaArray ? rows[0].inner : rows[0]).length || 0;
+      const out = Array.from({ length: cols }, () => []);
+      for (const row of rows) {
+        const r = row instanceof NovaArray ? row.inner : row;
+        r.forEach((v, i) => { if (out[i]) out[i].push(v); });
+      }
+      return new NovaArray(out.map(c => new NovaArray(c)));
+    });
+
+    // ── partition(arr, fn) ────────────────────────────────────────────────
+    // Split array into [passing, failing] based on predicate fn.
+    this.globalScope.set('partition', (arr, fn) => {
+      const inner = arr instanceof NovaArray ? arr.inner : (Array.isArray(arr) ? arr : []);
+      const pass = [], fail = [];
+      for (const v of inner) {
+        const ok = (typeof fn === 'function') ? fn(v) : _self.runFunctionNode(fn, _self.globalScope, [v]);
+        (ok ? pass : fail).push(v);
+      }
+      return new NovaArray([new NovaArray(pass), new NovaArray(fail)]);
+    });
+
+    // ── sortBy(arr, fn, order?) ───────────────────────────────────────────
+    // Sort by a key function.  order: 'asc' (default) | 'desc'
+    this.globalScope.set('sortBy', (arr, fn, order) => {
+      const inner = arr instanceof NovaArray ? [...arr.inner] : (Array.isArray(arr) ? [...arr] : []);
+      const desc = String(order || '').toLowerCase() === 'desc';
+      inner.sort((a, b) => {
+        const ka = (typeof fn === 'function') ? fn(a) : _self.runFunctionNode(fn, _self.globalScope, [a]);
+        const kb = (typeof fn === 'function') ? fn(b) : _self.runFunctionNode(fn, _self.globalScope, [b]);
+        const cmp = ka < kb ? -1 : ka > kb ? 1 : 0;
+        return desc ? -cmp : cmp;
+      });
+      return new NovaArray(inner);
+    });
+
+    // ── countBy(arr, fn) ─────────────────────────────────────────────────
+    // Count how many elements map to each key: { key: count }
+    this.globalScope.set('countBy', (arr, fn) => {
+      const inner = arr instanceof NovaArray ? arr.inner : (Array.isArray(arr) ? arr : []);
+      const out = {};
+      for (const v of inner) {
+        const key = String((typeof fn === 'function') ? fn(v) : _self.runFunctionNode(fn, _self.globalScope, [v]));
+        out[key] = (out[key] || 0) + 1;
+      }
+      return new NovaObject(out);
+    });
+
+    // ── frequencies(arr) ─────────────────────────────────────────────────
+    // Count occurrences of each value.  Returns NovaObject {value: count}.
+    this.globalScope.set('frequencies', (arr) => {
+      const inner = arr instanceof NovaArray ? arr.inner : (Array.isArray(arr) ? arr : []);
+      const out = {};
+      for (const v of inner) { const k = _self.stringify(v); out[k] = (out[k] || 0) + 1; }
+      return new NovaObject(out);
+    });
+
+    // ── range2(start, end, step?) ─────────────────────────────────────────
+    // Named range2 to avoid clobbering the existing range() builtin.
+    // Returns a NovaArray (range() returns a NovaRange).
+    this.globalScope.set('range2', (start, end, step) => {
+      const s = Number(start), e = Number(end), st = step !== undefined ? Number(step) : 1;
+      if (st === 0) throw new Error('range2: step cannot be 0');
+      const out = [];
+      if (st > 0) { for (let i = s; i <= e; i += st) out.push(i); }
+      else { for (let i = s; i >= e; i += st) out.push(i); }
+      return new NovaArray(out);
+    });
+
+    // ── linspace(start, end, n) ───────────────────────────────────────────
+    // n evenly spaced values from start to end (inclusive).
+    this.globalScope.set('linspace', (start, end, n) => {
+      const s = Number(start), e = Number(end), count = Math.max(2, Number(n));
+      const out = [];
+      for (let i = 0; i < count; i++) out.push(s + (e - s) * i / (count - 1));
+      return new NovaArray(out);
+    });
+
+    // ── pipe(value, ...fns) ───────────────────────────────────────────────
+    // Thread a value through a sequence of functions left-to-right.
+    this.globalScope.set('pipe', (value, ...fns) => {
+      return fns.reduce((v, fn) => {
+        if (typeof fn === 'function') return fn(v);
+        if (fn && fn.body !== undefined) return _self.runFunctionNode(fn, _self.globalScope, [v]);
+        return v;
+      }, value);
+    });
+
+    // ── compose(...fns) ───────────────────────────────────────────────────
+    // Compose functions right-to-left.  Returns a new function.
+    this.globalScope.set('compose', (...fns) => {
+      return (value) => fns.reduceRight((v, fn) => {
+        if (typeof fn === 'function') return fn(v);
+        if (fn && fn.body !== undefined) return _self.runFunctionNode(fn, _self.globalScope, [v]);
+        return v;
+      }, value);
+    });
+
+    // ── memoize(fn) ───────────────────────────────────────────────────────
+    // Wrap a function so repeated calls with the same args return cached results.
+    this.globalScope.set('memoize', (fn) => {
+      const cache = new Map();
+      return (...args) => {
+        const key = JSON.stringify(args.map(a => _self.stringify(a)));
+        if (cache.has(key)) return cache.get(key);
+        const result = (typeof fn === 'function')
+          ? fn(...args)
+          : _self.runFunctionNode(fn, _self.globalScope, args);
+        cache.set(key, result);
+        return result;
+      };
+    });
+
+    // ── once(fn) ──────────────────────────────────────────────────────────
+    // Return a wrapper that calls fn at most once; subsequent calls return the first result.
+    this.globalScope.set('once', (fn) => {
+      let called = false, result;
+      return (...args) => {
+        if (!called) {
+          called = true;
+          result = (typeof fn === 'function') ? fn(...args) : _self.runFunctionNode(fn, _self.globalScope, args);
+        }
+        return result;
+      };
+    });
+
+    // ── debounce(fn, ms) ─────────────────────────────────────────────────
+    // Returns a debounced version of fn (trailing edge, async-safe).
+    this.globalScope.set('debounce', (fn, ms) => {
+      let timer = null;
+      return (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+          timer = null;
+          if (typeof fn === 'function') fn(...args);
+          else _self.runFunctionNode(fn, _self.globalScope, args);
+        }, Number(ms) || 0);
+      };
+    });
+
+    // ── throttle(fn, ms) ─────────────────────────────────────────────────
+    // Returns a throttled version of fn (leading edge).
+    this.globalScope.set('throttle', (fn, ms) => {
+      let last = 0;
+      return (...args) => {
+        const now = Date.now();
+        if (now - last >= Number(ms)) {
+          last = now;
+          if (typeof fn === 'function') return fn(...args);
+          return _self.runFunctionNode(fn, _self.globalScope, args);
+        }
+      };
+    });
+
+    // ── curry(fn, arity?) ─────────────────────────────────────────────────
+    // Auto-curry a function.  Calls fn when enough args have been collected.
+    this.globalScope.set('curry', (fn, arity) => {
+      const n = arity !== undefined ? Number(arity) : (fn.length || (fn.args && fn.args.length) || 1);
+      const curried = (collected) => (...args) => {
+        const all = [...collected, ...args];
+        if (all.length >= n) {
+          return (typeof fn === 'function') ? fn(...all) : _self.runFunctionNode(fn, _self.globalScope, all);
+        }
+        return curried(all);
+      };
+      return curried([]);
+    });
+
+    // ── partial(fn, ...boundArgs) ─────────────────────────────────────────
+    // Partially apply fn with the given leading arguments.
+    this.globalScope.set('partial', (fn, ...boundArgs) => {
+      return (...moreArgs) => {
+        const all = [...boundArgs, ...moreArgs];
+        if (typeof fn === 'function') return fn(...all);
+        return _self.runFunctionNode(fn, _self.globalScope, all);
+      };
+    });
+
+    // ── noop() ────────────────────────────────────────────────────────────
+    this.globalScope.set('noop', () => undefined);
+
+    // ── identity(x) ───────────────────────────────────────────────────────
+    this.globalScope.set('identity', (x) => x);
+
+    // ── tap(value, fn) ────────────────────────────────────────────────────
+    // Call fn(value) for side effects and return value unchanged.
+    this.globalScope.set('tap', (value, fn) => {
+      if (typeof fn === 'function') fn(value);
+      else if (fn && fn.body !== undefined) _self.runFunctionNode(fn, _self.globalScope, [value]);
+      return value;
+    });
+
+    // ── tryCatch(fn, handler?) ────────────────────────────────────────────
+    // Call fn(); if it throws, call handler(err) and return its value.
+    // If no handler, returns null on error.
+    this.globalScope.set('tryCatch', (fn, handler) => {
+      try {
+        return (typeof fn === 'function') ? fn() : _self.runFunctionNode(fn, _self.globalScope, []);
+      } catch (e) {
+        const err = e && e.payload !== undefined ? e.payload : (e instanceof Error ? e.message : String(e));
+        if (handler) {
+          return (typeof handler === 'function') ? handler(err) : _self.runFunctionNode(handler, _self.globalScope, [err]);
+        }
+        return null;
+      }
+    });
+
+    // ── repeat(n, fn) ─────────────────────────────────────────────────────
+    // Call fn(i) n times and return array of results.
+    this.globalScope.set('times', (n, fn) => {
+      const out = [];
+      for (let i = 0; i < Number(n); i++)
+        out.push((typeof fn === 'function') ? fn(i) : _self.runFunctionNode(fn, _self.globalScope, [i]));
+      return new NovaArray(out);
+    });
+
+    // ── objectFromEntries(arr) ────────────────────────────────────────────
+    // Build a NovaObject from [[key, value], ...] pairs.
+    this.globalScope.set('objectFromEntries', (arr) => {
+      const inner = arr instanceof NovaArray ? arr.inner : (Array.isArray(arr) ? arr : []);
+      const out = {};
+      for (const pair of inner) {
+        const p = pair instanceof NovaArray ? pair.inner : pair;
+        if (p && p.length >= 2) out[String(p[0])] = p[1];
+      }
+      return new NovaObject(out);
+    });
+
+    // ── invert(obj) ───────────────────────────────────────────────────────
+    // Swap keys and values of an object.
+    this.globalScope.set('invert', (obj) => {
+      const src = obj instanceof NovaObject ? obj.inner : (obj || {});
+      const out = {};
+      for (const [k, v] of Object.entries(src)) out[_self.stringify(v)] = k;
+      return new NovaObject(out);
+    });
+
+    // ── toPairs(obj) / fromPairs(arr) ─────────────────────────────────────
+    this.globalScope.set('toPairs', (obj) => {
+      const src = obj instanceof NovaObject ? obj.inner : (obj || {});
+      return new NovaArray(Object.entries(src).map(([k, v]) => new NovaArray([k, v])));
+    });
+    this.globalScope.set('fromPairs', (arr) => {
+      const inner = arr instanceof NovaArray ? arr.inner : (Array.isArray(arr) ? arr : []);
+      const out = {};
+      for (const pair of inner) {
+        const p = pair instanceof NovaArray ? pair.inner : pair;
+        if (p && p.length >= 2) out[String(p[0])] = p[1];
+      }
+      return new NovaObject(out);
+    });
+
+    // ── defaults(obj, ...sources) ──────────────────────────────────────────
+    // Like Object.assign but only fills in missing (null/undefined) keys.
+    this.globalScope.set('defaults', (obj, ...sources) => {
+      const tgt = obj instanceof NovaObject ? obj : new NovaObject({ ...(obj || {}) });
+      for (const src of sources) {
+        const s = src instanceof NovaObject ? src.inner : (src || {});
+        for (const [k, v] of Object.entries(s))
+          if (tgt.inner[k] === undefined || tgt.inner[k] === null) tgt.inner[k] = v;
+      }
+      return tgt;
+    });
+
+    // ── clamp2(min, max) → fn  (or clamp2(val, min, max)) ─────────────────
+    // Already have clamp(v,lo,hi) — this gives a curried version usable as a pipe step.
+    this.globalScope.set('clampFn', (lo, hi) => (v) => Math.min(Math.max(Number(v), Number(lo)), Number(hi)));
+
+    // ── lerp(a, b, t) ─────────────────────────────────────────────────────
+    // Linear interpolation between a and b at fraction t ∈ [0,1].
+    this.globalScope.set('lerp', (a, b, t) => Number(a) + (Number(b) - Number(a)) * Number(t));
+
+    // ── wrap(value, min, max) ─────────────────────────────────────────────
+    // Wrap value into [min, max) range (like modulo but for arbitrary ranges).
+    this.globalScope.set('wrap', (v, lo, hi) => {
+      const range = Number(hi) - Number(lo);
+      if (range === 0) return Number(lo);
+      return ((((Number(v) - Number(lo)) % range) + range) % range) + Number(lo);
+    });
+
+    // ── mapRange(value, inMin, inMax, outMin, outMax) ─────────────────────
+    // Remap a value from one range to another.
+    this.globalScope.set('mapRange', (v, inLo, inHi, outLo, outHi) => {
+      const t = (Number(v) - Number(inLo)) / (Number(inHi) - Number(inLo));
+      return Number(outLo) + t * (Number(outHi) - Number(outLo));
+    });
+
+    // ── roundTo(value, decimals) ──────────────────────────────────────────
+    this.globalScope.set('roundTo', (v, dec) => {
+      const f = 10 ** Number(dec || 0);
+      return Math.round(Number(v) * f) / f;
+    });
+
+    // ── toBase(number, base) ─────────────────────────────────────────────
+    this.globalScope.set('toBase', (n, base) => Number(n).toString(Number(base)));
+
+    // ── fromBase(str, base) ──────────────────────────────────────────────
+    this.globalScope.set('fromBase', (s, base) => parseInt(String(s), Number(base)));
+
+    // ── uuid() ────────────────────────────────────────────────────────────
+    // Already in nvk.uuid but expose at top level too.
+    this.globalScope.set('uuid', () => {
+      const crypto = require('crypto');
+      return crypto.randomUUID ? crypto.randomUUID() : crypto.randomBytes(16).toString('hex');
+    });
+
+    // ── timestamp() ───────────────────────────────────────────────────────
+    this.globalScope.set('timestamp', () => Date.now());
+
+    // ── isoDate() ─────────────────────────────────────────────────────────
+    this.globalScope.set('isoDate', () => new Date().toISOString());
+
+    // ── formatDate(ms?, format?) ─────────────────────────────────────────
+    // Format a timestamp or now.  format tokens: YYYY MM DD HH mm ss
+    this.globalScope.set('formatDate', (ms, fmt) => {
+      const d = new Date(ms !== undefined ? Number(ms) : Date.now());
+      const pad = (n) => String(n).padStart(2, '0');
+      const tokens = {
+        YYYY: d.getFullYear(), MM: pad(d.getMonth() + 1), DD: pad(d.getDate()),
+        HH: pad(d.getHours()), mm: pad(d.getMinutes()), ss: pad(d.getSeconds()),
+      };
+      const f = String(fmt || 'YYYY-MM-DD HH:mm:ss');
+      return f.replace(/YYYY|MM|DD|HH|mm|ss/g, m => tokens[m]);
+    });
+
+    // ── assertEq(a, b, msg?) ─────────────────────────────────────────────
+    // Throw if a !== b (deep structural for objects).
+    this.globalScope.set('assertEq', (a, b, msg) => {
+      if (!_deepEqual(a, b)) {
+        throw new Error((msg ? String(msg) + ': ' : 'assertEq: ') +
+          _self.stringify(a) + ' !== ' + _self.stringify(b));
+      }
+      return true;
+    });
+
+    // ── assertType(value, typeName, msg?) ─────────────────────────────────
+    this.globalScope.set('assertType', (v, typeName, msg) => {
+      const actual = _self._typeOf(v);
+      if (actual !== String(typeName)) {
+        throw new Error((msg ? String(msg) + ': ' : 'assertType: ') +
+          'expected ' + typeName + ', got ' + actual);
+      }
+      return true;
+    });
+
+    // ── inspect(value) ────────────────────────────────────────────────────
+    // Return a human-readable debug string with type info.
+    this.globalScope.set('inspect', (v) => {
+      const type = _self._typeOf(v);
+      const str = _self.stringify(v);
+      return `[${type}] ${str}`;
+    });
+
     this._initThread();
   }
 
@@ -430,7 +2105,7 @@ class Executor {
     }
     // NovaBool / NovaNumber / NovaString / NovaNull — all have _v
     if (v instanceof NovaBool || v instanceof NovaNumber ||
-        v instanceof NovaString || v instanceof NovaNull) {
+      v instanceof NovaString || v instanceof NovaNull) {
       return { _v: v.valueOf !== undefined ? v.valueOf() : null };
     }
     if (v instanceof NovaRange) return { start: v.start, end: v.end };
@@ -458,10 +2133,10 @@ class Executor {
     if (Array.isArray(v)) return v.map(x => this._rehydrate(x));
     if ('__jsfn__' in v) { try { return eval('(' + v.__jsfn__ + ')'); } catch { return null; } }
     if ('_v' in v) {
-      if (v._v === null)             return new NovaNull();
+      if (v._v === null) return new NovaNull();
       if (typeof v._v === 'boolean') return new NovaBool(v._v);
-      if (typeof v._v === 'number')  return new NovaNumber(v._v);
-      if (typeof v._v === 'string')  return new NovaString(v._v);
+      if (typeof v._v === 'number') return new NovaNumber(v._v);
+      if (typeof v._v === 'string') return new NovaString(v._v);
       return v._v;
     }
     if ('start' in v && 'end' in v && Object.keys(v).length === 2)
@@ -502,12 +2177,12 @@ class Executor {
     // Also snapshot the global user-defined variables (functions, declared vars)
     // but skip built-in keys that are circular, huge, or executor-internal.
     const SKIP = new Set([
-      'scope','array','std','core','nova','nvk','qae','novaRegex','fetch',
-      'setTimeout','typecheck','satisfies','typeOf','Thread',
-      'ForLoop','WhileLoop','IfBlock','TryCatch','Pipeline','FuncDef',
-      'MatchBlock','Timer','Counter','Stack','Queue','LinkedList',
-      'State','Observable','Validator','DataStream','Transformer',
-      'TransformerJSON','TransformerBase64','Router','EventBus','Memo','Lazy','Signal',
+      'scope', 'array', 'std', 'core', 'nova', 'nvk', 'qae', 'cregex', 'fetch',
+      'setTimeout', 'typecheck', 'satisfies', 'typeOf', 'Thread',
+      'ForLoop', 'WhileLoop', 'IfBlock', 'TryCatch', 'Pipeline', 'FuncDef',
+      'MatchBlock', 'Timer', 'Counter', 'Stack', 'Queue', 'LinkedList',
+      'State', 'Observable', 'Validator', 'DataStream', 'Transformer',
+      'TransformerJSON', 'TransformerBase64', 'Router', 'EventBus', 'Memo', 'Lazy', 'Signal',
     ]);
     for (const [k, v] of Object.entries(this.globalScope.variables || {})) {
       if (SKIP.has(k) || snap.hasOwnProperty(k)) continue;
@@ -523,20 +2198,20 @@ class Executor {
   _initThread() {
     const _path = require('path');
     const _workerScriptPath = _path.join(__dirname, 'nova_thread_worker.js');
-    const _executorPath     = _path.join(__dirname, 'executor.js');
+    const _executorPath = _path.join(__dirname, 'executor.js');
     const _exe = this;
 
     class NovaThread {
       constructor(fnNode, callerScope) {
-        this._fnNode      = fnNode;
+        this._fnNode = fnNode;
         this._callerScope = callerScope;
-        this._worker      = null;
-        this._mutations   = []; // { name, value } buffered until join()
+        this._worker = null;
+        this._mutations = []; // { name, value } buffered until join()
         this._msgHandlers = [];
-        this._done        = false;
-        this._result      = undefined;
-        this._error       = null;
-        this._sab  = new SharedArrayBuffer(8);
+        this._done = false;
+        this._result = undefined;
+        this._error = null;
+        this._sab = new SharedArrayBuffer(8);
         this._flag = new Int32Array(this._sab);
         this._proxy = this._makeProxy();
       }
@@ -544,13 +2219,13 @@ class Executor {
       _makeProxy() {
         const t = this;
         return new NovaObject({
-          start:      ()   => { t.start(); return t._proxy; },
-          join:       ()   => t.join(),
-          send:       (v)  => { t.send(v); return t._proxy; },
+          start: () => { t.start(); return t._proxy; },
+          join: () => t.join(),
+          send: (v) => { t.send(v); return t._proxy; },
           on_message: (fn) => { t.on_message(fn); return t._proxy; },
-          get result()     { return t._result; },
-          get error()      { return t._error; },
-          get done()       { return t._done; },
+          get result() { return t._result; },
+          get error() { return t._error; },
+          get done() { return t._done; },
         });
       }
 
@@ -689,24 +2364,103 @@ class Executor {
     return 'unknown';
   }
 
+  // ══════════════════════════════════════════════════════════════════════
+  // _runAsyncBody(stmts, scope, execFn)
+  // ──────────────────────────────────────────────────────────────────────
+  // Shared engine for both top-level `await` and `func async` bodies.
+  // Runs statements one by one; when an `await` suspension is thrown it
+  // chains a real .then() on the Promise, patches the AST node in-place
+  // with the resolved value, re-executes the statement, then continues.
+  // Returns a Promise that resolves with the last statement result
+  // (or whatever was thrown as __return).
+  _runAsyncBody(stmts, scope, execFn) {
+    const self = this;
+    let i = 0;
+    let lastResult;
+
+    // Walk AST tree depth-first; replace first { kind:'await' } node with
+    // { kind:'value', value:val } so the statement can be re-executed cleanly.
+    function patchFirst(node, val) {
+      if (!node || typeof node !== 'object') return false;
+      for (const key of Object.keys(node)) {
+        const child = node[key];
+        if (child && typeof child === 'object') {
+          if (child.kind === 'await') { node[key] = { kind: 'value', value: val }; return true; }
+          if (patchFirst(child, val)) return true;
+        }
+      }
+      return false;
+    }
+
+    // Sentinel to distinguish "no suspension" from a real return value of null/undefined
+    const NO_SUSPENSION = Symbol('no_suspension');
+
+    // Run one statement; if it suspends on await, chain .then() and recurse.
+    function runOne(stmt) {
+      try {
+        lastResult = execFn(stmt, scope);
+        return NO_SUSPENSION; // no suspension — caller proceeds to next stmt
+      } catch (e) {
+        if (e !== null && typeof e === 'object' && '__return' in e)
+          return Promise.resolve({ __earlyReturn__: e.__return });
+        if (e !== null && typeof e === 'object' && e.__awaitSuspension__) {
+          return e.promise.then((val) => {
+            patchFirst(stmt, val);
+            return runOne(stmt); // re-run the same statement with patched value
+          });
+        }
+        return Promise.reject(e);
+      }
+    }
+
+    function step() {
+      while (i < stmts.length) {
+        const stmt = stmts[i++];
+        const suspension = runOne(stmt);
+        if (suspension !== NO_SUSPENSION) {
+          // Suspension or return — chain remaining steps after it resolves
+          return suspension.then((r) => {
+            if (r && typeof r === 'object' && '__earlyReturn__' in r) return r.__earlyReturn__;
+            return step(); // continue from next statement
+          });
+        }
+      }
+      const ret = scope.get ? (scope.get('__return') != null ? scope.get('__return') : lastResult) : lastResult;
+      return Promise.resolve(ret);
+    }
+
+    return step();
+  }
+
   run(ast, scope) {
-    if (this.awaiting) return undefined; // blocked until await resolves
     if (ast && !scope) this.ast = ast;
     if (!ast) return;
     const stmts = Array.isArray(ast) ? ast : ast.nodes;
+    const execScope = scope || this.globalScope;
     let result;
-    for (const node of stmts) { // builtin events
+
+    // Run synchronously; if an await suspension bubbles up, hand off the
+    // current + remaining statements to _runAsyncBody (top-level await).
+    for (let i = 0; i < stmts.length; i++) {
+      const node = stmts[i];
       for (const h of (this.eventBus.get('nv:tick') || [])) {
-        const hs = new Scope('function', scope, this.globalScope);
+        const hs = new Scope('function', execScope, this.globalScope);
         this.runLoop(h.body, hs);
       }
-      result = this.execute(node, scope || this.globalScope);
+      try {
+        result = this.execute(node, execScope);
+      } catch (e) {
+        if (e !== null && typeof e === 'object' && e.__awaitSuspension__) {
+          const execFn = this.execute.bind(this);
+          return this._runAsyncBody(stmts.slice(i), execScope, execFn);
+        }
+        throw e;
+      }
     }
     return result;
   }
 
   runLoop(body, scope) {
-    if (this.awaiting) return null; // blocked until await resolves
     const stmts = Array.isArray(body) ? body : body.nodes;
     for (const node of stmts) {
       try { this.execute(node, scope || this.globalScope); }
@@ -742,6 +2496,8 @@ class Executor {
         if (fs.existsSync(kitdefFile)) {
           const kitMod = require(kitdefFile);
           if (!kitMod.kitdef) throw new Error(`Kit "${name}": kitdef.js must export { kitdef }`);
+          // Process all metadata fields (events, dvars, init, hooks, etc.)
+          _self._processKitMod(kitMod, name);
           return { kind: 'kit', exports: kitMod.kitdef };
         }
         const indexNova = path.join(novaModDir, 'index.nova');
@@ -854,28 +2610,186 @@ class Executor {
     return content;
   }
 
-  stringify(v) {
-    if (v === null || v === undefined) return 'null';
-    if (v instanceof NovaNull) return 'null';
-    if (v instanceof NovaBool) return v.valueOf() ? 'true' : 'false';
-    if (v instanceof NovaString) return v.valueOf();
-    if (v instanceof NovaNumber) return String(v.valueOf());
-    if (v instanceof NovaRange) return v.toString();
-    if (v instanceof NovaStruct) return v.toString();
-    if (v instanceof NovaArray) return '[' + v.inner.map(x => this.stringify(x)).join(', ') + ']';
-    if (v instanceof NovaObject) return '{' + Object.entries(v.inner).map(([k, x]) => k + ': ' + this.stringify(x)).join(', ') + '}';
-    if (v instanceof NovaValue) return v.toString();
-    if (v instanceof Scope) return v.toString();
-    if (v && v.kind === 'function') return 'Function [' + (v.name || 'anon') + ']';
-    if (v && v.kind === 'class') return 'Class [' + (v.node && v.node.name) + ']';
-    if (v instanceof NovaEnum) return v.toString();
+  stringify(v, indent = 0, seen = new WeakSet()) {
+    const pad = "  ".repeat(indent);
+
+    const color = {
+      reset: "\x1b[0m",
+      key: "\x1b[36m",
+      string: "\x1b[32m",
+      number: "\x1b[33m",
+      bool: "\x1b[35m",
+      null: "\x1b[90m",
+      func: "\x1b[31m",
+      circular: "\x1b[91m",
+    };
+
+    const nl = "\n";
+
+    const next = (x, i = indent + 1) =>
+      this.stringify(x, i, seen);
+
+    if (v === null || v === undefined)
+      return color.null + "null" + color.reset;
+
+    if (v instanceof NovaNull)
+      return color.null + "null" + color.reset;
+
+    if (v instanceof NovaBool)
+      return color.bool + String(v.valueOf()) + color.reset;
+
+    if (v instanceof NovaString)
+      return color.string + `"${v.valueOf()}"` + color.reset;
+
+    if (v instanceof NovaNumber)
+      return color.number + String(v.valueOf()) + color.reset;
+
+    if (v instanceof Promise)
+      return color.func + `Promise [${v.name || "anon"}]` + color.reset;
+
+    if (v instanceof NovaRange)
+      return v.toString();
+
+    if (v instanceof NovaStruct)
+      return v.toString();
+
+    // ── Plain JS getter/setter descriptor { read, write } ────────────────────
+    // Scope variables with modifiers (tracked, lazy, clamp, etc.) are stored as
+    // plain objects with read() / write() functions.  Show the live value instead.
+    if (
+      v !== null && typeof v === 'object' &&
+      !(v instanceof NovaValue) && !(v instanceof NovaArray) &&
+      !(v instanceof NovaObject) && !(v instanceof NovaStruct) &&
+      !(v instanceof NovaEnum) && !(v instanceof Scope) &&
+      !(v instanceof Promise) && !Array.isArray(v) &&
+      typeof v.read === 'function' && typeof v.write === 'function'
+    ) {
+      return color.key + '[get/set ×]' + color.reset;
+    }
+
+    if (typeof v === "object" && v !== null) {
+      if (seen.has(v))
+        return color.circular + "[Circular]" + color.reset;
+
+      seen.add(v);
+    }
+
+    if (v instanceof NovaArray) {
+      if (!v.inner.length)
+        return "[]";
+
+      return "[\n" +
+        v.inner.map(x =>
+          pad + "  " + next(x, indent + 1)
+        ).join(",\n") +
+        nl + pad + "]";
+    }
+
+    if (v instanceof NovaObject) {
+      // ── Build annotation badges ─────────────────────────────────────────────
+      const _annotations = [];
+
+      // Operator overloads stored under __operators
+      const _opsRaw = v.inner.__operators;
+      if (_opsRaw) {
+        const _opsObj = _opsRaw instanceof NovaObject
+          ? _opsRaw.inner
+          : (typeof _opsRaw === 'object' && _opsRaw !== null ? _opsRaw : {});
+        const _binOps = Object.keys(
+          _opsObj.binary instanceof NovaObject ? _opsObj.binary.inner : (_opsObj.binary || {})
+        );
+        const _unOps = Object.keys(
+          _opsObj.unary instanceof NovaObject ? _opsObj.unary.inner : (_opsObj.unary || {})
+        ).map(k => 'u' + k);
+        const _allOps = [..._binOps, ..._unOps];
+        _annotations.push('\x1b[33m[ops:' + (_allOps.length ? ' ' + _allOps.join(' ') : '') + ']\x1b[0m');
+      }
+
+      // Meta traps attached via attachMeta()
+      if (v._meta) {
+        const _traps = [];
+        if (typeof v._meta.get === 'function') _traps.push('get');
+        if (typeof v._meta.set === 'function') _traps.push('set');
+        if (typeof v._meta.missing === 'function') _traps.push('missing');
+        if (_traps.length) _annotations.push('\x1b[36m[meta:' + _traps.join(',') + ']\x1b[0m');
+      }
+
+      const _prefix = _annotations.length ? _annotations.join(' ') + ' ' : '';
+
+      // Hide internal plumbing keys from display
+      const _HIDE = new Set(['__operators']);
+      const _entries = Object.entries(v.inner).filter(([k]) => !_HIDE.has(k));
+
+      if (!_entries.length)
+        return _prefix + "{}";
+
+      return _prefix + "{\n" +
+        _entries.map(([k, x]) =>
+          pad + "  " +
+          color.key + k + color.reset +
+          ": " +
+          next(x, indent + 1)
+        ).join(",\n") +
+        nl + pad + "}";
+    }
+
+    if (v instanceof NovaValue)
+      return v.toString();
+
+    if (v instanceof Scope)
+      return v.toString();
+
+    if (v && v.kind === "function")
+      return color.func +
+        `Function [${v.name || "anon"}]` +
+        color.reset;
+
+    if (v && v.kind === "class")
+      return color.func +
+        `Class [${v.node?.name || "Unknown"}]` +
+        color.reset;
+
+    if (v instanceof NovaEnum)
+      return v.toString();
+
     switch (typeof v) {
-      case 'number': return isNaN(v) ? 'NaN' : String(v);
-      case 'string': return v;
-      case 'boolean': return String(v);
-      case 'object': return JSON.stringify(v);
-      case 'function': return 'Function [' + (v.registered ? 'Registered' : 'NativeJs') + ']';
+      case "number":
+        return color.number +
+          (isNaN(v) ? "NaN" : String(v)) +
+          color.reset;
+
+      case "string":
+        return color.string +
+          `"${v}"` +
+          color.reset;
+
+      case "boolean":
+        return color.bool +
+          String(v) +
+          color.reset;
+
+      case "object": {
+        const entries = Object.entries(v);
+
+        if (!entries.length)
+          return "Native {}";
+
+        return "Native {\n" +
+          entries.map(([k, val]) =>
+            pad + "  " +
+            color.key + k + color.reset +
+            ": " +
+            next(val, indent + 1)
+          ).join(",\n") +
+          nl + pad + "}";
+      }
+
+      case "function":
+        return color.func +
+          `Function [${v.registered ? "Registered" : "NativeJs"}]` +
+          color.reset;
     }
+
     return String(v);
   }
 
@@ -911,13 +2825,17 @@ class Executor {
 
     const ls = new Scope('function', scope, this.globalScope);
     ls.set('this', scope);
+    ls._funcName = fn.name || null;  // used by __func__ dvar
 
     (fn.args || []).forEach((arg, i) => {
       if (typeof arg === 'string') { ls.set(arg, args[i]); return; }
       if (arg.rest) { ls.set(arg.name, new NovaArray(args.slice(i))); return; }
-      const v = args[i] !== undefined
-        ? args[i]
-        : (arg.defaultValue ? this.evaluate(arg.defaultValue, ls) : undefined);
+      // `default` sentinel → treat as if argument was omitted (use default value)
+      const rawArg = args[i];
+      const useDefault = rawArg === DEFAULT_SENTINEL || rawArg === undefined;
+      const v = useDefault
+        ? (arg.defaultValue ? this.evaluate(arg.defaultValue, ls) : undefined)
+        : rawArg;
       if (arg.type && !this.types.check(v, arg.type)) {
         const tn = arg.type.name || JSON.stringify(arg.type);
         throw new Error("Argument '" + arg.name + "': expected " + tn + ", got " + this._typeOf(v));
@@ -951,11 +2869,30 @@ class Executor {
       return iter;
     }
 
+    // ── Async function: execute body inside a Promise chain ──
+    if (fn.isAsync) {
+      // Delegate to the shared _runAsyncBody engine which handles await suspensions
+      // via .then() chains, patching AST nodes in-place for each resolved await.
+      const execFn = originalExecute;
+      const self = this;
+      return new Promise((resolve, reject) => {
+        self._runAsyncBody(fn.body, ls, execFn)
+          .then(resolve)
+          .catch((e) => {
+            if (e !== null && typeof e === 'object' && '__return' in e) resolve(e.__return);
+            else reject(e);
+          });
+      }).finally(() => {
+        this.execute = originalExecute;
+        if (fn.defer) this.execute(fn.defer);
+      });
+    }
+
     try {
       let result;
       for (const stmt of fn.body) result = this.execute(stmt, ls);
       const ret = ls.get('__return') !== undefined ? ls.get('__return') : result;
-      return fn.isAsync ? Promise.resolve(ret) : ret;  // ← add this
+      return ret;
     } catch (e) {
       if (e !== null && typeof e === 'object' && '__return' in e) {
         if (fn.memoize) fn._memoCache.set(JSON.stringify(args), () => e.__return);
@@ -1004,12 +2941,20 @@ class Executor {
           switch (current.type) {
             case 'if': {
               if (this.evaluate(current.args, scope)) {
-                this._runBodyWithYields(current.body, scope, collector);
+                const _sig = this._runBodyWithYields(current.body, scope, collector);
                 executed = true;
+                if (_sig === 'break') throw { __break: true };
+                if (_sig === 'continue') throw { __continue: true };
               } else current = current.next;
               break;
             }
-            case 'else': { this._runBodyWithYields(current.body, scope, collector); executed = true; break; }
+            case 'else': {
+              const _sig = this._runBodyWithYields(current.body, scope, collector);
+              executed = true;
+              if (_sig === 'break') throw { __break: true };
+              if (_sig === 'continue') throw { __continue: true };
+              break;
+            }
             case 'while': {
               const c = Array.isArray(current.args) ? current.args[0] : current.args;
               while (this.evaluate(c, scope)) {
@@ -1026,7 +2971,11 @@ class Executor {
               }
               executed = true; break;
             }
-            default: { this.execute(node, scope); executed = true; break; }
+            default: {
+              try { this.execute(node, scope); }
+              catch (e) { if (e && '__yield' in e) { collector.push(e.__yield); } else throw e; }
+              executed = true; break;
+            }
           }
         }
         return;
@@ -1097,6 +3046,16 @@ class Executor {
     switch (node.kind) {
       case 'EOF': return undefined;
 
+      // ── @classic compatibility block ──
+      // All Classic novac keywords (foreach, gear, echo, macro, etc.) are
+      // only parseable inside @classic { } blocks. The executor just runs
+      // their body statements normally — the gating happens at parse time.
+      case 'classic_block': {
+        let result;
+        for (const n of node.body) result = this.execute(n, scope);
+        return result;
+      }
+
       // ── type declarations ──
       case 'type_decl': {
         this.types.registerType(node.name, node);
@@ -1187,7 +3146,8 @@ class Executor {
       // ── declare ──
       case 'declare': {
         if (node.destructure) {
-          const val = this.evaluate(node.value, scope);
+          const evaled = this.evaluate(node.value, scope);
+          const val = evaled instanceof NovaObject ? evaled.inner : evaled;
           if (node.destructure.kind === 'objpattern') {
             for (const { key, alias, defaultValue } of node.destructure.props) {
               let v = val && Object.prototype.hasOwnProperty.call(val, key) ? val[key] : undefined;
@@ -1207,15 +3167,143 @@ class Executor {
           }
           return val;
         }
-        scope.set(node.name, undefined);
-        let val = this.evaluate(node.value, scope);
-        if (node.isPointer) val = new NovaPointer(val, (v) => v, (nv) => { val.inner = nv; });
+        scope.setOwn(node.name, undefined);
+        const isLazy = node.modifiers?.lazy;
+        let val = isLazy ? undefined : this.evaluate(node.value, scope);
+        if (!isLazy && node.isPointer) val = new NovaPointer(val, (v) => v, (nv) => { val.inner = nv; });
         // runtime type check on declare
-        if (node.explicitType && !this.types.check(val, node.explicitType)) {
-          const tn = node.explicitType.name || JSON.stringify(node.explicitType);
-          throw new Error("Variable '" + node.name + "': expected " + tn + ", got " + this._typeOf(val));
+        if (node.explicitType) {
+          const checkType = node.explicitType;
+          const hasValueUnion = checkType.kind === 'union_type' &&
+            checkType.variants.some(v => v.kind === 'value_type');
+
+          if (!this.types.check(val, checkType)) {
+            const tn = checkType.name || (hasValueUnion
+              ? checkType.variants.map(v => v.kind === 'value_type' ? String(v.value) : v.name).join(' | ')
+              : JSON.stringify(checkType));
+            throw new Error("Variable '" + node.name + "': expected " + tn + ", got " + this._typeOf(val) + '(' + val + ')');
+          }
+
+          // If it's a value union, build a descriptor that enforces it on every write
+          if (hasValueUnion && !node.modifiers) {
+            const self = this;
+            let _val = val;
+            const applySet = (v) => {
+              if (!self.types.check(v, checkType)) {
+                const tn2 = checkType.variants.map(vt => vt.kind === 'value_type' ? String(vt.value) : vt.name).join(' | ');
+                throw new Error("Variable '" + node.name + "': value must be one of [" + tn2 + "], got " + String(v));
+              }
+              _val = v;
+            };
+            scope.variables[node.name] = { read: () => _val, write: applySet };
+            return val;
+          }
+        }
+
+        // ── smart variable modifiers ──
+        const mods = node.modifiers;
+        if (mods) {
+          const self = this;
+          const varName = node.name;
+
+          // Build constraint checker from explicitType (value union)
+          let typeConstraint = null;
+          if (node.explicitType && node.explicitType.kind === 'union_type') {
+            // Check if it's a value-union (has literal values) or type-union
+            typeConstraint = (v) => {
+              if (!self.types.check(v, node.explicitType)) {
+                // Also do value equality check for each variant
+                const ok = node.explicitType.variants.some(variant => {
+                  if (variant.kind === 'named_type') {
+                    // Try as literal value: "true","false","null", or a quoted string
+                    const n = variant.name;
+                    if (n === 'true') return v === true;
+                    if (n === 'false') return v === false;
+                    if (n === 'null') return v == null;
+                    return self.types.check(v, variant);
+                  }
+                  return false;
+                });
+                if (!ok) throw new Error("Variable '" + varName + "': value must be one of the declared union variants, got " + self._typeOf(v) + "(" + v + ")");
+              }
+            };
+          }
+
+          // clamp constraint (fnum/fint)
+          let clampFn = null;
+          if (mods.clampType) {
+            const rangeExpr = mods.clampExpr;
+            clampFn = (v) => {
+              const range = self.evaluate(rangeExpr, scope);
+              const arr = range instanceof NovaArray ? range.inner : (Array.isArray(range) ? range : [range]);
+              const min = Number(arr[0] ?? -Infinity), max = Number(arr[1] ?? Infinity);
+              let n = typeof v === 'number' ? v : Number(v);
+              n = Math.min(max, Math.max(min, n));
+              if (mods.clampType === 'fint') n = Math.trunc(n);
+              return n;
+            };
+          }
+
+          // Build getter/setter functions
+          const getterFn = mods.getter ? this.evaluate(mods.getter, scope) : null;
+          const setterFn = mods.setter ? this.evaluate(mods.setter, scope) : null;
+
+          // State
+          let _val = val;
+          let _frozen = false;
+          let _lazyReady = !mods.lazy;
+          const _lazyNode = mods.lazy ? node.value : null;
+
+          const applySet = (v) => {
+            if ((mods.frozen || mods.once) && _frozen) throw new Error("Variable '" + varName + "' is " + (mods.once ? 'write-once and already set' : 'frozen and cannot be reassigned'));
+            if (mods.nonull && (v === null || v === undefined || (typeof v === 'symbol' && v.toString().includes('NOVA_NULL')) || v instanceof NovaNull)) throw new Error("Variable '" + varName + "' cannot be null or undefined");
+            if (clampFn) v = clampFn(v);
+            if (typeConstraint) typeConstraint(v);
+            const old = _val;
+            if (setterFn) {
+              const result = self._call(setterFn, [v, old]);
+              if (result !== undefined) v = result;
+            }
+            if (mods.tracked) console.log('[tracked] ' + varName + ': ' + self.stringify(old) + ' → ' + self.stringify(v));
+            _val = v;
+            _lazyReady = true;
+          };
+
+          const applyGet = () => {
+            if (!_lazyReady) {
+              _val = self.evaluate(_lazyNode, scope);
+              if (clampFn) _val = clampFn(_val);
+              if (mods.tracked) console.log('[tracked] ' + varName + ': (lazy init) → ' + self.stringify(_val));
+              _lazyReady = true;
+            }
+            if (getterFn) return self._call(getterFn, [_val]);
+            return _val;
+          };
+
+          // Apply initial value — run through full pipeline including setter
+          if (val !== undefined) {
+            if (clampFn) val = clampFn(val);
+            if (typeConstraint) typeConstraint(val);
+            if (setterFn) {
+              const result = self._call(setterFn, [val, undefined]);
+              if (result !== undefined) val = result;
+            }
+            if (mods.tracked) console.log('[tracked] ' + varName + ': (init) → ' + self.stringify(val));
+            _val = val;
+          }
+          // After init: freeze if frozen or once
+          if (mods.frozen || mods.once) _frozen = true;
+
+          // Register as descriptor in scope
+          scope.variables[varName] = { read: applyGet, write: applySet };
+          return _val;
         }
-        return scope.set(node.name, val, node.isConst);
+
+        return scope.setOwn(node.name, val, node.isConst);
+      }
+
+      case 'dot_cmd': {
+        return this.dot_commands[node.cmd.value](...node.args)
       }
 
       // ── branch ──
@@ -1224,38 +3312,72 @@ class Executor {
         while (current && !executed) {
           switch (current.type) {
             case 'if': {
-              if (this.evaluate(current.args, scope)) { this.runLoop(current.body, scope); executed = true; }
-              else current = current.next;
+              if (this.evaluate(current.args, scope)) {
+                const bs = new Scope('block', scope, this.globalScope);
+                const _sig = this.runLoop(current.body, bs);
+                executed = true;
+                if (_sig === 'break') throw { __break: true };
+                if (_sig === 'continue') throw { __continue: true };
+              } else current = current.next;
               break;
             }
-            case 'else': { this.runLoop(current.body, scope); executed = true; break; }
-            case 'unless': { if (!this.evaluate(current.args, scope)) this.runLoop(current.body, scope); executed = true; break; }
+            case 'else': {
+              const bs = new Scope('block', scope, this.globalScope);
+              const _sig = this.runLoop(current.body, bs);
+              executed = true;
+              if (_sig === 'break') throw { __break: true };
+              if (_sig === 'continue') throw { __continue: true };
+              break;
+            }
+            case 'unless': {
+              if (!this.evaluate(current.args, scope)) {
+                const bs = new Scope('block', scope, this.globalScope);
+                const _sig = this.runLoop(current.body, bs);
+                if (_sig === 'break') throw { __break: true };
+                if (_sig === 'continue') throw { __continue: true };
+              }
+              executed = true; break;
+            }
             case 'while': {
               const c = Array.isArray(current.args) ? current.args[0] : current.args;
-              while (this.evaluate(c, scope)) { if (this.runLoop(current.body, scope) === 'break') break; }
+              while (this.evaluate(c, scope)) {
+                const bs = new Scope('block', scope, this.globalScope);
+                if (this.runLoop(current.body, bs) === 'break') break;
+              }
               executed = true; break;
             }
             case 'until': {
               const c = Array.isArray(current.args) ? current.args[0] : current.args;
-              while (!this.evaluate(c, scope)) { if (this.runLoop(current.body, scope) === 'break') break; }
+              while (!this.evaluate(c, scope)) {
+                const bs = new Scope('block', scope, this.globalScope);
+                if (this.runLoop(current.body, bs) === 'break') break;
+              }
               executed = true; break;
             }
             case 'do': {
               const c = Array.isArray(current.args) ? current.args[0] : current.args;
-              do { if (this.runLoop(current.body, scope) === 'break') break; } while (this.evaluate(c, scope));
+              do {
+                const bs = new Scope('block', scope, this.globalScope);
+                if (this.runLoop(current.body, bs) === 'break') break;
+              } while (this.evaluate(c, scope));
               executed = true; break;
             }
             case 'repeat': {
               const t = this.evaluate(Array.isArray(current.args) ? current.args[0] : current.args, scope);
-              for (let i = 0; i < t; i++) { if (this.runLoop(current.body, scope) === 'break') break; }
+              for (let i = 0; i < t; i++) {
+                const bs = new Scope('block', scope, this.globalScope);
+                if (this.runLoop(current.body, bs) === 'break') break;
+              }
               executed = true; break;
             }
             case 'for': {
               const [init, cond, upd] = current.args;
-              if (init) this.execute(init, scope);
-              while (!cond || this.evaluate(cond, scope)) {
-                if (this.runLoop(current.body, scope) === 'break') break;
-                if (upd) this.execute(upd, scope);
+              const bs = new Scope('block', scope, this.globalScope);
+              if (init) this.execute(init, bs);
+              while (!cond || this.evaluate(cond, bs)) {
+                const loopBs = new Scope('block', bs, this.globalScope);
+                if (this.runLoop(current.body, loopBs) === 'break') break;
+                if (upd) this.execute(upd, bs);
               }
               executed = true; break;
             }
@@ -1267,7 +3389,11 @@ class Executor {
 
       case 'for_of': {
         const it = this._toIterable(this.evaluate(node.iterable, scope));
-        for (const val of it) { scope.set(node.varName, val); if (this.runLoop(node.body, scope) === 'break') break; }
+        for (const val of it) {
+          const bs = new Scope('block', scope, this.globalScope);
+          bs.set(node.varName, val);
+          if (this.runLoop(node.body, bs) === 'break') break;
+        }
         break;
       }
       case 'for_in': {
@@ -1276,15 +3402,20 @@ class Executor {
           : obj instanceof NovaStruct ? Object.keys(obj.inner)
             : obj instanceof Scope ? Object.keys(obj.variables).filter(k => k !== 'scope' && k !== 'array')
               : Object.keys(obj || {});
-        for (const key of keys) { scope.set(node.varName, key); if (this.runLoop(node.body, scope) === 'break') break; }
+        for (const key of keys) {
+          const bs = new Scope('block', scope, this.globalScope);
+          bs.set(node.varName, key);
+          if (this.runLoop(node.body, bs) === 'break') break;
+        }
         break;
       }
       case 'each': {
         const it = this._toIterable(this.evaluate(node.iterable, scope));
         for (let i = 0; i < it.length; i++) {
-          scope.set(node.varName, it[i]);
-          if (node.indexName) scope.set(node.indexName, i);
-          if (this.runLoop(node.body, scope) === 'break') break;
+          const bs = new Scope('block', scope, this.globalScope);
+          bs.set(node.varName, it[i]);
+          if (node.indexName) bs.set(node.indexName, i);
+          if (this.runLoop(node.body, bs) === 'break') break;
         }
         break;
       }
@@ -1329,9 +3460,13 @@ class Executor {
         const name = this.stringify(this.evaluate(node.event, scope));
         const val = node.value ? this.evaluate(node.value, scope) : undefined;
         for (const h of (this.eventBus.get(name) || [])) {
-          const hs = new Scope('function', scope, this.globalScope);
-          if (h.param) hs.set(h.param, val);
-          this.runLoop(h.body, hs);
+          if (h._native && typeof h._native === 'function') {
+            try { h._native(val); } catch (_) { }
+          } else {
+            const hs = new Scope('function', scope, this.globalScope);
+            if (h.param) hs.set(h.param, val);
+            this.runLoop(h.body, hs);
+          }
         }
         break;
       }
@@ -1426,6 +3561,33 @@ class Executor {
       case 'eval': {
         return this.execute(node.code, scope);
       }
+
+      case 'register_escape': {
+        // register_escape NAME expr
+        // Registers a custom escape sequence into the lexer's CUSTOM_ESCAPES map.
+        // The value can be:
+        //   - a string → used as the literal replacement
+        //   - a function → called with (args[]) at lex time on future strings
+        //     (note: already-lexed strings are not retroactively affected)
+        const { CUSTOM_ESCAPES } = require('./lexer');
+        const val = this.evaluate(node.value, scope);
+        if (typeof val === 'string' || typeof val === 'function') {
+          CUSTOM_ESCAPES.set(node.name, val);
+        } else if (val && typeof val === 'object' && typeof val.__call === 'function') {
+          // Nova function — wrap as JS function that calls it
+          const novafn = val;
+          CUSTOM_ESCAPES.set(node.name, (args) => {
+            try {
+              const childScope = scope.child();
+              return String(this._callFunction(novafn, args, childScope) ?? '');
+            } catch (e) { return ''; }
+          });
+        } else {
+          CUSTOM_ESCAPES.set(node.name, String(val ?? ''));
+        }
+        return undefined;
+      }
+
       case 'import': {
         const exports = this._loadModuleExports(node.source, scope);
         if (Array.isArray(node.names) && node.names.length > 0) {
@@ -1481,6 +3643,7 @@ class Executor {
         return undefined;
       }
       default: {
+        if (Array.isArray(node)) return this.run(node)
         const r = this._execNovaClassic(node, scope);
         if (r !== null) return r;
         this.error('Unknown node kind: ' + node.kind, node);
@@ -1496,6 +3659,10 @@ class Executor {
     switch (expr.kind) {
       case 'EOF': return undefined;
 
+      case 'regex_literal':
+        let pattern = this.evaluate(expr.pattern);
+        return new RegExp(typeof pattern === 'string' ? pattern : pattern.inner, expr.flags);
+
       case 'url_literal':
         return expr.value;
 
@@ -1508,7 +3675,7 @@ class Executor {
       case 'fetch_expr': {
         const url = this.evaluate(expr.url, scope);
         const options = expr.options ? this.evaluate(expr.options, scope) : null;
-        return this._syncFetch(url, options);
+        return fetch(url, options);
       }
 
       case 'value': {
@@ -1516,13 +3683,160 @@ class Executor {
         if (typeof raw === 'string' || typeof raw === 'number') return raw;
         if (typeof raw === 'symbol') {
           const s = raw.toString();
-          if (s === 'Symbol(NOVA_TRUE)') return new NovaBool(true);
-          if (s === 'Symbol(NOVA_FALSE)') return new NovaBool(false);
+          if (s === 'Symbol(NOVA_TRUE)') return true;
+          if (s === 'Symbol(NOVA_FALSE)') return false;
           if (s === 'Symbol(NOVA_NULL)') return new NovaNull();
         }
         return raw;
       }
 
+      // ── Dynamic / meta variables ──────────────────────────────────────────
+      case 'dvar': {
+        const _os = require('os');
+        const _pth = require('path');
+        const _cry = require('crypto');
+        const dname = expr.name;
+
+        switch (dname) {
+          case 'default':
+            // Return the sentinel so runFunctionNode knows to use the param default
+            return DEFAULT_SENTINEL;
+
+          case '__line__':
+            return expr.srcLine ?? 0;
+
+          case '__col__':
+            return expr.srcCol ?? 0;
+
+          case '__file__': {
+            const f = process.argv[1];
+            return f ? _pth.resolve(f) : '<repl>';
+          }
+
+          case '__dirname__': {
+            const f = process.argv[1];
+            return f ? _pth.dirname(_pth.resolve(f)) : process.cwd();
+          }
+
+          case '__func__': {
+            // Walk scope chain looking for a named function scope
+            let s = scope;
+            while (s) {
+              if (s.kind === 'function' && s._funcName) return s._funcName;
+              s = s.parent;
+            }
+            return '<top>';
+          }
+
+          case '__date__': {
+            const d = new Date();
+            return d.toISOString().slice(0, 10);
+          }
+
+          case '__time__': {
+            const d = new Date();
+            return d.toISOString().slice(11, 19);
+          }
+
+          case '__datetime__':
+            return new Date().toISOString();
+
+          case '__timestamp__':
+            return Date.now();
+
+          case '__version__':
+            return '2.0';
+
+          case '__pid__':
+            return process.pid;
+
+          case '__platform__':
+            return process.platform;
+
+          case '__arch__':
+            return _os.arch();
+
+          case '__argv__':
+            return new NovaArray(process.argv);
+
+          case '__env__':
+            return new NovaObject({ ...process.env });
+
+          case '__scope__':
+            return scope;
+
+          case '__caller__': {
+            let s2 = scope && scope.parent;
+            while (s2) {
+              if (s2.kind === 'function' && s2._funcName) return s2._funcName;
+              s2 = s2.parent;
+            }
+            return '<top>';
+          }
+
+          case '__module__': {
+            const f2 = process.argv[1];
+            if (!f2) return '<repl>';
+            return _pth.basename(f2, _pth.extname(f2));
+          }
+
+          case '__namespace__': {
+            // Walk scope looking for a namespace marker
+            let s3 = scope;
+            while (s3) {
+              if (s3._namespace) return s3._namespace;
+              s3 = s3.parent;
+            }
+            return null;
+          }
+
+          case '__random__':
+            return Math.random();
+
+          case '__uuid__':
+            return _cry.randomUUID ? _cry.randomUUID() : _cry.randomBytes(16).toString('hex');
+
+          case '__iter__': {
+            // Walk scopes looking for an active loop counter
+            let s4 = scope;
+            while (s4) {
+              if (s4._loopIndex !== undefined) return s4._loopIndex;
+              s4 = s4.parent;
+            }
+            return -1;
+          }
+
+          case '__stack__': {
+            const frames = [];
+            let s5 = scope;
+            while (s5) {
+              if (s5.kind === 'function') frames.push(s5._funcName || '<anon>');
+              s5 = s5.parent;
+            }
+            return new NovaArray(frames);
+          }
+
+          default: {
+            // Check kit-registered custom dvars
+            if (this._customDvars && this._customDvars.has(dname)) {
+              try { return this._customDvars.get(dname)(scope, this); } catch (_) { return null; }
+            }
+            return null;
+          }
+        }
+      }
+
+      // { key? true/false } — boolean prop literal
+      case 'bool': return new NovaBool(expr.value);
+
+      // { key? <expr> } where expr must evaluate to a boolean
+      case 'bool_assert': {
+        const v = this.evaluate(expr.expr, scope);
+        const raw = v instanceof NovaBool ? v.valueOf() : v;
+        if (typeof raw !== 'boolean') throw new Error("Boolean property expression must be true or false, got " + this._typeOf(v));
+        return new NovaBool(raw);
+      }
+
       // inline function node -> make callable
       case 'function': {
         const fn = (...args) => this.runFunctionNode(expr, scope, args);
@@ -1537,12 +3851,15 @@ class Executor {
       }
 
       case 'ref': {
-        let i = 0;
         function getRef(nv, namee = expr.name) {
-          if (scope.has(namee)) {
-            return scope.get(namee)
+          const val = scope.get(namee);
+          if (val !== null && val !== undefined) {
+            return val;
           } else if (nv.blocks.has(namee)) {
             return nv.runFunctionNode(nv.blocks.get(namee), nv.blocks.get(namee).scope, [])
+          } else if (nv._customDvars && nv._customDvars.has(namee)) {
+            // Custom dynamic variable registered via dvars or nova.registerDvar
+            try { return nv._customDvars.get(namee)(scope, nv); } catch (_) { return null; }
           } else if (nv.options.unknownRefs) {
             if (nv.optionDecls.hasOwnProperty('unknownRefs')) {
               return nv.optionDecls.unknownRefs(namee)
@@ -1571,6 +3888,8 @@ class Executor {
 
       case 'object': {
         const obj = {};
+        const boolKeys = new Set();
+        let metaDescriptor = null;
         for (const entry of expr.props) {
           if (entry.kind === 'spread') {
             const v = this.evaluate(entry.value, scope);
@@ -1578,8 +3897,20 @@ class Executor {
               : v instanceof Scope ? v.variables : (v && typeof v === 'object' ? v : {});
             Object.assign(obj, src);
           } else if (entry.kind === 'computed') {
-            const key = this.stringify(this.evaluate(entry.key, scope));
-            obj[key] = this.evaluate(entry.value, scope);
+            const keyVal = this.evaluate(entry.key, scope);
+            const key = this.stringify(keyVal);
+            // Detect [method] key used as meta-protocol marker
+            if (key === '__meta__' || (entry.key.kind === 'ref' && entry.key.name === 'method')) {
+              metaDescriptor = this.evaluate(entry.value, scope);
+            } else if (key === '__expr__' || (entry.key.kind === 'ref' && entry.key.name === 'expr')) {
+              //detect [expr] key
+              obj['.expr'] = this.evaluate(entry.value, scope);
+            } else if (key === '__op__' || (entry.key.kind === 'ref' && entry.key.name === 'op')) {
+              //detect [operator] key
+              obj['__operators'] = this.evaluate(entry.value, scope);
+            } else {
+              obj[key] = this.evaluate(entry.value, scope);
+            }
           } else {
             // prop or method shorthand
             const val = entry.value;
@@ -1587,12 +3918,52 @@ class Executor {
               const fn = (...args) => this.runFunctionNode(val, scope, args);
               fn.args = val.args; fn.body = val.body; try { Object.defineProperty(fn, "name", { value: val.name || entry.key, configurable: true }); } catch (_) { }
               obj[entry.key] = fn;
+            } else if (entry.boolProp) {
+              // { key? true/false } — value must be boolean; record key as bool-constrained
+              const bv = this.evaluate(val, scope);
+              const raw = bv instanceof NovaBool ? bv.valueOf() : bv;
+              if (typeof raw !== 'boolean') throw new Error("Property '" + entry.key + "' declared with ? must be true or false");
+              obj[entry.key] = raw;
+              boolKeys.add(entry.key);
             } else {
               obj[entry.key] = this.evaluate(val, scope);
             }
           }
         }
-        return new NovaObject(obj);
+        const novaObj = new NovaObject(obj);
+        // Build combined meta: user descriptor + bool-key enforcement
+        const hasBoolKeys = boolKeys.size > 0;
+        if (metaDescriptor || hasBoolKeys) {
+          const md = metaDescriptor
+            ? (metaDescriptor instanceof NovaObject ? metaDescriptor.inner : metaDescriptor)
+            : {};
+          const self2 = this;
+          const capturedScope = scope;
+          const callMeta = (fn, args) => {
+            if (!fn) return undefined;
+            if (typeof fn === 'function') return fn(...args);
+            if (fn && fn.args !== undefined && fn.body) return self2.runFunctionNode(fn, capturedScope, args);
+          };
+          novaObj.attachMeta({
+            get: md.get ? (k, v) => callMeta(md.get, [k, v]) : null,
+            set: (k, v, inner) => {
+              // Bool-key enforcement always runs first
+              if (hasBoolKeys && boolKeys.has(k)) {
+                const raw = v instanceof NovaBool ? v.valueOf() : v;
+                if (typeof raw !== 'boolean') throw new Error("Property '" + k + "' is bool-constrained and must be true or false, got " + self2._typeOf(v));
+                v = raw; // normalise to JS bool
+              }
+              if (md.set) {
+                const result = callMeta(md.set, [k, v]);
+                if (result !== false) inner[k] = v;
+              } else {
+                inner[k] = v;
+              }
+            },
+            missing: md.missing ? (k) => callMeta(md.missing, [k]) : null,
+          });
+        }
+        return novaObj;
       }
 
       case 'new_expr': {
@@ -1607,7 +3978,8 @@ class Executor {
 
       case 'assign': {
         const val = this.evaluate(expr.value, scope);
-        const n = expr.name;
+        let n = expr.name;
+        if (n.kind === 'dexpr') n = { name: this.evaluate(n.code, scope) }
         if (n.kind === 'deref') {
           const ptr = this.evaluate(n.operand, scope);
           if (!(ptr instanceof NovaPointer)) this.error('Deref non-pointer', expr);
@@ -1628,6 +4000,7 @@ class Executor {
           else if (obj && typeof obj === 'object') obj[idx] = val;
           return val;
         }
+        if (n.kind === 'link') return this.evaluate({ kind: 'assign', name: n.linked, value: { kind: 'value', value: val } }, scope);
         return scope.set(n.name != null ? n.name : n, val);
       }
 
@@ -1650,6 +4023,32 @@ class Executor {
       case 'ternary': return this.evaluate(expr.condition, scope)
         ? this.evaluate(expr.consequent, scope) : this.evaluate(expr.alternate, scope);
 
+      case 'if_ternary': {
+        let cond = this.evaluate(expr.cond, scope);
+        if (cond) { return this.evaluate(expr.operand, scope) }
+        else if (expr.elseExpr) { return this.evaluate(expr.elseExpr, scope) }
+      }
+
+      case 'run_expr': return this.execute(expr.code, scope)
+
+      case 'native':
+	let val = this.evaluate(expr.value);
+        return val instanceof NovaValue ? val.inner : val;
+
+      case 'ast': return { kind:"ast", ast: expr.ast };
+
+      case 'link': return {
+        read: () => this.evaluate(expr.linked),
+        write: (val) =>
+          this.evaluate({
+            kind: 'assign',
+            name: expr.linked,
+            value: { kind: 'value', value: val }
+          }, scope)
+      };
+
+      case 'dexpr': return this.evaluate(expr.code, scope);
+
       case 'rate_cast': {
         const val = this.evaluate(expr.value, scope);
         return this._rateCast(val, expr.cast_type);
@@ -1716,7 +4115,7 @@ class Executor {
         if (obj == null || obj instanceof NovaNull) return null;
         if (obj instanceof NovaStruct) return obj.inner[expr.name];
         if (obj instanceof NovaObject || obj instanceof NovaArray) return obj.get(expr.name);
-        return obj instanceof Scope ? obj.get(expr.name) : obj?.[expr.name];
+        return obj?.[expr.name];
       }
       case 'optional_subscript': {
         const obj = this.evaluate(expr.object, scope);
@@ -1737,6 +4136,14 @@ class Executor {
 
       case 'arrowfunc': {
         const self = this;
+        // If the lambda is marked async or generator, build a proper fn node
+        // so runFunctionNode handles the Promise chain / yield collection.
+        if (expr.isAsync || expr.isGenerator) {
+          const fn = (...args) => self.runFunctionNode(expr, scope, args);
+          fn.args = expr.args; fn.body = expr.body;
+          fn.isAsync = expr.isAsync; fn.isGenerator = expr.isGenerator;
+          return fn;
+        }
         const fn = (...args) => {
           const ls = new Scope('function', scope, self.globalScope);
           (expr.args || []).forEach((name, i) => ls.set(typeof name === 'string' ? name : name.name, args[i]));
@@ -1756,7 +4163,7 @@ class Executor {
         if (obj instanceof NovaStruct) return this._structGet(obj, pn, scope);
         // NovaArray: check _arrayMethod first so built-in names take priority
         if (obj instanceof NovaArray) {
-          const m = this._arrayMethod(obj, pn);
+          const m = this._arrayMethod(obj, pn, scope);
           if (m !== undefined) return m;
           const v = obj.get(pn);
           return v !== undefined ? v : null;
@@ -1767,7 +4174,8 @@ class Executor {
           const m = this._objectMethod(obj, pn);
           return m !== undefined ? m : null;
         }
-        return obj instanceof Scope ? obj.get(pn) : (obj != null ? obj[pn] : null);
+        if (!(Object.hasOwnProperty(obj, 'name')) && pn === 'name') return (typeof expr.object.name === 'string') ? expr.object.name : 'anon';
+        return (obj != null ? obj[pn] : null);
       }
 
       case 'call': {
@@ -1780,7 +4188,7 @@ class Executor {
           if (obj instanceof NovaStruct) fn = this._structGet(obj, expr.name.name, scope);
           else if (obj instanceof Scope) fn = obj.get(expr.name.name);
           else if (obj instanceof NovaArray) {
-            fn = this._arrayMethod(obj, expr.name.name);
+            fn = this._arrayMethod(obj, expr.name.name, scope);
             if (fn === undefined) fn = obj.get(expr.name.name);
           }
           else if (obj instanceof NovaObject) {
@@ -1805,11 +4213,25 @@ class Executor {
 
       case 'binary': {
         const op = expr.operator;
-        if (op === '&&' || op === 'and') { const l = this.evaluate(expr.left, scope); return l ? this.evaluate(expr.right, scope) : l; }
-        if (op === '||' || op === 'or') { const l = this.evaluate(expr.left, scope); return l ? l : this.evaluate(expr.right, scope); }
-        if (op === '??') { const l = this.evaluate(expr.left, scope); return (l == null || l instanceof NovaNull) ? this.evaluate(expr.right, scope) : l; }
         const left = this.evaluate(expr.left, scope);
         const right = this.evaluate(expr.right, scope);
+        if (left instanceof NovaObject) {
+          let overload = left?.get?.('__operators')?.get?.('binary')?.get?.(expr.operator);
+          if (overload) return overload(right);
+        } else if (typeof left === 'object') {
+          let overload = left?.__operators?.binary?.[op]
+          if (overload) return overload(right);
+        }
+        if (right instanceof NovaObject) {
+          let overload = right?.get?.('__operators')?.get?.('binary')?.get?.(expr.operator);
+          if (overload) return overload(left);
+        } else if (typeof right === 'object') {
+          let overload = right?.__operators?.binary?.[op]
+          if (overload) return overload(left);
+        }
+        if (op === '&&' || op === 'and') return left ? right : left;
+        if (op === '||' || op === 'or') return left ? left : right
+        if (op === '??') return (left == null || left instanceof NovaNull) ? right : left;
         switch (op) {
           case '+': return left + right; case '-': return left - right;
           case '*': return left * right; case '/': return left / right; case '%': return left % right;
@@ -1936,13 +4358,8 @@ class Executor {
       }
 
       case 'unary': {
+        // ONE-Special handlong ones, (only delete)
         switch (expr.operator) {
-          case '-': return -this.evaluate(expr.operand, scope);
-          case '+': return +this.evaluate(expr.operand, scope);
-          case '!': case 'not': return !this.evaluate(expr.operand, scope);
-          case '~': return ~this.evaluate(expr.operand, scope);
-          case 'typeof': return this._typeOf(this.evaluate(expr.operand, scope));
-          case 'void': this.evaluate(expr.operand, scope); return undefined;
           case 'delete': {
             const o = expr.operand;
             if (o.kind === 'ref') return scope.delete(o.name);
@@ -1952,8 +4369,7 @@ class Executor {
               else if (obj instanceof Scope) obj.delete(o.name);
               else delete obj[o.name];
               return true;
-            }
-            if (o.kind === 'subscript') {
+            } if (o.kind === 'subscript') {
               const obj = this.evaluate(o.object, scope); const idx = this.evaluate(o.index, scope);
               if (obj instanceof NovaObject || obj instanceof NovaArray) obj.delete(idx);
               else if (obj instanceof Scope) obj.delete(idx);
@@ -1962,6 +4378,19 @@ class Executor {
             }
             this.error('Invalid delete operand', expr);
           }
+        }
+        let operand = this.evaluate(expr.operand, scope);
+        if (operand instanceof NovaObject) {
+          let overload = operand?.get?.('__operators')?.get?.('unary')?.get?.(expr.operator);
+          if (overload) return overload();
+        }
+        switch (expr.operator) {
+          case '-': return -operand
+          case '+': return +operand
+          case '!': case 'not': return !operand
+          case '~': return ~operand
+          case 'typeof': return this._typeOf(operand);
+          case 'void': return undefined;
           default: this.error("Unknown unary operator '" + expr.operator + "'", expr);
         }
       }
@@ -2013,33 +4442,13 @@ class Executor {
 
       case 'await': {
         const val = this.evaluate(expr.operand, scope);
+        // If it's not a Promise, return as-is (mirrors JS behaviour).
         if (!(val instanceof Promise)) return val;
-
-        // ── Sync-block until the promise settles — no real JS async/await ──
-        // SharedArrayBuffer as a cross-turn signal:
-        //   flag[0] === 0  → pending  (Atomics.wait sleeps here)
-        //   flag[0] === 1  → resolved
-        //   flag[0] === 2  → rejected
-        const sab  = new SharedArrayBuffer(8);
-        const flag = new Int32Array(sab);
-        let resolved, rejected;
-
-        this.awaiting = true;
-
-        val.then(
-          (v) => { resolved = v; Atomics.store(flag, 0, 1); Atomics.notify(flag, 0); },
-          (e) => { rejected = e; Atomics.store(flag, 0, 2); Atomics.notify(flag, 0); }
-        );
-
-        // Block synchronously until the microtask above fires.
-        // Atomics.wait is always allowed in Node.js worker threads and the
-        // main thread when --allow-atomics-wait is set (default in most envs).
-        Atomics.wait(flag, 0, 0);
-
-        this.awaiting = false;
-
-        if (Atomics.load(flag, 0) === 2) throw rejected;
-        return resolved;
+        // Return the Promise itself — the caller (runFunctionNode for async fns,
+        // or top-level run) must handle it with .then() chaining.
+        // We signal suspension by throwing an AwaitSuspension so the nearest
+        // async function frame can chain the continuation properly.
+        throw { __awaitSuspension__: true, promise: val };
       }
 
       default: this.error('Unknown expression kind: ' + expr.kind, expr);
@@ -2064,21 +4473,22 @@ class Executor {
   }
 
   // ── built-in array methods ──
-  _arrayMethod(arr, name) {
+  _arrayMethod(arr, name, scope) {
     const inner = arr.inner;
     const self = this;
+    const sc = scope || self.globalScope;
     const wrap = (v) => Array.isArray(v) ? new NovaArray(v) : v;
     switch (name) {
-      case 'map': return (fn) => new NovaArray(inner.map((v, i) => self._call(fn, [v, i])));
-      case 'filter': return (fn) => new NovaArray(inner.filter((v, i) => self._call(fn, [v, i])));
-      case 'reduce': return (fn, init) => inner.reduce((acc, v, i) => self._call(fn, [acc, v, i]), init);
-      case 'find': return (fn) => inner.find((v, i) => self._call(fn, [v, i]));
-      case 'findIndex': return (fn) => inner.findIndex((v, i) => self._call(fn, [v, i]));
-      case 'some': return (fn) => inner.some((v, i) => self._call(fn, [v, i]));
-      case 'every': return (fn) => inner.every((v, i) => self._call(fn, [v, i]));
+      case 'map': return (fn) => new NovaArray(inner.map((v, i) => self._call(fn, [v, i], sc)));
+      case 'filter': return (fn) => new NovaArray(inner.filter((v, i) => self._call(fn, [v, i], sc)));
+      case 'reduce': return (fn, init) => inner.reduce((acc, v, i) => self._call(fn, [acc, v, i], sc), init);
+      case 'find': return (fn) => inner.find((v, i) => self._call(fn, [v, i], sc));
+      case 'findIndex': return (fn) => inner.findIndex((v, i) => self._call(fn, [v, i], sc));
+      case 'some': return (fn) => inner.some((v, i) => self._call(fn, [v, i], sc));
+      case 'every': return (fn) => inner.every((v, i) => self._call(fn, [v, i], sc));
       case 'flat': return (depth = 1) => new NovaArray(inner.flat(depth));
-      case 'flatMap': return (fn) => new NovaArray(inner.flatMap((v, i) => { const r = self._call(fn, [v, i]); return r instanceof NovaArray ? r.inner : r; }));
-      case 'sort': return (fn) => { const copy = [...inner]; copy.sort((a, b) => fn ? self._call(fn, [a, b]) : (a > b ? 1 : a < b ? -1 : 0)); return new NovaArray(copy); };
+      case 'flatMap': return (fn) => new NovaArray(inner.flatMap((v, i) => { const r = self._call(fn, [v, i], sc); return r instanceof NovaArray ? r.inner : r; }));
+      case 'sort': return (fn) => { const copy = [...inner]; copy.sort((a, b) => fn ? self._call(fn, [a, b], sc) : (a > b ? 1 : a < b ? -1 : 0)); return new NovaArray(copy); };
       case 'reverse': return () => new NovaArray([...inner].reverse());
       case 'slice': return (a, b) => new NovaArray(inner.slice(a, b));
       case 'splice': return (start, del, ...items) => { const removed = inner.splice(start, del ?? inner.length, ...items); return new NovaArray(removed); };
@@ -2091,7 +4501,7 @@ class Executor {
       case 'unshift': return (...vals) => { inner.unshift(...vals); return inner.length; };
       case 'concat': return (...others) => new NovaArray(inner.concat(...others.map(o => o instanceof NovaArray ? o.inner : o)));
       case 'fill': return (v, s, e) => { inner.fill(v, s, e); return arr; };
-      case 'forEach': return (fn) => new NovaArray(inner.forEach((v, i) => self._call(fn, [v, i])));
+      case 'forEach': return (fn) => new NovaArray(inner.forEach((v, i) => self._call(fn, [v, i], sc)));
       case 'keys': return () => new NovaArray([...inner.keys()]);
       case 'values': return () => new NovaArray([...inner.values()]);
       case 'entries': return () => new NovaArray(inner.map((v, i) => new NovaArray([i, v])));
@@ -2105,7 +4515,7 @@ class Executor {
       case 'groupBy': return (fn) => {
         const groups = {};
         inner.forEach(v => {
-          const key = self._call(fn, [v]);
+          const key = self._call(fn, [v], sc);
           if (!groups[key]) groups[key] = [];
           groups[key].push(v);
         });
@@ -2121,8 +4531,6 @@ class Executor {
         }
         return new NovaArray(copy);
       };
-      case 'reverse': return () => new NovaArray([...inner].reverse());
-      case 'sort': return (fn) => { const copy = [...inner]; copy.sort((a, b) => fn ? self._call(fn, [a, b]) : (a > b ? 1 : a < b ? -1 : 0)); return new NovaArray(copy); };
       case 'min': return () => inner.reduce((min, v) => v < min ? v : min, inner[0]);
       case 'max': return () => inner.reduce((max, v) => v > max ? v : max, inner[0]);
       case 'sum': return () => inner.reduce((acc, v) => acc + v, 0);
@@ -2175,9 +4583,9 @@ class Executor {
   }
 
   // call a nova or JS fn
-  _call(fn, args) {
+  _call(fn, args, scope) {
     if (typeof fn === 'function') return fn(...args);
-    if (fn && fn.args !== undefined && fn.body) return this.runFunctionNode(fn, this.globalScope, args);
+    if (fn && fn.args !== undefined && fn.body) return this.runFunctionNode(fn, scope || this.globalScope, args);
     return fn;
   }
 
@@ -3199,4 +5607,4 @@ req.end();`;
   }
 }
 
-module.exports = { Executor, Scope, TypeRegistry };
+module.exports = { Executor, Scope, TypeRegistry };