tjs-lang 0.8.1 → 0.8.2

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.8.1",
+  "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",

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 {

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/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 {

package/src/lang/dialect.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'bun:test'
+import { tjs } from './index'
+import { dialectForFilename, sourceKindForFilename } from './dialect'
+
+describe('source dialect', () => {
+  // A line of vanilla JS whose meaning TJS would otherwise change: structural
+  // `==` (→ Eq), honest truthiness (→ toBool), and `typeof` (→ TypeOf).
+  const JS = `function f(a, b) { if (a == b) { return typeof a } return null }`
+
+  const isMolested = (code: string) =>
+    code.includes('Eq(') || code.includes('toBool') || code.includes('TypeOf')
+
+  describe('dialect option', () => {
+    it("dialect: 'js' preserves plain-JS semantics (no rewrites)", () => {
+      expect(isMolested(tjs(JS, { dialect: 'js' }).code)).toBe(false)
+    })
+
+    it("dialect: 'tjs' applies native footgun-removal modes", () => {
+      expect(isMolested(tjs(JS, { dialect: 'tjs' }).code)).toBe(true)
+    })
+
+    it('a bare string still defaults to native TJS (backward compatible)', () => {
+      expect(isMolested(tjs(JS).code)).toBe(true)
+    })
+
+    it("dialect: 'js' is equivalent to the TjsCompat directive", () => {
+      const viaOption = tjs(JS, { dialect: 'js' }).code
+      const viaDirective = tjs(`TjsCompat\n${JS}`).code
+      // Both leave the comparison/typeof untouched.
+      expect(isMolested(viaOption)).toBe(false)
+      expect(isMolested(viaDirective)).toBe(false)
+    })
+  })
+
+  describe('dialectForFilename', () => {
+    it('maps JS extensions to the js dialect', () => {
+      for (const f of ['a.js', 'a.mjs', 'a.cjs', 'deep/b.JS']) {
+        expect(dialectForFilename(f)).toBe('js')
+      }
+    })
+
+    it('maps .tjs and unknown/TS extensions to the tjs dialect', () => {
+      // .ts is not a tjs() dialect — it routes through fromTS — so the dialect
+      // helper reports 'tjs'; use sourceKindForFilename to tell them apart.
+      for (const f of ['a.tjs', 'a.ts', 'a.mts', 'a.d.ts', 'noext']) {
+        expect(dialectForFilename(f)).toBe('tjs')
+      }
+    })
+  })
+
+  describe('sourceKindForFilename', () => {
+    it('classifies js / ts / tjs by extension', () => {
+      expect(sourceKindForFilename('x.js')).toBe('js')
+      expect(sourceKindForFilename('x.mjs')).toBe('js')
+      expect(sourceKindForFilename('x.cjs')).toBe('js')
+      expect(sourceKindForFilename('x.ts')).toBe('ts')
+      expect(sourceKindForFilename('x.mts')).toBe('ts')
+      expect(sourceKindForFilename('x.d.ts')).toBe('ts')
+      expect(sourceKindForFilename('x.tjs')).toBe('tjs')
+      expect(sourceKindForFilename('x')).toBe('tjs')
+    })
+  })
+})

package/src/lang/dialect.ts

@@ -0,0 +1,50 @@
+/**
+ * Dialect resolution for file-based tooling.
+ *
+ * The subset invariant (see PRINCIPLES.md) says plain JavaScript must transpile
+ * through TJS without changing meaning, while native `.tjs` gets the full
+ * footgun-removal feature set. The unit of opt-in is the *dialect* — and for a
+ * file, the dialect is its extension. This is the one canonical mapping that
+ * CLIs, bundler plugins, module loaders, and doc systems should all share so
+ * `.js` is never silently "improved" into different semantics.
+ */
+
+/** Source dialect understood by `tjs(src, { dialect })`. */
+export type Dialect = 'js' | 'tjs'
+
+/** How a file should be transpiled, based on its extension. */
+export type SourceKind = 'js' | 'ts' | 'tjs'
+
+const JS_EXT = /\.[mc]?js$/i // .js .mjs .cjs
+const TS_EXT = /\.[mc]?ts$/i // .ts .mts .cts  (excludes .d.ts — handled below)
+const TJS_EXT = /\.tjs$/i
+
+/**
+ * Classify a file by extension into the source kind that determines its
+ * transpile path:
+ *  - `'tjs'` → native TJS: `tjs(src)` (all modes ON — the better language)
+ *  - `'js'`  → plain JS:   `tjs(src, { dialect: 'js' })` (semantics preserved)
+ *  - `'ts'`  → TypeScript: route through `fromTS` (TS → TJS → JS)
+ *
+ * Unknown extensions default to `'tjs'` (the native language). `.d.ts` is
+ * treated as TypeScript.
+ */
+export function sourceKindForFilename(filename: string): SourceKind {
+  if (TJS_EXT.test(filename)) return 'tjs'
+  if (JS_EXT.test(filename)) return 'js'
+  if (TS_EXT.test(filename)) return 'ts'
+  return 'tjs'
+}
+
+/**
+ * Map a filename to the `dialect` option for `tjs()`. `.js`/`.mjs`/`.cjs` ⇒
+ * `'js'` (plain JavaScript, semantics preserved); everything else ⇒ `'tjs'`
+ * (native TJS).
+ *
+ * NOTE: TypeScript files are NOT a `tjs()` dialect — transpile them with
+ * `fromTS` first. Use {@link sourceKindForFilename} when you need to tell
+ * `.ts` apart from `.js`/`.tjs`.
+ */
+export function dialectForFilename(filename: string): Dialect {
+  return sourceKindForFilename(filename) === 'js' ? 'js' : 'tjs'
+}

package/src/lang/emitters/ast.ts

@@ -124,7 +124,8 @@ export function transformFunction(
   source: string,
   returnTypeAnnotation: string | undefined,
   options: TranspileOptions = {},
-  requiredParamsFromPreprocess?: Set<string>
+  requiredParamsFromPreprocess?: Set<string>,
+  helpers?: Map<string, FunctionDeclaration>
 ): {
   ast: BaseNode
   signature: FunctionSignature
@@ -175,6 +176,9 @@ export function transformFunction(
     source,
     filename: options.filename || '<source>',
     options,
+    helpers,
+    helperSteps: helpers ? new Map() : undefined,
+    helperTransforming: helpers ? new Set() : undefined,
   }
 
   // Transform function body
@@ -244,8 +248,21 @@ export function transformFunction(
   // Generate input schema for runtime validation
   const inputSchema = parametersToJsonSchema(signatureParams)
 
+  // Collect transitively-used helper bodies (transformed once) onto the root
+  // node. The VM installs these into ctx.helpers so callLocal can dispatch by
+  // name — call sites stay tiny and recursion is a runtime loop.
+  const helperBodies =
+    ctx.helperSteps && ctx.helperSteps.size > 0
+      ? Object.fromEntries(ctx.helperSteps)
+      : undefined
+
   return {
-    ast: { op: 'seq', steps, inputSchema },
+    ast: {
+      op: 'seq',
+      steps,
+      inputSchema,
+      ...(helperBodies && { helpers: helperBodies }),
+    },
     signature,
     warnings: ctx.warnings,
   }
@@ -1079,6 +1096,34 @@ function transformCallExpression(
     // This would be caught above, but just in case
   }
 
+  // Helper call? Emit callLocal referencing the helper by name. The body is
+  // transformed once and stored in ctx.helperSteps (collected onto the seq
+  // node), so call sites stay tiny and recursion is just a runtime loop.
+  if (ctx.helpers?.has(funcName)) {
+    const paramNames = ensureHelperTransformed(funcName, ctx, expr)
+    const argExprs = expr.arguments.map((arg) =>
+      expressionToValue(arg as Expression, ctx)
+    )
+    if (argExprs.length !== paramNames.length) {
+      throw new TranspileError(
+        `Helper '${funcName}' expects ${paramNames.length} argument(s), got ${argExprs.length}`,
+        getLocation(expr),
+        ctx.source,
+        ctx.filename
+      )
+    }
+    return {
+      step: {
+        op: 'callLocal',
+        name: funcName,
+        args: argExprs,
+        ...(resultVar && { result: resultVar }),
+        ...(resultVar && isConst && { resultConst: true }),
+      },
+      resultVar,
+    }
+  }
+
   // Check if it's a known atom
   // For now, we assume any function call is an atom call
   // The VM will validate at runtime
@@ -1097,6 +1142,89 @@ function transformCallExpression(
   }
 }
 
+/**
+ * Ensure a helper's body has been transformed once into `ctx.helperSteps`,
+ * returning its parameter names (for arity checking at the call site).
+ *
+ * Bodies are stored by name and called by reference at runtime, so recursion
+ * is fine: when a helper references itself (or a mutually-recursive sibling)
+ * the call site only needs the param names — the steps are filled in when the
+ * in-progress transform completes. The `helperTransforming` set just prevents
+ * re-entering a transform that's already underway.
+ */
+function ensureHelperTransformed(
+  name: string,
+  ctx: TransformContext,
+  callSite: CallExpression
+): string[] {
+  const fn = ctx.helpers!.get(name)!
+  // Accept plain identifiers (`x`) and example/default params (`x: 0` → `x = 0`
+  // after colon-shorthand desugaring). Destructuring isn't supported in v1.
+  // Helpers are arity-checked and called with explicit args, so the example/
+  // default is never applied — we only need the parameter name and position.
+  const paramNames: string[] = []
+  for (const param of fn.params) {
+    let id: Identifier | undefined
+    if (param.type === 'Identifier') {
+      id = param as Identifier
+    } else if (
+      param.type === 'AssignmentPattern' &&
+      (param as any).left?.type === 'Identifier'
+    ) {
+      id = (param as any).left as Identifier
+    }
+    if (!id) {
+      throw new TranspileError(
+        `Helper '${name}' parameters must be plain identifiers (optionally with an example value); destructuring is not supported`,
+        param.loc?.start ?? getLocation(callSite),
+        ctx.source,
+        ctx.filename
+      )
+    }
+    paramNames.push(id.name)
+  }
+
+  // Already transformed, or transform already underway (recursive reference):
+  // the call site only needs paramNames; the body is/will be in helperSteps.
+  if (ctx.helperSteps!.has(name) || ctx.helperTransforming!.has(name)) {
+    return paramNames
+  }
+
+  ctx.helperTransforming!.add(name)
+  try {
+    // Transform the helper body in a fresh inner context — isolated locals,
+    // params as the only known identifiers; helpers map is shared so it can
+    // call (and recurse into) other helpers.
+    const helperCtx: TransformContext = {
+      depth: 0,
+      locals: new Map(),
+      parameters: new Map(
+        paramNames.map((p) => [
+          p,
+          {
+            name: p,
+            type: { kind: 'any' as const },
+            required: true,
+          } as ParameterDescriptor,
+        ])
+      ),
+      atoms: ctx.atoms,
+      warnings: ctx.warnings,
+      source: ctx.source,
+      filename: ctx.filename,
+      options: ctx.options,
+      helpers: ctx.helpers,
+      helperSteps: ctx.helperSteps,
+      helperTransforming: ctx.helperTransforming,
+    }
+    const bodySteps = transformBlock(fn.body, helperCtx)
+    ctx.helperSteps!.set(name, { steps: bodySteps, paramNames })
+  } finally {
+    ctx.helperTransforming!.delete(name)
+  }
+  return paramNames
+}
+
 /**
  * Handle method calls like arr.map(), str.slice(), etc.
  */
@@ -1544,6 +1672,21 @@ function expressionToExprNode(
       // Handle global function calls (e.g., parseInt(x), parseFloat(x))
       if (call.callee.type === 'Identifier') {
         const funcName = (call.callee as Identifier).name
+
+        // Helper calls cannot be nested inside expressions — like template
+        // literals and complex calls, they must live at statement level so the
+        // expression sandbox stays call-free. Lift to a temp first.
+        if (ctx.helpers?.has(funcName)) {
+          throw new TranspileError(
+            `Helper '${funcName}' cannot be called inside an expression. ` +
+              `Assign its result to a variable first: ` +
+              `const result = ${funcName}(...); then use result.`,
+            getLocation(expr),
+            ctx.source,
+            ctx.filename
+          )
+        }
+
         return {
           $expr: 'call',
           callee: funcName,

package/src/lang/emitters/js-tests.ts

@@ -18,6 +18,13 @@ export interface TestResult {
   error?: string
   /** Whether this was an implicit signature test */
   isSignatureTest?: boolean
+  /**
+   * The test could not be *run* (e.g. it references a name TJS can't resolve at
+   * build time — like an AJS atom — or the harness couldn't execute the module).
+   * Inconclusive ≠ failed: it never blocks transpilation. Surfaced as a warning
+   * (e.g. in the playground). See PRINCIPLES.md ("more, never illegal").
+   */
+  inconclusive?: boolean
   /** Source line number (1-indexed) where the test or error occurred */
   line?: number
   /** Source column number (1-indexed) */
@@ -678,7 +685,7 @@ export function runAllTests(
       ${body}
       __testResults.push({ idx: ${i}, passed: true });
     } catch (e) {
-      __testResults.push({ idx: ${i}, passed: false, error: e.message || String(e) });
+      __testResults.push({ idx: ${i}, passed: false, isRef: e instanceof ReferenceError, error: e.message || String(e) });
     }
   `
     })
@@ -721,7 +728,10 @@ export function runAllTests(
         __sigTestResults.push({ idx: ${i}, passed: false, error: 'Expected ' + __format(__expected) + ' at \\'${testLabel}\\', got ' + __format(__actual) });
       }
     } catch (e) {
-      __sigTestResults.push({ idx: ${i}, passed: false, error: e.message || String(e) });
+      // The function threw on its example inputs — the example couldn't be
+      // *evaluated* (e.g. it calls an atom that doesn't exist at build time).
+      // That's inconclusive, not a mismatch. Never block transpilation on it.
+      __sigTestResults.push({ idx: ${i}, passed: false, threw: true, error: e.message || String(e) });
     }
   `
     })
@@ -834,62 +844,62 @@ export function runAllTests(
       typeMatches
     )
 
-    // Map block test results
+    // Map block test results. A block test that threw a ReferenceError
+    // couldn't *run* (it names something TJS can't resolve at build time, e.g.
+    // an AJS atom) → inconclusive, not failed. An assertion failure (plain
+    // Error from expect()) is a genuine failure.
     for (const r of blockResults) {
       const test = tests[r.idx]
-      // Skip block tests that fail due to unresolved imports
-      const isImportError =
-        hasUnresolvedImports &&
+      const inconclusive =
         !r.passed &&
-        r.error &&
-        /is not defined$/.test(r.error)
+        (r.isRef ||
+          (hasUnresolvedImports && r.error && /is not defined$/.test(r.error)))
       results.push({
         description: test.description,
-        passed: isImportError ? true : r.passed,
-        error: isImportError ? undefined : r.error,
+        passed: r.passed,
+        inconclusive: inconclusive || undefined,
+        error: r.error,
         line: test.line,
       })
     }
 
-    // Map signature test results
+    // Map signature test results. A test that *threw* (couldn't evaluate the
+    // example) is inconclusive; only a clean value-mismatch is a failure.
     for (const r of sigTestResults) {
       const info = syncSigTestInfos[r.idx]
-      // Skip signature tests that fail due to unresolved imports
-      const isImportError =
-        hasUnresolvedImports &&
+      const inconclusive =
         !r.passed &&
-        r.error &&
-        /is not defined$/.test(r.error)
+        (r.threw ||
+          (hasUnresolvedImports && r.error && /is not defined$/.test(r.error)))
       const label = info.className
         ? `${info.className}.${info.funcName}`
         : info.funcName
       results.push({
         description: `${label} signature example`,
-        passed: isImportError ? true : r.passed,
-        error: isImportError ? undefined : r.error,
+        passed: r.passed,
+        inconclusive: inconclusive || undefined,
+        error: r.error,
         isSignatureTest: true,
         line: info.line,
       })
     }
   } catch (e: any) {
-    // If module fails due to unresolved imports (ReferenceError from stripped imports),
-    // skip tests gracefully rather than marking them as failures
-    const isUnresolvedRef = hasUnresolvedImports && e instanceof ReferenceError
-
-    // The error came from module-level code (e.g. an undefined identifier
-    // in `console.log(... x ...)`), NOT from the function/test under test.
-    // Don't attribute a line — otherwise the editor would mark the function
-    // declaration's line as the error site, misleading the user about where
-    // the actual problem is. The test still appears as failed in the test
-    // list with the explanatory message; the user finds the real error
-    // through the runtime console.
+    // The whole module failed to execute, so NO test could run — every result
+    // here is inconclusive, never a failure. Making transpilation fail because
+    // an auto-generated test harness couldn't execute the module would turn
+    // legal code illegal (e.g. a module referencing AJS atoms, or — an edge —
+    // two top-level functions on one line). See PRINCIPLES.md.
+    //
+    // No line is attributed: the error came from module-level execution, not a
+    // specific function, and mis-attributing it would point the editor at the
+    // wrong site. The message is preserved as a warning on each result.
+    const note = `Module could not be executed for testing: ${e.message}`
     for (const test of tests) {
       results.push({
         description: test.description,
-        passed: isUnresolvedRef,
-        error: isUnresolvedRef
-          ? undefined
-          : `Module execution failed: ${e.message}`,
+        passed: false,
+        inconclusive: true,
+        error: note,
       })
     }
     for (const info of syncSigTestInfos) {
@@ -898,10 +908,9 @@ export function runAllTests(
         : info.funcName
       results.push({
         description: `${label} signature example`,
-        passed: isUnresolvedRef,
-        error: isUnresolvedRef
-          ? undefined
-          : `Module execution failed: ${e.message}`,
+        passed: false,
+        inconclusive: true,
+        error: note,
         isSignatureTest: true,
       })
     }