tjs-lang 0.8.0 → 0.8.2

package/docs/README.md

@@ -20,9 +20,11 @@ ASTs that run sandboxed with fuel (gas) limits.
 | Document | Description |
 |----------|-------------|
 | [Technical Context](https://github.com/tonioloewald/tjs-lang/blob/main/CONTEXT.md) | Architecture deep dive, design decisions |
+| [The Universal Endpoint](https://github.com/tonioloewald/tjs-lang/blob/main/docs/universal-endpoint.md) | Isomorphic atoms: the same agent + one security model running in the data center and the browser client |
 | [WASM Quick Start](https://github.com/tonioloewald/tjs-lang/blob/main/docs/WASM-QUICKSTART.md) | Build WASM-accelerated libraries with zero toolchain setup |
 | [Design Patterns](https://github.com/tonioloewald/tjs-lang/blob/main/guides/patterns.md) | Common patterns in TJS and AJS |
 | [Schema Validation](https://github.com/tonioloewald/tjs-lang/blob/main/guides/tosijs-schema.md) | Working with tosijs-schema |
+| [LM Studio Setup](https://github.com/tonioloewald/tjs-lang/blob/main/docs/lm-studio-setup.md) | Running the LLM test suite locally — install, model loading, leaked-VRAM/CORS gotchas |
 
 ## Examples
 

package/docs/lm-studio-setup.md

@@ -0,0 +1,143 @@
+# Running the LLM test suite (LM Studio setup)
+
+The LLM-dependent tests (`bun test` without `SKIP_LLM_TESTS`) talk to a local
+**LM Studio** OpenAI-compatible server. This doc captures the setup and the
+pain points hit getting it working on Linux — read the troubleshooting section
+first if a model won't load or LLM tests fail fast.
+
+## What has to be true
+
+- LM Studio server running at **`http://localhost:1234/v1`** — this is hardcoded
+  (`src/batteries/models.ts` → `DEFAULT_BASE_URL`), **no env override**. Any
+  OpenAI-compatible server on 1234 works (Ollama bound to 1234 is a drop-in).
+- **One chat LLM and one embedding model loaded** — the model audit
+  (`src/batteries/audit.ts`) needs both; it auto-detects a structured-output LLM
+  from the chat model.
+- **CORS enabled** in LM Studio (see below) — required for the playground-example
+  tests, which run under happy-dom and send a CORS preflight.
+
+## Quick start (happy path)
+
+1. Install LM Studio, **update the runtimes** (see Install).
+2. Load a chat LLM + an embedding model (e.g. `nomic-embed-text-v1.5`).
+3. Developer → **Start Server** (port 1234) → **Enable CORS**.
+4. Warm a clean audit cache, then run the full suite:
+   ```bash
+   rm -f .models.cache.json
+   bun run test:llm        # warms + writes one clean cache, in isolation
+   bun test                # full suite reuses that cache (avoids the race below)
+   ```
+
+Sanity check the server (note **127.0.0.1**, not `localhost` — see IPv6 note):
+```bash
+curl -s http://127.0.0.1:1234/v1/models | grep -oE '"id":"[^"]*"'
+~/.lmstudio/bin/lms ps     # what's loaded + on GPU or CPU
+```
+
+## Install (Linux)
+
+- **AppImage only** — no `.deb`/apt/snap. On the Ubuntu 24.04 / Mint 22 base,
+  install `libfuse2t64` first, then `chmod +x` and run.
+- Requires **x86-64 + AVX2** (`grep -w avx2 /proc/cpuinfo`).
+- **Update the inference runtimes after installing.** A fresh install ships with
+  old engines; recent model architectures (Gemma 3/3n/QAT, etc.) won't load until
+  you update. LM Studio → Settings → **Runtime** → update all. (A fresh install
+  needed many updates.)
+- The CLI lives at `~/.lmstudio/bin/lms` (`lms bootstrap` adds it to PATH).
+
+## Enable CORS (needed for playground-example tests)
+
+`demo/examples.test.ts` runs under happy-dom (a browser-like env) and issues a
+CORS preflight `OPTIONS` to `localhost:1234`. Without CORS enabled LM Studio
+answers `400` and those ~8 tests fail with **"Cross-Origin Request Blocked"**.
+Toggle **Enable CORS** in the LM Studio server settings. (Production doesn't hit
+this — the playground proxies LLM calls through the `/run` cloud function.)
+
+## Troubleshooting
+
+### "Error loading model. (Exit code: null)" — crash partway through loading
+
+The loader process died, almost always **out of VRAM** (it crashes mid-offload —
+e.g. at ~53% of a 5–6.5 GB model) or, rarely, an architecture the runtime can't
+build. Diagnose:
+
+```bash
+nvidia-smi --query-gpu=memory.used,memory.free --format=csv,noheader
+nvidia-smi --query-compute-apps=pid,used_memory,process_name --format=csv
+```
+
+Two fixes:
+
+- **Free VRAM** (see stray-worker note) so the model fits, or
+- **Force CPU load** — slower but reliable, fits in system RAM:
+  ```bash
+  ~/.lmstudio/bin/lms load <model-id> --gpu off
+  ```
+
+The recent **gemma-4 / gemma-3n** models are multimodal (note the `mmproj-*.gguf`
+projector files) and memory-heavy. A 12 GB card runs them fine **once VRAM is
+actually free**. Blackwell GPUs (RTX 50xx) need a recent driver — 595+/CUDA 13
+works.
+
+### Leaked VRAM / killing the stray `node` worker — THE big one
+
+LM Studio's **embedding worker** (`~/.lmstudio/.internal/utils/node` running
+`embeddingworker.js`) can leak VRAM — observed holding **6.5 GB** while only
+~700 MB of embedding models were loaded — and it is a **detached child process
+that survives app restarts.** Closing/reopening the LM Studio window does *not*
+reap it, so VRAM stays pinned and every subsequent GPU load crashes. Failed
+GPU loads compound the leak (partial offloads never released).
+
+Reclaim it by killing the workers directly, then verify before relaunching:
+
+```bash
+pkill -f 'LM-Studio/lm-studio'
+pkill -f '.lmstudio/.internal/utils/node'   # the stuck embedding/resource workers
+sleep 2
+nvidia-smi --query-gpu=memory.used,memory.free --format=csv,noheader  # should drop to ~1 GB used
+```
+
+Then relaunch LM Studio fresh, Start Server, reload both models. If "restarting"
+didn't help, you didn't kill these — check `nvidia-smi --query-compute-apps`.
+
+### `curl localhost:1234` fails but the server is up
+
+`localhost` may resolve to IPv6 `::1` while LM Studio listens on IPv4
+`0.0.0.0:1234` → connection refused. Use **`127.0.0.1`** for manual probes.
+(`ss -ltn | grep 1234` confirms it's listening regardless.)
+
+### LLM tests fail *fast* (single-digit ms) with "No LLM/embedding available"
+
+The audit classified no usable model and the result is cached. Causes:
+- Models weren't loaded/ready when the audit ran (it caches the bad result for 24h).
+- A model is listed in `/v1/models` (downloaded) but fails to load (see above).
+
+Fix: make sure both model types are loaded and inferring, then **clear the cache**:
+```bash
+rm -f .models.cache.json
+```
+
+### Audit misclassifies models on a parallel run
+
+`.models.cache.json` (cwd, 24h TTL) is shared, and many test files call `audit()`
+concurrently. Clearing the cache right before a full parallel `bun test` makes
+several audits probe **at once**, and under that load classifications come back
+scrambled (embedding models tagged `LLM`, etc.). **Work around it** by writing one
+clean cache in isolation first (`bun run test:llm`) and *not* clearing it before
+the full run. (Proper fix is tracked in TODO — serialize the audit / isolate the
+cache.)
+
+### 3 `TJS Performance > CLI cold start` failures
+
+Known, not LLM-related: `perf.test.ts` asserts cold start `< 200ms`; a loaded or
+slower box measures ~210ms. Ignore, or relax the threshold.
+
+## Command reference
+
+```bash
+~/.lmstudio/bin/lms ps                 # loaded models, device (GPU/CPU/Local), TTL
+~/.lmstudio/bin/lms server status      # is the OpenAI endpoint up + which port
+~/.lmstudio/bin/lms load <id> --gpu off   # CPU-only load (off | max | 0..1)
+nvidia-smi --query-compute-apps=pid,used_memory,process_name --format=csv
+curl -s http://127.0.0.1:1234/v1/models | grep -oE '"id":"[^"]*"'
+```

package/docs/universal-endpoint.md

@@ -0,0 +1,122 @@
+# The universal endpoint: isomorphic atoms, one security model
+
+> An emergent win. The VM was built to run *untrusted* agent code safely —
+> fuel-metered, capability-sandboxed, monadic errors instead of exceptions.
+> Isomorphism was never a goal. But because of how those pieces fit, the same
+> agent program runs **unchanged in the data center and in the browser client**,
+> with one security model spanning both — and that turned out to be the most
+> valuable property in production.
+
+## What it buys you
+
+In production we ran a **single agent endpoint that exists in two places at
+once**: in the data center, and locally inside the web client. Tools (atoms)
+come in matched pairs — a client-side implementation that can satisfy a request
+from data already loaded in the browser, and a server-side implementation that
+hits the datastore. The agent program is identical on both sides and doesn't
+know which one it's talking to.
+
+Concretely: both endpoints expose a `getRecords` atom.
+
+- **Client `getRecords`** — looks for the records already loaded in the client.
+  If they're there, it returns them with **zero network round-trips**. If they're
+  not, it transparently delegates to the server-side `getRecords`.
+- **Server `getRecords`** — queries the datastore.
+
+Same name, same input/output schema, same authorization envelope. A program
+written against `getRecords` runs locally-first and falls back to the server only
+on a genuine miss — and you never wrote that fallback logic into the program. It
+lives in the atom.
+
+The three wins that fell out:
+
+1. **One security model, front to back.** The same capability/fuel/RBAC envelope
+   is enforced in the browser and on the server — not duplicated, not "the client
+   asks nicely and the server re-checks." The *same rules* run in both places.
+2. **Minimized round-tripping / data locality.** Code travels to the data.
+   Reads that hit already-loaded client state never leave the browser; only real
+   misses go to the server.
+3. **Parallel tools.** The full toolset is available on both sides, so an
+   orchestration can run partly local and partly remote, transparently.
+
+## Why it falls out of the architecture (rather than being bolted on)
+
+Three properties of the AJS/AgentVM design make this work, and none of them were
+added for isomorphism — they were there for *safe sandboxed execution*:
+
+**1. Code is data.** An agent is a JSON AST (`ajs\`...\``/`transpile()`), not
+compiled JavaScript. The same program serializes and runs anywhere a JS
+`AgentVM` exists — a Node server, a Cloud Function, or a browser tab. "Code
+travels to data" stops being a slogan and becomes a deployment option.
+
+**2. The VM is environment-agnostic; all IO is injected.** `AgentVM` has zero IO
+by default. Every side effect arrives through `ctx.capabilities` (`fetch`,
+`store`, `llm`, …) passed to `run()`. So the *same* agent gets browser-flavored
+capabilities in the client and data-center capabilities on the server — the
+program is unaware of the difference. (See `src/vm/runtime.ts` — atoms only ever
+reach the outside world via `ctx.capabilities`.)
+
+**3. Atoms are the seam.** `new AgentVM(customAtoms)` merges environment-specific
+implementations over the core set:
+
+```ts
+// src/vm/vm.ts
+constructor(customAtoms = {}) {
+  this.atoms = { ...coreAtoms, ...customAtoms }
+}
+```
+
+The atom *contract* (op name, input/output schema) is identical across
+environments; the *implementation* differs. The client VM is built with a
+client `getRecords`; the server VM with a server `getRecords`. Swapping the
+implementation per environment is the whole trick — and it's just object spread.
+
+```ts
+// client
+const clientVM = new AgentVM({
+  getRecords: defineAtom('getRecords', In, Out, async (input, ctx) => {
+    const local = findLoaded(input, ctx)            // already in the client?
+    if (local) return local                          // → no round-trip
+    return ctx.capabilities.fetch(SERVER_ENDPOINT, …) // → fall back to server
+  }),
+})
+
+// server
+const serverVM = new AgentVM({
+  getRecords: defineAtom('getRecords', In, Out, async (input, ctx) =>
+    ctx.capabilities.store.query(input)              // hit the datastore
+  ),
+})
+```
+
+## Why the single security model is the real prize
+
+Normally the client and server each reimplement data access *and* authorization,
+kept in sync by hand, and the client can't safely share the server's auth logic —
+so the server re-validates everything and you maintain two security surfaces.
+
+Here there's one. Authorization is the injected-capability boundary plus the
+fuel budget plus RBAC — and the RBAC **rules themselves are TJS** (`src/rbac/`,
+`rules.tjs`), i.e. portable, serializable data, not compiled server code. So the
+exact same rule set evaluates in the browser and in the data center. A request
+that's denied locally is denied for the same reason it'd be denied server-side,
+because it's *the same rule running*. Fuel metering and monadic errors (no
+thrown exceptions to exploit) apply identically in both runtimes.
+
+Front-to-back, the security model isn't *mirrored* — it's *singular*.
+
+## When to reach for it
+
+- A rich client that already holds a working set of data, where most reads can be
+  served locally and only misses need the server.
+- A system where you want one authorization story rather than a client SDK's
+  rules and a server API's rules drifting apart.
+- Agent/tool orchestration that should run wherever the data is cheapest to
+  reach, without rewriting the program per environment.
+
+## See also
+
+- `CONTEXT.md` — architecture deep dive
+- AJS pillar in `CLAUDE.md` — "Code travels to data"
+- `src/vm/vm.ts`, `src/vm/runtime.ts` — the VM and the capability boundary
+- `src/rbac/` — portable (TJS) security rules

package/llms.txt

@@ -8,6 +8,7 @@ This file is a navigation index for AI agents. It does not contain the docs them
 
 - [CLAUDE-TJS-SYNTAX.md](CLAUDE-TJS-SYNTAX.md) — TJS syntax reference. Critical: `function foo(x: 'default')` is NOT a TypeScript string-literal type. The colon value is an **example**; `'default'` widens to `string`. LLMs get this wrong constantly.
 - [CLAUDE.md](CLAUDE.md) — project overview, common commands, architecture, security model, and key APIs.
+- [PRINCIPLES.md](PRINCIPLES.md) — **non-negotiable language invariants**: options-off TJS ⊇ JS, and TJS ⊇ AJS. A richer layer may do *more* with the same source but must never make subset-legal code illegal (e.g. un-runnable signature tests are inconclusive, not errors). The opt-in unit is the **dialect**: `tjs(src, { dialect: 'js' })` preserves plain-JS semantics, `'tjs'` (default) is native; file tools map extension→dialect via `dialectForFilename`/`sourceKindForFilename` from `tjs-lang/lang`. TypeScript routes through `fromTS` (`tjs-lang/lang/from-ts`) so the lean lang bundle stays TS-free — the full `js | ts | tjs` routing recipe is in PRINCIPLES.md. A violation is a bug.
 
 ## Language guides
 
@@ -27,7 +28,9 @@ This file is a navigation index for AI agents. It does not contain the docs them
 - [CONTEXT.md](CONTEXT.md) — architecture deep dive (two-layer design, atom system, value resolution).
 - [docs/function-predicate-design.md](docs/function-predicate-design.md) — Type / Generic / FunctionPredicate design.
 - [docs/generic-dts-design.md](docs/generic-dts-design.md) — `.d.ts` generation from TJS.
-- [docs/WASM-QUICKSTART.md](docs/WASM-QUICKSTART.md) — inline WASM, SIMD, `wasmBuffer()`.
+- [docs/WASM-QUICKSTART.md](docs/WASM-QUICKSTART.md) — inline WASM, SIMD, `wasmBuffer()` (5-minute intro).
+- [DOCS-WASM.md](DOCS-WASM.md) — canonical WASM reference: both inline `wasm{}` blocks and top-level `wasm function` declarations, memory model, cross-file composition (Phase 3), boundary distribution form (Phase 4), tjs-lang/linalg, current limitations.
+- [wasm-library-plan.md](wasm-library-plan.md) — cross-file WASM library design + phased implementation history. Shipped in v0.8.0; see plan for what's deferred.
 - [docs/native-engine-integration.md](docs/native-engine-integration.md) — embedding into a native runtime.
 
 ## Examples and live code
@@ -44,6 +47,7 @@ This file is a navigation index for AI agents. It does not contain the docs them
 - `tjs-lang/vm` → `src/vm/index.ts` — VM and atoms.
 - `tjs-lang/eval` → `src/lang/eval.ts` — `Eval`, `SafeFunction`.
 - `tjs-lang/batteries` → `src/batteries/index.ts` — LM Studio integration (lazy, local-only).
+- `tjs-lang/linalg` → `src/linalg/index.tjs` — SIMD linear-algebra kernels (`dot`, `norm_sq`, `dot_at`, `norm_sq_at`).
 
 ## Source map (for code-reading agents)
 
@@ -55,7 +59,10 @@ This file is a navigation index for AI agents. It does not contain the docs them
 - `src/lang/runtime.ts` — TJS runtime: monadic errors, `checkType`, `createRuntime`.
 - `src/lang/inference.ts` — infer `TypeDescriptor` from example values.
 - `src/lang/json-schema.ts` — JSON Schema from `TypeDescriptor`.
-- `src/lang/wasm.ts` — WASM bytecode emission.
+- `src/lang/wasm.ts` — WASM bytecode emission. Multi-function module composition; wasm-to-wasm `call <index>` resolution; per-function index map for cross-call resolution (v0.8.0).
+- `src/lang/emitters/js-wasm.ts` — JS bootstrap emitter for compiled wasm modules (one `WebAssembly.compile` per file).
+- `src/lang/module-loader.ts` — transpile-time `.tjs`/`.ts`/`.js` module loader; used by cross-file `wasm function` composition (v0.8.0).
+- `src/linalg/index.tjs` — `tjs-lang/linalg` stdlib source (v0.8.0).
 - `src/lang/linter.ts` — static analysis (unused vars, unreachable code).
 - `src/vm/runtime.ts` — atom implementations, expression sandboxing, fuel charging (security-critical, ~3000 lines).
 - `src/vm/vm.ts` — `AgentVM` class.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "typescript",
@@ -22,6 +22,25 @@
   "license": "Apache-2.0",
   "main": "./dist/index.js",
   "types": "./dist/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "eval": [
+        "./dist/src/lang/eval.d.ts"
+      ],
+      "lang": [
+        "./dist/src/lang/transpiler.d.ts"
+      ],
+      "lang/from-ts": [
+        "./dist/src/lang/emitters/from-ts.d.ts"
+      ],
+      "vm": [
+        "./dist/src/vm/index.d.ts"
+      ],
+      "batteries": [
+        "./dist/src/batteries/index.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -96,24 +115,25 @@
     "@codemirror/state": "^6.5.3",
     "@codemirror/theme-one-dark": "^6.1.3",
     "@codemirror/view": "^6.39.9",
+    "@eslint/js": "^10.0.1",
     "@happy-dom/global-registrator": "^20.1.0",
     "@types/bun": "latest",
     "@types/jsdom": "^21.1.7",
-    "@typescript-eslint/eslint-plugin": "^5.62.0",
-    "@typescript-eslint/parser": "^5.62.0",
     "acorn-walk": "^8.3.4",
     "chokidar": "^4.0.3",
     "codemirror": "^6.0.2",
     "esbuild": "^0.28.0",
-    "eslint": "^8.57.1",
+    "eslint": "^10.4.1",
     "firebase": "^10.12.0",
     "firebase-admin": "^13.6.0",
     "firebase-functions": "^7.0.5",
+    "globals": "^17.6.0",
     "marked": "^9.1.6",
     "prettier": "^2.8.8",
     "tosijs": "^1.5.6",
     "tosijs-ui": "^1.4.7",
     "typescript": "^5.6.2",
+    "typescript-eslint": "^8.61.0",
     "valibot": "^0.36.0",
     "vitest": "^2.0.5"
   },

package/src/batteries/audit.ts

@@ -190,9 +190,10 @@ async function checkEmbedding(
   }
 }
 
-// Tiny 1x1 red PNG as base64 for vision testing
+// 32x32 solid-red PNG (base64). NOT 1x1 — degenerate sizes are rejected by
+// real vision preprocessors (e.g. gemma: "Cannot handle this data type (1,1,1)").
 const TINY_TEST_IMAGE =
-  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=='
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAAMUlEQVR4nGO4o6FBU8QwasFoEI2motF8MFpUjJamo/XBaJU52qoYbReNNh01hkg+AACGobA9N+tfoAAAAABJRU5ErkJggg=='
 
 async function checkVision(baseUrl: string, modelId: string): Promise<boolean> {
   try {
@@ -225,13 +226,13 @@ export async function auditModels(baseUrl: string): Promise<ModelAudit[]> {
   const cachedData = await readCache(baseUrl)
 
   // 2. Get current model list from server
-  let serverModelIds: string[] = []
+  let serverModelIds: string[]
   try {
     const res = await fetch(`${baseUrl}/models`)
     if (!res.ok) throw new Error('Could not connect')
     const data = (await res.json()) as { data: { id: string }[] }
     serverModelIds = data.data.map((m) => m.id).sort()
-  } catch (e) {
+  } catch {
     // If we have cache and server is unavailable, use cache
     if (cachedData) {
       console.log('⚠️ LM Studio unavailable, using cached model audit.')
@@ -270,7 +271,7 @@ export async function auditModels(baseUrl: string): Promise<ModelAudit[]> {
     let type: ModelAudit['type'] = 'Unknown'
     let structured = false
     let vision = false
-    let statusMsg = ''
+    let statusMsg: string
     let dimension: number | undefined = undefined
 
     const isLLM = await checkLLM(baseUrl, model.id)

package/src/batteries/llm.ts

@@ -73,7 +73,10 @@ export function getLLMCapability(
             model: model.id,
             messages,
             temperature: 0.7,
-            tools,
+            // Only include tools when non-empty: an empty tools array makes
+            // LM Studio apply a tool-call grammar that can't be combined with
+            // a structured-output response_format ("lazy grammar" 400).
+            ...(tools && tools.length > 0 ? { tools } : {}),
             response_format: responseFormat,
           }),
         })
@@ -89,7 +92,8 @@ export function getLLMCapability(
       } catch (e: any) {
         if (e.cause?.code === 'ECONNREFUSED') {
           throw new Error(
-            'No LLM provider configured. Please start LM Studio or provide an API key.'
+            'No LLM provider configured. Please start LM Studio or provide an API key.',
+            { cause: e }
           )
         }
         throw e
@@ -117,7 +121,8 @@ export function getLLMCapability(
       } catch (e: any) {
         if (e.cause?.code === 'ECONNREFUSED') {
           throw new Error(
-            'No LLM provider configured. Please start LM Studio or provide an API key.'
+            'No LLM provider configured. Please start LM Studio or provide an API key.',
+            { cause: e }
           )
         }
         throw e

package/src/builder.ts

@@ -1,6 +1,5 @@
 import { coreAtoms, type Atom, type OpCode, type ExprNode } from './runtime'
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 type _AtomMap = typeof coreAtoms
 
 // --- Condition String Parser ---
@@ -358,7 +357,6 @@ export interface ArgRef {
 // --- Typed Builder ---
 
 // Helper to extract input type from Atom definition
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 type AtomInput<T> = T extends Atom<infer I, any> ? I : never
 
 // The Builder instance type with dynamic methods inferred from AtomMap
@@ -523,7 +521,6 @@ export class TypedBuilder<M extends Record<string, Atom<any, any>>> {
   return(schema: any): BuilderType<M> {
     const atom = this.atoms['return']
     if (!atom) throw new Error("Atom 'return' not found")
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const _schema = schema.schema ?? schema
     return this.add(atom.create({ schema: _schema }))
   }

package/src/cli/commands/check.ts

@@ -3,13 +3,14 @@
  */
 
 import { readFileSync } from 'fs'
-import { tjs } from '../../lang'
+import { tjs, dialectForFilename } from '../../lang'
 
 export async function check(file: string): Promise<void> {
   const source = readFileSync(file, 'utf-8')
 
   try {
-    const result = tjs(source)
+    // `.js`/`.mjs` ⇒ plain-JS semantics preserved; `.tjs` ⇒ native modes.
+    const result = tjs(source, { dialect: dialectForFilename(file) })
 
     // Report function info from types
     if (result.types && Object.keys(result.types).length > 0) {

package/src/cli/commands/emit.ts

@@ -21,7 +21,7 @@ import {
   existsSync,
 } from 'fs'
 import { join, basename, dirname, extname } from 'path'
-import { tjs } from '../../lang'
+import { tjs, dialectForFilename } from '../../lang'
 import { generateDocs } from '../../lang/docs'
 import { generateDTS } from '../../lang/emitters/dts'
 
@@ -84,9 +84,11 @@ async function emitFile(
   const filename = basename(inputPath)
 
   try {
-    // Use 'report' mode to get test results without throwing
+    // Use 'report' mode to get test results without throwing.
+    // `.js`/`.mjs` ⇒ plain-JS semantics preserved; `.tjs` ⇒ native modes.
     const result = tjs(source, {
       filename,
+      dialect: dialectForFilename(inputPath),
       debug: options.debug,
       runTests: 'report',
     })

package/src/cli/commands/run.ts

@@ -8,15 +8,19 @@ import { readFileSync } from 'fs'
 import { resolve } from 'path'
 import { preprocess } from '../../lang/parser'
 import { transpileToJS } from '../../lang/emitters/js'
+import { dialectForFilename } from '../../lang/dialect'
 import * as runtime from '../../lang/runtime'
 
 export async function run(file: string): Promise<void> {
   const absolutePath = resolve(file)
   const source = readFileSync(absolutePath, 'utf-8')
 
+  // `.js`/`.mjs` ⇒ plain-JS semantics preserved; `.tjs` ⇒ native modes.
+  const dialect = dialectForFilename(file)
+
   try {
     // Preprocess: transforms Type, Generic, Union declarations, runs tests
-    const preprocessed = preprocess(source)
+    const preprocessed = preprocess(source, { dialect })
 
     if (preprocessed.testErrors.length > 0) {
       console.error('Test failures:')
@@ -27,7 +31,7 @@ export async function run(file: string): Promise<void> {
     }
 
     // Transpile to JS
-    const result = transpileToJS(preprocessed.source)
+    const result = transpileToJS(preprocessed.source, { dialect })
 
     if (result.warnings && result.warnings.length > 0) {
       for (const warning of result.warnings) {

package/src/cli/commands/test.ts

@@ -123,7 +123,7 @@ export async function test(
   const pluginPath = getPluginPath()
 
   // Determine what to test
-  let testFiles: string[] = []
+  let testFiles: string[]
 
   if (!input) {
     // Find all .test.tjs files in current directory

package/src/cli/commands/types.ts

@@ -3,12 +3,12 @@
  */
 
 import { readFileSync } from 'fs'
-import { tjs } from '../../lang'
+import { tjs, dialectForFilename } from '../../lang'
 
 export async function types(file: string): Promise<void> {
   const source = readFileSync(file, 'utf-8')
 
-  const result = tjs(source)
+  const result = tjs(source, { dialect: dialectForFilename(file) })
 
   // Output the type information as JSON
   const typeInfo = {

package/src/lang/codegen.test.ts

@@ -1543,8 +1543,11 @@ function map(arr: [''], counter = strLength): [0] { return arr.map(counter) }`)
         )
         const sig = testResults?.find((t) => t.isSignatureTest)
         expect(sig).toBeDefined()
+        // The module couldn't execute (runtime ReferenceError on `x`), so the
+        // test couldn't run → inconclusive, never a build-blocking failure.
         expect(sig?.passed).toBe(false)
-        expect(sig?.error).toContain('Module execution failed')
+        expect(sig?.inconclusive).toBe(true)
+        expect(sig?.error).toContain('could not be executed')
         // Critical: no line attribution → editor won't mark a misleading line
         expect(sig?.line).toBeUndefined()
       })

package/src/lang/core.ts

@@ -12,7 +12,7 @@ import type {
   FunctionSignature,
   TypeDescriptor,
 } from './types'
-import { parse, validateSingleFunction } from './parser'
+import { parse, extractFunctions } from './parser'
 import { transformFunction } from './emitters/ast'
 import {
   transpileToJS,
@@ -26,6 +26,7 @@ export {
   preprocess,
   extractTDoc,
   validateSingleFunction,
+  extractFunctions,
 } from './parser'
 export { transformFunction } from './emitters/ast'
 
@@ -47,14 +48,15 @@ export function transpile(
     vmTarget: true,
   })
 
-  const func = validateSingleFunction(program, options.filename)
+  const { entry, helpers } = extractFunctions(program, options.filename)
 
   const { ast, signature, warnings } = transformFunction(
-    func,
+    entry,
     originalSource,
     returnType,
     options,
-    requiredParams
+    requiredParams,
+    helpers.size > 0 ? helpers : undefined
   )
 
   return {